GCDigital Tools views documentation

Give feedback about this page

We encourage you to submit feedback using one of the following open feedback options:

If you encounter issues with the open feedback options then please contact us through the OneGC email account.

Filters

Content details
Development stage
Section type
Exclusive filters

Overview

The GCDigital Tools views are generated from the GCDigital Tools dataset and can make the GCDigital Tools more relevant and easier to use for certain tasks by providing only the information that is relevant to the task and ordering it in a way that makes sense for the user.

There are four steps to creating a GCDigital Tools view:

  1. Defining the view structure
  2. Tagging content that is relevant to the view
  3. Creating a page that retrieves and displays tagged content
  4. Testing the view

Defining the view structure

The view structure consists of two levels of content groupings, view pages and view page sections. View pages can be used to divide up content according the logical steps for a task or scenario, helping users to focus on what is relevant for a given step. View page sections can be used to group and order content on a page to make it easier to consume for users.

View pages

To determine which view pages are needed, consider the logical steps for the task or scenario for which the view is addressing. For instance, a task with four discrete phases could have a view page for each phase, allowing users to proceed from phase to phase, only being presented with the content that is relevant to the current phase.

For each view page, determine which content should be included. Varying sizes of blocks of content can be included, from large content sections to much smaller blocks of content such as individual list items and paragraphs. The content that will be included on a view page can be controlled by applying one or more tags to that content.

For more details about the dataset structure, see the GCDigital Tools dataset schema.

For simple views, the default page sections and ordering of content can be used to present the content that is included in the page. For more advanced views, the content could be reordered or combined in different ways to produce different page structures and designs.

It is recommended that any custom page sections and ordering of content be designed and tested with users to ensure that the resulting view page is easy for them to use and meets their needs. Custom page sections can be produced by using tags to create new content groupings, which don't exist in the Playbook by default, which can then be retrieved from the dataset and output to sections in the view page.

Tagging content that is relevant to the view

Each piece of content can be tagged through the use of CSS classes, where each piece of content can have multiple tags. There is no specific naming convention for tags, but they do need to be unique. There should be a unique tags for view-level content grouping and each page-level content grouping. The tag can be either an existing supported tag or a new tag. The suggested format for new tags is: dpgn-<group>-<item> (e.g., dpgn-stage-alpha).

Tags can be applied directly to content in the source .md files, using either the HTML class attribute (for blocks of HTML content) or through the Kramdown approach for applying CSS classes (for blocks of Markdown content). Tags applied to a parent container (e.g., list) will also apply to the child items.

Content type HTML example Markdown (Kramdown) example
Section / container 
<section class="dpgn-stage-alpha dpgn-stage-live">...</section>
 n/a
List 
<ul class="dpgn-stage-alpha dpgn-stage-live">...</ul>
 
<!-- markdownlint-disable MD032 -->
- List item 1
- List item 2
- List item 3
{: .dpgn-stage-alpha .dpgn-stage-live}
<!-- markdownlint-enable MD032 -->
List item 
<li class="dpgn-stage-alpha dpgn-stage-live">List item</li>
 
- {: .dpgn-stage-alpha .dpgn-stage-live} List item
Table 
<table class="dpgn-stage-alpha dpgn-stage-live">
 
| Header 1 | Header 2 |
|----------|----------|
| Data 1   | Data 2   |
{: .dpgn-stage-alpha .dpgn-stage-live}
Table row 
<tr class="dpgn-stage-alpha dpgn-stage-live">
 n/a
Table cell 
<td class="dpgn-stage-alpha dpgn-stage-live">Table cell</td>
 n/a
Paragraph 
<p class="dpgn-stage-alpha dpgn-stage-live">Paragraph content</p>
 
Paragraph content
{: .dpgn-stage-alpha .dpgn-stage-live}

Supported tags

The following tags are supported by default by the Digital Playbook:

View tags:

Section tags:

Section tags are mainly used for dataset generation and filtering. Each of these tags should only be used to identify sections or containers of the specified type.

Special tags:

Creating a page that retrieves and displays tagged content

The GCDigital Tools provides several helper functions to make it easier to produce the desired output. This section will cover the basics of building a view page and the available helper functions.

Building a view page

  1. Create English and French .md files for each view page using the template files in views-vues/view-template-modele-vue/. These new .md files should placed in "en" and "fr" folders in the directory for the new view (views/&lt;view-name&gt;).</li>
  2. For each .md file, update the following properties in the data at the start of the file delimited by "—":
    1. title: Title of the view page
    2. altLangPage: Filename (without extension) for the .md file in the other language
    3. collectionDirectory: Folder for the view (in the form views/&lt;view-name&gt;)
  3. Build the content for each .md file:
    • Simple views: Update the relevantTags parameter in the include statement with the tags for the view page. Multiple tags should be separated with commas (e.g., "dpgn-stage-alpha,dpgn-stage-live").</li>
    • Advanced views: Use the GCDigital Tools helper functions and/or build custom output using Jekyll and Liquid on the Playbook data from site.data.playbook (English) or site.data.guide (French).

Helper functions

The following are three of the more commonly used helper functions. For the rest of the functions, see _includes/functions (each function has usage instructions in the comments at the beginning of the file).

filtered-standard-guideline-content.html

output-guideline.html

output-sections.html

output-section-content.html

output-content-array.html

Including content from the view in the Playbook dataset

Normally the source of content for the Playbook dataset are the .md files in the /en and /fr directories. It is also possible to include content from the /views-vues directory. To do that, add the data-dpgn-data-include attribute to the content in question.

The content can only be added to a sub-section of a guideline or standard within the dataset. The supported sections are the named sections with the standard or guideline (introduction in the case of a standard and introduction, checklist, guides or solutions in the case of a guideline).

Note: When applying the attribute in Markdown files, the curly brackets need to be escaped:

- {: data-dpgn-data-include='&#123; "guideline": "8.2", "section": "checklist" &#125;'} List item content

Testing the view

  1. If not already done, set up GitHub pages for your repository:
    1. Go to the repository settings
    2. In the GitHub pages section, set "Source" to "gh-pages branch"
  2. Create a new "gh-pages" branch from the branch used to create the view
  3. Go to your branches page. Refresh the page periodically until the gh-pages build for the gh-pages branch either passes (green checkmark) or fails (red x).
  4. If the build passes, the view can be found at https://<github-handle>.github.io/digital-playbook-guide-numerique/views-vues/<view-directory>/en/<filename>.html
  5. If the build fails, review your code and correct the error. To get the build error messages, you can use Travis-CI by:
    1. Going to the Travis-CI website
    2. Sign in using your GitHub account
    3. Go to your profile (upper-right corner)
    4. Click the "Sync account"
    5. Enable integration for the <username>/digital-playbook-guide-numerique repository
    6. Do a new push to the branch used to create the view (e.g., make a change and commit it).
    7. Go to the branches page and wait for the Travis-CI build to complete. If the build fails then review the Travis-CI log (can either be reached through the Travis-CI website or by clicking the red "x" and then clicking Travis-CI).