Better support for AlpineJS

[JuroOravec]

Description

In my project, we use Django + AlpineJS, I've made a few changes that allow me to pass AlpineJS bindings through components more intuitively. Basically it's the same concept as Vue's passthrough/fallthrough attributes.

So I can pass AlpineJS syntax like @click.stop to my Django components:

{% component "icon"
  icon="outline_trash"
  @click.stop="$dispatch('user_delete', { role })"
%}{% endcomponent %}

Whereas the icon component looks roughly something like this:

<div {{ attrs }}>
    <span>
        <svg ...>
        {% for path in icon_paths %}
          <path stroke-linecap="round" stroke-linejoin="round" d="{{ path }}" />
        {% endfor %}
        </svg>

        {% slot "content" default %}{% endslot %}
    </span>
</div>

3 things happen behind the scene in the example above:

1. I can pass component kwargs with special characters like @, ., -. So @click.stop is a valid key.
2. In my icon component, I check the names of all args and kwargs of the get_context_data() method. All UNKNOWN kwargs get collected into an attrs variable.
3. I assign the attrs variable to the top level <div>, so

   <div {{ attrs }}>
   ...

   ends up rendered as

   <div @click.stop="$dispatch('user_delete', { role })">
   ...

What do you think?

Notes

1. For allowing extra special characters in kwargs, the inspiration comes from django-slippers, which allows @.:- in kwargs (see implementation). I suggest to add also # to the mix.

2. With recent introduction of component_vars.is_filled, the attrs should be probably accessed via component_vars.attrs or component_vars.fallthrough_attrs.

3. Similarly to Vue, it should be the component class that decides if it wants to use the fallthrough attrs feature or not. I suggest an opt-in, so that, by default, user gets an error if they pass in unknown args/kwargs.

   class MyComp(component.Component):
   	template_name = "abc.html"
   	fallthrough_attrs = True

   NOTE: While Vue sets this via inheritAttrs, I think fallthrough_attrs is more self-explanatory. (and googling for fallthrough attrs also gets you to the Vue docs)

4. This is the logic that extracts the "fallthrough attrs" from kwargs passed to get_context_data()

   argspec = inspect.getfullargspec(self.get_context_data)
   # NOTE: I use keyword-only args in my project, might want to add argspec.kwargs?
   known_prop_names = set([*argspec.args, *argspec.kwonlyargs])
   
   passthrough_props = {
       k: v for k, v in kwargs.items() if k not in known_prop_names
   }

   So if I define get_context_data as:

   def get_context_data(self,  name, age=None, city=None):
   	return {...}

   then known_prop_names is ["name", "age", "city"]

   and so if I render the component like so:

   {% component "my_comp" name="one" dogs_count=13 %}
   {% endcomponent %}

   then name IS recognized, but dogs_count is NOT recognized. So component_vars.fallthrough_attrs gets populated with {"dogs_count": 13}

5. This bit from above:

   argspec = inspect.getfullargspec(self.get_context_data)
   known_prop_names = set([*argspec.args, *argspec.kwonlyargs])

   could be done at class definition (__new__) so that we don't have to call inspect.getfullargspec on every render.

Implementation

Implementation consists of 2 sub-features:

1. Allow to pass kwargs with special characters
2. Implementing the "fallthrough attrs" on the Component class

[tissieres]

For reference, django-web-components supports these characters: @:_-. and also has a nice way to handle attributes in general.

[EmilStenstrom]

I think this is a very valid use-case, passing things like @click.stop="$dispatch('user_delete', { role })" through a component.

I'm not sure about the "invalid attribute pass-through to attrs" solution though. I see that slippers and django-web-components have solved it this way. But I don't like that we're adding "magic" that transforms @click.stop to attrs (or component_vars.attrs) without it being explicit in the code. People reading the code will likely not understand it without going to the docs, which I'd like to avoid if possible.

An easier way to follow this would be if attrs was right there as an attribute:

{% component "icon"
  icon="outline_trash"
  attrs="@click.stop=\"$dispatch('user_delete', { role })\""
%}{% endcomponent %}

(this would necessitate we don't mess up escaped quotes...)

... but I guess that limits the usability when you want to add more than one attribute. Maybe we could solve this with newlines?

{% component "icon"
  icon="outline_trash"
  attrs="
      @click.stop=\"$dispatch('user_delete', { role })\"
      x-data=\"{ open: false }\"
  "
%}{% endcomponent %}

or with triple quotes?

{% component "icon"
  icon="outline_trash"
  attrs="""
      @click.stop="$dispatch('user_delete', { role })"
      x-data="{ open: false }"
  """
%}{% endcomponent %}

[dylanjcastillo]

I also like the colon version more!

[EmilStenstrom]

I like having attrs:param=x as an API because it's explicit, but I must say it doesn't look very elegant.

Another option: What if we just started passing through variables to the get_context_data without the need for attrs at all?

{% component "icon"
  icon="outline_trash"
  @click.stop="$dispatch('user_delete', { role })"
  x-data="{ open: false }"
%}{% endcomponent %}

Then in your get_context_data in attrs (or some other variable) you would do:

def get_context_data(**kwargs):
    return {"attrs": self.kwargs_to_html_attr(kwargs, "@click.stop", "x-data")}

[tissieres]

Merging attributes is also quite useful, especially when using CSS utility classes. It could be specified as an option in the component class for example.

[JuroOravec]

@tissieres on the topic of merging attributes, what do you think of how it was done in django-web-components?

[tissieres]

I like having a way to specify that I want to merge some attributes with those already specified in the component template, but I don't like the fact that the class attribute is not handled as the other attributes in django-web-components. Using a template tag does not seem appropriate but I was not able to propose a better idea in this discussion.

[EmilStenstrom]

So, let summarize the different options:

A) Magic attrs (similar to Vue and django-web-components)

• component.fallthrough_attrs = True
• {% component @click.stop="..." x-data="..." %}
• <div {{ attrs }}>

B) Allow special symbols and handle everything in get_context_data

• {% component @click.stop="..." x-data="..." %}
• def get_context_data(**kwargs): return {"attrs": kwargs["@click.stop"] + " " + kwargs["x-data"]}
• <div {{ attrs }}>

C) Namespaced parameters

• {% component attrs:@click.stop="..." attrs:x-data="..." %}
• def get_context_data(**attrs): return {"attrs": attrs}
• <div {{ attrs }}>

D) Triple quoted parameters (no special chars in params needed)

• {% component attrs="""@click.stop="..." \n x-data="..." """ %}
• def get_context_data(attrs): return {"attrs": attrs}
• <div {{ attrs }}>

Did I miss any?

[tissieres]

No, I was referring to the situation where the template already have an attribute with the same name and we want to merge the value given in the component with those. For example the template is <div class="bg-red-100"> and the component {% component "foobar" merge_attrs:class="text-xl" %}, then instead of <div class="text-xl">, we would have <div class="text-xl bg-red-100">.

[JuroOravec]

In case of merging attributes, I think it makes most sense to think about this from the perspective of a component author (as opposed to component user), so I'm leaning towards taking a similar approach to django-web-components. That is, merging would be done with a template tag that accepts a dict of our attributes, and any other extra attributes as defaults. class attributes are merged, while other attributes would be overriden.

The reason for this is that, as component author:

• I may NEED for a component to have some specific CSS class(es), maybe because I use it for styling, or there's some logic associated with it. So while I want to allow component users to supply their own CSS classes, I do NOT want to let them override mine:

   <div class="my_comp EXTERNAL_CLASSES"> <!-- I'm OK with adding component user's classes -->
   <div class="EXTERNAL_CLASSES"> <!-- I'm NOT OK with component user's classes overriding my internal ones -->

  CSS classes are a bit of a special case, because many popular frameworks set the styling via them (e.g. Tailwind, Bootstrap, etc...). So if component user is trying to modify styling of the underlying HTML tag, there's a good chance they will use the class attribute for that.

  • We could take similar approach for the style attribute, as that may be used frequently too. But generally, a prefered approach is to move the styling into a CSS, so there's once again only the class attribute on the HTML tag that decides on the styling.

• For every other HTML attribute, the case is the opposite - there's a low chance that the user will want to override the HTML attributes that I've set. But if they do, they can do so, but it's their responsibility. Meaning that, as component author, I will supply my value for a certain attribute, but I do not think too hard about trying to merge or resolve the values. The HTML attribute API surface is huge, my time is limited, and it has minimal impact. So letting user override the values is a good enough solution.

For context, the perspective of component user is:

• I want to supply my own HTML attributes, so I can customize styling, event handling, or other behavior.

  • NOTE: As @tissieres pointed out there may be cases where they would want to forcefully override the class attribute instead of merging it, to achieve a specific styling. So they would achieve the latter case in:

     <div class="my_comp EXTERNAL_CLASSES">
     <div class="EXTERNAL_CLASSES">

    However, as said earlier, this could break the component. So instead, I believe it should be up to the component author to make the component accept some kind of input that, when supplied, would render <div class="EXTERNAL_CLASSES"> instead of <div class="my_comp EXTERNAL_CLASSES">

    So long story short, IMO component user should NOT use merge_attrs:. Instead, the component should be refactored. Ofc, there may be a need for something similar for when component user does not have access to the component source code (e.g. 3rd party lib). But I would leave that for later iteration.

[EmilStenstrom]

See ticket here: #488

[JuroOravec]

Awesome!

Btw, could I get a quick review on this one to clear it out of the way? #482

UPDATE: Merged, thanks!

[JuroOravec]

Hey all, I made a first go at the feature at #491 (WIP), please let me what you think!

[JuroOravec]

Hi all, this feature has just been released as v0.74 🎉 See the README section "Rendering HTML attributes"