Controllers: Asset Management

All the assets of your web-application can be placed inside of your application folder or at the root of your webfolder. In both places you will find a folder named "assets". In there you will find subfolders named img, css, js and etc. The names are self-explanatory. You can put your assets in there and use any deep hierarchy of subfolders.

The assets at the top of your web folder will be available to all your applications (if you have). Every application can override assets from the top of your web folder by creating an asset with the same name.

Assets will be compiled or otherwise modified. The result will be saved into subfolders named "compiled". As long as the original file will not be modified, these compiled versions will be delivered for future requests instead of compiling all the time. Furthermore the clients will be informed about the last modification date. 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.

Also the etag identification of a file will be contemplated before a asset will be send to the browser. This 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. Browser will be told to use it's cached version and the asset will not be streamed.

Every asset handler can decide if a compilation is necessary. If an asset do not need to be compiled the system use something like a link to the original file. These technique will be used by the image compiler, to save space for useless duplication of images.

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 "compiled" can be done everytime safely. This caches will be rebuild automatically.

General Usage

Links to Assets

Assets will be linked from your html source always pointing to the path assets/ASSET_TYPE/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/css/mySubfolder/style.css use the following tag:

<link rel="stylesheet" href="assets/css/mySubfolder/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.
• live: Like force the asset will always compiled. But it will compile the asset as it would be compiled in a production environment.
• auto: This is the standard flag. The asset will be recompiled if the cached version is out-of-date. If you set this flag or leave it, the behaviour is exactly the same.

Using the flag live (in a development environment of course) can be confusing. If you call an asset with the flag live a new compiled version will be saved into the cache. If you call the next time the asset without this flag the system will recognize an up-to-date cached asset and you will get delivered all the time the "live"-version of the compiled asset. You can reverse this by calling the asset with the flag force.

Here an example how to use these flags:

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

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

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

Asset Types

For now the following assets will be processed as follows:

Images

Images placed inside the folder "img" will be resized accordingly to the users display size. High density displays like retina displays will be detected and small mobile devices. For this reason you should use high resolution images 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.

An example: Acoording to the given design you have to place an image of 150x50 pixels onto the page. In this case you will 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 img-controller. Retina-displays will show a sharp image and mobile browsers will get a downsized image.

For now PNG, GIF and JPG are supported.

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

Stylesheets

Sometimes everyone miss features that don't exist in CSS yet like variables, nesting, mixins, inheritance. This is now possible by using SCSS. To learn more about this CSS-Extension read the basic introduction here: http://sass-lang.com/guide But you do not have to use SCSS. If you dont want or need it, just use simple CSS as always.

Depending on the constant "ENVIRONMENT" the served stylesheet will be compressed if it was set to "testing" or "production". If set to "development" it will be only normalized. In case of a compiler error a css comment will be inserted at the beginning of your stylesheet. The stylesheet will be delivered uncompiled.

Only SCSS is supported, not SASS!

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

JavaScript

You Javascript files will be automatically minified if you are on production environment (depending on the constant "ENVIRONMENT"), so that it can be delivered to the client quicker. Otherwise it will be left untouched. In case of a compiler error a JavaScript comment will be inserted at the beginning of your script. The file will be delivered uncompiled.

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

Other Binaries

For other files (for example pdf-files for download) the folder "etc" was scheduled. For now no special processing will be done for these files. Just put your files inside of the folder "assets/etc" being prepared for future enhancements.