feat: adds optional classes for page header and footer

affects: @buildit/gravity-ui-nunjucks, @buildit/gravity-ui-web So far Gravity has mandated that page headers and footers had to be *direct* descendents of the \`<body>\` element. Unfortunately, this doesn't play nice with frameworks like React, which recommend having another wrapper element around your page structure. To ease compatibiliy in such cases, this change adds _optional_ component class names that can be used when the page header and footer cannot be direct descendents of the \`<body>\` element. ISSUES CLOSED: #280
buildit · Jul 19, 2019 · e481709 · e481709
1 parent c545c24
commit e481709
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 10 deletions.
diff --git a/...vity-ui-nunjucks/src/_patterns/03-organisms/00-page-structure/00-page-header.md b/...vity-ui-nunjucks/src/_patterns/03-organisms/00-page-structure/00-page-header.md
@@ -2,10 +2,14 @@
 
 This is the main Page Header that sits above every page. It contains the company logo and main site navigation.
 
-When using this component, make sure the following restrictions are enforced:
+Ideally, the Page Header is a `<header>` element that is a _direct_ child of `<body>`, in which case no class is necessary. For compatibility with frameworks or CMSes where you cannot add the page header as a direct child of `<body>`, you may use `<header class="grav-c-page-header">` instead.
 
-* The Page Header _must_ be a direct child of `<body>`
-* The Page Header _should_ be the first component on the page
+When using this component, make sure the following advice is followed:
+
+* The Page Header **must** be a descendent of `<body>` that is not nested with another [sectioning element](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines#Section_Elements_in_HTML5). This is so that it had an implict ARIA landmark role of `banner`.
 * There **must** only be 1 instance of a Page Header on a page
 
-The Page Header is identified by being the only `<header>` element that is a direct child of `<body>` (which has an implict ARIA role of `banner`). Adding a class name to the Page Header component would be redundant.
+
+## See also
+
+* [Default landmark roles for HTML5 sectioning elements](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/HTML5.html)
diff --git a/...vity-ui-nunjucks/src/_patterns/03-organisms/00-page-structure/01-page-footer.md b/...vity-ui-nunjucks/src/_patterns/03-organisms/00-page-structure/01-page-footer.md
@@ -2,13 +2,15 @@
 
 This is the main Page Footer that sits below every page. It contains some additional links to privacy, accessibility statements and some additional useful information.
 
-When using this component, make sure the following restrictions are enforced:
+Ideally, the Page Footer is a `<footer>` element that is a _direct_ child of `<body>`, in which case no class is necessary. For compatibility with frameworks or CMSes where you cannot add the page footer as a direct child of `<body>`, you may use `<footer class="grav-c-page-footer">` instead.
 
-* The Page Footer _should_ be the last component on the template/page
-* There **must** only be 1 instance of a Page Footer on a template/page
+When using this component, make sure the following advice is followed:
+
+* The Page Footer **must**_** be a descendent of `<body>` that is not nested with another [sectioning element](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines#Section_Elements_in_HTML5). This is so that it had an implict ARIA landmark role of `contentinfo`.
+* There **must** only be 1 instance of a Page Footer on a page
 
-The Page Footer is identified by its ARIA attrbute `role="contentinfo"`, which may be used by assistive technologies. Since this ARIA role cannot be used for anything else, adding a class name to the Page Footer component would be redundant.
 
 ## See also
 
+* [Default landmark roles for HTML5 sectioning elements](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/HTML5.html)
 * [W3C ARIA Landmarks Example](https://www.w3.org/TR/2017/NOTE-wai-aria-practices-1.1-20171214/examples/landmarks/contentinfo.html)
diff --git a/...gravity-ui-web/src/sass/05-components/03-organisms/00-page-structure/_00-page-header.scss b/...gravity-ui-web/src/sass/05-components/03-organisms/00-page-structure/_00-page-header.scss
@@ -5,7 +5,8 @@ $grav-page-heading-trigger-breakpoint: grav-breakpoint(medium);
 // is in case we want to give it any kind of full-bleed background styling.
 // The child elements within therefore need to respect the maximum content
 // width ($grav-page-content-max-width) themselves, where necessary.
-body > header {
+body > header,
+.grav-c-page-header {
   > div {
     @include grav-l-container;
 

diff --git a/...gravity-ui-web/src/sass/05-components/03-organisms/00-page-structure/_01-page-footer.scss b/...gravity-ui-web/src/sass/05-components/03-organisms/00-page-structure/_01-page-footer.scss
@@ -1,4 +1,5 @@
-body > footer {
+body > footer,
+.grav-c-page-footer {
   @include grav-color-grp-b-apply('border-bottom-color', 'accent');
   @include grav-font-size(-1);