feat(twig): implements stimulus_action() and stimulus_target() Twig functions, close #119

[Kocal]

Hi 👋

This PR is a proposal for #119, which adds stimulus_action() and stimulus_target() Twig functions.

stimulus_action() can be a bit hard to use because it supports many syntaxes, since Stimulus allows to use multiple actions in a single data-action attribute and we should takes care of the default event:

• stimulus_action('controller', 'method')
• a custom event: stimulus_action('controller', 'method', 'event)
• multiple controllers/actions:

{{ stimulus_action({
  'controller': 'method',
  'controller-2': ['method', 'method2'],
  'controller-3': {'click': 'onClick'},
  'controller-4': ['method', {'click': 'onClick'}, {'window@resize': 'onWindowResize'}],
}) }}

For stimulus_target:

• stimulus_target('controller', 'target')
• stimulus_target('controller', 'target1 target2'), Stimulus allows multiple targets
• stimulus_target({ 'controller1': 'target', 'controller2': 'target2 target3' }), array syntax

Usage:

<div {{ stimulus_controller('foo') }}>
  <div {{ stimulus_target('foo', 'myTarget') }}></div>
  <!-- <div data-foo-target="myTarget"></div> -->

  <div {{ stimulus_target('foo', 'myTarget mySecondTarget') }}></div>
  <!-- <div data-foo-target="myTarget mySecondTarget"></div> -->

  <div {{ stimulus_target({ 'foo': 'myTarget', 'bar': 'anotherTarget' }) }}></div>
  <!-- <div data-foo-target="myTarget" data-bar-target="anotherTarget"></div> -->

  {# Listen to default event and call "onClick" #}
  <a {{ stimulus_action('foo', 'onClick') }}>A link</a>
  <!-- <div data-action="foo#onClick">A link</a> -->

  {# Listen to event "click" and call "onClick" #}
  <a {{ stimulus_action('foo', 'onClick', 'click') }}>A Link</a>
  <!-- <div data-action="click->foo#onClick">A link</a> -->

  {# Listen to default event, call "onClick" from "foo" controller and "onClick" + "onSomethingElse" from "bar" controller #}
  <a {{ stimulus_action({
    'foo': 'onClick', 
    'bar': ['onClick', 'onSomethingElse']
  }) }}>A link</a>
  <!-- <div data-action="click->foo#onClick bar#onClick bar#onSomethingElse">A div</div> -->

  {# It is possible to pass a map, here "bar#onWindowResize" will be called on "window@resize" #}
  <div {{ stimulus_action({
    'foo': 'onClick', 
    'bar': ['onClick', {'window@resize': 'onWindowResize'}]
  }) }}>A div</a>
  <!-- <div data-action="foo#onClick bar#onClick window@resize->bar#onWindowResize">A div</div> -->
</div>

WDYT? Thanks!

---

For #119 (comment), I think it should belongs to another PR.

[moismailzai]

This looks good to me, just a few thoughts!

[moismailzai]

Overall the proposed syntax / documentation / implementation looks good to me. Seeing some duplicated logic in the methods but I think there may be some more work done in here (eg. #123) so maybe not a good idea to start consolidating logic yet. +1 from me.

[weaverryan]

I like this a lot! The super advanced syntaxes are ugly, but logical - and they will be rarely used. The simple syntax is... nice and simple :). Good work!

[weaverryan]

Don't forget to expose these new functions up in getFunctions() ;)

[Kocal]

OMG yes 😱

I totally forgot about them, usually I write tests for Twig Extensions by creating a fake loader and doing assertions on $twig->render() This way I can test the extension and its integration with Twig.

Thanks! 😄

[Kocal]

Friendly ping @weaverryan @tgalopin

Thanks!

[weaverryan]

As I don't see any other feedback, I'm going to merge this. Thanks @Kocal! But... would you mind opening a PR to the README to document these? I'd like to have that before we release :)

[Kocal]

Thanks @weaverryan, I'm on it!

[Kocal]

Opened at #125