feat: Publish & Document Jinja Macros

[jmuzina]

Done

Feature branch PR for publishing & documenting Jinja macros

• Document hero macro #5325
• Add macros to npm package; rename macros to include vf_ namespace #5329
• Add macro install instructions to docs pages #5330
• Show Jinja Macro usage in pattern code snippets #5321
• Document tiered list macro #5351

QA

• See QA instructions on the above PRs if you want to re-QA the feature PR.

Check if PR is ready for release

If this PR contains Vanilla SCSS code changes, it should contain the following changes to make sure it's ready for the release:

• PR should have one of the following labels to automatically categorise it in release notes:
  • Feature 🎁, Breaking Change 💣, Bug 🐛, Documentation 📝, Maintenance 🔨.
• Vanilla version in package.json should be updated relative to the most recent release, following semver convention:
  • if CSS class names are not changed it can be bugfix release (x.x.X)
  • if CSS class names are changed/added/removed it should be minor version (x.X.0)
  • see the wiki for more details
• Any changes to component class names (new patterns, variants, removed or added features) should be listed on the what's new page.

[webteam-app]

Demo

Jenkins

demos.haus

[bartaz]

Looks good overall.

One downside is that the start of the page is very table-heavy, full of props you need to parse (before you even see what the pattern actually looks like).

I'd personally suggest moving the "Jinja Macro" section to the bottom of the page. I know we want devs to have access to this spec, but to me it seems like having the examples first would give a better overview of the component. They are gonna copy the snippet in 90% of cases anyway. Then, if they want to have a look at the reference, they can find it on the page.

Thoughts?

[jmuzina]

One downside is that the start of the page is very table-heavy, full of props you need to parse (before you even see what the pattern actually looks like). I'd personally suggest moving the "Jinja Macro" section to the bottom of the page. I know we want devs to have access to this spec, but to me it seems like having the examples first would give a better overview of the component. They are gonna copy the snippet in 90% of cases anyway. Then, if they want to have a look at the reference, they can find it on the page. Thoughts?

@bartaz Good point. I've moved it to just above the "import" section as I feel it might be a bit disjointed to read examples -> import instructions -> Jinja API docs

We could also move the Jinja API docs to their own tab / sub-page, any thoughts on putting it at bottom of page vs on a separate sub-page? @bartaz @pastelcyborg @advl

[pastelcyborg]

I'd think moving the Jinja API docs to a separate tab would fall under the decision we made about moving the Jinja examples/code samples to a separate tab - that is, we decided not to do that because it would increase complexity and make the docs more convoluted.

I think the structure as represented right now is acceptable. The only change I would possibly make is moving the macro API docs after the Jinja import instructions, but it's really not a big deal either way.

[apollo13]

Hi, this looks interesting. The slot checking in the macro calling is a bit ugly imo -- the following jinja issue has an alternative that is nicer I think: pallets/jinja#482 (comment)

This would kinda look like this:

{% macro vf_hero(
  title_text,
  subtitle_text='',
  layout="fallback",
  is_split_on_medium=false
) -%}
  {% set has_subtitle = subtitle|trim|length > 0 %}
  {% set has_subtitle = subtitle_text|trim|length > 0 %}
  {% set description_content = caller(description=True) if 'description' in caller.arguments else '' %}
  {% set cta_content = caller(cta=True) if 'cta' in caller.arguments else '' %}

(see the last lines) and then used in call like this:

{% call(description, cta) vf_hero(…) %}
{% if description %}
…
{% else if cta %}
…
{% endif %}
{% endif %}

Personally I think this is more readable.

[bartaz]

LGTM

[jmuzina]

Hi, this looks interesting. The slot checking in the macro calling is a bit ugly imo -- the following jinja issue has an alternative that is nicer I think: pallets/jinja#482 (comment)

Hi @apollo13 , thanks for your feedback! We've discussed it as a team and decided to stick with the current approach, at least for now - we've established this style as a team standard for this opening round of macros, but will keep it in mind for the future. It's nice to have some feedback from someone who is so familiar with these!

[apollo13]

Hi Julie, ok fine with me. The good thing is that if you decide to change it in the future you can support both syntaxes in parallel during a deprecation period. So it is not an end-of-world type decision.

…

On Thu, Oct 3, 2024, at 17:55, Julie Muzina wrote: > Hi, this looks interesting. The slot checking in the macro calling is a bit ugly imo -- the following jinja issue has an alternative that is nicer I think: pallets/jinja#482 (comment) <pallets/jinja#482 (comment)> > Hi @apollo13 <https://github.com/apollo13> , thanks for your feedback! We've discussed it as a team and decided to stick with the current approach, at least for now - we've established this style as a team standard for this opening round of macros, but will keep it in mind for the future. It's nice to have some feedback from someone who is so familiar with these! — Reply to this email directly, view it on GitHub <#5342 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAT5C363IKB4U5ZBLCKT33ZZVSH5AVCNFSM6AAAAABOBTK2I6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOJRG43TENBQG4>. You are receiving this because you were mentioned.Message ID: ***@***.***>