Beta Railo Extensions: CFJAVASCRIPT / CFSTYLESHEET
Another fine example of extending your Railo server by Andrea Campolonghi. Working on large ajax projects it is not uncommon to see pages that include a lot of javascript and css files. We're often times mixing and matching javascript plugins which sometimes has css stylings that go along with the plugins. We have worked to a solution that can help developers and let the server do the job of compressing and concatenating files. Let's imagine that your app need the following js files:
- A.js
- B.js
- C.js
What I wanted was a tag that could get a reference to these files, compress them and craete a new file cocatenating the compressed files into one. And of course this job must be done once for any files combination so we're not recreating these file each and every request.
How do I install the tags?
Install them via the application area of your railo server admin. From your Railo SERVER Admin ( example: http://{YOUR DOMAIN}/railo-context/admin/server.cfm?action=extension.providers ), add a new provider - http://preview.getrailo.org/ExtensionProvider.cfc
And install the application: (e.g.: http://{YOUR DOMAIN}/railo-context/admin/server.cfm?action=extension.applications)
Important! Remember to restart Railo after the installation has completed. ( e.g.: http://{YOUR DOMAIN}/railo-context/admin/server.cfm?action=services.restart )
CFJAVSCRIPT Usage:
<cfset src = ['/cfjs/test/js/A.js','/cfjs/test/js/B.js'] />
<cfjavascript src="#src#" />
You pass to the src attribute an array with relative paths for the interested js files. The tag will compress them and make a new file that is included using a regular script tag.
If you do not provide a filename and a path to be used as base for the new generated file tha tag will use the follwing rules :
- create a directory /_cfjavascript
- create a filename generating an hash() of the passed array ( so to be unique for the given set of files )
You can override this defaults like ( if you choose a filename be sure that is unique for you app or at least for the choosen path ):
<cfset src = ['/cfjs/test/js/A.js','/cfjs/test/js/B.js'] />
<cfjavascript src="#src#" path="/cfjs/test/jscompressed" filename="myJs"/>
Once the file is stored, the tag will try to reuse it by default. You can force this behavior in 2 ways:
- set the cache attribute to false
- add to your url the string '_cfjavascript_nocache'
If one of these 2 condition evaluates to true the tag will skip the cache and will reload the files.
But what about debugging? Debugging compressed js can be a nightmare. You can ask to cfjavascript to include the source ( from the src array ) if :
- debug atrribute is set to true
- your url contains the parameter '_cfjavascript_debug'
In both these case you will have simply obtain the inclusion of your JavaScript resources ( order is respected ). More attributes are available in the following table..
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| src | String or [String] | true | A single ( or an array of ) relative path that point to the js files to be compressed. Path must be relative and inside the context web root. | |
| path | String | false | /_cfjavascript | A relative path that will be used to store the compressed file and to serve it to the web server. If not provided a directory called /_cfjavascript will be created and used. |
| filename | String | false | If provided give the name to the js generated file. Filename must be unique in the choosen 'path' ( or per project if a single path is used all along the project ). Tag will check if a file exists when decide if generated a new compression or serving a cached copy. If not provided an hash is used. |
|
| cache | boolean | false | true | If true the compression is done once for any different sets or src paths. From this point the saved file will be served to the web server. Set this to false if you want to force the tag to generate a new compressed file ( you can obtain the same result adding '_cfjavascript_nocache' to the url ). |
| debug | boolean | false | false | If true the tag will output the files as originally are. The src array order is respected. You can obtain the same result adding '_cfjavascript_debug' to the url. This is incredibly usefull for js debugging. |
| linebreak | Numeric | false | 800 | The linebreak option is used in that case to split long lines after a specific column. It can also be used to make the code more readable, easier to debug (especially with the MS Script Debugger) Specify 0 to get a line break after each semi-colon in JavaScript, and after each rule in CSS. |
| munge | boolean | false | false | If true minify and also obfuscate local symbols. |
| preserveAllSemiColons | boolean | false | false | Preserve unnecessary semicolons (such as right before a '}') |
| disableOptimizations | boolean | false | true | Disable all the built-in micro optimizations. |
CFSTYLESHEET Usage
The tag works in the same way of CFJAVASCRIPT using a dedicated compressor instance specialized for css resources. The compression, concatenation, caching and debug works identically with some small syntax and approach change:
- url parameters for forcing the reload is '_cfstylesheet_nocache' and the one to include source to debug is '_cfstylesheet_debug'
- the path attribute is particulary important here as css referes to assets like images based on the css files position itself.
- some attribute change ( see the following list )
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| src | String or [String] | true | A single ( or an array of ) relative path that point to the css files to be compressed. Path must be relative and inside the context web root. | |
| path | String | false | /_cfstylesheet | A relative path that will be used to store the compressed file and to serve it to the web server. Css files need to point to external resources as images.... The path should be the same of the original files so to be sure do not break css dependencies |
| filename | String | false | If provided give the name to the js generated file. Filename must be unique in the choosen 'path' ( or per project if a single path is used all along the project ). Tag will check if a file exists when decide if generated a new compression or serving a cached copy. If not provided an hash is used. |
|
| cache | boolean | false | true | If true the compression is done once for any different sets or src paths. From this point the saved file will be served to the web server. Set this to false if you want to force the tag to generate a new compressed file ( you can obtain the same result adding '_cfjavascript_nocache' to the url ). |
| debug | boolean | false | false | If true the tag will output the files as originally are. The src array order is respected. You can obtain the same result adding '_cfjavascript_debug' to the url. This is incredibly usefull for js debugging. |
| linebreak | Numeric | false | 800 | The linebreak option is used in that case to split long lines after a specific column. It can also be used to make the code more readable, easier to debug (especially with the MS Script Debugger) Specify 0 to get a line break after each semi-colon in JavaScript, and after each rule in CSS. |
As always, if there's any questions or feedback, please drop Andrea Campolonghi a line on the Railo-Beta mailing list!
There are no comments for this entry.
[Add Comment]