Document hero macro #5325

jmuzina · 2024-08-26T19:59:12Z

Done

Adds documentation of the hero macro to the hero page.
Adds some markup comments to the major blocks in the hero macro to make each element of the pattern more distinct in the HTML code snippets.
Minor hero macro API changes per naming convention discussions

Note: this PR does not show the hero macro call. #5321 introduces the ability to view the Jinja macro call in the docs page.

Fixes WD-14522

QA

Open hero docs
Review the macro documentation and verify you have a clear idea of how to use the macro.

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.

Screenshots

webteam-app · 2024-08-26T19:59:16Z

Demo

Jenkins

demos.haus

jmuzina · 2024-08-26T20:12:27Z

The only thing this doesn't really cover is how to import/include this specific macro. I need to see how that will line up with @pastelcyborg 's work on adding the macros to NPM and the general macros docs

jmuzina · 2024-08-28T18:40:18Z

Import instructions were added, with namespaced macro (following convention from #5329)

jmuzina · 2024-08-28T18:51:55Z

Added link to the macro installation page, assuming merge of #5330 as-is

* Update building-vanilla.md * Update pattern docs * Roll back pattern docs * Update building-vanilla.md

templates/docs/patterns/hero/index.md

…tle/description

bartaz

Looks good.
I added some small suggestion on improvements to the options table, but I'm fine without those as well if you don't agree.

templates/docs/patterns/hero/index.md

Co-authored-by: Bartek Szopka <[email protected]>

@pastelcyborg

* 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]>

@pastelcyborg

* 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

* 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]>

@pastelcyborg

* 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]>

@pastelcyborg

* 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]>

@pastelcyborg

* 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]>

@pastelcyborg

* 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]>

@pastelcyborg

* 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]>

@pastelcyborg

* 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]>

@pastelcyborg

* 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]>

jmuzina added the Documentation 📝 Documentation changes or updates label Aug 26, 2024

jmuzina marked this pull request as ready for review August 28, 2024 18:40

jmuzina requested review from pastelcyborg, bartaz and advl August 28, 2024 18:40

jmuzina added Review: QA needed Review: Code needed labels Aug 28, 2024

jmuzina force-pushed the document-hero branch from 0138991 to eb28550 Compare August 28, 2024 18:41

jmuzina mentioned this pull request Aug 28, 2024

Add macro install instructions to docs pages #5330

Merged

3 tasks

pastelcyborg added 5 commits August 28, 2024 17:25

Add macro install instructions to docs pages (canonical#5330)

db3ddef

* Update building-vanilla.md * Update pattern docs * Roll back pattern docs * Update building-vanilla.md

Add macros directory to published files

c090f5f

Rename hero macro

4b29745

Rename tiered list macro

b4462d9

Update releases.yml

f8c2147

pastelcyborg reviewed Aug 28, 2024

View reviewed changes

jmuzina added 5 commits August 29, 2024 11:22

End hero title and subtitle params with _text per new naming convention

8f1a1cb

Add html block comments to hero macro

101bf24

Add hero macro docn

8f47c6b

Add Hero macro import instructions

f6cc820

Add link to @pastelcyborg jinja macros installation guide

2aaf560

jmuzina force-pushed the document-hero branch from 7f5b850 to 2aaf560 Compare August 29, 2024 15:25

Fix hero title_text being renamed from rebase

1657f2f

jmuzina force-pushed the document-hero branch from ff83627 to 1657f2f Compare August 29, 2024 15:28

jmuzina added 3 commits August 29, 2024 11:32

Adjust jinja parameters column order

0b1320b

lowercase param types

4989be4

adjust slots column ordering

a04b4dd

jmuzina added 3 commits August 30, 2024 12:05

Param/slot table widths set by percentage

11f5964

More consistent whitespace control chars around jinja macro import

34cffac

Revise hero element/description table word choice around title/substi…

fabf553

…tle/description

jmuzina force-pushed the feature/expose-macros branch from f8c2147 to 4059b1b Compare September 3, 2024 17:41

jmuzina added 2 commits September 3, 2024 13:42

Merge branch 'feature/expose-macros' into document-hero

2c567f4

comma-separated string with line breaks for hero layout type options

3e85dfe

jmuzina requested a review from bartaz September 3, 2024 17:49

bartaz added Review: QA +1 Review: Code +1 (with changes) and removed Question ❓ Further information is requested Review: QA needed Review: Code +1 labels Sep 4, 2024

bartaz approved these changes Sep 4, 2024

View reviewed changes

jmuzina and others added 2 commits September 4, 2024 08:33

Update is required column by @bartaz

0d7222f

Co-authored-by: Bartek Szopka <[email protected]>

Code review suggestions from @bartaz

776c194

Co-authored-by: Bartek Szopka <[email protected]>

jmuzina merged commit 78a9b85 into canonical:feature/expose-macros Sep 4, 2024
4 checks passed

jmuzina deleted the document-hero branch September 4, 2024 12:37

jmuzina mentioned this pull request Sep 4, 2024

feat: Quote Wrapper Pattern #5275

Merged

3 tasks

jmuzina mentioned this pull request Sep 11, 2024

feat: Publish & Document Jinja Macros #5342

Merged

8 tasks

jmuzina mentioned this pull request Sep 17, 2024

Document tiered list macro #5351

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document hero macro #5325

Document hero macro #5325

jmuzina commented Aug 26, 2024 •

edited

Loading

webteam-app commented Aug 26, 2024

jmuzina commented Aug 26, 2024

jmuzina commented Aug 28, 2024

jmuzina commented Aug 28, 2024

bartaz left a comment

Document hero macro #5325

Document hero macro #5325

Conversation

jmuzina commented Aug 26, 2024 • edited Loading

Done

QA

Check if PR is ready for release

Screenshots

webteam-app commented Aug 26, 2024

Demo

Jenkins

demos.haus

jmuzina commented Aug 26, 2024

jmuzina commented Aug 28, 2024

jmuzina commented Aug 28, 2024

bartaz left a comment

Choose a reason for hiding this comment

jmuzina commented Aug 26, 2024 •

edited

Loading