Support and Documentation

Theme management

This concepts guide provides explanations for themes.

Style packages

An uploaded style package can contain CSS, JavaScript, or both. It can also be combined with a built-in style package to modify or extend the styles that are provided. This behavior can be specified on the Theme configuration page under Built-In CSS and Built-In JS.

Style_Package_Configuration.png
Back end

The Style Package module adds a stylePackage field to Theme in a modification. This can be accessed in the view model like so:

return Optional.ofNullable(WebRequest.getCurrent().as(ThemeRequest.class).getCurrentTheme())
        .map(theme -> theme.as(StyleThemeModification.class).getStylePackageOrDefault())
        .map(stylePackage -> createViews(viewClass, stylePackage))
        .orElse(null);

See the vm-style-package module for the implementation of StylePackageViewModel. The key line is:

StylePackageUrls urls = model.resolveForCurrentRequest();

This line returns absolute URLs suitable for rendering on the front end. It is not necessary to pass these URLS to the {{cdn}} helper.

Front end

The following template file links a style package's CSS and JavaScript to the front end.

{!-- StylePackage CSS --}
{{#each stylePackage}}
    {{#with cssUrl}}
        <link data-cssvarsponyfill="true" class="Webpack-css" rel="stylesheet" href="{{this}}">
    {{/with}}
    {{#with additionalCssUrls}}
        {{#each this}}
            <link data-cssvarsponyfill="true" class="Webpack-css" rel="stylesheet" href="{{this}}">
        {{/each}}
    {{/with}}
{{/each}}

{!-- StylePackage JS --}
{{#each stylePackage}}
    {{#with jsUrl}}
        <script src="{{this}}" async></script>
    {{/with}}
    {{#with additionalJsUrls}}
        {{#each this}}
            <script src="{{this}}" async></script>
        {{/each}}
    {{/with}}
    {{#with error}}
        <script>console.log("{{this}}")</script>
    {{/with}}
{{/each}}

To use the supplied StylePackageViewModel, modify page.json in the root style guide to include the definition for the following view model:

Give your front end access to the view model by including StylePackage.json in the theme. In page.json, include the following stanza.

"stylePackage": {
  "_include": "StylePackage.json"
}

The following snippet shows StylePackage.json:

{
  "_view": "page.StylePackage",
  "cssPath": "/styleguide/All.min.css",
  "jsPath": "/styleguide/All.min.js",
  "additionalCssPaths": [""],
  "additionalJsPaths": [""],
  "error": ""
}