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 <[email protected]> * Code review suggestions from @bartaz Co-authored-by: Bartek Szopka <[email protected]> --------- Co-authored-by: pastelcyborg <[email protected]> Co-authored-by: Bartek Szopka <[email protected]>
canonical · Sep 11, 2024 · 6c81e69 · 6c81e69
1 parent caea0bd
commit 6c81e69
Show file tree

Hide file tree

Showing 9 changed files with 141 additions and 26 deletions.
diff --git 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 -%}
 
+    <!-- Title block -->
     {#- Only add a class attribute if needed -#}
     <h1{% if title_class|trim|length > 0 %} class="{{ title_class }}"{% endif %}>
-      {{ title }}
+      {{ title_text }}
     </h1>
   {%- endmacro %}
 
   {%- macro _hero_subtitle_block() -%}
     {% if has_subtitle %}
+      <!-- Optional subtitle block -->
       <h2>
-        {{ subtitle }}
+        {{ subtitle_text }}
       </h2>
     {% endif %}
   {%- endmacro %}
 
   {%- macro _hero_cta_block() -%}
     {% if has_cta -%}
+      <!-- Optional CTA block -->
       <div class="p-cta-block">
         {{ cta_content }}
       </div>
@@ -104,6 +107,7 @@
 
   {%- macro _hero_description_block() -%}
     {% if has_description %}
+      <!-- Optional description block -->
       <div class="p-section--shallow">
         {{ description_content }}
       </div>
@@ -112,6 +116,7 @@
 
   {%- macro _hero_signpost_image_block() -%}
     {% if layout == '25-75' and has_signpost_image -%}
+      <!-- Signpost image block -->
       <div class="p-section--shallow">
         {{ signpost_image_content }}
       </div>
@@ -130,12 +135,13 @@
       </div>
     {% endif -%}
     <div class="{{ row_classes | join(' ') }}">
-      {%- if is_fallback %}
+      {%- if is_fallback -%}
         <div class="{{ col_classes[0] }}">
           {{- _hero_description_block() -}}
           {{ _hero_cta_block() -}}
         </div>
         {% if has_image -%}
+          <!-- Optional image block -->
           <div class="{{ col_classes[1] }}">
             {{ image_content }}
           </div>
@@ -151,6 +157,7 @@
           {{- _hero_description_block() -}}
           {{- _hero_cta_block() -}}
         </div>
+        <!-- Full-width image -->
         {{ image_content -}}
       {% elif has_signpost_image %}
         {#- 25/75 Signpost layout -#}
@@ -167,6 +174,7 @@
         </div>
         {% if has_image %}
           {#- Signpost with image is always full-width, so set it after the columns -#}
+          <!--- Full width image underneath signpost hero -->
           {{- image_content }}
         {% endif -%}
       {% else %}
@@ -179,6 +187,7 @@
           {{- _hero_cta_block() -}}
         </div>
         {% if has_image -%}
+          <!-- Optional image block -->
           <div class="{{ col_classes[1] }}">
             {{ image_content }}
           </div>

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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -17,12 +17,103 @@ The hero pattern is composed of the following elements:
 
 | Element              | Description                                                              |
 | -------------------- | ------------------------------------------------------------------------ |
-| Title (**required**) | <code>h1</code> title text                                               |
-| Subtitle             | <code>h2</code> subtitle text                                            |
-| Description          | <code>p</code> 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
+
+<div style="overflow: auto;">
+  <table style="overflow: visible; width: auto;">
+    <thead>
+      <tr>
+        <th style="width: 20%;">Name</th>
+        <th style="width: 10%;">Is required</th>
+        <th style="width: 25%;">Type</th>
+        <th style="width: 15%;">Default</th>
+        <th style="width: 30%;">Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>layout</code></td>
+        <td>Yes</td>
+        <td>
+          One of:
+            <code>'50/50'</code>,
+            <code>'50/50-full-width-image'</code>,
+            <code>'75/25'</code>,
+            <code>'25/75'</code>,
+            <code>'fallback'</code>
+        </td>
+        <td><code>'fallback'</code></td>
+        <td>Choice of hero layout.</td>
+      </tr>
+      <tr>
+        <td><code>title_text</code></td>
+        <td>Yes</td>
+        <td><code>string</code></td>
+        <td><code>N/A</code></td>
+        <td><code>h1</code> title text</td>
+      </tr>
+      <tr>
+        <td><code>subtitle_text</code></td>
+        <td>No</td>
+        <td><code>string</code></td>
+        <td><code>N/A</code></td>
+        <td><code>h2</code> subtitle text</td>
+      </tr>
+      <tr>
+        <td><code>is_split_on_medium</code></td>
+        <td>Yes</td>
+        <td><code>boolean</code></td>
+        <td><code>false</code></td>
+        <td>Whether the layout is split on tablet-sized devices.</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+### Slots
+
+<div style="overflow: auto;">
+  <table style="overflow: visible; width: auto;">
+    <thead>
+      <tr>
+        <th style="width: 20%;">Name</th>
+        <th style="width: 25%;">Is required</th>
+        <th style="width: 55%;">Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>description</code></td>
+        <td>No</td>
+        <td>Paragraph-style content below the title and subtitle.</td>
+      </tr>
+      <tr>
+        <td><code>cta</code></td>
+        <td>Yes</td>
+        <td>Contents of a <a href="/docs/patterns/cta-block">Call to action block</a> beneath the title and description.</td>
+      </tr>
+      <tr>
+        <td><code>image</code></td>
+        <td>Yes, when <code>layout='50/50-full-width-image'</code></td>
+        <td>Image content.</td>
+      </tr>
+      <tr>
+        <td><code>signpost_image</code></td>
+        <td>Yes, when <code>layout='25/75'</code></td>
+        <td>Small image (such as a logo) to place in the left column of the 25/75 Hero.</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
 ## 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 <code>.p-image-container .is-cover</code> at the same level as the grid columns.
+the first column and place the image in a <code>.p-image-container .is-cover</code> at the same level as the grid
+columns.
 This will make the image take up the full width of the hero.
 
 <div class="embedded-example"><a href="/docs/examples/patterns/hero/hero-50-50-full-width-image" class="js-example">
@@ -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.