Scripts and Stylesheets

Managing scripts and stylesheets in a web application involves several common tasks:

• Selecting raw or minified versions
• Including excluding map files
• Minifying files

These tasks vary depending on whether the web site is being developed, tested or prepared for production. Expansive supports these use cases via the exp-css and the exp-js.

exp-css

The exp-css plugin manages CSS files and provides the Expansive transformations:

• prefix — Add browser vendor prefixes to CSS rules
• render — Generate HTML link elements for required CSS files
• minify — Minify CSS files to compress
• extract — Extract inline styles to support CSP

The prefix service automatically adds vendor prefixes, such as webkit- to CSS rules. In this way, you can use only the standard, portable CSS rules and prefixes will be prepended as required. The prefix plugin uses the autoprefixer tool.

The render service will intelligently select raw, minified and map files as required. The default configuration is set for a debug mode where minified files will be used if a corresponding map file exists, otherwise the raw CSS file is used. A release mode can be selected via configuration properties a minified version can be selected.

The minify service will minify CSS files to reduce their size.

Configuration Properties

The exp-css services can be enabled and configured via properties in the expansive.json configuration file.

The default configuration without any configuration properties suits a development profile where minified CSS files are used only if they have an associated map file. A default release configuration in expansive.json would look like:

{
    "release": {
        "services": {
            "css": {
                "minify": true
            }
        }
    }
}

This would then be selected via pak mode release.

exp-js

The exp-js plugin managed JS script files and provides the Expansive services:

• minify— Minify JS files to compress
• render— Generate HTML link elements for required JS files
• extract — Extract inline scripts to support CSP

Configuration Properties

The exp-js services can be enabled and configured via properties in the expansive.json configuration file.

The default configuration without any configuration properties, suits a development profile where minified JS files are used only if they have an associated map file. A default release configuration in expansive.json would look like:

{
    "release": {
        "services": {
            "js": {
                "minify": true,
                "usemap": false
            }
        }
    }
}

Automated Library Configuration

You can manually define your <script> and stylesheet <link> elements if you wish. However, as you develop your application and install various script and stylesheet libraries, you will need to manually add or modify references to these script and stylesheet references. If there are dependencies between libraries, order matters. For example, Bootstrap must be loaded after jQuery. While this is not too tedious, Expansive provides an elegant way to automate the generation and maintenance of script and stylesheet element references. As you install and remove packages, the script and stylesheet elements can be adjusted automatically.

If you install your script and CSS libraries using the Pak package manager, Expansive can automatically determine the required script and CSS references and can correctly generate them for you in your HTML.

The exp-css plugin provides the renderStyles API and the exp-js service offer the renderScripts API. These APIs can be placed in your HTML where you would like to generate your script and CSS references. For example, consider an application that installs the following libraries:

• Bootstrap
• Angular
• Angular-Route
• Angular-Animate
• Font-Awesome

$ pak install angular angular-route angular-animate bootstrap font-awesome exp-js exp-css
   [Install] angular 1.3.14
   [Install] angular-route 1.3.9
   [Install] angular-animate 1.3.9
   [Install] jquery 2.1.3
   [Install] bootstrap 3.3.2
   [Install] font-awesome 4.3.0
   [Install] exp-js 0.2.0
   [Install] exp-css 0.2.0
   [Install] jquery 2.1.3
   [Install] bootstrap 3.3.2

The following layout page can use the renderStyles and renderScripts to automatically generate the required HTML for the stylesheets and scripts.

<html>
<head>
    <@ renderStyles() @>
    <@ renderScripts() @>
</head>
<body>
    <@ content @>
</body>
</html>

This will be rendered as:

<html>
<head>
    <link href="angular/angular-csp.css" ... />
    <link href="bootstrap/css/bootstrap.min.css" ... />
    <link href="bootstrap/css/bootstrap-theme.min.css" ... />
    <link href="font-awesome/css/font-awesome.min.css" ... />

    <script src="angular/angular.min.js"></script>
    <script src="angular-animate/angular-animate.min.js"></script>
    <script src="angular-route/angular-route.min.js"><</script>
    <script src="jquery/jquery.min.js"></script>
    <script src="bootstrap/js/bootstrap.js"></script>
</head>
</html>

Note that all required stylesheets and scripts are rendered in the correct order.

renderScripts and renderStyles

The renderScripts and renderStyles APIs have the following signatures:

function renderScripts(filter = null, extras = [])
function renderStyles(filter = null, extras = [])

Where filter is an optional filename pattern or array of patterns. If not supplied, then all the default the scripts/styles are rendered. If filter is provided, only the files that match the filter will be rendered. Wild-cards are supported including ** to match in any directory and ! to negate a pattern and exclude a filename. The optional extras argument is an array of extra files to render. Combined, these two arguments provide the ability to select, include or exclude files.

You can also add files to be rendered by modifying the collections.scripts and collections.styles lists.

Prerequisites

To use this automatic configuration, you must meet these prerequisites

• You must install the relevant libraries using the Pak package manager.
• You must have the exp-css and the exp-js plugins installed.
• You must add renderStyles() and renderScripts() to your page or layout.

Want More?

Use the exp-less to process Less stylesheets and the exp-sass to process Sass stylesheets.