Skip to content

Latest commit

 

History

History
143 lines (95 loc) · 7.01 KB

resources.md

File metadata and controls

143 lines (95 loc) · 7.01 KB

Resources

Resource Basics

Shunter uses Mincer to compile and serve assets required by the front end such as CSS, JavaScript and image files. In the case of JavaScript and CSS, dependent files can be required from within a single file that will then be referenced within a layout template. Mincer makes use of EJS templating to manage requiring of resource files.

Mincer takes a load path and handles every file it finds within that directory. Mincer creates a logical path for each asset, and bases its logical path on the relative folder structure to the load path. In production mode, Mincer will reference a manifest file to match these logical paths to fingerprinted file names.

Note: if two assets are loaded that have the same logical path, the first one in 'wins'. This is important if you are using modules to load in extra resources and templates.

For example if a module you were using were to have resources/css/foo.css, it would result in the logical path 'foo.css'. However, when the resources for your host app are loaded in and it also has resources/css/foo.css, this too will be given the logical path 'foo.css' and because the asset path for your host app is loaded first, it 'wins'. This can be useful for deliberately overriding, but if you wanted both files then your host apps file would need to be different, e.g. foo_ext.css. For more information on how inheritance works see the Modules and Inheritance page.

Writing CSS

By default CSS files should be placed in a directory named css within a resources directory in the root of your Shunter application. The location of the resources and CSS directory can be modified by overriding the defaults in the config object.

You might want to set up a main.css.ejs in resources/css to act as your manifest file. It will require your other internal stylesheets and set some defaults. If you are including modules with CSS files in them, you could refer to them here.

CSS files can be included in your layout template by using the Dust assetPath helper. This helper will determine the location of your file according to the type of file that it is and retrieve it from the location specified in your config files. By default this helper will look for CSS files in the resources/css directory so the following would create a path to main.css residing in the resources/css folder:

<link rel="stylesheet" href="{@assetPath src="main.css"/}"/>

Further CSS files may be required from within a CSS file in the following way:

/*
 *= require bootstrap.css
 */

If you would like to recursively include an entire directory of CSS files you may use the 'require_tree' directive. eg:

/*
 *= require_tree components
 */

Writing Javascript

You should set up main.js.ejs in resources/js within the root of your Shunter application JavaScript files should be placed here. The location of the resources and JavaScript directory can be modified by overriding the defaults in the config object.

Javascript files can be included in your layout template by using the Dust assetPath helper. This helper will determine the location of your file according to the type of file that it is and retrieve it from the location specified in your config files. By default this helper will look for JavaScript files in the resources/js directory so the following would create a path to main.js residing in the resources/js folder:

<script src="{@assetPath src="main.js"/}"></script>

Further JavaScript files may be required from within a JavaScript file by doing the following:

//= require jquery-1.9.1.js
//= require components/forms.js

If you would like to recursively include an entire directory of JavaScript files you may use the 'require_tree' directive. eg:

//= require_tree components

Adding Images

Images can also be included using the assetPath helper. Image files should be placed in a directory named img within a resources directory in the root of your Shunter application. The location of the resources and img directory can be modified by overriding the defaults in the config object.

background-image: url(<%= asset_path('icons/png/icon-login-25x25-white.png') %>);
<img src="{@assetPath src="myimg.png"/}" alt="" />

Other Static Assets

Static assets are possible, but you should only use these when you are unable to utilise Mincer (e.g. html emails, 500 error page).

By default, assets in the public subdirectory are served on the path public.

If it isn't convenient to have one or both of these as 'public' you can override them by setting the config option using config.path.public for where the assets are saved and config.web.public for the path that you would like to serve them on.

Built In EJS Extensions

Mincer uses an EJS engine for pre-processing assets within resource files. Assets to be included must therefore include the .ejs suffix

Shunter uses an implementation of the Mincer assetPath helper that is distinct from Shunter's Dust assetPath helper. It behaves in a similar way and this is what you would use to return paths to assets in a CSS file, for example:

#logo {
	background: url(<%= asset_path('logo.png') %>);
}

Writing EJS Extensions

You can write your own EJS helpers to assist with the processing of CSS and JavaScript. Custom EJS extensions should sit in a directory named ejs within your Shunter application.

EJS helper files must export a single function which is called with the Mincer environment, manifest and Shunter config object.

An example helper might look like the following, which outputs the current year:

// <app>/ejs/current-year.js
module.exports = function(environment, manifest, config) {
	environment.registerHelper('currentYear', function() {
		var date = new Date();
		return date.getFullYear();
	});
};

Production Differences

Shunter provides a build script that will do the following things for a production environment:

  • Concatenate and minify CSS and JavaScript
  • Write static files to public/resources with MD5-fingerprinted file names for cache invalidation
  • Create a manifest.json file that maps the logical names for resources to their actual fingerprinted file names

To run the build script:

./node_modules/.bin/shunter-build

After this script has run, you should see that the public directory in your project has a resources subfolder, with all your compiled assets present.

To run Shunter in production mode (and use the built resources):

NODE_ENV=production node app.js