CakeDC Blog

This article is part of the CakeDC Advent Calendar 2024 (December 7th 2024)

This article continues our exploration of htmx integration with CakePHP, focusing on two powerful features that can significantly enhance user experience: inline editing and lazy loading of actions. These features demonstrate how htmx can transform traditional web interfaces into dynamic, responsive experiences while maintaining clean, maintainable code.

Other Articles in the Series

• Building Dynamic Web Applications with CakePHP and HTMX: A Practical Guide
• Building Dynamic Web Applications with CakePHP and HTMX: Infinite Scroll

Inline Editing with htmx

Inline editing allows users to modify content directly on the page without navigating to separate edit forms. This pattern is particularly useful for content-heavy applications where users need to make quick updates to individual fields. With htmx, we can implement this feature with minimal JavaScript while maintaining a smooth, intuitive user experience.

Basic Implementation

The inline editing feature consists of three main components:

1. A display view that shows the current value with an edit button
2. An edit form that appears when the user clicks the edit button
3. A controller action that handles both display and edit modes

Let's implement each component:

Controller Setup

First, we'll create a dedicated action in our controller to handle both viewing and editing states:

// /src/Controller/PostsController.php
public function inlineEdit(int $id, string $field)
{
    $post = $this->Posts->get($id, contain: []);
    $allowedFields = ['title', 'overview', 'body', 'is_published'];
    if (!in_array($field, $allowedFields)) {
        return $this->response->withStatus(403);
    }

    $mode = 'edit';
    if ($this->request->is(['post', 'put'])) {
        if ($this->request->getData('button') == 'cancel') {
            $mode = 'view';
        } else {
            $value = $this->request->getData($field);
            $post->set($field, $value);
            if ($this->Posts->save($post)) {
                $mode = 'view';
            }
        }
    }

    if ($this->getRequest()->is('htmx')) {
        $this->viewBuilder()->disableAutoLayout();
        $this->Htmx->setBlock('edit');
    }
    $this->set(compact('post', 'mode', 'field'));
}

View Helper

To maintain consistency and reduce code duplication, we'll create a helper to generate inline-editable fields:

// /src/View/Helper/HtmxWidgetsHelper.php
public function inlineEdit(string $field, $value, EntityInterface $entity): string
{
    $url = $this->Url->build([
        'action' => 'inlineEdit',
        $entity->get('id'),
        $field
    ]);
    return sprintf(
        '<div class="inline-edit-wrapper">
            <span class="field-value">%s</span>
            <button class="btn btn-sm inline-edit-btn" hx-get="%s">
                <i class="fas fa-edit"></i>
            </button>
        </div>',
        $value,
        $url
    );
}

Template Implementation

The template handles both view and edit modes:

// /templates/Posts/inline_edit.php
<?php
$formOptions = [
    'id' => 'posts',
    'hx-put' => $this->Url->build([
        'action' => 'inlineEdit',
        $post->id,
        $field,
    ]),
    'hx-target' => 'this',
    'hx-swap' => 'outerHTML',
    'class' => 'inline-edit-form inline-edit-wrapper',
];
?>
<?php $this->start('edit'); ?>
<?php if ($mode == 'view'): ?>
    <?php if ($field == 'is_published'): ?>
    <?= $this->HtmxWidgets->inlineEdit($field, $post->is_published ? 'Published' : 'Unpublished', $post); ?>
    <?php elseif ($field == 'body'): ?>
        <?= $this->HtmxWidgets->inlineEdit('body', $this->Text->autoParagraph(h($post->body)), $post) ?>
    <?php elseif ($field == 'overview'): ?>
        <?= $this->HtmxWidgets->inlineEdit('overview', $this->Text->autoParagraph(h($post->overview)), $post) ?>
    <?php else: ?>
        <?= $this->HtmxWidgets->inlineEdit($field, $post->get($field), $post); ?>
    <?php endif; ?>
<?php else: ?>
    <?= $this->Form->create($post, $formOptions) ?>
    <?= $this->Form->hidden('id'); ?>
    <?php if ($field == 'title'): ?>
        <?= $this->Form->control('title'); ?>
    <?php elseif ($field == 'overview'): ?>
        <?= $this->Form->control('overview'); ?>
    <?php elseif ($field == 'body'): ?>
        <?= $this->Form->control('body'); ?>
    <?php elseif ($field == 'is_published'): ?>
        <?= $this->Form->control('is_published'); ?>
    <?php endif; ?>
    <div class="inline-edit-actions">
        <?= $this->Form->button('<i class="fas fa-check"></i>', [
            'class' => 'btn btn-primary btn-sm inline-edit-trigger',
            'name' => 'button',
            'value' => 'save',
            'escapeTitle' => false,
        ]); ?>
        <?= $this->Form->button('<i class="fas fa-times"></i>', [
            'class' => 'btn btn-secondary btn-sm inline-edit-trigger',
            'name' => 'button',
            'value' => 'cancel',
            'escapeTitle' => false,
        ]); ?>
    </div>
    <?= $this->Form->end() ?>
<?php endif; ?>
<?php $this->end(); ?>
<?= $this->fetch('edit'); ?>

Styling

The CSS ensures a smooth transition between view and edit modes:

.inline-edit-wrapper {
    display: inline-flex;
    align-items: center;
    gap: 0.5rem;
}
.inline-edit-btn {
    padding: 0.25rem;
    background: none;
    border: none;
    cursor: pointer;
    opacity: 0.5;
}
.inline-edit-wrapper:hover .inline-edit-btn {
    opacity: 1;
}

.inline-edit-form {
    display: inline-flex;
    align-items: center;
    gap: 0.5rem;
}

.inline-edit-form .input {
    margin: 0;
}

.inline-edit-form input {
    padding: 0.25rem 0.5rem;
    height: auto;
    width: auto;
}

.inline-edit-actions {
    display: inline-flex;
    gap: 0.25rem;
}

.inline-edit-actions .btn {
    padding: 0.25rem 0.5rem;
    line-height: 1;
    height: auto;
}

.inline-edit-actions .btn {
    padding: 0.25rem;
    min-width: 24px;
    min-height: 24px;
}

.inline-edit-actions .btn[title]:hover::after {
    content: attr(title);
    position: absolute;
    bottom: 100%;
    left: 50%;
    transform: translateX(-50%);
    background: rgba(0,0,0,0.8);
    color: white;
    padding: 0.25rem 0.5rem;
    border-radius: 4px;
    font-size: 12px;
    white-space: nowrap;
}

Usage example

In the index template, we can use the helper to create inline-editable fields and provide a button to trigger the edit mode inside a table cell:

// /templates/Posts/index.php
<?= $this->HtmxWidgets->inlineEdit('title', $post->title, $post) ?>
<?= $this->HtmxWidgets->inlineEdit('is_published', $post->is_published ? __('Yes') : __('No'), $post) ?>

Inline Editing Flow

The inline editing feature transforms static content into interactive, editable fields directly on the page. This implementation follows a clear state-based workflow that provides immediate visual feedback while maintaining data integrity.

State Management

The system maintains two distinct states for each editable field:

• View State: Displays the current value with an edit button
• Edit State: Shows an editable form with save and cancel options

Workflow Steps

1. Initial Display

   • Each editable field is wrapped in a container that includes both the value and an edit button
   • The edit button remains subtle until the user hovers over the field, providing a clean interface
   • The field's current value is displayed in a formatted, read-only view

2. Entering Edit Mode

   • When the user clicks the edit button, htmx sends a GET request to fetch the edit form
   • The server determines the appropriate input type based on the field (text input, textarea, or checkbox)
   • The edit form smoothly replaces the static display

3. Making Changes

   • Users can modify the field's value using the appropriate input control
   • The form provides clear save and cancel options
   • Visual feedback indicates the field is in edit mode

4. Saving or Canceling

   • Saving triggers a PUT request with the updated value
   • The server validates and updates the field
   • If the value is invalid, the form is redisplayed with error messages
   • Canceling reverts to the view state without making changes
   • Both actions transition smoothly back to the view state that has been performed on success for edit and always on cancel

HTMX Attributes in Action

The implementation uses several key htmx attributes to manage the editing flow:

1. View State Attributes

   • hx-get: Fetches the edit form when the edit button is clicked
   • hx-target: Ensures the form replaces the entire field container
   • hx-swap: Uses "outerHTML" to maintain proper DOM structure

2. Edit State Attributes

   • hx-put: Submits the updated value to the server
   • hx-target: Targets the form container for replacement
   • hx-swap: Manages the transition back to view mode

Lazy Loading Actions

Lazy loading actions is a performance optimization technique where we defer loading action buttons until they're needed. This is particularly useful in tables or lists with many rows, where each row might have multiple actions that require permission checks or additional data loading.

Implementation

First, let's create a controller action to handle the lazy loading of actions:

// /src/Controller/PostsController.php
public function tableActions(int $id)
{
    $post = $this->Posts->get($id, contain: []);
    if ($this->getRequest()->is('htmx')) {
        $this->viewBuilder()->disableAutoLayout();
        $this->Htmx->setBlock('actions');
    }
    $this->set(compact('post'));
}

Table Actions Template

Create a reusable element for the action buttons:

// /templates/Posts/table_actions.php
<?php $this->start('actions'); ?>
<?= $this->Html->link(__('View'), ['action' => 'view', $post->id]) ?>
<?= $this->Html->link(__('Edit'), ['action' => 'edit', $post->id]) ?>
<?= $this->Form->postLink(__('Delete'), ['action' => 'delete', $post->id], ['confirm' => __('Are you sure you want to delete # {0}?', $post->id)]) ?>
<?php $this->end(); ?>
<?= $this->fetch('actions'); ?>

Template Element

Create a reusable element for the action buttons:

// /templates/element/lazy_actions.php
<div class="action-wrapper"
    hx-get="<?= $this->Url->build([
        'action' => 'tableActions',
        $entity->id,
    ]) ?>"
    hx-trigger="click"
    hx-swap="outerHTML"
    hx-target="this"
    hx-indicator="#spinner-<?= $entity->id ?>"
>
    <?= $this->Html->tag('button', '<i class="fas fa-ellipsis-vertical"></i>', [
        'class' => 'btn btn-light btn-sm rounded-circle',
        'type' => 'button'
    ]) ?>
    <div id="spinner-<?= $entity->id ?>" class="htmx-indicator" style="display: none;">
        <div class="spinner-border spinner-border-sm text-secondary" role="status">
            <span class="visually-hidden">Loading...</span>
        </div>
    </div>
</div>

Usage in Tables

Implementation of the lazy loading trigger in your table rows is done by replacing the static actions with the lazy loading trigger:

The static actions is displayed as:

<!-- /templates/Posts/index.php -->
<td class="actions">
    <?= $this->Html->link(__('View'), ['action' => 'view', $post->id]) ?>
    <?= $this->Html->link(__('Edit'), ['action' => 'edit', $post->id]) ?>
    <?= $this->Form->postLink(__('Delete'), ['action' => 'delete', $post->id], ['confirm' => __('Are you sure you want to delete # {0}?', $post->id)]) ?>
</td>

And lazy loading trigger is displayed as:

<!-- /templates/Posts/index.php -->
<td class="actions">
    <?= $this->element('lazy_actions', ['entity' => $post]) ?>
</td>

Modal Forms and Views with htmx

Modal dialogs provide a focused way to present forms and content without navigating away from the current page. Using htmx, we can create dynamic modals that load their content asynchronously while maintaining a clean, maintainable codebase.

Implementation Overview

The modal implementation consists of several components:

1. A modal container element in the default layout
2. A dedicated modal layout for content
3. A helper class for generating modal-triggering links
4. JavaScript handlers for modal lifecycle events

Basic Setup

First, add the modal container to your default layout:

<!-- /templates/element/modal_container.php -->
<?php if (!$this->getRequest()->is('htmx')): ?>
<div id="modal-area"
    class="modal modal-blur fade"
    style="display: none"
    aria-hidden="false"
    tabindex="-1">
    <div class="modal-dialog modal-lg modal-dialog-centered" role="document">
        <div class="modal-content"></div>
    </div>
</div>
<script type="text/x-template" id="modal-loader">
    <div class="modal-body d-flex justify-content-center align-items-center" style="min-height: 200px;">
        <div class="spinner-border text-primary" style="width: 3rem; height: 3rem;" role="status">
            <span class="visually-hidden">Loading...</span>
        </div>
    </div>
</script>
<?php endif; ?>

Modal Layout

Create a dedicated layout for modal content:

<!-- /templates/layout/modal.php -->
<?php
/**
 * Modal layout
 */
echo $this->fetch('css');
echo $this->fetch('script');

?>
<div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
        <div class="modal-header">
            <h5 class="modal-title"><?= $this->fetch('title') ?></h5>
            <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
        </div>
        <div class="modal-body">
            <?= $this->fetch('content') ?>
        </div>
    </div>
</div>

Modal Helper

Create a helper to generate modal-triggering links:

<?php
// /src/View/Helper/ModalHelper.php
declare(strict_types=1);

namespace App\View\Helper;

use Cake\View\Helper;

class ModalHelper extends Helper
{
    protected array $_defaultConfig = [
        'modalTarget' => '#modal-area',
    ];

    public array $helpers = ['Html', 'Url'];

    public function link(string $title, array|string $url, array $options = []): string
    {
        $defaultOptions = $this->getModalOptions($this->Url->build($url), 'get');
        $options = array_merge($defaultOptions, $options);

        return $this->Html->tag('a', $title, $options);
    }

    public function getModalOptions(string $url, string $method): array
    {
        $options = [
            'hx-target' => $this->getConfig('modalTarget'),
            'hx-trigger' => 'click',
            'hx-headers' => json_encode([
                'X-Modal-Request' => 'true',
            ]),
            'href' => 'javascript:void(0)',
            'data-bs-target' => $this->getConfig('modalTarget'),
        ];
        if (strtolower($method) === 'get') {
            $options['hx-get'] = $url;
        } else {
            $options['hx-' . strtolower($method)] = $url;
        }

        return $options;
    }
}

Controller Integration

Update your AppController to handle modal requests:

// /src/Controller/AppController.php
public function beforeRender(EventInterface $event)
{
    if ($this->isModalRequest()) {
        $this->viewBuilder()->setLayout('modal');
        $this->viewBuilder()->enableAutoLayout();
    }
}

protected function isModalRequest(): bool
{
    return $this->getRequest()->getHeader('X-Modal-Request') !== [];
}

JavaScript Integration

Add event handlers to manage modal behavior in your application's JavaScript:

// /webroot/js/app.js
document.addEventListener('htmx:beforeRequest', function(evt) {
    const target = evt.detail.target;
    if (target.id === 'modal-area') {
        const modalContent = document.querySelector('#modal-area .modal-content');
        if (modalContent) {
            modalContent.innerHTML = document.getElementById('modal-loader').innerHTML;
        }
        const modal = bootstrap.Modal.getInstance(target) || new bootstrap.Modal(target);
        modal.show();
    }
});

This handler ensures proper modal initialization and loading state display.

Usage Example

To create a modal-triggering link:

<!-- /templates/Posts/infinite.php -->
<?= $this->Modal->link(__('Edit'), ['action' => 'edit', $post->id]) ?>

Implementing Edit Form in Modal

Let's look at how to implement a complete edit form using modals. This requires changes to both the controller action and template.

Controller Action

Update the edit action to handle both regular and modal requests:

// /src/Controller/PostsController.php
public function edit($id = null)
{
    $post = $this->Posts->get($id, contain: []);
    if ($this->request->is(['patch', 'post', 'put'])) {
        $post = $this->Posts->patchEntity($post, $this->request->getData());

        $success = $this->Posts->save($post);
        if ($success) {
            $message = __('The post has been saved.');
            $status = 'success';
        } else {
            $message = __('The post could not be saved. Please, try again.');
            $status = 'error';
        }
        $redirect = Router::url(['action' => 'index']);

        if ($this->getRequest()->is('htmx')) {
            if ($success) {
                $response = [
                    'messages' => [
                        ['message' => $message, 'status' => $status],
                    ],
                    'reload' => true,
                ];
                return $this->getResponse()
                    ->withType('json')
                    ->withHeader('X-Response-Type', 'json')
                    ->withStringBody(json_encode($response));
            }
        } else {
            $this->Flash->{$status}($message);
            if ($success) {
                return $this->redirect($redirect);
            }
        }
    }
    $this->set(compact('post'));
    if ($this->getRequest()->is('htmx')) {
        $this->Htmx->setBlock('post');
    }
}

Edit Form Template

Create a template that works both as a standalone page and within a modal:

<!-- /templates/Posts/edit.php -->
<?php
$this->assign('title', __('Edit Post'));
?>
<?php $this->start('post'); ?>
<div class="row">
    <div class="column-responsive column-80">
        <div class="posts form content">
            <?= $this->Form->create($post) ?>
            <fieldset>
                <?php
                    echo $this->Form->control('title');
                    echo $this->Form->control('body');
                    echo $this->Form->control('overview');
                    echo $this->Form->control('is_published');
                ?>
            </fieldset>
            <?= $this->Form->button(__('Submit')) ?>
            <?= $this->Form->end() ?>
        </div>
    </div>
</div>
<?php $this->end(); ?>
<?= $this->fetch('post'); ?>

The edit implementation seamlessly handles both modal and regular form submissions while maintaining consistent behavior across different request types. When validation errors occur, they are displayed directly within the modal, providing immediate feedback to users. Upon successful save, the page automatically refreshes to reflect the changes, and users receive feedback through toast notifications that appear in the corner of the screen.

The response processing on the client side follows the same pattern we explored in the previous article of this series.

Modal Workflow

Our modal implementation creates a smooth, intuitive user experience through several coordinated steps. During initial setup, we add the modal container to the default layout and initialize Bootstrap's modal component. A loading indicator template is also defined to provide visual feedback during content loading.

When a user clicks a modal-triggering link, HTMX sends a request with a special X-Modal-Request header. During this request, the loading indicator appears, giving users immediate feedback that their action is being processed.

The server recognizes the modal request through the special header and switches to the modal layout. This layout ensures content is properly formatted for display within the modal structure. As soon as the content is ready, the modal automatically appears on screen with a smooth animation.

For form submissions within the modal, HTMX handles the process using its attributes system. The server's response determines whether to update the modal's content (in case of validation errors) or close it (on successful submission). Throughout this process, toast notifications keep users informed of the operation's status, appearing briefly in the corner of the screen before automatically fading away.

Conclusion

Implementing inline editing and lazy loading actions with htmx in CakePHP demonstrates the framework's flexibility and htmx's power in creating dynamic interfaces. The combination allows developers to build modern, responsive features with minimal JavaScript while maintaining clean, maintainable code. CakePHP's built-in helpers and htmx's declarative approach work together seamlessly to create a superior user experience.

This article is the last one of the series of articles about htmx and CakePHP. We have covered a lot of ground and I hope you have learned something new and useful.

Demo Project for Article

The examples used in this article are located at https://github.com/skie/cakephp-htmx/tree/3.0.0 and available for testing.

This article is part of the CakeDC Advent Calendar 2024 (December 7th 2024)