Document hero macro (canonical#5325)

* Add macro install instructions to docs pages (canonical#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]>
pastelcyborg · Sep 19, 2024 · 331aaad · 331aaad
1 parent eb0a770
commit 331aaad
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 10 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-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
 ) -%}