Controllers: Asset Management

Summary

All the assets of your web-application can be placed inside a folder named assets. You can use any folder hierarchy you want.

Assets will be based on the type compiled or otherwise modified before sending them to the client:

• Images will be downscaled for small displays
• SCSS will be compiled to CSS
• JavaScript will be compressed

Features

Caching of compiled files:

The compiled version will be cached and as long as the original file will not be modified, these compiled versions will be delivered.

In the most cases you do not have to delete the compiled assets. The controller will recognize a new version of the origin asset, and will delete the cached one by itself. But removing all the contents inside of the folders holding a compiled version can be done everytime safely. This caches will be rebuild automatically.

It could be useful to delete the entire cache from time to time (e.g. after heavy reconstructions of your assets), because there is no garbage collection. The system will not recognize deletion of original files and the compiled version will stay.

Support of Browser Caching:

Browsers caching techniques are also supported and files will not be delivered at all if they are cached by the browser.

Clients will be informed about the last modification date and the Etag hash-value of the requested file. As long as the browser hold a up-to-date version of the asset, the asset will not be streamed again. Instead the library will send a 304 response, which means that the browser should use the it's cached version.

The handling of Etag has an additional advantage with serving compiled css or javascript files. Unimportant modification in the original file (like insert an empty line) results into the same compiled version and thus into the same Etag. So browsers will be told to use it's cached version and the asset will not be streamed.

Space Saving Handling:

Furthermore every asset handler can decide if a compilation is necessary. If an asset do not need to be compiled the the original file will be send to the client. These technique will be used for example by the image compiler, to save space for useless duplication of images.

Environment Dependence:

The output of some asset types depends on the environment of your CodeIgniter instance (depending on the constant "ENVIRONMENT"). JavaScript files will be compressed for example if you set your environment to production or testing.

General Usage

Links to Assets

Assets will be linked from your html source always pointing to the path assets/PATH_TO_ASSET/FILENAME_OF_ASSET.

To link for example to your css assets named style.css that you have saved in the folder application/assets/some_subfolder_if_needed/style.css use the following tag:

<link rel="stylesheet" href="assets/some_subfolder_if_needed/style.css" type="text/css" />

Special Flags

Behind the asset name you can add a slash and a flag for special purposes (especially for debugging):

• /off The compiler will not be used. The original asset file will be delivered.
• /force The asset will be compiled even if the compiled version is up-to-date.
• /development Deliver always the asset as it would be compiled in a development environment.
• /testing Deliver always the asset as it would be compiled in a testing environment.
• /production Deliver always the asset as it would be compiled in a production environment.
• /force/development Combination of the above options.
• /force/testing Combination of the above options.
• /force/production Combination of the above options.

Here an example how to use these flags:

Retrieve your stylesheet at the "normal" way:
http://domain.tld/assets/style.css

Retrieve your stylesheet as it would be in a production environment:
http://domain.tld/assets/style.css/production

Retrieve your original stylesheet without the use of the compiler:
http://domain.tld/assets/style.css/off

Asset Types

For now the following assets will be processed as follows:

Images

Imagefiles with the extensions jpg, jpeg, gif and png will be resized accordingly to the users display size. All types of displays should be detected, from high density displays like retina displays down to small mobile devices. For this reason you should use high resolution images (twice as big as displayed) from the beginning. The controller will serve the client an image with an optimized size automatically. The only thing you have to pay attention to, is the correct marking of the used img tags and set a little JavaScript into yout page.

The required JavaScript will be automatically inserted if you use the master template library. If you do not use the master template library you can add it manually:

<script>document.cookie='resolution='+Math.max(screen.width,screen.height)+("devicePixelRatio" in window ? ","+devicePixelRatio : ",1")+'; path=/';</script>

You should add this snippet as soon as possible in your head. Here is a best practice example:

<head>
    <meta charset="..." />
    <meta http-equiv="x-ua-compatible" content="...">
    <script>document.cookie='resolution='+Math.max(screen.width,screen.height)+("devicePixelRatio" in window ? ","+devicePixelRatio : ",1")+'; path=/';</script>
    [...]
</head>

The img tag mus have always the correct sizes:

<img width="150" height="50" src="..." />

An example:

Acoording to the given design you have to place an image of 150x50 pixels onto the page. In this case you should save a double-sized image into the img folder with 300x100 pixels. The most important thing now, is to write your img tag with the correct sizes: <img width="150" height="50" src="..." />. That's all. Everything else will be done by the library. Retina-displays will show a sharp image and mobile browsers will get a downsized image.

Used library: http://adaptive-images.com/

Stylesheets

Stylesheetfiles with the extensions css or scss will be compiled as SCSS. You can use variables, nesting, mixins, inheritance etc. and the library will produce the CSS for you. If you dont want or need it, just use simple CSS as always.

To learn more about SCSS read the basic introduction here: http://sass-lang.com/guide

Furthermore the stylesheet will be compressed in a testing or production CodeIgniter environment. Otherwise it will be only normalized.

In case of a compiler error a css comment will be inserted at the beginning of your stylesheet and the stylesheet will be delivered uncompiled.

Used library: http://leafo.net/scssphp/

JavaScript

JavaScript files with the extension js will be automatically minified if you are on production or testing CodeIgniter environment. Otherwise it will be left untouched.

In case of a compiler error a JavaScript comment will be inserted at the beginning of your script and the file will be delivered uncompiled.

Used library: https://github.com/tedious/JShrink

Other Binaries

For other files for now no special processing will be done. Just put your files inside of the assets folder being prepared for future enhancements.