Topics

Filters


In This Guide

By default, Styleguide lists all of the available templates sorted by directory and file name. As your Styleguide project grows, you may want to limit the display so designers can quickly focus on the templates pertinent to the theme.


Adding a UI filter

For a given theme, you can add a filtering control so designers can quickly isolate the template to view.

  1. In a text editor, open the default or theme-specific configuration file _config.json.
  2. Add a key /navigation/filters.
  3. For each filter you want to add, do the following:

    1. Add a key for the filter label.
    2. Add an array of filename patterns to include in the filter. The patterns are case sensitive and should end in .html or use a file glob. The rules for pattern matching are similar to those for glob.

The following snippet is an example of adding filters to Styleguide.

{
  "navigation": { 
    "filters": {  
      "Articles": [  
        "/*Article*.html" 
      ],
      "URLs": [  
        "twitter/*Url*.html", 
        "instagram/*Url*.html",
        "facebook/*Url*.html"
      ],
      "Pages": [  
        "/styleguide/core/page/*" 
      ]
    }
  }
}
  • Declares filters for Styleguide.
  • Defines a filter for articles, declares the filter’s label.
  • Lists the file pattern included in the filter—any template that includes Article in the file name.
  • Defines a filter for URLs; declares the filter’s label.
  • Lists the file patterns included in the filter—files in three different directories with Url included in the filename.
  • Defines a filter for a directory of templates, declares the filter’s label.
  • File glob for filtering all of the templates in the directory /styleguide/core/page/.

The following illustration is an example of the resulting filters.

Filtered styleguide


Filtering templates with file globbing

Most Brightspot themes have a large number of templates that address virtually all types of digital publishing. The following diagram shows a small subset of the templates available in the default theme.

express/
└── styleguide/
    ├── auth/
    ├── blog/
    ├── community/
    ├── core/
    ├── facebook/
    ├── googleplus/
    ├── instagram/
    ├── linkedin/
    ├── pinterest/
    ├── tumblr/
    ├── twitter/
    └── youtube/

If your Brightspot project uses only some of those templates, you can filter the unneeded ones using the key visibleExamples in the configuration file _config.json. This reduces the number of extraneous templates designers see in Styleguide. For example, if your Brightspot project only posts to social networks, you can filter the templates in Styleguide to only those associated with social networking.

The examples in the following sections use file globbing at the directory level; file globbing for template filtering is not available at the individual template level. For example, you can filter on templates matching the pattern /facebook/**/*, but not the pattern /facebook/**/OpenGraph*. See _hidden for information about hiding at the template level.

Filtering with a single glob

You can filter templates with a single glob within the theme’s configuration file _config.json.

{
  "hiddenExamples": true, 
  "visibleExamples": "/facebook/**/*" 
}
  • Activates the filtering mechanism. This line is mandatory.
  • Filters for templates matching the file glob <template_directory>/styleguide/facebook/**/*.

The following illustration shows the result of the above filter.

Filter with single file glob

Filtering with multiple file globs

You can filter with multiple globs within the theme’s configuration file _config.json. Using this technique you can display templates from multiple directories.

{
  "hiddenExamples": true,
  "visibleExamples": [
    "/facebook/**/*",
    "/googleplus/**/*",
    "/twitter/**/*"
  ]
}

Referring to the previous snippet, Styleguide displays the templates in only the following directories:

  • <template_directory>/styleguide/facebook/**/*
  • <template_directory>/styleguide/googleplus/**/*
  • <template_directory>/styleguide/twitter/**/*

Filtering on globs from template sources

Most Styleguide themes import templates from the default theme, and you may have customized themes that import templates from other themes as well. You can filter the imported templates using file globbing so only certain ones appear in the Styleguide UI.

{
  "sources": [ 
    {
      "source": "/styleguide", 
      "hiddenExamples": true,
      "visibleExamples": "/facebook/**/*" 
    }
  ]
}
  • Activates the filtering mechanism. This line is mandatory.
  • Indicates that the current theme imports templates from the global theme directory brightspot/express/styleguide/.
  • Filters for templates in the directory facebook/ within the sourced directory. You can also use an array of file globs as explained in Filtering with multiple file globs.