cf-component-demo

Contains Jade templates for creating docs and demos for Capital Framework components.

They are built to be consumed by Topdoc (a tool for generating usage guides for CSS). We use Topdoc in a Gruntfile via the grunt-topdoc task.

If you're new to Capital Framework we encourage you to start here.

The templates:

code_examples

A CSS documentation template. This template lists, labels, and exposes the CSS and HTML code for each pattern. It also uses Rainbow for syntax highlighting.

docs

An updated version of code_examples. As soon as docs has been tested enough it will eventually replace code_examples.

simple

A simple template to list and label each pattern. No markup or CSS is shown.

simple-headless

The same as simple except with no html,head,body tags. This allows you to pull the output into another HTML file.

raw

A bare bones template that simply renders the markup for each pattern. This is a good template if you want to browser test your patterns on an isolated page. Optionally you can add html5shiv to polyfill the styling of HTML5 elements in older browsers.

Getting started

First familiarize yourself with Topdoc and the Topdoc comment specification. The general idea is that you place special Topdoc comments in your stylesheet which Topdoc parses and then merges with a Jade template. This repository contains custom templates that use custom Topdoc comment formatting and custom grunt-topdoc task options.

These instructions are from the perspective of a Captial Framework component repository that uses grunt-topdoc to generate demos and docs.

Requirements

• npm
• grunt-cli
• That's it! npm will help you install everything else you need.

Step 1: In package.json list the grunt-topdoc and cf-component-demo npm packages as devDependencies.

"devDependencies": {
  "grunt-topdoc": "~0.2.0",
  "cf-component-demo": "git://github.com/cfpb/cf-component-demo.git"
}

Step 2: Install the devDependencies.

npm install

Step 3: Load the grunt-topdoc task in Gruntfile.js.

grunt.loadNpmTasks('grunt-topdoc');

Step 4: Set up the grunt-topdoc task in Gruntfile.js.

Read about the custom options we set up for these templates

topdoc: {
  demo: {
    options: {
      source: 'demo/static/css/',
      destination: 'demo/',
      template: 'node_modules/fj-component-demo/' + ( grunt.option('tpl') || 'raw' ) + '/',
      templateData: {
        ltIE9AltSource: 'static/css/main.lt-ie9.min.css',
        ltIE8Source: 'static/css/main.lt-ie8.min.css',
        html5Shiv: true,
        family: '<%= pkg.name %>',
        title: '<%= pkg.name %> demo',
        repo: '<%= pkg.repository.url %>',
        custom: '<%= grunt.file.read("demo/custom.html") %>'
      }
    }
  }
}

Step 5: Run the grunt-topdoc task.

grunt topdoc

Your page will be exported to the destination path.

Specs

Custom Topdoc comment specification

Topdoc parameters

We have expanded the YAML structure of what Topdoc handles out of the box. Data that is unique to these templates are labeled with cf-only.

| Key | | Description | | --- | --- | --- | | name | required | A name for a group of patterns. Topdoc assumes everything between two Topdoc comments is a group of patterns. | | family | required, cf-only | This should match the Capital Framework repository name in the grunt-topdoc options. It is used to identify the current components Topdoc comments so that it can ignore any other Topdoc comments that might come from other dependencies. | | tags | | An array of obligatory tags. Right now we are tagging each pattern group with the current component family and any dependency family. In the future we hope to use these tags for enhancements such as listing all patterns with a specific dependency. | | patterns | cf-only | An array containing pattern objects. Patterns are broken up into groups. For example, default buttons, secondary buttons, and tertiary buttons, would all be good candidates for pattern groups. Within each group, you can list the available patterns; for example, .btn and .btn:hover would each be their own pattern. | | patterns[i].name | cf-only | The name of the pattern. | | patterns[i].codenotes | cf-only | An array of notes. Code notes are wrapped in <pre> and <code> tags and appear in a list. | | patterns[i].notes | cf-only | An array of notes. Notes appear in a list as normal text. | | patterns[i].markup | cf-only | You can write HTML in here and two things will happen. 1: The HTML will be rendered on the page. 2: The code will be exposed in pre & code tags. |

Example comment formatting

/* topdoc
    name: Example group name
    family: cf-example-component
    patterns:
    - name: Example pattern name
      codenotes:
        - "Code notes are wrapped in pre and code tags and appear in a list."
        - "..."
        - "..."
      notes:
        - "Notes appear in a list as normal text."
        - "..."
        - "..."
      markup: |
        <p>You can write HTML in here and two things will happen.</p>
        <ol>
          <li>The HTML will be rendered on the page.</li>
          <li>The code will be exposed in pre code tags.</li>
        </ol>
    - name: You can keep adding patterns
      markup: |
        <p>Foo.</p>
    tags:
    - example-tag
*/

.a-css-rule {
...
}

.another-css-rule {
...
}

/* topdoc
  name: EOF
  eof: true
*/

Ignoring the rest of the stylesheet

By default, Topdoc uses all CSS after a Topdoc comment. This means that if you concatenate your CSS files together, there is a chance that unrelated CSS will be associated with your last Topdoc comment. To get around this, you can either make sure that your CSS is last to be concatenated or you can use the EOF comment block. This comment block tells Topdoc to ignore everything that comes after; it looks like this:

/* topdoc
  name: EOF
  eof: true
*/

Custom grunt-topdoc options

| Key | | Description | | --- | --- | --- | | source | required | A directory containing CSS to be parsed and merged with a Jade template. Ignores .min files. Defaults to src/. | | destination | required | The destination directory where the usage guides will be written. | | template | required | The path to the Jade template file. If it is a directory it will import all the sub files. | | templateData | required | An object containing data to be passed to the Jade template. | | templateData.title | required | A title to give to the page. It's used in <title>. It's also used as an <h1> for the page in the code_examples and simple templates. | | templateData.family | required | This is the identifier that should also be used in the component's Topdoc comments. It is used to ignore any other Topdoc comments that might come from dependencies. | | templateData.repo | required | A link to the repository. The code_examples template uses this to link out to the source code. | | templateData.html5Shiv | | You can optionally add the HTML5 Shiv to the template by setting this option to true. Set it to false or exclude this option if you don't need it. Only used in the raw template. | | templateData.ltIE9AltSource | | A path to use if you need to serve an alternate version of your CSS to IE less than 9. Only used in the raw template. | | templateData.ltIE8Source | | A path to use if you need to include an additional stylesheet for IE less than 8. Only used in the raw template. | | templateData.custom | | A string of HTML to be appended to the raw template. Use grunt.file.read if you want to point to a file and convert it into a string. Only used in the raw template. |

Example Grunt task

topdoc: {
  demo: {
    options: {
      source: 'demo/static/css/',
      destination: 'demo/',
      template: 'node_modules/fj-component-demo/raw/',
      templateData: {
        title: '<%= pkg.name %> demo',
        family: '<%= pkg.name %>',
        repo: '<%= pkg.repository.url %>',
        html5Shiv: true,
        ltIE9AltSource: 'static/css/main.lt-ie9.min.css',
        ltIE8Source: 'static/css/main.lt-ie8.min.css',
        custom: '<%= grunt.file.read("demo/custom.html") %>'
      }
    }
  }
}

Getting involved

We welcome your feedback and contributions.

• Find out about contributing
• File a bug using this handy template

Open source licensing info

1. TERMS
2. LICENSE
3. CFPB Source Code Policy