gsa-logo
Important COVID-19 News:
To find healthcare service providers and pricing, visit Health care
For additional information click here.

CALC Style Guide Documentation

Welcome to the CALC Style Guide Documentation! Here you'll find guidelines on how to update and add new content to the CALC Style Guide.

Overview

The style guide is a Django app in the styleguide directory. The bulk of its textual content is in styleguide/templates/styleguide.html, which is a standard Django template.

Supporting the style guide is the styleguide template tag library, which provides some of the technical infrastructure to display the guide and ensure its content is accurate.

Providing direct links to source files on GitHub is a great way to familiarize newcomers with the codebase and figure out where all the code related to a particular piece of front-end technology is located.

The {% pathname %} template tag is useful for linking to any CALC source file or directory relative to the root of the repository. The relative path is displayed along with a hyperlink to view the file or directory on GitHub.

At render time, the existence of the file or directory is also verified and an exception is thrown if it doesn't exist, to prevent documentation rot.

Example

See README.md for some basic info.
  See {% pathname "README.md" %} for some basic info.

More specialized template tags are available for linking to specific types of source files.

SASS

You can link to SASS relative to the root of CALC's SASS directory in frontend/source/sass:

Example

See base/_debug.scss for some debug-specific SASS.
  See {% scss "base/_debug.scss" %} for some debug-specific SASS.

JavaScript

You can link to JS relative to the root of CALC's JS directory in frontend/source/js:

Example

See common/ga.js for Google Analytics stuff.
  See {% js "common/ga.js" %} for Google Analytics stuff.

Web components

The {% webcomponent %} tag can be used to link to the source code for a web component (also known as a custom element).

Example

We use an <upload-widget> with a nested <input is="upload-input"> to progressively enhance the front end.
  We use an {% webcomponent '<upload-widget>' %} with a nested
  {% webcomponent '<input is="upload-input">' %} to
  progressively enhance the front end.

Determining the source file of a web component is actually non-trivial, and a SOURCE_FILENAME property needs to be defined on the prototype of every web component mentioned in the style guide, or else an alert will be displayed.

Under the hood, this is accomplished via the <a is="web-component-link"> component. See its source code for more guidance on how to define the SOURCE_FILENAME property on your custom elements.

Python objects

You can link to the source code of any Python object, too:

Example

See styleguide.views.docs for this page's Django view.
  See {% pyobjname 'styleguide.views.docs' %} for this
  page's Django view.

Django templates

You can also link to a template via its template path:

Example

See our admin overrides at admin/base.html.
  See our admin overrides at {% template_link "admin/base.html" %}.

You can also render just the GitHub URL for the template source with the {% template_url %} tag.

Template tags

You can link to the source code for custom template tags via {% template_tag %}, and tag libraries via {% template_tag_library %}:

Example

The {% template_tag %} tag from the styleguide library is nice.
  The {% template_tag 'styleguide' 'template_tag' %} tag from
  the {% template_tag_library 'styleguide' %} library is nice.

Example areas

The {% example %} tag can be used to provide inline example areas with their HTML source code displayed:

Example

Example

CALC's about page URL is at /about/.

<p>CALC's about page URL is at /about/.</p>
  {% example %}
  <p>CALC's about page URL is at {% url 'about' %}.</p>
  {% endexample %}

It's important to note that the code snippet shown is the the example's source after it's been processed by the templating engine. If you instead want the original, "raw" source to be shown in the code snippet, you can use the {% template_example %} tag:

Example

Example

CALC's about page URL is at /about/.

  <p>CALC's about page URL is at {% url 'about' %}.</p>
  {% template_example %}
  <p>CALC's about page URL is at {% url 'about' %}.</p>
  {% endtemplate_example %}

Full-page examples

It's sometimes useful to have example areas be contained in their own iframes that can be popped-out into separate browser tabs for further inspection. This can be done using the {% fullpage_example %} tag.

To use this tag, you'll need to make a template in the styleguide/templates/styleguide_fullpage_examples directory.

For example, suppose we've created a simple template at styleguide_fullpage_examples/inception.html with the following content:

{% extends "styleguide_fullpage_example.html" %}

{% block body %}
{# BEGIN SNIPPET #}
<h1>Full-page inception!</h1>
{# END SNIPPET #}
{% endblock %}

Note the presence of {# BEGIN SNIPPET #} and {# END SNIPPET #}: these aren't just comments, they actually specify what should be shown in the source code area of the example. This allows us to easily omit code that's necessary for the rendering of the template, but extraneous to the concept being communicated.

We can embed the template as a full-page example area by passing the name of the template without its file extension:

Example

Example

<h1>Full-page inception!</h1>
  {% fullpage_example "inception" %}

Sometimes we may not want to show any source code in the example, which can be accomplished by passing an extra argument to the tag:

Example

Example

  {% fullpage_example "inception" show_html=False %}

Sections

The {% guide %} tag can be used to create a table of contents (TOC). Between its start and end tags, {% guide_section %} can be used to add individual sections, which are linked from the TOC.

Example

{% guide %}

{% guide_section "Introduction" %}
<p>Here is an introduction!</p>

{% guide_section "Stuff" %}
<p>Here is where we write about stuff!</p>

{% endguide %}

Currently, the TOC is flat rather than hierarchical: there's no way to define subsections of sections. You can manually create subsections by using the <h4> tag, but these won't be listed in the TOC.