feat: Publish & Document Jinja Macros (#5342)

* 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 * 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]> * Rename hero macro * 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]> * Update _index.scss * Update _index.scss * Add tiered list docs; minor formatting updates * File formatting fixes * Change "call to action block" to "CTA block" * Add cta block slot docs * Add code comments * Apply static widths to table columns * Add route for serving raw example template * Render flask template in HTML code snippet * Show rendered/raw example * Enable switching between Jinja code snippets and rendered HTML * Slight example.js docs improvements & refactors * Run prettier * RM example guide * Switch jinja example trigger from .js-show-template to [data-lang='jinja'] * Use raw query parameter instead of `/example` path * Syntax-highlight HTML within Jinja template macro calls * Optional chain to avoid possible null index error * Make HTML the default example language, instead of Jinja * Simplify example xmlhttprequest check * Change initializer keywords to `let` or `const` * Move throttle() to a utils function * fix HTML snippets including JS at the bottom * Revert "Move throttle() to a utils function" This reverts commit 75e51b8. * rename `createPreCode` param `hide` to `isHidden` * Reapply "Move throttle() to a utils function" This reverts commit 99b32c9. * swap xmlhttprequest for fetch() * Moved fetch code from example file into shared utils * Move utils to window scope, rather than JS import * prettier * set no-cache on raw template endpoint * Re-remove extracted utils functions * replace `let` with `const` where applicable * Additional try/catch handler in `fetchResponse()` * renderdropdown guard * promise.all parallelization improvement * rename `EXAMPLE_OPTION_CFG` to `EXAMPLE_LANGUAGE_OPTION_CONFIG` * Move HTML body extraction functions into `fetchHtmlSource()` and return them there instead of generating them in the callback * rename `fetchHtmlSource()` to `fetchRenderedHtml()` * Switch default example language from HTML to jinja if jinja is found * Clean up parallelization per code review * Prepare macros for release (bump to 4.17.0) * Move jinja macro API docs to bottom of hero/tiered list pages * Remove markup comments from hero macro output --------- Co-authored-by: pastelcyborg <[email protected]> Co-authored-by: Bartek Szopka <[email protected]>
canonical · Oct 4, 2024 · e2d9aa7 · e2d9aa7
1 parent f831b0c
commit e2d9aa7
Show file tree

Hide file tree

Showing 25 changed files with 730 additions and 198 deletions.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vanilla-framework",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "author": {
     "email": "[email protected]",
     "name": "Canonical Webteam"
@@ -53,7 +53,8 @@
     "_index.scss",
     "/scss",
     "!/scss/docs",
-    "!/scss/standalone"
+    "!/scss/standalone",
+    "/templates/_macros"
   ],
   "devDependencies": {
     "@canonical/cookie-policy": "3.6.4",

diff --git a/releases.yml b/releases.yml
@@ -1,3 +1,13 @@
+- version: 4.17.0
+  features:
+    - component: Tiered list
+      url: /docs/patterns/tiered-list
+      status: Updated
+      notes: The tiered list pattern macro has been published.
+    - component: Hero
+      url: /docs/patterns/hero
+      status: Updated
+      notes: The hero pattern macro has been published.
 - version: 4.16.0
   features:
     - component: CTA Block / Borderless

diff --git a/templates/_macros/hero.jinja → templates/_macros/vf_hero.jinja b/templates/_macros/hero.jinja → 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.
@@ -10,13 +10,13 @@
 # cta: call-to-action block below the description
 # image: slot for image content
 # signpost_image: slot for signpost (left column) image content in 25/75 layout. Required for 25/75 layout.
-{% macro hero(
-  title,
-  subtitle='',
+{% 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') %}
   {% set has_description = description_content|trim|length > 0 %}
   {% set cta_content = caller('cta') %}
@@ -79,14 +79,14 @@
 
     {#- 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 %}
       <h2>
-        {{ subtitle }}
+        {{ subtitle_text }}
       </h2>
     {% endif %}
   {%- endmacro %}
@@ -127,7 +127,7 @@
       </div>
     {% endif -%}
     <div class="{{ row_classes | join(' ') }}">
-      {%- if is_fallback %}
+      {%- if is_fallback -%}
         <div class="{{ col_classes[0] }}">
           {{- _hero_description_block() -}}
           {{ _hero_cta_block() -}}

diff --git a/templates/_macros/tiered-list.jinja → templates/_macros/vf_tiered-list.jinja b/templates/_macros/tiered-list.jinja → templates/_macros/vf_tiered-list.jinja
@@ -9,7 +9,7 @@
 # list_item_title_[1-25]: title element of each child list item
 # list_item_description_[1-25]: description element of each child list item
 # cta: CTA block element
-{% macro tiered_list(
+{% macro vf_tiered_list(
   is_description_full_width_on_desktop=true,
   is_list_full_width_on_tablet=true) -%}
   {%- set title_content = caller('title') -%}
@@ -62,6 +62,8 @@
         {%- set list_item_description_content = caller('list_item_description_' + number|string) -%}
         {%- set has_description_content = list_item_description_content|trim|length > 0 -%}
 
+        {#- Check to see if title/description content exist, since we're
+            iterating through 25 potential list items -#}
         {%- if has_title_content and has_description_content -%}
           {%- if is_list_full_width_on_tablet == true %}
             <div class="row">

diff --git a/templates/docs/building-vanilla.md b/templates/docs/building-vanilla.md
@@ -4,7 +4,8 @@ context:
   title: Building with Vanilla
 ---
 
-Here you will find information on how you can use different tools to build Vanilla into production CSS.
+Here you will find information on how you can use different tools to build
+Vanilla into production HTML and CSS.
 
 ## Sass
 
@@ -73,6 +74,39 @@ To watch for changes in your Sass files, add the following script to your `packa
 
 Now if you open an extra terminal and run `yarn watch-css`, the CSS will be rebuilt every time your Sass files are edited and saved.
 
+## Jinja Macros
+
+A variety of Vanilla's components and patterns are offered as
+[Jinja macros](https://jinja.palletsprojects.com/templates/#macros), which may
+be useful to you if you build sites using the
+[Jinja](https://jinja.palletsprojects.com/) templating engine. These macros can
+help abstract away some of the complexity of Vanilla's HTML, making producing
+complex page layouts simpler and faster.
+
+In order to pull Vanilla's macros into your project, you may need to expose them
+to your webserver or templating engine. An example of this using Flask and Jinja
+might look like the following:
+
+```python
+from flask import Flask
+from jinja2 import ChoiceLoader, FileSystemLoader
+
+app = Flask(__name__)
+
+# ChoiceLoader attempts loading templates from each path in successive order
+loader = ChoiceLoader([
+    FileSystemLoader('templates'),
+    FileSystemLoader('node_modules/vanilla-framework/templates/')
+])
+
+# Loader supplied to jinja_loader overwrites default jinja_loader
+app.jinja_loader = loader
+
+```
+
+After making the macros available to your webserver/templating engine, see the
+individual component/pattern docs for import and usage instructions.
+
 ## Webpack
 
 [Webpack](https://webpack.js.org/) is used to compile JavaScript modules, and can be used to inject Vanilla styles to the DOM. To get set up using Vanilla with Webpack, add the `webpack` and `vanilla-framework` packages to your project dependencies:

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
@@ -1,15 +1,15 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/hero.jinja" import hero %}
+{% from "_macros/vf_hero.jinja" import vf_hero %}
 
 {% block title %}Hero / 50/50 / Full width image{% endblock %}
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% set is_paper = true %}
 {% block content %}
 
-{% call(slot) hero(
-  title='H1 - ideally one line, up to two',
-  subtitle='H2 placeholder - aim for one line, 2 is acceptable.',
+{% call(slot) vf_hero(
+  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
@@ -1,15 +1,15 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/hero.jinja" import hero %}
+{% from "_macros/vf_hero.jinja" import vf_hero %}
 
 {% block title %}Hero / 50/50 / Split on Medium{% endblock %}
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% set is_paper = true %}
 {% block content %}
 
-{% call(slot) hero(
-  title='H1 - ideally one line, up to two',
-  subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph',
+{% call(slot) vf_hero(
+  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
@@ -1,15 +1,15 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/hero.jinja" import hero %}
+{% from "_macros/vf_hero.jinja" import vf_hero %}
 
 {% block title %}Hero / 50/50{% endblock %}
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% set is_paper = true %}
 {% block content %}
 
-{% call(slot) hero(
-  title='H1 - ideally one line, up to two',
-  subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph',
+{% call(slot) vf_hero(
+  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
@@ -1,14 +1,14 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/hero.jinja" import hero %}
+{% from "_macros/vf_hero.jinja" import vf_hero %}
 
 {% block title %}Hero / 75/25{% endblock %}
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% set is_paper = true %}
 {% block content %}
-{% call(slot) hero(
-  title='H1 - ideally one line, up to two',
-  subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph',
+{% call(slot) vf_hero(
+  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
@@ -1,14 +1,14 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/hero.jinja" import hero %}
+{% from "_macros/vf_hero.jinja" import vf_hero %}
 
 {% block title %}Hero / Fallback{% endblock %}
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% set is_paper = true %}
 {% block content %}
-{% call(slot) hero(
-  title='H1 - ideally one line, up to two',
-  subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph',
+{% call(slot) vf_hero(
+  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
@@ -1,14 +1,14 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/hero.jinja" import hero %}
+{% from "_macros/vf_hero.jinja" import vf_hero %}
 
 {% block title %}Hero / Signpost logo / Full width image{% endblock %}
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% set is_paper = true %}
 {% block content %}
-{% call(slot) hero(
-  title='H1 - ideally one line, up to two',
-  subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph',
+{% call(slot) vf_hero(
+  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
@@ -1,14 +1,14 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/hero.jinja" import hero %}
+{% from "_macros/vf_hero.jinja" import vf_hero %}
 
 {% block title %}Hero / Signpost logo{% endblock %}
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% set is_paper = True %}
 {% block content %}
-{% call(slot) hero(
-  title='H1 - ideally one line, up to two',
-  subtitle='H2 placeholder - aim for one line, 2 is acceptable, more - use a paragraph',
+{% call(slot) vf_hero(
+  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/tiered-list/50-50-desktop-with-description-cta.html b/templates/docs/examples/patterns/tiered-list/50-50-desktop-with-description-cta.html
@@ -1,12 +1,12 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/tiered-list.jinja" import tiered_list %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
 
 {% block title %}Tiered list / 50/50 on desktop with description CTA{% endblock %}
 
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% block content %}
-{%- call(slot) tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=true) -%}
+{%- call(slot) vf_tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=true) -%}
   {%- if slot == 'title' -%}
     <h2>H2 - up to two lines; ideally one.</h2>
   {%- endif -%}

diff --git a/templates/docs/examples/patterns/tiered-list/50-50-desktop-with-description.html b/templates/docs/examples/patterns/tiered-list/50-50-desktop-with-description.html
@@ -1,12 +1,12 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/tiered-list.jinja" import tiered_list %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
 
 {% block title %}Tiered list / 50/50 on desktop with description{% endblock %}
 
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% block content %}
-{%- call(slot) tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=true) -%}
+{%- call(slot) vf_tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=true) -%}
   {%- if slot == 'title' -%}
     <h2>H2 - up to two lines; ideally one.</h2>
   {%- endif -%}

diff --git a/templates/docs/examples/patterns/tiered-list/50-50-desktop-with-list-item-cta.html b/templates/docs/examples/patterns/tiered-list/50-50-desktop-with-list-item-cta.html
@@ -1,12 +1,12 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/tiered-list.jinja" import tiered_list %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
 
 {% block title %}Tiered list / 50/50 on desktop with list item CTA{% endblock %}
 
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% block content %}
-{%- call(slot) tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=true) -%}
+{%- call(slot) vf_tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=true) -%}
   {%- if slot == 'title' -%}
     <h2>H2 - up to two lines; ideally one.</h2>
   {%- endif -%}

diff --git a/templates/docs/examples/patterns/tiered-list/50-50-tablet-with-description.html b/templates/docs/examples/patterns/tiered-list/50-50-tablet-with-description.html
@@ -1,12 +1,12 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/tiered-list.jinja" import tiered_list %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
 
 {% block title %}Tiered list / 50/50 on tablet with description{% endblock %}
 
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% block content %}
-{%- call(slot) tiered_list(is_description_full_width_on_desktop=true, is_list_full_width_on_tablet=false) -%}
+{%- call(slot) vf_tiered_list(is_description_full_width_on_desktop=true, is_list_full_width_on_tablet=false) -%}
   {%- if slot == 'title' -%}
     <h2>H2 - up to two lines; ideally one.</h2>
   {%- endif -%}

diff --git a/templates/docs/examples/patterns/tiered-list/50-50-tablet-without-description.html b/templates/docs/examples/patterns/tiered-list/50-50-tablet-without-description.html
@@ -1,12 +1,12 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/tiered-list.jinja" import tiered_list %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
 
 {% block title %}Tiered list / 50/50 on tablet without description{% endblock %}
 
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% block content %}
-{%- call(slot) tiered_list(is_list_full_width_on_tablet=false) -%}
+{%- call(slot) vf_tiered_list(is_list_full_width_on_tablet=false) -%}
   {%- if slot == 'title' -%}
     <h2>H2 - up to two lines; ideally one.</h2>
   {%- endif -%}

diff --git a/templates/docs/examples/patterns/tiered-list/50-50-with-description.html b/templates/docs/examples/patterns/tiered-list/50-50-with-description.html
@@ -1,12 +1,12 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/tiered-list.jinja" import tiered_list %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
 
 {% block title %}Tiered list / 50/50 with description{% endblock %}
 
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% block content %}
-{%- call(slot) tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=false) -%}
+{%- call(slot) vf_tiered_list(is_description_full_width_on_desktop=false, is_list_full_width_on_tablet=false) -%}
   {%- if slot == 'title' -%}
     <h2>H2 - up to two lines; ideally one.</h2>
   {%- endif -%}

diff --git a/templates/docs/examples/patterns/tiered-list/full-width-with-description.html b/templates/docs/examples/patterns/tiered-list/full-width-with-description.html
@@ -1,12 +1,12 @@
 {% extends "_layouts/examples.html" %}
-{% from "_macros/tiered-list.jinja" import tiered_list %}
+{% from "_macros/vf_tiered-list.jinja" import vf_tiered_list %}
 
 {% block title %}Tiered list / Full-width with description{% endblock %}
 
 {% block standalone_css %}patterns_all{% endblock %}
 
 {% block content %}
-{%- call(slot) tiered_list(is_description_full_width_on_desktop=true, is_list_full_width_on_tablet=true) -%}
+{%- call(slot) vf_tiered_list(is_description_full_width_on_desktop=true, is_list_full_width_on_tablet=true) -%}
   {%- if slot == 'title' -%}
     <h2>H2 - up to two lines; ideally one.</h2>
   {%- endif -%}