From 6c81e692f645884bbc0580a776c4a64c5660825c Mon Sep 17 00:00:00 2001 From: Julie Muzina Date: Wed, 4 Sep 2024 08:37:17 -0400 Subject: [PATCH] Document hero macro (#5325) * Add macro install instructions to docs pages (#5330) * Update building-vanilla.md * Update pattern docs * Roll back pattern docs * Update building-vanilla.md * Add macros directory to published files * Rename hero macro * Rename tiered list macro * Update releases.yml * End hero title and subtitle params with _text per new naming convention * Add html block comments to hero macro * Add hero macro docn * Add Hero macro import instructions * Add link to @pastelcyborg jinja macros installation guide * Fix hero title_text being renamed from rebase * Adjust jinja parameters column order * lowercase param types * adjust slots column ordering * Adjust slots is required per code review * Markup params table * Markup slots table * parameter & slot tables horizontally scroll rather than using mobile cards * Param/slot table widths set by percentage * More consistent whitespace control chars around jinja macro import * Revise hero element/description table word choice around title/substitle/description * comma-separated string with line breaks for hero layout type options * Update is required column by @bartaz Co-authored-by: Bartek Szopka <83575+bartaz@users.noreply.github.com> * Code review suggestions from @bartaz Co-authored-by: Bartek Szopka <83575+bartaz@users.noreply.github.com> --------- Co-authored-by: pastelcyborg <168636120+pastelcyborg@users.noreply.github.com> Co-authored-by: Bartek Szopka <83575+bartaz@users.noreply.github.com> --- templates/_macros/vf_hero.jinja | 25 ++-- .../hero/hero-50-50-full-width-image.html | 4 +- .../hero/hero-50-50-split-on-medium.html | 4 +- .../examples/patterns/hero/hero-50-50.html | 4 +- .../examples/patterns/hero/hero-75-25.html | 4 +- .../examples/patterns/hero/hero-fallback.html | 4 +- .../hero/hero-signpost-full-width-image.html | 4 +- .../examples/patterns/hero/hero-signpost.html | 4 +- templates/docs/patterns/hero/index.md | 114 +++++++++++++++++- 9 files changed, 141 insertions(+), 26 deletions(-) diff --git a/templates/_macros/vf_hero.jinja b/templates/_macros/vf_hero.jinja index a0018c211..3b4847455 100644 --- a/templates/_macros/vf_hero.jinja +++ b/templates/_macros/vf_hero.jinja @@ -1,6 +1,6 @@ # Params -# title: Hero title text (required) -# subtitle: Hero subtitle text +# title_text: Hero title text (required) +# subtitle_text: Hero subtitle text # layout: layout of hero section. Options are '50/50', '50/50-full-width-image', '75/25', '25/75', 'fallback' # is_split_on_medium: whether the layout is split on tablet in 50/50, 25/75, and 75/25 layouts. # If false, the layout is stacked on tablet. @@ -11,12 +11,12 @@ # image: slot for image content # signpost_image: slot for signpost (left column) image content in 25/75 layout. Required for 25/75 layout. {% macro vf_hero( - title, - subtitle='', + 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') %} {% set has_description = description_content|trim|length > 0 %} {% set cta_content = caller('cta') %} @@ -80,22 +80,25 @@ {% set title_class = "u-no-margin--bottom" %} {%- endif -%} + {#- Only add a class attribute if needed -#} 0 %} class="{{ title_class }}"{% endif %}> - {{ title }} + {{ title_text }} {%- endmacro %} {%- macro _hero_subtitle_block() -%} {% if has_subtitle %} +

- {{ subtitle }} + {{ subtitle_text }}

{% endif %} {%- endmacro %} {%- macro _hero_cta_block() -%} {% if has_cta -%} +
{{ cta_content }}
@@ -104,6 +107,7 @@ {%- macro _hero_description_block() -%} {% if has_description %} +
{{ description_content }}
@@ -112,6 +116,7 @@ {%- macro _hero_signpost_image_block() -%} {% if layout == '25-75' and has_signpost_image -%} +
{{ signpost_image_content }}
@@ -130,12 +135,13 @@ {% endif -%}
- {%- if is_fallback %} + {%- if is_fallback -%}
{{- _hero_description_block() -}} {{ _hero_cta_block() -}}
{% if has_image -%} +
{{ image_content }}
@@ -151,6 +157,7 @@ {{- _hero_description_block() -}} {{- _hero_cta_block() -}}
+ {{ image_content -}} {% elif has_signpost_image %} {#- 25/75 Signpost layout -#} @@ -167,6 +174,7 @@ {% if has_image %} {#- Signpost with image is always full-width, so set it after the columns -#} + {{- image_content }} {% endif -%} {% else %} @@ -179,6 +187,7 @@ {{- _hero_cta_block() -}} {% if has_image -%} +
{{ image_content }}
diff --git a/templates/docs/examples/patterns/hero/hero-50-50-full-width-image.html b/templates/docs/examples/patterns/hero/hero-50-50-full-width-image.html index b9835fd99..ef18d3fbf 100644 --- a/templates/docs/examples/patterns/hero/hero-50-50-full-width-image.html +++ b/templates/docs/examples/patterns/hero/hero-50-50-full-width-image.html @@ -8,8 +8,8 @@ {% block content %} {% call(slot) vf_hero( - title='H1 - ideally one line, up to two', - subtitle='H2 placeholder - aim for one line, 2 is acceptable.', + title_text='H1 - ideally one line, up to two', + subtitle_text='H2 placeholder - aim for one line, 2 is acceptable.', layout='50/50-full-width-image' ) -%} {%- if slot == 'description' -%} diff --git a/templates/docs/examples/patterns/hero/hero-50-50-split-on-medium.html b/templates/docs/examples/patterns/hero/hero-50-50-split-on-medium.html index d455bde4b..27d483f23 100644 --- a/templates/docs/examples/patterns/hero/hero-50-50-split-on-medium.html +++ b/templates/docs/examples/patterns/hero/hero-50-50-split-on-medium.html @@ -8,8 +8,8 @@ {% block content %} {% call(slot) vf_hero( - title='H1 - ideally one line, up to two', - subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', + title_text='H1 - ideally one line, up to two', + subtitle_text='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', layout='50/50', is_split_on_medium=true ) -%} diff --git a/templates/docs/examples/patterns/hero/hero-50-50.html b/templates/docs/examples/patterns/hero/hero-50-50.html index 49a2e0727..b80299440 100644 --- a/templates/docs/examples/patterns/hero/hero-50-50.html +++ b/templates/docs/examples/patterns/hero/hero-50-50.html @@ -8,8 +8,8 @@ {% block content %} {% call(slot) vf_hero( - title='H1 - ideally one line, up to two', - subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', + title_text='H1 - ideally one line, up to two', + subtitle_text='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', layout='50/50' ) -%} {%- if slot == 'description' -%} diff --git a/templates/docs/examples/patterns/hero/hero-75-25.html b/templates/docs/examples/patterns/hero/hero-75-25.html index 0ff1c748d..04caa5430 100644 --- a/templates/docs/examples/patterns/hero/hero-75-25.html +++ b/templates/docs/examples/patterns/hero/hero-75-25.html @@ -7,8 +7,8 @@ {% set is_paper = true %} {% block content %} {% call(slot) vf_hero( - title='H1 - ideally one line, up to two', - subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', + title_text='H1 - ideally one line, up to two', + subtitle_text='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', layout='75/25', is_split_on_medium=true ) -%} diff --git a/templates/docs/examples/patterns/hero/hero-fallback.html b/templates/docs/examples/patterns/hero/hero-fallback.html index 126104e03..35e92ce1e 100644 --- a/templates/docs/examples/patterns/hero/hero-fallback.html +++ b/templates/docs/examples/patterns/hero/hero-fallback.html @@ -7,8 +7,8 @@ {% set is_paper = true %} {% block content %} {% call(slot) vf_hero( - title='H1 - ideally one line, up to two', - subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', + title_text='H1 - ideally one line, up to two', + subtitle_text='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', layout='fallback', is_split_on_medium=true ) -%} diff --git a/templates/docs/examples/patterns/hero/hero-signpost-full-width-image.html b/templates/docs/examples/patterns/hero/hero-signpost-full-width-image.html index b8787cd2d..b7bf12fe3 100644 --- a/templates/docs/examples/patterns/hero/hero-signpost-full-width-image.html +++ b/templates/docs/examples/patterns/hero/hero-signpost-full-width-image.html @@ -7,8 +7,8 @@ {% set is_paper = true %} {% block content %} {% call(slot) vf_hero( - title='H1 - ideally one line, up to two', - subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', + title_text='H1 - ideally one line, up to two', + subtitle_text='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', layout='25/75' ) -%} {%- if slot == 'signpost_image' -%} diff --git a/templates/docs/examples/patterns/hero/hero-signpost.html b/templates/docs/examples/patterns/hero/hero-signpost.html index b8c2a59e5..ba4eb6448 100644 --- a/templates/docs/examples/patterns/hero/hero-signpost.html +++ b/templates/docs/examples/patterns/hero/hero-signpost.html @@ -7,8 +7,8 @@ {% set is_paper = True %} {% block content %} {% call(slot) vf_hero( - title='H1 - ideally one line, up to two', - subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', + title_text='H1 - ideally one line, up to two', + subtitle_text='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph', layout='25/75' ) -%} {%- if slot == 'signpost_image' -%} diff --git a/templates/docs/patterns/hero/index.md b/templates/docs/patterns/hero/index.md index c5dea7452..e0bda1c51 100644 --- a/templates/docs/patterns/hero/index.md +++ b/templates/docs/patterns/hero/index.md @@ -17,12 +17,103 @@ The hero pattern is composed of the following elements: | Element | Description | | -------------------- | ------------------------------------------------------------------------ | -| Title (**required**) | h1 title text | -| Subtitle | h2 subtitle text | -| Description | p description text | +| Title (**required**) | Title text (to be placed in `h1` heading) | +| Subtitle | Subtitle text (using `h2` style) | +| Description | Description text (one or more paragraphs) | | Call to action block | [Call to action block](/docs/patterns/cta-block) beneath the description | | Image | Main hero visual | +## Jinja Macro + +### Parameters + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameIs requiredTypeDefaultDescription
layoutYes + One of: + '50/50', + '50/50-full-width-image', + '75/25', + '25/75', + 'fallback' + 'fallback'Choice of hero layout.
title_textYesstringN/Ah1 title text
subtitle_textNostringN/Ah2 subtitle text
is_split_on_mediumYesbooleanfalseWhether the layout is split on tablet-sized devices.
+
+ +### Slots + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameIs requiredDescription
descriptionNoParagraph-style content below the title and subtitle.
ctaYesContents of a Call to action block beneath the title and description.
imageYes, when layout='50/50-full-width-image'Image content.
signpost_imageYes, when layout='25/75'Small image (such as a logo) to place in the left column of the 25/75 Hero.
+
+ ## 50/50 ### 50/50 on large @@ -52,7 +143,8 @@ View example of the hero pattern in 50/50 that is split on medium and small The above hero layouts place the hero image in the right column by default. However, this is not suitable for very wide images. If you have a very wide image or otherwise want your image to take up the full hero width, place the title by itself in -the first column and place the image in a .p-image-container .is-cover at the same level as the grid columns. +the first column and place the image in a .p-image-container .is-cover at the same level as the grid +columns. This will make the image take up the full width of the hero.
@@ -101,5 +193,19 @@ View example of the hero pattern in fallback configuration ## Import +### Jinja Macro + +To import the Hero Jinja macro, copy the following import statement into your Jinja template. + +```jinja +{% raw -%} +{% from "_macros/vf_hero.jinja" import vf_hero %} +{%- endraw -%} +``` + +View the [building with Jinja macros guide](/docs/building-vanilla#jinja-macros) for macro installation instructions. + +### SCSS + Since Patterns leverage many other parts of Vanilla in their composition and content, we recommend [importing the entirety of Vanilla](/docs#install) for full support.