Case study templates developer guide
Case studies can be found on Case Studies. Each case study is built using predefined Jinja macros. There are two types of macros, custom macros for case studies and general Vanilla defined macros. Currently, all macros are in the /templates/macros folder, but with the new Vanilla update we will be able to import macros directly from the npm package. This documentation will be updated once this change has been made. The copy doc template used to create case study can be found here.
Steps to create case studies
- Create a static case study using the template guide below
- Create a Discourse post to show case study on index pages
If you need to update a previously created discourse post, you will need to be the owner of the post or ask a member of the Sites team
1. Template guide
Vanilla macros
Vanilla macros have more functionalities and offer more flexibility. In this guide we are only including the parameters and slots that are needed for the case studies. Further information about each Vanilla macro can be found directly on documentation in the respective macro file.
Hero section
{% from "_macros/vf_hero.jinja" import vf_hero %}
{%- call(slot) vf_hero(
title_text="Example hero title",
layout="25/75",
is_split_on_medium="true"
) -%}
{% if slot == "signpost_image" %}
{{ image(url="....", ...) }}
{% endif %}
{%- endcall -%}
Parameters:
- title_text (required): Hero title text
- layout (optional): Layout of hero section. Required as 25/75 if signpost image is attached, otherwise this parameter can be left out
- is_split_on_medium (optional): Whether the layout is split on tablet. False by default.
Slots:
- signpost_image (required): Slot for signpost (left column) image content in 25/75 layout. Required for 25/75 layout.
These are the only parameters and slots required for case study templates. There are more functionalities that the Vanilla Hero pattern offers.
Quote section
{% from "_macros/vf_quote-wrapper.jinja" import vf_quote_wrapper %}
{%- call(slot) vf_quote_wrapper(
quote_text="Example quote text",
citation_source_name_text="John Doe",
citation_source_title_text="ESA Mission Operations",
citation_source_organisation_text="",
is_shallow=True
-%}
{%- endcall -%}
Parameters:
- quote_text (required): The text of the quote
- citation_source_name_text (optional): The name of the source being quoted
- citation_source_title_text (optional): The title of the source being quoted
- citation_source_organisation_text (optional): The organisation associated with the source being quoted
- is_shallow (required): Whether the quote section should be displayed in a shallow section. Always True for case study quote sections.
These are the only parameters required for case study templates. There are more functionalities that the Vanilla Quote Wrapper pattern offers.
Custom case study macros
Basic text section + list
{% from "macros/_macros-text_list.jinja" import text_list %}
{%- call(slot) text_list(title="Example title for text list") -%}
{%- if slot == "list_item_content_1" -%}
List item content 1
{%- endif -%}
{%- if slot == "list_item_content_2" -%}
List item content 2
{%- endif -%}
{%- if slot == "list_item_content_3" -%}
List item content 3
{%- endif -%}
{%- endcall -%}
Parameters:
- title (required): Title of text section
Slots:
- list_item_content_[1-10] (required): List item content
Highlights
{% from "macros/_macros-highlights.jinja" import highlights %}
{%- call(slot) highlights(num_items=3) -%}
{%- if slot == "highlights_item_content_1" -%}
Highlights item content 1
{%- endif -%}
{%- if slot == "highlights_item_content_2" -%}
Highlights item content 2
{%- endif -%}
{%- if slot == "highlights_item_content_3" -%}
Highlights item content 3
{%- endif -%}
{%- endcall -%}
Parameters:
- num_item (requires 3-4 items): Number of highlight list items
Slots:
- highlights_item_content_[1-4] (required): Highlights list item content, it must have the same number of items as num_item.
Basic text section
{% from "macros/_macros-text.jinja" import text %}
{%- call(slot) text(title="Example title") -%}
{%- if slot == "content" -%}
<p>Example paragraph 1</p>
<p>Example paragraph 2</p>
<p>Example <a href="">rich text</p>
{%- endif -%}
{%- endcall -%}
Parameters:
- title (optional): Title of the text section
Slots:
- content (required): Description of text section, each list item is a paragraph. The paragraph can also include rich text.
Image section
{% from "macros/_macros-image.jinja" import image_wrapper %}
{%- call(slot) image_wrapper(caption="Example caption", right_align="false") -%}
{%- if slot == "image_content" -%}
{{ image(url="...",
alt="...",
width="...",
height="...",
hi_def="True",
loading="lazy",
attrs={"class": "p-image-container__image"}) | safe
}}
{%- endif -%}
{%- endcall -%}
Parameters:
- caption (optional): Caption for image
- right_align (optional): If image should be right aligned, false by default.
Slots:
- image_content (required): Slot for image content, the image must have the class “p-image-container__image”
Video section
{% from 'macros/_macros-case-study-video.jinja' import case_study_video %}
{%- call(slot) case_study_video(top_rule_variant="muted", title="Optional video section title", video_id="i9oDHGPBlwo", video_title="Trusted open source for everyone", caption="Optional video caption goes here") -%}
{%- if slot == "content" -%}
<p>
Optional paragraph text: To meet these challenges, Canonical deployed its Kubernetes and Ceph distributions across data centres located at ESA’s European Space Operations Centre in Darmstadt, Germany. Canonical assisted ESA in the architecture, design and deployment of Kubernetes across hundreds of VMs and dozens of clusters, all connected to physical clusters of Ceph storage, as part of its Managed Services offering. Canonical are also working on the deployment of PostgreSQL and Kafka, which will also be a Managed Service, allowing ESA to focus more on supporting mission operations.
</p>
{%- endif -%}
{%- endcall -%}
Parameters:
- top_rule_variant (optional): Variant of the top rule to use (One of “default”, “highlighted”, “muted”, “none”. Default is “muted”)
- title (optional): Title of the video section.
- video_id (required): ID of the YouTube video to embed.
- video_title (required): Title of the video for accessibility
- caption (optional): Caption for the video
Slots:
- content (optional): Main content of the video section.
Footer CTA section
{% from "macros/_macros-cta.jinja" import cta %}
{{ cta(title="Contact us", link="/contact-us", has_modal="true") }}
Parameters:
- title (required): Title of the CTA
- link (required): Link of the CTA
- has_modal (optional): Whether the CTA invokes a modal. Defaults to true.
There is a default CTA applied for each case study, wrapped in {% block cta_content %}. To overwrite the default CTA, make sure to call the macro and wrap it in the cta_content block.
2. Create Discourse post
You have to create a Discourse post to make sure that it shows on the case study index page. You have to create a Discourse post here.
(Please reach out if you do not have access to create a Discourse post)
You can copy the metadata below and fill it up accordingly. Remember to name the Discourse case study post as: [Case study] Title of case study. You should also un-list the post on Discourse to hide it from view. Once the post is published, you will be able to see the case study card on the index page.
Note: Once the case study is merged and live on canonical.com, you need to set the active as true and it should show on the index page.
Note: To show the case study only on canonical.com/case-study and not on ubuntu.com/engage, you need to set the is_static as true.
|Key | Value|
|--- | ---|
|topic_name | Title of case study |
|path | /case-study/<case_study_filename> |
|subtitle | Subtitle of case study to be shown on index card |
|meta_image | Meta image provided in copydoc |
|publish_date | YYYY-MM-DD |
|active | false |
|language | en |
|type | case study |
|tags | product_tag |
|is_static | <optional_boolean> |
Last updated 9 days ago.