Resolving Path References

Default Path References

When Styleguide builds a custom theme, it includes the resources in the theme’s directories. Styleguide looks up files that are referenced by other data or template files, which can be specified with absolute or relative paths.

Example: Absolute Path

The ArticleBreakingNews.json file is theme-specific, residing in the /themes/mytheme/styleguide/article directory. The _include key in the file is set to /article/ArticlePage.json.

The Styleguide lookup logic is as follows:

  1. In the theme-specific directory, look for /themes/mytheme/styleguide/article/ArticlePage.json.
  2. Throw exception if file not found.

Example: Relative Path

The EmployeePage.json file is theme-specific, residing in the /themes/mytheme/styleguide/corporate/employee directory. The _include key in the file is set to ../../core/page/ContentPage.hbs.

The Styleguide lookup logic is as follows:

  1. In the theme-specific directory, look for /themes/mytheme/styleguide/core/page/ContentPage.hbs.
  2. Throw exception if file not found.

You can add additional paths for searching for theme files; for details, see Extended Path References.

Extended Path References

The section Default Path References states that by default, Styleguide looks for files only within the current theme’s directory. You can add additional path references using the sources key in the theme’s configuration file _config.json.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
   "sources": [
       {
         "source": "/path/to/templates1"
       },
       {
         "source": "/path/to/templates2"
       }
   ]
 }

In the previous snippet, lines 4 and 7 indicate Styleguide includes templates found in the directories /path/to/templates1/ and /path/to/templates2/—in addition to the current theme’s directory.

Styleguide’s standard themes, such as Frost and Falcon, import the default theme. As a result, if you are sourcing from a standard theme, you should not source the default theme.

See also:

Retaining Theme Files with Identical Names

At build time, Styleguide collects all of a theme’s files (template, data, styling) into the directory target/classes/. If you have any sources for the theme, there is a possibility that two or more sources have files with the same name. Therefore, by default, Styleguide overwrites files that have the same name, retaining the last one found.

Consider a custom theme that has the following configuration file _config.json.

{
  "sources": [
    {
      "source": "/themes/parent-theme/styleguide"
    }
  ]
}

In the previous snippet, Styleguide collects files from two themes: first from the sourced theme’s directory express/themes/parent-theme/styleguide/, then from the custom theme’s own styleguide/ directory. If there is a file named BirthdayParty.hbs in both themes, Styleguide retains the one from the custom theme, because that theme is always sourced last.

../../_images/styleguide-template-overwrites.svg

In the previous diagram, Styleguide found two files named BirthdayParty.hbs. While processing the first set of files in the parent theme, it placed the first occurrence of BirthdayParty.hbs inside the build directory target/classes/events/. After finding the second occurrence inside the custom theme, it overwrote the first occurrence.

You can retain files with the same name by adding a key destination to the corresponding source key.

1
2
3
4
5
6
7
8
{
  "sources": [
    {
      "source": "/parent-theme",
      "destination": "family"
    }
  ]
}

In the previous snippet, line 5 indicates that at build time, Styleguide collects all files originating from the parent theme into a target directory family/—implying that files with the same name are preserved.

../../_images/styleguide-template-preserve.svg

See also:

Filtering Sourced Themes with Globbing

If you have a parent theme sourced into a custom theme, you can filter for only those parent templates you want to include in the custom theme. This technique reduces the custom theme’s complexity and corresponding debugging and build time.

1
2
3
4
5
6
7
8
{
  "sources": [
    {
      "source": "/themes/parent-theme/styleguide",
      "files": "events/Anniversary*"
    }
  ]
}

In the previous snippet, line 5 filters for only those files in the parent theme’s path events/Anniversary* (all files in the subdirectory events that start with Anniversary). You can filter files using any globbing pattern described in Glob Primer.

See also:

Suppressing a Source from Styleguide’s UI

If you are sourcing several parent templates into one larger custom template, you can suppress the parent templates from the Styleguide’s UI using the key hidden.

1
2
3
4
5
6
7
8
{
  "sources": [
    {
      "source": "/themes/parent-theme/styleguide",
      "hidden": true
    }
  ]
}

In the previous snippet, line 5 processes all of the templates in parent-theme, but those templates do not appear in the Styleguide UI. (The templates are available for use as Views in the backend.) The default value for hidden is false, so omitting this key is equivalent to including all of the templates in the UI.

See also: