Contrib.social

DX object to collect and manage HTMX behaviors

Open on Drupal.org →
Created on 12 May 2025, 24 days ago

Problem/Motivation

We have both attributes and headers as tools to implement actions using HTMX. We also have defined sets of actions in the existing Ajax API that it would be beneficial to provide equivalent actions.

Proposed resolution

This issue is currently a placeholder until the related issues are completed and committed. For now the code for the proposed object is inserted here in the summary.


namespace Drupal\Core\Render\Hypermedia;

use Drupal\Component\Utility\NestedArray;
use Drupal\Core\Http\HtmxHeaderInterface;
use Drupal\Core\Http\HtmxResponseHeaders;
use Drupal\Core\Render\Hypermedia\Operations\HtmxOperationInterface;
use Drupal\Core\Render\Hypermedia\Operations\HtmxRequestOperationInterface;
use Drupal\Core\Template\AttributeHelper;
use Drupal\Core\Template\HtmlAttributeInterface;
use Drupal\Core\Template\HtmxAttribute;

/**
 * Collects HTMX attributes and headers and manages complex behaviors.
 *
 * An instance of this object is required to add HTMX behaviors to a render
 * element.
 *
 * Methods to configure common behaviors are provided:
 *
 * @code
 * $htmx = new Htmx();
 * $node_url = Url::fromRoute(
 *    route_name: entity.node.canonical',
 *    route_parameters: ['node' => 123],
 *  );
 * $htmx->insert($node_url, 'div.example', 'article.page')
 *
 * $build = [
 *    '#htmx' => $htmx,
 *  ];
 * @endcode
 *
 * Attributes may also be specified explicitly:
 *
 * @code
 * $htmx = new Htmx();
 * $form_url = Url::fromRoute(
 *   route_name: 'config.export_single',
 *   route_parameters: ['config_type' => $config_type, 'config_name' => $config_name],
 * );
 *
 * $htmx->attributes()
 *   ->post($form_url)
 *   ->select('select[data-drupal-selector="edit-config-name"]')
 *   ->target('select[data-drupal-selector="edit-config-name"]')
 *   ->swap('outerHTML');
 *
 * $build = [
 *   '#htmx' => $htmx,
 * ];
 * @endcode
 *
 * HTMX headers are added in a similar way.
 *
 * @code
 * // Also update the browser URL.
 * $push = Url::fromRoute(
 *   route_name: 'config.export_single',
 *   route_parameters: ['config_type' => $default_type, 'config_name' => $default_name],
 * );
 *
 * $htmx = new Htmx();
 * $htmx->headers()->pushUrl($push);
 * $build = [
 *   '#htmx' => $htmx,
 * ];
 * @endcode
 *
 * @see \Drupal\Core\Template\HtmxAttribute
 * @see \Drupal\Core\Http\HtmxResponseHeaders
 */
class Htmx implements HtmxInterface {

  /**
   * Optional request operation.
   *
   * @var \Drupal\Core\Render\Hypermedia\Operations\HtmxRequestOperationInterface|null
   */
  protected HtmxRequestOperationInterface|null $requestOperation = NULL;

  /**
   * Additional operations that do not depend on a request.
   *
   * @var \Drupal\Core\Render\Hypermedia\Operations\HtmxOperationInterface[]
   */
  protected array $additionalOperations = [];

  public function __construct(
    public readonly HtmxAttribute $attributes = new HtmxAttribute(),
    public readonly HtmxHeaderInterface $headers = new HtmxResponseHeaders(),
  ) {}

  /**
   * {@inheritdoc}
   */
  public function attributes(): HtmxAttribute {
    return $this->attributes;
  }

  /**
   * {@inheritdoc}
   */
  public function headers(): HtmxHeaderInterface {
    return $this->headers;
  }

  /**
   * {@inheritdoc}
   */
  public function getCombinedAttributes(array|HtmlAttributeInterface $attributes): HtmlAttributeInterface|array {
    return AttributeHelper::mergeCollections($attributes, $this->attributes);
  }

  /**
   * {@inheritdoc}
   */
  public function getCombinedHeaders(array $headers): array {
    return NestedArray::mergeDeep($headers, $this->headers->toArray());
  }

  /**
   * {@inheritdoc}
   */
  public function merge(HtmxInterface $htmx): HtmxInterface {
    $this->attributes->merge($htmx->attributes());
    $this->headers->merge($htmx->headers());
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function setRequestOperation(HtmxRequestOperationInterface $operation): HtmxInterface {
    $this->requestOperation = $operation;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function setAdditionalOperation(HtmxOperationInterface $operation): HtmxInterface {
    if ($operation instanceof HtmxRequestOperationInterface) {
      throw new \ValueError('Htmx::setRequestOperation() must be used to add HtmxRequestOperationInterface operations');
    }
    $this->additionalOperations[] = $operation;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function hasOperations(): bool {
    return $this->requestOperation instanceof HtmxRequestOperationInterface
    || count($this->additionalOperations) !== 0;
  }

  /**
   * {@inheritdoc}
   */
  public function processOperations(): void {
    if ($this->hasOperations() === FALSE) {
      return;
    }
    $operations = [];
    if (count($this->additionalOperations) !== 0) {
      $operations = $this->additionalOperations;
    }
    if ($this->requestOperation instanceof HtmxRequestOperationInterface) {
      array_unshift($operations, $this->requestOperation);
    }
    foreach ($operations as $operation) {
      $operation->setProperties($this);
    }
  }

Remaining tasks

Implement and improve the proposed data object.

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

📌 Task
Status

Active

Version

11.0 🔥

Component

render system

Created by

🇺🇸United States fathershawn New York

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @fathershawn
  • Comment 24 days ago →
    🇺🇸United States fathershawn New York
  • Comment 24 days ago →
    🇺🇸United States fathershawn New York
  • Comment 22 days ago →
    🇺🇸United States fathershawn New York

    I had a conversation in Slack with @cilefen about how much we should present an abstract interface to the rest of the system and keep the HTMX implementation interface encapsulated. This alternate architecture would argue that we should name the facade class Ajax as that is the concept we are implementing. We would not provide direct access to the HtmxAttribute and HtmxHeader subsystems. The means of altering these subsystems would be to use an operation.

    Such an architecture only exposes HTMX concepts to developers that need to create a combination of attributes and headers that is not available as an operation. In that case, the developer would create a new operation to encapsulate that combination. Of course such a developer could forsake the facade altogether and deal with the attribute and header subsystem directly.

    This idea could be take further in 📌 Define and process an #htmx render array key Active and rather than define a new render array key, only add a new callback. The existing ajax callback would make an early return if the #ajax key did not point to an array and similarly the new callback if it did not point to an instance of the facade.

    What is the right architecture?

  • Comment 15 days ago →
    🇬🇧United Kingdom catch

    iirc the original reason to have separate #ajax and #htmx render array keys was so that it would be easy to track converting from one to the other and eventually deprecating #ajax.

    If we did something like this:

    The existing ajax callback would make an early return if the #ajax key did not point to an array and similarly the new callback if it did not point to an instance of the facade.

    Then presumably we could also issue deprecations for the old syntax that way. So as long as there's a way to clearly identify when which system we're using, then it comes down to what we want the eventual API to be like. I don't currently have a strong opinion between adding new things to #ajax before removing old things from #ajax, vs. adding #htmx in parallel and then eventually removing #ajax.

    If there are ways to consolidate/reduce the list of AJAX commands that's great, the main thing is we need clear instructions for how to convert specific things from one to the other, even if it's no longer a 1-1 conversion.

  • Comment 15 days ago →
    🇺🇸United States fathershawn New York

    Thank you @catch. I wanted to layout the concerns expressed to me, and I'm comfortable with our original course. I think it is cleaner to create and transition to a parallel system. The HtmxInterface that I propose in the issue summary offers two paths for a developer.

    A developer does not need to know anything about how HTMX works. Choosing from a defined set of operations, such as Replace or Insert, the developer adds the required data to the operation and inserts it into the Htmx object.

    Alternatively, a developer can dive completely into the world of HTMX using the attribute and header subsystem objects that are part of the Htmx object. I guess there is also a third path which is to create their own implementation of HtmxOperationInterface to package these into something reusable.

    This offers both simplicity and power in something that I think is straightforward to manage. Creating all the operations will be our final task in the initiative. I'm confident that we can offer a migration guide that maps ajax commands to htmx operations.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024