Theme resources

A resource is CSS or JavaScript that you want to include in your theme. Resources are used for visual styling and for providing additional front-end components.

With resources, you can specify when your resources should be included and where in the page's head area they should be included.

When - CSS classes and dependencies

Rather than serve resources all the time, Metrici provides very fine control to tailor exactly which resources are included in the head area of the page. Removing little-used resources from most pages improves the user experience, while still allowing specialist resources to be brought in on the pages that need them.

Resource inclusion is controlled by CSS classes in the page itself. This is intuitive for CSS and for modern JavaScript which binds jQuery functions to class-based selectors. For example, you might have a custom CSS class "mybox" to style a box, and a resource with reference "mybox" that includes the CSS to support the class. The resource inclusion rules means that the CSS for mybox is only brought in when the mybox class is actually used.

As well as responding directly to CSS classes, resources can require other resources. For example, if mybox required both CSS and JavaScript, you could say that the mybox resource requires the mybox-css and mybox-js resources. The mybox-css and mybox-js resources can then be used to bring in the appropriate CSS and JavaScript.

In addition to CSS classes, the resource inclusion always includes a resource called "head", which requires two other resources, "standard" and "custom". The standard resource is used to bring in all the standard head material for Metrici, and you can replace the customer resource so that it requires your custom CSS and JavaScript. An example of this is given below.

Where - ordering rules

Knowing what CSS and JavaScript to bring in is only half the story. Because of the the way CSS works and because of dependencies between JavaScript libraries, you need fine control over the order in which the resources are written to the head area.

To achieve this, each resource can provide one or more follows statements. These list resources that, if present, this resource must follow. Note that the follows statement does not imply dependency. If you need Resource A prior to Resource B in your head area, then you have to say both that Resource B requires Resource A and that Resource B follows Resource A.

You can also use the precedes statement to ensure that your resource should precede another one. So "B follows A" has exactly the same effect as "A precedes B". Precedes is useful because it allows you to place your resource in front of resources that you don't want to change, such as standard resources.

Resource ordering can get a bit difficult to understand. To make things simpler, the head area is split into a number of sections, and you can place your resources in a specific section. These are

  • css-framework – CSS frameworks, such as Bootstrap, which should go first.
  • css-standard – standard CSS components, such as Metrici's own CSS.
  • css-theme – CSS that is specific to this theme.
  • js-framework – JavaScript frameworks, such as jQuery, which should go first.
  • js-standard – standard JavaScript components, such as Metrici's own JavaScript and jQuery plug-ins.
  • js-theme – JavaScript that is specific to this theme.

Specifying a section is the same as specifying that your resource depends on section-start and section-end, follows section-start and precedes section-end.

You can use the sections as follows:

  • If you are including branding and stying that you want to include all the time, put your CSS in section css-theme and your JavaScript in section js-theme. You will also want to define the custom resource to require your CSS and JavaScript references.
  • If you are creating new components that will be included only when needed, put your CSS in css-standard and say it follows standard-css. Similarly, put your JavaScript in js-standard and say it follows standard-js.
If your ordering rules can not be resolved consistently (for example, if A follows B and B follows A), then the ordering logic is abandoned and your resources will appear out of sequence. If this occurs, look in the head section of your page for diagnostic information.

Defining resources

Use the Resource (library.theme.ThemeResourceType) type to define resources, and then include them in the Resources list on your theme.

Resources allow you to enter:

  • A reference for the the resource.
  • A section for the resource.
  • Requires, follows and precedes rules.
  • Content for the resource. This is optional - some resources only existing to manage dependencies and ordering.

To illustrate this, consider the following requirement:

  • Across the entire theme, turn the text fuchsia.
  • If there are any mybox components, put a black border around them and show their text when clicked.

The resources you need are as follows:

reference requires section follows precedes content notes
custom mytheme-css         Override the standad custom resource to require mytheme-css.
mytheme-css   css-theme     
<style type="text/css">
  body {
    color: fuchsia;
  }
</style>
 Provides additional CSS that is always brought in.
mybox mybox-js
mybox-css 		         Translates the mybox class into two separate resources.
mybox-css   css-standard standard-css   
<style type="text/css">
  .mybox {
    border: 1px solid black;
    padding: 10px;
  }
</style>

Provides styling for mybox.

The style will be inserted after the standard Metrici styling, but before the custom theme styling.
mybox-js jquery js-standard standard-js   
<script type="text/JavaScript">
  $(function(){
    $('.mybox').click(function(){
      alert($(this).text());
    });
  });
</script>

Provides behaviour for mybox.

Like the styling, this will be inserted after the standard styling but before the custom theme behaviour (if there was any).

This requires the jquery library, which is a standard resource.

See Advanced theme configuration for more details of overriding the standard theme components and applying filters for even finer control.

You can effectively delete a resource brought in from another theme by defining it again, but without any requires, section, follows, precedes or content.