Scripts and Stylesheets

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

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:

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.

PropertyDescription
dotminUse .min.css as the output file extension after minification. Otherwise will be .css. Default to true.
enableEnable the service.
filesArray of file patterns to process. Defaults to ['**.css', '!**.css.map', '!*.less']. May include negated patterns beginning with !.
minifyEnable minifying of Javascript files. Default to false.
prefixAutoprefix styles using vendor specific browser prefixes. Defaults to true.
usemapUse minified stylesheet if corresponding source maps is present. Defaults to true.
useminUse minified stylesheet if present. Defaults to null. Set explicitly to false to disable the use of minified resources.

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:

Configuration Properties

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

PropertyDescription
dotminUse .min.js as the output file extension after minification. Otherwise will be .js. Default to true.
enableEnable the service.
filesArray of file patterns to process. Defaults to ['lib/**.js', '!lib/**.min.map']. May include negated patterns beginning with !.
forceAlways minify even if a minified version exists in contents. Default to false
minifyEnable minifying of Javascript files. Default to false.
usemapUse minified stylesheet if corresponding source maps is present. Defaults to true.
useminUse minified stylesheet if present. Defaults to null. Set explicitly to false to disable the use of minified resources.

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:

$ 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

Want More?

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

© Embedthis Software, 2003-2015. All rights reserved.