This functionality is moved to #3524030: Provide a factory object for HTMX headers and attributes
Problem/Motivation
HTMX is designed as an extension of HTML. It is therefore a declarative markup system that uses attributes.
<button hx-get="/contacts/1" hx-target="#contact-ui"> <1>
Fetch Contact
</button>
Instead, we have declarative attributes much like the
hrefattribute on anchor tags and theaction
attribute on form tags. Thehx-getattribute tells htmx:
“When the user clicks this button, issue aGETrequest to
/contacts/1.” Thehx-targetattribute tells
htmx: “When the response returns, take the resulting HTML and place it
into the element with the idcontact-ui.”
from Hypermedia Systems
HTMX is just as happy with data-hx-get and so we will maintain standard markup in our implementation.
HTMX uses over 30 such attributes. Expecting Drupal developers to learn all the names and data requirements of those attributes will make the Drupal learning curve even more challenging.
Proposed resolution
Create a class with methods to abstract the details of these attributes. These methods would both document and collect the necessary data. Another way of understanding this class is to regard the attributes of HTMX and their expected data as an interface. The HtmxAttribute class then implements that interface.
This class may be used directly by developers who have, or wish to acquire, knowledge about how HTMX works. It may also power higher level classes which add behavior or accomplish tasks for developers without requiring them to know how it works.
Our current HTML Attribute object does not implement an interface. Create a shared interface that can identify Attribute and HtmxAttribute objects and move shared methods to a trait or traits.
Alter \Drupal\Core\Template\AttributeHelper::mergeCollections and Attribute::merge() to operate on the interface.
Support the HTMX architecture that some attribute values are either JSON or a concatenation of a string to JSON.
- Create AttributeJson
A developer could use this object and merge it into an Attributes object attached to a render array. The primary use of this object in PHP is to manage this data composed into an Htmx object that will be keyed to a render array property and processed in the rendering pipeline. See #3524030: Provide a factory object for HTMX headers and attributes. A developer could also use the provided twig function in a template to create an HtmxAttribute object, configure it with its methods, and place the object in the template to render the resulting attributes.
Remaining tasks
User interface changes
None
Introduced terminology
None
API changes
None by policy. HtmlAttributeInterface abstracts features of \Drupal\Core\Template\Attribute that are shared with the new HTMX attribute class.
Data model changes
Two new attribute value objects
Release notes snippet
| Comment | File | Size | Author |
|---|---|---|---|
| #9 | 3523725-nr-bot.txt | 5.02 KB | needs-review-queue-bot |
Issue fork drupal-3523725
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
- 3523725-htmx-attributes
changes, plain diff MR !12097
Comments
Comment #3
fathershawnAll tests green
Comment #4
fathershawnMissed bringing over the Twig function
Comment #5
fathershawnComment #6
fathershawnNew test passes.
Comment #7
fathershawnComment #8
fathershawnComment #9
needs-review-queue-bot commentedThe Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".
This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.
Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.
Comment #10
fathershawnComment #11
fathershawnComment #12
fathershawnComment #13
fathershawnApplied a suggestion and will be refactoring some improvements inspired by @larowan review. A maintainer should add him to the credits.
Comment #14
fathershawnComment #15
fathershawnAll tests green.
There are two open questions:
AttributeJsonAttributeHtmxString.Comment #16
nod_I don't understand why we need the single quote. If you add a JSON::encode(), to the process assets MR it just works.
It doesn't matter that the source html doesn't look pretty. Once it's in the JS it's the correct value.
Comment #17
fathershawnThat's a great question! I didn't think it would but I didn't try. I simply went from the example syntax at htmx.org but that's clearly written for hand-rolling the html. I'll repeat the experiment with an attribute value selector and remove the complexity. Simpler is better!!
Comment #18
fathershawnConfirmed! I can now remove a trait and a class - thank you @nod_ :)
I altered the render arrays in the test module to
Which produces
data-hx-target="div[data-drupal-htmx-target="insert-here"]"through the standard string attribute. HTMX worked as expected.Comment #19
fathershawnAll threads resolved - all tests passing :)
Comment #20
fathershawnWe agreed in Slack to pause on this builder while we work on #3526267: Remove core/drupal.ajax dependency from big_pipe/big_pipe using attributes that are "hand-rolled."
Comment #21
fathershawnComing back to this now - we needed the htmx javascript API in #3526267: Remove core/drupal.ajax dependency from big_pipe/big_pipe but not attributes.
Comment #22
fathershawnComment #23
fathershawnComment #24
fathershawnComment #25
fathershawnTagged
\Drupal\Core\Template\HtmlAttributeInterfaceas @internal as that seems consistent with the policy on Attribute class internals.Comment #26
fathershawnDiscussed and agreed in Slack that a single change record and release note will cover:
Comment #27
fathershawnBased on #26 and the description of the tag (A change record needs to be drafted before an issue is committed.) I'm removing the CR tag from this issue as these are sequential dependencies and the tag belongs on final component.
Comment #28
fathershawnReading through the governance doc I am marking this for framework manager review since it is blocking other work.
Comment #29
fathershawnI brought the summary up to date with the code. We have 5 unresolved comment threads on the MR. Most open threads have a response.
Following a comment from @catch I updated the code in
\Drupal\Core\Template\HtmxAttributefor:to pass in and instance of
CacheableDependencyInterfaceand collect the cacheable metadata emitted by the Url object.There is an open question about the advisability of adding return types in
\Drupal\Core\Template\Attribute. I understand this class to be internal by policy but maybe that's not right?The other 3 open threads all have answers.
I have time to move this project forward to let's get this to RTBC so it can be committed and work can start on the next layer!!
Comment #30
fathershawn@catch can you give guidance about adding return types to
\Drupal\Core\Template\Attribute?I hit a name collision on the BC policy with the Attribute name (As you and @nicxvan noted that was for PHP attributes). But it also seems to be permitted with these:
PHP and JavaScript classes
In general, only interfaces can be relied on as the public API. With the exception of base classes, developers should generally assume that implementations of classes will change, and that they should not inherit from classes in the system, or be prepared to update code for changes if they do. See also more specific notes below.
Public methods not specified in an interface
Public methods on a class that aren't on a corresponding interface are considered @internal.
We are adding an interface in this issue, but there no interface for this class now. @larowan seemed to think it was okay here: https://git.drupalcode.org/project/drupal/-/merge_requests/12097#note_51...
Comment #31
needs-review-queue-bot commentedThe Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".
This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.
Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.
Comment #32
fathershawnComment #33
fathershawnThank you @phenaproxima for improving the code with your questions and suggestions. I've resolved all comments with either updates or answers except those related to return types (see #30). All tests are passing.
Comment #34
catchGiven @larowlan's:
and https://www.drupal.org/about/core/policies/core-change-policies/bc-polic... I think we're OK to add the return type hints to
Attributehere with a change record. It's allowed under the bc policy, and we can be fairly confident it won't break any existing code.Comment #35
nicxvan commentedOk that was tedious, but I clicked on all documentation links and confirmed they align except the ones that I have suggestions for.
I also reviewed all changes and have been following. I think this is ready assuming the three suggestions are accepted and tests pass.
Only remaining substantial question I have is where does sanitization happen?
I see some attributes do check the expected value is a boolean, but I don't see anything else, is that all handled upstream of this?
Comment #36
fathershawn@nicxvan First, thank you for so carefully checking the tedious mundane details! Suggestions committed and test updated for the one method name fix.
Sanitization happens in the attribute value object's
::__toStringmethod. They all extend AttributeValueBase which sanitizes the name property. We addAttributeJsonin this MR, and follow this pattern.Comment #37
nicxvan commentedI think this is ready, the extensive feedback has been addressed!
Comment #38
fathershawnComment #39
fathershawn@catch @larowlan @nod_ A CacheableMetadata parameter was added to methods that take a URL based on feedback. This complicates calling these methods within Twig as the caching has already bubbled.
For example:
Does this change the utility of a providing the attribute object within Twig? Should we drop that Twig function from this MR?
Comment #40
nod_I'd drop it. We can always add a followup to add it and we can figure out the problems without holding the working part of the MR
Comment #41
fathershawnThanks @nod_ !!
Removed the twig function from this issue's MR and the change record. It is extra.
CR is updated with the full picture of how all 4 issue changes work together.
Comment #42
nod_few cosmetic feedbacks
Comment #44
fathershawnSuggested changes made.
Comment #45
fathershawnUnrelated toolbar tests failing. Rebasing onto HEAD.
Comment #46
fathershawnRequired tests passing. The php 8.5 test seems to be failing in general due to widespread deprecations.
Comment #47
nicxvan commentedI think this is rtbc, I reviewed the comments from nod and the two commits since my initial rtbc.
Comment #48
nod_We need the empty URL thing for the post/patch/delete/put methods too
Comment #49
fathershawnRe: #48 - okay. It's not documented at
as it is for get. Did you find support for all five in the code @nod_? It will make our code simpler so I'm going ahead. It would be good to document in a comment here for future reference with a link to their code or other documentation.
Comment #50
fathershawnMade all five http verb methods operate the same way.
Comment #51
fathershawnAll tests passing
Comment #52
fathershawnThe empty URL behavior discussed in #48 & #49 is in the
issueAjaxRequestfunction ofhtmx.jsAs of this note this can be seen at https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js#L4426Turns out this goes back to RFC 2396 on the URI specification co-authored by Tim Berners-Lee in 1998 no less!
Comment #53
nod_We've had a discussion on slack with @fathershawn about this.
The current approach of the MR is not ideal:
\Drupal\Core\TemplatenamespaceThankfully we can fix it by moving things around:
\Drupal\Core\HtmxnamespaceCacheableMetadata, with anapplyTo()andcreateFromRenderArray(we need this to unserialize the json attributes) methods that we call on a render array to augment it.#attributeskey, and json_encode what needs to be json_encoded and let the existing code handle the attribute renderingComment #54
nicxvan commentedGreat catch!
Is there a test we can add showing this, or does it need implementation for that?
Comment #55
fathershawnComment #57
fathershawnComment #60
nod_@nicxvan not sure how we'd test this reliably. Maybe check if there are any AttributeValueBase in the #attributes array at the preprocess step? but then which render array do we test? or maybe a bunch of asserts?
@fathershawn: now that you're a maintainer you can give credit, credits are given for closed issues now too :)
Comment #61
pdureau commentedI am not familiar about the
applyTomethod from CacheableMetadata, is it resolved late? Ideally, we keep the HTML values separated as long as possible and we move them to#attributesjust before rendering.We are working on at least on two other features with attributes values which must be set and kept distinct from
#attributesbut merged to#attributesbefore rendering: #3517033: Add a Style API and #3531854: Add a Design Tokens & CSS variables API. So a generic behavior and/or standard "way" may be useful.