press

The press module is a JavaScript and CSS minimizer that is designed to be transparent to the application developer:
Simply replace <script> tags with #{press.script} tags, and <link rel="stylesheet"> tags with #{press.stylesheet} tags.

Enable press

Run the following command to install the press module in your copy of Play, and note the version of the module that is installed.

play install press

Include the following line in your application’s conf/application.conf file to load the press module. Be sure to use the appropriate version number:

module.press=${play.path}/modules/press-1.0

By default, press does not minimize JavaScript and CSS files when Play is in dev mode. Add the following line to conf/application.conf in order to see the compressed output in dev:

press.enabled=true

Add the following line to conf/routes to import the press routes. This simply makes the urls used by the press module more uniform:

*  /  module:press

Use press to aggregate and compress files

Replace <script> with #{press.script}

For example, your template includes the following JavaScript files:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js" type="text/javascript"></script>
<script src="/public/javascripts/header.login.js" type="text/javascript"><script>
<script src="/public/javascripts/main.js" type="text/javascript"></script>
<script src="/public/javascripts/library.min.js" type="text/javascript"></script>

You would change the template to look like this:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js" type="text/javascript"></script>
#{press.script 'header.login.js' /}
#{press.script 'main.js' /}
#{press.script src:'library.min.js', compress:false /}
#{press.compressed-script /}

The #{press.compressed-script /} tag outputs a <script> tag whose source is the compressed output of the other files.

Note:

• library.min.js is already minimized. We don’t need to minimize it again so we add the parameter compress:false.
• Don’t try to minimize files included from an external website :) (eg if you include jQuery from Google’s CDN)

Replace <link rel="stylesheet"> with #{press.stylesheet}

For example, your template includes the following CSS files:

<link href="/public/stylesheets/styles.css" rel="stylesheet"></link>
<link href="/public/stylesheets/header.login.css" rel="stylesheet"></link>

You would change the template to look like this:

#{press.stylesheet 'header.login.css' /}
#{press.stylesheet 'main.css' /}
#{press.compressed-stylesheet /}

Sample output

The above example will output something that looks like this:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js" type="text/javascript" language="javascript" charset="utf-8"></script>
<!-- press-js: header.login.js -->
<!-- press-js: main.js -->
<!-- press-js: libary.min.js -->
<script src="/press/js/sNJSWMCDDFAekXYWryWgigJJ.js" type="text/javascript" language="javascript" charset="utf-8"></script>
<!-- press-css: header.login.css -->
<!-- press-css: main.css -->
<link href="/press/css/mDcFcAqEAhDvWvFVBfCOiQJJ.css" rel="stylesheet" type="text/css" charset="utf-8" ></link>

All JavaScript files are compressed into a single JS file and all CSS files are compressed into a single CSS file. press outputs HTML comments indicating the order in which each JavaScript/CSS file was added to compression

Use press to compress files individually

Instead of compressing files in a group, you can instead compress files individually (without aggregating them). To compress files individually use the #{press.single-script} and #{press.single-stylesheet} tags.

#{press.single-script 'widget.js' /}
#{press.single-stylesheet 'header.login.css' /}
#{press.single-stylesheet 'widget.css' /}

The above example will output something that looks like this:

<script src="/public/javascripts/press/widget.min.js" type="text/javascript" language="javascript" charset="utf-8"></script>
<link href="/public/stylesheets/press/header.login.min.css" rel="stylesheet" type="text/css" charset="utf-8" ></link>
<link href="/public/stylesheets/press/widget.min.css" rel="stylesheet" type="text/css" charset="utf-8" ></link>

Tips

• The source CSS and JS files MUST be UTF-8 encoded
• The source files will be output in compressed format in the same order as they appear in HTML when compression is disabled.
• It doesn’t matter where the #{press.compressed-script} and #{press.compressed-stylesheet} tags are declared. Even if there are #{press.script} or #{press.stylesheet} tags after them in the template, they will still be included in compression.
• In dev mode, changes to the JS and CSS files are detected real time. Simply save and refresh the page. See Caching for options related to caching and the defaults for each mode.
• If the same file is included twice an exception will be thrown.
• Don’t use press from within a 404.html or 500.html template. When invoking an error template Play changes the request object causing press to fail.

Caching

When a compressed file is generated for a given set of input files, it is stored on disk in a configurable location. The next time the same set of files in the same order is requested, the file is retrieved from the cache.

press uses different caching mechanisms depending on whether Play is in dev or production mode. These can be overridden in Configuration.

• In dev mode, press by default uses the caching strategy Change: press will detect changes to the JS and CSS files real time. Simply save and refresh the page.
• In production mode, press by default uses the caching strategy Always: press will not auto-detect changes. The cache is cleared each time the server is restarted.
• There is a third caching strategy that can be configured called Never, in which press will not use the cache. Compression will be performed for every page request. This mode obviously puts a high load on the server and is only recommended if one of the above strategies cannot be used for some reason.

Configuration

Many configuration options are different between dev and production. All of them can be overridden. For more information on how to override a Play configuration option for a particular environment, see Managing application.conf in several environments

press.enabled

Whether or not press is enabled.

press.enabled=true
Each #{press.script} and #{press.stylesheet} tag will output an HTML comment
The #{press.compressed-script} and #{press.compressed-stylesheet} tags will output a <script> or <link rel="stylesheet"> tag with its src attribute pointing to the compressed source.

press.enabled=false
Each #{press.script} and #{press.stylesheet} tag will output a corresponding <script> or <link rel="stylesheet"> tag with the original, uncompressed source.
The #{press.compressed-script} and #{press.compressed-stylesheet} tag will output nothing

By default, when play is in dev mode press is disabled, and in production it is enabled

press.cache

The caching strategy to use. See Caching.

press.cache=Always
The cache will always be used, regardless of whether the component files have changed. The cache will be cleared when the server is restarted – this mode is recommended for a production environment.

press.cache=Change
The compressed file will be regenerated when the last modified date of one of the source js or css files is detected to have changed – recommended for a dev environment.

press.cache=Never
The cache will not be used: the js and css files will be compressed on every request

By default, when play is in dev mode the caching strategy is Change, and in production it is Always.

press.cache.clearEnabled

Indicates whether the action to clear the cache from the web is enabled in production.
Press exposes an action to clear the compressed js and css cache at /press/clear

By default, when play is in dev mode the action is available and in production it is disabled.
press.cache.clearEnabled=true

press.key.lifetime

The amount of time to keep the compression key, in play Time duration format (see play.libs.Time.parseDuration)

When the #{press.compressed-script} or #{press.compressed-stylesheet} tag is output, a temporary key is generated and used as part of the file name. The browser then requests the file and the server responds with the compressed javascript. So the key must last as long as the time between when the browser receives the HTML and when it makes the request for the JS. The default is 2 minutes
press.key.lifetime=2mn

press.compression.maxTimeMillis

The maximum amount of time in milli-seconds that compression is allowed to take before a timeout exception is thrown.
press.compression.maxTimeMillis=60000

press.js.sourceDir

The source directory for javascript files, relative to the application root
press.js.sourceDir=/public/javascripts/

press.css.sourceDir

The source directory for css files, relative to the application root
press.css.sourceDir=/public/stylesheets/

press.js.outputDir

The output directory where compressed javascript files will be written to, relative to the application root. Note: This directory will be created if it doesn’t exist.
press.js.outputDir=/public/javascripts/press/

press.css.outputDir

The output directory where compressed css files will be written to, relative to the application root. Note: This directory will be created if it doesn’t exist.
press.css.outputDir=/public/stylesheets/press/

press.htmlCompatible

By default, the output produced by press is compatible with XHTML. This means that <link> tags are closed. If press.htmlCompatible is true, the output will be compatible with HTML, meaning that <link> tags will not be closed.
press.htmlCompatible=false

Options for the YUI compressor

See http://developer.yahoo.com/yui/compressor for details

press.yui.css.lineBreak=-1
press.yui.js.lineBreak=-1
press.yui.js.munge=true
press.yui.js.warn=false
press.yui.js.preserveAllSemiColons=false
press.yui.js.preserveStringLiterals=false

How press works

press uses YUI Compressor to perform JavaScript and CSS minimization.

Each #{press.script} tag is replaced with a corresponding HTML comment, eg <!-- press-js: main.js -->. This is necessary in order to indicate the order in which the files are declared, required to generate the compressed output (explained below).

The #{press.compressed-script} tag is replaced with a <script> tag containing a key derived from the page URL, eg

<script src="/press/js/sNJSWMCDDFAekXYWryWgigJJ.js" type="text/javascript" language="javascript" charset="utf-8"></script>

When the page is ready to be sent to the browser, press scans the output for comments of the form <!-- press-js: main.js --> and creates a list of files that will be compressed, that is associated with the key.

When the browser makes a request for /press/js/sNJSWMCDDFAekXYWryWgigJJ.js, press extracts the key from the file path and uses it to retrieve the list of files. If there is already a compressed file containing those files in that order in the cache, press returns that file to the browser. Otherwise it generates the compressed file on the fly and saves it to the cache.

The process is the same for CSS files.

Gotchas

Relative image urls will not work in a compressed CSS file because the location of the file that is output by press is not the same as the original file. Use absolute urls.

Some utilities (such as Aloha text editor) will attempt to build a path using the dynamically generated url paths (eg /press/js/sNJSWMCDDFAekXYWryWgigJJ.js). In order to get around this problem you can add the following at the bottom of your routes file, after including the press routes:

GET      /press/js/         staticDir:public/javascripts
GET      /press/css/         staticDir:public/stylesheets

Don’t use press from within a 404.html or 500.html template. When invoking an error template Play changes the request object causing press to fail.

Thanks

The following people have contributed to the development of this plugin:

• John Pletka
• waxzce
• dabeeeenster
• orefalo
• nzakas

Thanks!

Questions

If anything in the documentation is not clear, if you find a bug, or if you have questions, please use the play google group and include the word “press” in the subject line:
http://groups.google.com/group/play-framework