Quote wrapper pattern/macro

canonical · Oct 9, 2024 · e4b2da7 · e4b2da7
1 parent e2d9aa7
commit e4b2da7
Show file tree

Hide file tree

Showing 25 changed files with 833 additions and 0 deletions.
diff --git a/releases.yml b/releases.yml
@@ -8,6 +8,10 @@
       url: /docs/patterns/hero
       status: Updated
       notes: The hero pattern macro has been published.
+    - component: Quote wrapper
+      url: /docs/patterns/quote-wrapper
+      status: New
+      notes: We've introduced a new quote wrapper pattern.
 - version: 4.16.0
   features:
     - component: CTA Block / Borderless

diff --git a/side-navigation.yaml b/side-navigation.yaml
@@ -115,6 +115,8 @@
       url: /docs/patterns/hero
     - title: Tiered list
       url: /docs/patterns/tiered-list
+    - title: Quote Wrapper
+      url: /docs/patterns/quote-wrapper
 - heading: Utilities
   ordering: alphabetical
   subheadings:

diff --git a/templates/_macros/quote-wrapper.jinja b/templates/_macros/quote-wrapper.jinja
@@ -0,0 +1,167 @@
+{#
+  Params
+  - title_text (string) (optional): The text to be displayed as the heading
+  - quote_size (string) (required): The size of the quote. Possible values are 'small', 'medium', 'large'. Default is 'medium'.
+  - quote_text (string) (required): The text of the quote. The macro will surround it with quotes, so there is no need to quote it yourself.
+  - citation_source_name_text (string) (optional): The name of the source being quoted
+  - citation_source_title_text (string) (optional): The title of the source being quoted
+  - citation_source_organisation_text (string) (optional): The organisation associated with the source being quoted.
+  - is_shallow (boolean) (optional): Whether the quote wrapper pattern should be displayed in a shallow section. Defaults to false.
+  Slots
+  - signpost_image (optional): The signpost_image of the source being quoted
+  - heading_link (optional): Link to be displayed beside the heading text
+  - cta (optional): Contents of the call to action block to be displayed below the quote
+  - image (optional): An image to be displayed below the quote
+#}
+{%- macro quote_wrapper(
+  title_text="",
+  quote_size="medium",
+  quote_text="",
+  citation_source_name_text="",
+  citation_source_title_text="",
+  citation_source_organisation_text="",
+  is_shallow=False
+) -%}
+  {% set heading_link_content = caller('heading_link') %}
+  {% set has_heading_link =  heading_link_content|trim|length > 0 %}
+  {% set has_title = title_text|length > 0 %}
+  {% set has_heading_row = has_title or has_heading_link %}
+  {% set signpost_image_content = caller('signpost_image') %}
+  {% set has_signpost_image = signpost_image_content|trim|length > 0 %}
+  {% set has_citation_source_name = citation_source_name_text|trim|length > 0 %}
+  {% set has_citation_source_title = citation_source_title_text|trim|length > 0 %}
+  {% set has_citation_source_organisation = citation_source_organisation_text|trim|length > 0 %}
+  {% set has_citation = has_citation_source_name or has_citation_source_title or has_citation_source_organisation %}
+  {% set cta_content = caller('cta') %}
+  {% set has_cta = cta_content|trim|length > 0 %}
+  {% set image_content = caller('image') %}
+  {% set has_image = image_content|trim|length > 0 %}
+  {% set quote_size = quote_size|trim|lower %}
+
+  {# Translate quote size param to quote heading level #}
+  {% if quote_size == 'large' %}
+    {% set quote_heading_level = 2 %}
+  {% elif quote_size == 'small' %}
+    {% set quote_heading_level = 6 %}
+  {% else %}
+    {% set quote_heading_level = 4 %}
+  {% endif %}
+
+  {%- macro _quote_body() -%}
+    {#- Only use shallow section spacing if a another block follows -#}
+    <div {% if has_cta or has_image or has_citation %} class="p-section--shallow"{% endif %}>
+      <p class="p-heading--{{ quote_heading_level }}">
+        <i>
+          &#8220;{{ quote_text }}&#8221;
+        </i>
+      </p>
+    </div>
+  {%- endmacro %}
+
+  {%- macro _citation_block() -%}
+    {%- if has_citation -%}
+      {#- Optional citation block -#}
+      <p>
+        {% if has_citation_source_name -%}
+          {#- Optional citation source name -#}
+          <strong>{{ citation_source_name_text }}</strong>
+          {% if has_citation_source_title or has_citation_source_organisation -%}
+            {#- If the citation name is followed by title and/or organisation, add a line break -#}
+            <br>
+          {% endif -%}
+        {% endif -%}
+        {% if has_citation_source_title or has_citation_source_organisation -%}
+          {#- Optional citation source title and/or organisation -#}
+          <span class="u-text--muted">
+            {% if has_citation_source_title -%}
+              {#- Optional citation source title -#}
+              {{ citation_source_title_text }}
+              {%- if has_citation_source_organisation %}
+                {#- Add a line break between the title and org if both are present -#}
+                <br>
+              {%- endif %}
+            {% endif %}
+            {%- if has_citation_source_organisation -%}
+              {#- Optional citation source organisation -#}
+              {{ citation_source_organisation_text }}
+            {%- endif %}
+          </span>
+        {%- endif %}
+      </p>
+    {% endif %}
+  {%- endmacro -%}
+
+  {%- macro _heading_block() %}
+    {% if has_heading_row -%}
+      {#- Optional heading -#}
+      <div class="p-section--shallow">
+        <hr class="p-rule--highlight is-fixed-width">
+        <div class="row">
+          {%- if has_title %}
+            {#- Optional heading text -#}
+            <div class="col-3 col-medium-2">
+              <p class="p-muted-heading">{{ title_text }}</p>
+            </div>
+          {%- endif -%}
+
+          {%- if has_heading_link %}
+            {#- Optional heading link  -#}
+            <div class="col-3 col-medium-4 col-start-large-10 col-start-medium-3">
+              <p class="p-text--default">
+                {{ heading_link_content }}
+              </p>
+            </div>
+          {% endif -%}
+        </div>
+      </div>
+    {% endif -%}
+  {%- endmacro %}
+
+  <div class="p-section{% if is_shallow %}--shallow{% endif %}">
+    {{- _heading_block() -}}
+    <div class="row">
+      {% if has_signpost_image -%}
+        {#- Optional signpost image -#}
+        <div class="col-3 col-medium-2">
+          <div class="p-section--shallow">
+            {{ signpost_image_content }}
+          </div>
+        </div>
+      {% endif -%}
+      {#- Skip to fourth column if the signpost_image (which takes up first three columns) is missing -#}
+      <div class="col-9 col-start-large-4 col-medium-4 col-start-medium-3">
+        <hr class="p-rule--muted">
+        {% if has_citation -%}
+          {#-  When a citation is present, wrap the quote and citation in a nested grid to space them properly  -#}
+          <div class="row">
+            <div class="col-6">
+              {{ _quote_body() }}
+            </div>
+            <div class="col-3">
+              <hr class="p-rule--muted u-hide--large">
+              {{ _citation_block() }}
+            </div>
+          </div>
+        {% else -%}
+          {#-  When no citation is present, display quote body without a nested grid  -#}
+          {{ _quote_body() }}
+        {% endif -%}
+
+        {%- if has_cta or has_image -%}
+          {#-  Optional CTA and/or image block  -#}
+          {%- if has_cta %}
+            {#-  Optional CTA block -#}
+            <div class="p-cta-block">
+              {{ cta_content }}
+            </div>
+          {% endif -%}
+
+          {% if has_image -%}
+            {#-  Optional image block  -#}
+            {{ image_content }}
+          {% endif -%}
+        {% endif -%}
+      </div>
+    </div>
+  </div>
+{% endmacro -%}
diff --git a/templates/docs/examples/patterns/quote-wrapper/combined.html b/templates/docs/examples/patterns/quote-wrapper/combined.html
@@ -0,0 +1,25 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Quote Wrapper / Combined{% endblock %}
+
+{% block standalone_css %}patterns_all{% endblock %}
+
+{% block content %}
+{% with is_combined = true %}
+<section>{% include 'docs/examples/patterns/quote-wrapper/large.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/large-no-cta-image-or-citation.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/large-no-signpost.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/large-no-citation.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/large-no-header.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/large-no-header-no-signpost.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/large-shallow.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/large-minimal.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/medium.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/medium-no-signpost.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/medium-no-citation.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/medium-no-header.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/small.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/small-no-signpost.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/small-no-citation.html' %}</section>
+<section>{% include 'docs/examples/patterns/quote-wrapper/small-no-header.html' %}</section>
+{% endwith %}
+{% endblock %}
diff --git a/templates/docs/examples/patterns/quote-wrapper/large-minimal.html b/templates/docs/examples/patterns/quote-wrapper/large-minimal.html
@@ -0,0 +1,16 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/quote-wrapper.jinja" import quote_wrapper %}
+
+{% block title %}Quote Wrapper / Large quote / Minimal{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+
+{% block content %}
+
+{% call(slot) quote_wrapper(
+  quote_size="large",
+  quote_text="This is a company where intelligence and learning are highly valued."
+) -%}
+
+{% endcall -%}
+
+{% endblock %}
diff --git a/templates/docs/examples/patterns/quote-wrapper/large-no-citation.html b/templates/docs/examples/patterns/quote-wrapper/large-no-citation.html
@@ -0,0 +1,35 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/quote-wrapper.jinja" import quote_wrapper %}
+
+{% block title %}Quote Wrapper / Large quote / No citation{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+
+{% block content %}
+
+{% call(slot) quote_wrapper(
+  title_text="Our hiring process",
+  quote_size="large",
+  quote_text="This is a company where intelligence and learning are highly valued."
+) -%}
+
+{%- if slot == 'heading_link' -%}
+  <a href="#">All the success stories &rsaquo;</a>
+{%- endif -%}
+
+{%- if slot == 'signpost_image' -%}
+  <img src="https://assets.ubuntu.com/v1/8c8bd206-example-logo-h2.png" width="114" alt="Canonical logo">
+{%- endif -%}
+
+{%- if slot == 'cta' -%}
+  <a href="#">Explore careers &rsaquo;</a>
+{%- endif -%}
+
+{%- if slot == 'image' -%}
+  <div class="p-image-container--cinematic is-cover">
+    <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/da3fbf74-summit2022_crowd.png" alt="Ubuntu Summit crowd">
+  </div>
+{%- endif -%}
+
+{% endcall -%}
+
+{% endblock %}
diff --git a/templates/docs/examples/patterns/quote-wrapper/large-no-cta-image-or-citation.html b/templates/docs/examples/patterns/quote-wrapper/large-no-cta-image-or-citation.html
@@ -0,0 +1,28 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/quote-wrapper.jinja" import quote_wrapper %}
+
+{% block title %}Quote Wrapper / Large quote / No CTA, image, or citation{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+
+{% block content %}
+
+{% call(slot) quote_wrapper(
+  title_text="Our hiring process",
+  quote_size="large",
+  quote_text="This is a company where intelligence and learning are highly valued.",
+  citation_source_name_text="Alyson Richens",
+  citation_source_title_text="Customer Success Manager",
+  citation_source_organisation_text="Canonical"
+) -%}
+
+{%- if slot == 'heading_link' -%}
+  <a href="#">All the success stories &rsaquo;</a>
+{%- endif -%}
+
+{%- if slot == 'signpost_image' -%}
+  <img src="https://assets.ubuntu.com/v1/8c8bd206-example-logo-h2.png" width="114" alt="Canonical logo">
+{%- endif -%}
+
+{% endcall -%}
+
+{% endblock %}
diff --git a/templates/docs/examples/patterns/quote-wrapper/large-no-header-no-signpost.html b/templates/docs/examples/patterns/quote-wrapper/large-no-header-no-signpost.html
@@ -0,0 +1,29 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/quote-wrapper.jinja" import quote_wrapper %}
+
+{% block title %}Quote Wrapper / Large quote / No header or signpost{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+
+{% block content %}
+
+{% call(slot) quote_wrapper(
+  quote_size="large",
+  quote_text="This is a company where intelligence and learning are highly valued.",
+  citation_source_name_text="Alyson Richens",
+  citation_source_title_text="Customer Success Manager",
+  citation_source_organisation_text="Canonical"
+) -%}
+
+{%- if slot == 'cta' -%}
+  <a href="#">Explore careers &rsaquo;</a>
+{%- endif -%}
+
+{%- if slot == 'image' -%}
+  <div class="p-image-container--cinematic is-cover">
+    <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/da3fbf74-summit2022_crowd.png" alt="Ubuntu Summit crowd">
+  </div>
+{%- endif -%}
+
+{% endcall -%}
+
+{% endblock %}
diff --git a/templates/docs/examples/patterns/quote-wrapper/large-no-header.html b/templates/docs/examples/patterns/quote-wrapper/large-no-header.html
@@ -0,0 +1,33 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/quote-wrapper.jinja" import quote_wrapper %}
+
+{% block title %}Quote Wrapper / Large quote / No header{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+
+{% block content %}
+
+{% call(slot) quote_wrapper(
+  quote_size="large",
+  quote_text="This is a company where intelligence and learning are highly valued.",
+  citation_source_name_text="Alyson Richens",
+  citation_source_title_text="Customer Success Manager",
+  citation_source_organisation_text="Canonical"
+) -%}
+
+{%- if slot == 'signpost_image' -%}
+  <img src="https://assets.ubuntu.com/v1/8c8bd206-example-logo-h2.png" width="114" alt="Canonical logo">
+{%- endif -%}
+
+{%- if slot == 'cta' -%}
+  <a href="#">Explore careers &rsaquo;</a>
+{%- endif -%}
+
+{%- if slot == 'image' -%}
+  <div class="p-image-container--cinematic is-cover">
+    <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/da3fbf74-summit2022_crowd.png" alt="Ubuntu Summit crowd">
+  </div>
+{%- endif -%}
+
+{% endcall -%}
+
+{% endblock %}
diff --git a/templates/docs/examples/patterns/quote-wrapper/large-no-signpost.html b/templates/docs/examples/patterns/quote-wrapper/large-no-signpost.html
@@ -0,0 +1,34 @@
+{% extends "_layouts/examples.html" %}
+{% from "_macros/quote-wrapper.jinja" import quote_wrapper %}
+
+{% block title %}Quote Wrapper / Large quote / No signpost{% endblock %}
+{% block standalone_css %}patterns_all{% endblock %}
+
+{% block content %}
+
+{% call(slot) quote_wrapper(
+  title_text="Our hiring process",
+  quote_size="large",
+  quote_text="This is a company where intelligence and learning are highly valued.",
+  citation_source_name_text="Alyson Richens",
+  citation_source_title_text="Customer Success Manager",
+  citation_source_organisation_text="Canonical"
+) -%}
+
+{%- if slot == 'heading_link' -%}
+  <a href="#">All the success stories &rsaquo;</a>
+{%- endif -%}
+
+{%- if slot == 'cta' -%}
+  <a href="#">Explore careers &rsaquo;</a>
+{%- endif -%}
+
+{%- if slot == 'image' -%}
+  <div class="p-image-container--cinematic is-cover">
+    <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/da3fbf74-summit2022_crowd.png" alt="Ubuntu Summit crowd">
+  </div>
+{%- endif -%}
+
+{% endcall -%}
+
+{% endblock %}