Tag Params

[mlrawlings]

New Feature

Description

Use the parentheses after the tag name to declare parameters that are available inside the tag body. The values of these parameters will be provided by the tag on which they are declared.

<mouse-position(mouse)>
  Mouse is at ${mouse.x}, ${mouse.y}.
</mouse-position>

Parameters should work like JS parameters and should support destructuring, etc.

<mouse-position({ x, y })>
  Mouse is at ${x}, ${y}.
</mouse-position>

Why

Currently a person creating a tag that needs to render its body and pass parameters has to create a transform of some sort to append these parameters to the renderBody function. Marko needs a standard way to introduce parameters to the body of a tag.

Marko already has tags that introduce variables into their body using the parenthesis that follow the tag name, so this maintains consistency with that approach:

<await(user from userPromise)>
   The user is ${user.name}!
</await>

<for(item in array)>
  <li>${item.id}</li>
</for>

Possible Implementation & Open Questions

This new behavior for the parentheses after the tag name conflicts with the current default for the parenthesis, which is for them to be considered arguments to pass data into the tag. This is being addressed in #878.

Because of the conflict, this will be implemented behind a feature flag for Marko 4. To enable the feature, you will set a flag in the marko-tag.json for a tag that needs to be able to receive parameters in its body.

{
  "feature-flags": [
    "tag-parameters"
  ]
}

The user of the tag will not have to do anything special. In Marko 5 (whenever that is) this behavior will be enabled by default.

[patrick-steele-idem]

Earlier discussion can be found in the following GitHub issue: #656

[mlrawlings]

Implemented in #1076