Community contributed extensions

GreenScript module

The GreenScript module help you to manage javascript and CSS dependencies and do minimizing work in the same time.

What’s New for v1.1c

What’s New for v1.1

What’s New for v1.0

Three steps to use GreenScript

  1. Install the module and enable it in your application.conf file
    • you know what I am talking about ...
  2. Document your javascript/css dependencies in conf/greenscript.conf file
    • Check the demo’s greenscript.conf file and you will know what it is
  3. Use greenscript tag in your template files: #{greenscript.js “myjs1 myjs2 ...” [options] /}
    • Yes, this part is a little bit complicated, but not that much. I am sure it won’t be difficult as #{list} tag

Manual

Configure GreenScript Plugin

# The GreenScript module
module.greenscript=${play.path}/modules/greenscript-xx

File locations

This part set the javascript, css and compressed file location in the filesystem, start from your application’s root.

# Default greenscript.dir.js point to /public/javascripts
greenscript.dir.js=/public/javascripts
#
# Default dir.css point to /public/stylesheets
greenscript.dir.css=/public/stylesheets
#
# Default minimized file folder point to /public/gs
greenscript.dir.minimized=/public/gs

URL Path

This part set the url path GreenScript used to output javascript, css or compressed files, start from root url.

Usually you will not need to set this part as it will reuse the dir settings, which is comply with Play’s default folder layout and route mapping. However, if you have shortcut set in your application’s route file (as what I did in the demo app), you are encouraged to override defalt setting here:

greenscript.url.js=/js
greenscript.url.css=/css
##
# IMPORTANT: make sure the mapping does not conflict with
# the mapping of greenscript module in your route file.
# see <a href="dyna-conf">Configuration at runtime</a>
greenscript.url.minimized=/compressed

Note that js and css url is used only when greenscript.miminize set to false, in which case, GreenScript will output links refer the original javascript/css files.

greenscript.url.minimized setting is used only when greenscript.minimize set to true, in which case, GreenScript will output links refer to the compressed(minimized) files

Minimize Settings

# Enable/Disable minimize
# 	Once minimize disabled, GreenScript will output the original javascript/css
# 	files without any processing. However, the order of the files is guaranteed
#	to follow the dependency graph you have defined in "greenscript.conf" file
#
#	When minimize turned on, GreenScript will merge all javascript/css files
#	within one HTTP request into a single file. Again the merge order is 
#	guaranteed to follow the dependency graph you have defined in the
#	"greenscript.conf" file
#
#	Note if you turn off minimize, the rest 2 settings (compress, cache) will
#	not function whatever the value they are
#
# By Default minimize is turned on in prod mode and turned off in dev mode
greenscript.minimize=false
#
# Enable/Disable compress
#	Once compress is enabled, GreenScript will compress the javascript/css files
#	while doing the merge operation.
#
# By default compress is turned on in prod mode and turned off in dev mode
greenscript.compress=false
#
# Enable/Disable cache
#	Once cache is turned on, GreenScript will try best to reuse the processed
#	file instead of repeat the merge/compress process.
#
# By default cache is turned on in prod mode and turned off in dev mode
greenscript.cache=false

Configure javascript/css dependencies

Javascript/css dependencies are documented in a separate configuration file named greenscript.conf, which should be put into the conf dir (the same place with your application.conf)

It’s fairly straght forward to document the file dependencies. Let’s say your have four javascript files a.js, b.js, c.js and d.js, the dependency relationship is b.js depends on a.js, c.js depends on both b.js and d.js, then here is the content of your greenscript.conf file:

js.b=a
js.c=b,d

The same way applies to css file dependencies. The only difference is css dependancy rule starts with css. while javascript file rule starts with js.. Below is the content of greenscript.conf file of the demo application:

# js.default means the file get loaded always, even no other file depends on it
js.default=prototype
# Javascript Dependencies
js.datepicker=prototype-base-extensions,prototype-date-extensions
js.livevalidation=prototype
js.pMask=prototype-event-extensions
js.prototype-base-extensions=prototype
js.prototype-date-extensions=prototype
js.prototype-event-extensions=prototype
js.dumb_1=prototype
#
# CSS Dependencies
css.color=reset
css.form=color,layout
css.layout=reset
#
# Other configuration should go to application.conf

Using tags

Now that your have understand how to configured the plugin and file dependencies, it’s time to see how GreenScript can simplify your life of dealing with javascript/css in your play template files.

The base template: main.html

Normally you should have a main.html (you might call it “base” or other names, but that doesn’t matter) served as a base template for all other templates, and in the “&lt;header&gt;” section of the main.html you will have the following lines if you are not using GreenScript:

<link rel="stylesheet" type="text/css" media="screen" href="@{'/public/stylesheets/main.css'}">
#{get 'moreStyles' /}
<script src="@{'/public/javascripts/jquery-1.4.2.min.js'}" type="text/javascript" charset="utf-8"></script>
#{get 'moreScripts' /}

And here is how it should be when you are using GreenScript:

#{greenscript.css "main", output:true/}
#{greenscript.js loadAll: true/}

Yes! that’s it. I know you might have some questions, don’t worry. Let me unveil the curtain.

Other templates

The differences of using GreenScript tag in other templates and in the main.html is that ususally you don’t “output” javascript or css files in your other templates, instead, you declare them (for the template usage). Here is a sample (found in ${play.path}/samples-and-tests/booking/app/views/Hotels/book.html) of how to declare javascripts and css when you don’t have GreenScript:

#{set 'moreScripts'}
    <script src="@{'/public/javascripts/jquery-ui-1.7.2.custom.min.js'}" type="text/javascript" charset="utf-8"></script>
#{/set}
#{set 'moreStyles'}
    <link rel="stylesheet" type="text/css" media="screen" href="@{'/public/ui-lightness/jquery-ui-1.7.2.custom.css'}" />
#{/set}

And see how you do with GreenScript available:

#{greenscript.js "jquery-ui-1.7.2.custom.min" /}
#{greenscript.css "/public/ui-lightness/jquery-ui-1.7.2.custom" /}

Easy, right? You might noticed that I have put the full path for the css file in this case. This is needed because the file is not in the default stylesheet file folder (configured with greenscript.dir.css, which default to /public/stylesheets).

Configuration at runtime

This beautiful feature enable app developer to turn on/off minimizing dynamically and could be very helpful when you need to debug your javascript/css. In order to use the feature, you will need to add an entry in your route file to map a url request to the controllers.greenscript.Configurator actions, for example:

# Enable GreenScript dynamic configuration
# IMPORTANT: make sure this routine map be different from your
# staticDir map to compressed file folder
GET /gsconf module:greenscript

Once you have done with that, you can reach the configuration page by typing http://localhost:9000/gsconf in the address bar of your favorite browser. The configuration is designed to be self guided and you won’t lost yourself there. Please be noted that runtime configuration will not be flushed to your configuration file. When you restart your app all the configurations you’ve made during last session are lost. Meaning if you want to change a configuration permanently, you must update your application.conf file. See Configuration section for detail.

You can also force GreenScript to reload the dependency configuration from “greenscript.conf” file if you have changed it. Just go to “css/js dependencies” tab and click “reload”. This feature is very friendly to developer, especially in the early stage of javascript involved development.

About Security p. There is no integrated security to access the configuration page. And here is my 2 cents on how to secury your GreenScript dynamic configuration access:

Module command

I’ve just told you that you can use command to copy the greenscript Configurator.configure.html template file to your app folder. Here is how to do it. First make sure you have enabled greenscript in your application.conf file. And then go to the console, enter your app root dir, and type:

play greenscript:cp -t MyGSConfigurator

The template file will be ready in {your-app-root}/app/views/MyGSConfigurator folder. Obviously your controller should be named MyGSConfigurator. It probably should looks like:

 package controllers;
import play.mvc.*;
@With({Secure.class, controllers.greenscript.Configurator.class})
@Secure(role=‘developer,admin’)
public class MyGSConfigurator extends Controller {
}

Keep it secret!

Okay, how do you feel about this Plugin? Still not satisfied because you don’t like to type 11 charaters for tag name each time? Well I have a secret weapon to alleviate your pain with that: Once you have enabled greenscript in your conf/application.conf file, go to console, enter your app root, and type:

play greenscript:cp -a gs

Now guess what happened? You are right, it copied the tags from module folder to your app folder: your-app-root/app/views/tag/gs. And now you can use tags in short version: #{gs.js “js1 js2 ...” /} and #{gs.css “css1 ...” /}. What? you are still not satisfied? how come? it’s already shorter than play’s #{script} tag! Okay, here is my nuclear weapon: 

play greenscript:cp -a .
...
#{js loadAll:true /}
#{js "js1 js2 ..." /}
..
#{css "css1 css2" /}

How do you expect anything more simpler than this?

Zero configuration

GreenScript plugin now support zero configuration. It means besides enabling it in your application.conf, you don’t need to do any configuration to use it, you don’t even need to create “greenscript.conf” file in your conf dir. But what do you get if you don’t do any configuration? Well basically you can still benefit from GreenScript with zero configuration:

So what do you lost without any configuration?

As an example to demonstrate zero configuration, I put the ${play.path}/samples-and-tests/booking sample in the samples-and-tests dir of greenscript, makes the minimum changes to the templates and application.conf files.

In conclusion, GreenScript is a flexible and powerful javascript/css management tool for your Play applicaiton development. You can use it in simple way (zero configuration) or in a way sophsicated enough to manage your complicated javascript and css dependencies.

CDN Support

Greenscript support CDN start from version 1.1a.

Configure CDN dependencies

# Note you must escape ':' if it is in the 'key' part, no need to escape if 
# it's in the 'value' part. This is due to the java.util.Properties treat ':' 
# as separator between key and value
js.http\://ajax.googleapis.com/ajax/libs/scriptaculous/1.8.3/scriptaculous.js=http://ajax.googleapis.com/ajax/libs/prototype/1.6.1.0/prototype.js

Load CDN items in tags

#{greenscript.js 'http://www.google.com/jsapi' /}

FAQ

I found there is no javascript and css links at all in my html file rendered out!!

Make sure you have add the following lines in your main.html (or in any other name) template:

#{greenscript.css "css files separated by blank", output:true/}
#{greenscript.js loadAll:true/}

Do I need to surround #{greenscript } tag with #{set ‘moreStyles’} in my other templates?

No, you just use #{greenscript.css ‘...’ /} to declare your css files. With greenscript, you can say ‘byebye’ to ‘moreStyles’ and ‘moreScripts’.

How to use GreenScript? Is it hard to configure?

You can use GreenScript with zero configuration. However, it’s suggested to create “greenscript.conf” file to describe your javascript and css file dependancies. You will love this feature because you just need to declare explicitly used javascript/css files in your templates, leave the dependencies to GreenScript.

I want to debug javascript, can GreenScript output uncompressed version of javascript/css files?

Yes, put “greenscript.minimize=false” in your application.conf file. Actually the setting is turned off by default when you are running app in “dev” mode. An nice feature you can use is dynamic configuration which enable you turn on/off minimizing/compressing without restart your app. See Configuration at runtime section for detail

Why don’t you use GreenScript in the dynamic configuration feature?

Well, I have no idea how you will configure the dir/url path settings, so I have to hard code my javascript/css links in my template. Fortunately it’s not a big work for a single page web app ;-)