h1. GreenScript module

The GreenScript module help you to manage javascript and CSS dependencies and do minimizing work in the same time.
<script type="text/javascript" src="http://www.ohloh.net/p/485839/widgets/project_users_logo.js"></script>

h2. <a>What's New for v1.2.3</a>

* upgrade YUI compressor version from 2.4.2 to 2.4.6
* Fix bug: 404 error while fetching cached files when change minimize/cache setting dynamically
* Fix bug: loaded logic breaks when minimize is enabled

h2. <a>What's New for v1.2.2</a>

* !!!Major bug fix for inline dependency declaration feature: refreshing page will cause dependency disorder
* greenscript.conf change detection in dev mode. thanks for the contribution comes from short-at (https://github.com/shorty-at)
* CDN resource order now kept when minimize enabled
* Configuration controller is secure now

h2. <a>What's New for v1.2d</a>

* configuration change (COMPATIBILITY BROKEN!): resource dir location shall NOT include resource root dir now.
** Previously: greenscript.dir.js=/public/javascripts
** Now: greenscript.dir.js=javascripts (suppose greenscript.dir.root=/public)
** Previously: greenscript.dir.css=/public/stylesheets
** Now: greenscript.dir.css=stylesheets (suppose greenscript.dir.root=/public)
* Fix bug: https://github.com/greenlaw110/greenscript/issues#issue/11
** greenscript now support dependency management in modules (your css/js files in modules, your greenscript.conf file in moduels)
* Support '.bundle' suffix in resource dependency configuration via greenscript.conf
** E.g. js.jq.bundle=http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js,http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.10/jquery-ui.js
** You can use '.bundle' to define an alias for a resource, or
** you can use '.bundle' to define a group of resources that always been used together
* Support inline dependency declaration (search for 'inline dependency declaration' in this document)

h2. <a>What's New for v1.2c</a>

* Fix bug: dependency management breaks for complicated dependencies
* Support reverse dependency declaration (search for "reverse dependency declaration" in this document)

h2. <a>What's New for v1.2b</a>

* Support transparent compression. You don't even invoke #{greenscript.css|js /} tag to get your css and js file compressed

h2. <a>What's New for v1.2a</a>

* Fix bug: IllegalStateException thrown out when app restart (in DEV mode)

h2. <a>What's New for v1.2</a>

* Completely rewrite. 
** GreenScript core logic detached from Play plugin project
** Clearly defined interface and well documented code comment
** Unit test cases for core logic
* Circular dependence relationship detect
* Unified javascript/css tag syntax
* Support inline javascript/css
* new tag options:
** media: pass media (screen, project, all, etc) to #{greenscript.css /} to specify the css file media target
** browser: pass to #{greenscript.css /} and #{greenscript.js /} to specify which browser it is targeted

h2. <a>What's New for v1.1c</a>

* greenscript.compress and greenscript.cache now default to true without regarding to the Play mode
* Unused compressed files in "gs" folder get cleaned
* Notice in configuration html page and demo application.conf file about greenscript.compress|cache option
* Fix bug in css.html tag: NPE encountered when trying to output without argument or "load/import"
* Add support to CDN
* Support reload dependency configuration at runtime

h2. <a>What's New for v1.1</a>

* Many bug fixes
* Completely new Plugin Configurator
* Add Command to enable user copy module tags/templates to user app directory
* More clear configuration settings
* Even more simplified tag syntax
* Support zero configuration
* Document improvement

h2. <a>What's New for v1.0</a>

* Bug fixes: 
** dependency management fail while in 'dev' mode
** <a href='http://github.com/greenlaw110/play-greenscript/issues#issue/1'>greenscript should use play configuration file</a>
* Enhancements:
** Tag simplified: 'sm:gsSM' parameter no longer needed for greenscript.css and greenscript.javascript tag
** Simplified alias for greenscript.javascript tag: greenscript.js
** Use 'import' to replace 'load'

h2. <a>Three steps to use GreenScript</a>

# Install the module and enable it in your application.conf file
** you know what I am talking about ...
# Document your javascript/css dependencies in conf/greenscript.conf file
** Check the demo's greenscript.conf file and you will know what it is
# 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

Step 2 and 3 are optional. The simplest form of using GreenScript is to add the following line into your application.conf file:

<samp>module.greenscript=${play.path}/modules/greenscript-xx</samp>

Immediately you have done that, your javascript file and css file will be compressed automatically.

h2. <a>Manual</a>

h3. <a id="configuration">Configure GreenScript Plugin</a>

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

h4. <a>File locations</a>

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

bc. # 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

h4. <a>URL Path</a>

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

p. 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:

bc. 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

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

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

h4. <a>Minimize Settings</a>

bc. # 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

h2. <a>Configure javascript/css dependencies</a>

p. Javascript/css dependencies are documented in a separate configuration file named <samp>greenscript.conf</samp>, which should be put into the conf dir (the same place with your application.conf). Start from v1.2d, greenscript.conf could be put under conf dir of modules, and these module level greenscript configuration will be merged with application greenscript.conf to define the whole depenedency graph of javascript and css files located in your application and module folders. One limitation to this module level greenscript.conf support is that your javascript and css file must be put in the same directory hierarchy. For example, if you app js/css files are put into ${app.root}/public/javascripts and ${app.root}/public/stylesheets, then all your module you want to use with greenscript must also store their javascripts and css files inside ${module.root}/public/javascripts and ${module.root}/public/stylesheets.

p. 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 <samp>greenscript.conf</samp> file:

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

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

bc. # 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

p. reverse dependency declaration (new in 1.2c)
bc. js.b-=a,c,d

The above line equals to three lines below:
bc. js.a=b
js.c=b
js.d=b

h3. <a id="using-tags">Using tags</a>

p. 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.

h4. <a>The base template: main.html</a>

p. 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 "<header>" section of the main.html you will have the following lines if you are not using GreenScript:

bc. <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' /}

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

bc. #{greenscript.css "main", output:'all'/}
#{greenscript.js output: 'all'/}

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

* Where is my "jquery-1.4.2.min.js" ?
** When you put <samp>output: 'all'</samp> in <samp>#{greenscript.js}</samp> tag, it will output all unloaded js dependency files as well as the default js file you've defined in <samp>greenscript.conf</samp>. I am sure <samp>jquery-1.4.2.min.js</samp> will be reached by either of the 2 lookup paths, otherwise, I assume you will not need that file. For perfectionist, here is how to load the file anyway: <samp>#{greenscript.js "jquery-1.4.2.min.js", output: true/}</samp>
* How can I get "moreStyles" and "moreScripts"?
** You get them automatically when you have <samp>output: true</samp> for <samp>#{greenscript.css}</samp> or <samp>output: 'all'</samp> for <samp>#{greenscript.js}</samp>. The assumption is you have told GreenScript that you need them in other places. I will let you know how to do that later at next section.
* Why do you use <samp>output</samp> for css while <samp>loadAll</samp> for js? 
** loadAll is deprecated now. Both css and js use 'output: "all"' to output all inline declared and dependencies that has not output yet

h4. <a>Other templates</a>

p. The differences of using GreenScript tag in other templates and in the <samp>main.html</samp> 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 <samp>${play.path}/samples-and-tests/booking/app/views/Hotels/book.html</samp>) of how to declare javascripts and css when you don't have GreenScript:

bc. #{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}

p. And see how you do with GreenScript available:

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

p. 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 <samp>greenscript.dir.css</samp>, which default to <samp>/public/stylesheets</samp>).

h4. <a>Inline body</a>

p. Greenscript Play module support inline body start from v1.2.

bc. #{greenscript.css}
dl > dt {
    font-weight: bold;
    color: #600;
}
#{/greenscript.css}

p. In the above sample, the block that defines dl > dt's style will be captured by greenscript and moved to your html page header. (Suppose you have "#{greenscript.css output:'all'}" in the header block of your main.html template. By using "output: true" parameter, the following sample will output the block in place rather than moving the enclosed body to the header:

bc. #{greenscript.js output:true}
    var rule = ruleById('first_name');
    rule.add(Validate.Presence)
    rule = ruleById('last_name');
    rule.add(Validate.Presence)
    rule = ruleById('email');
    rule.add(Validate.Email)
    rule.add(Validate.Presence)
    $$('input.date').each(function(el){
        new Control.DatePicker(el, {icon: '/public/images/calendar.png', locale: 'en_iso8601'});
    });
#{/greenscript.js}

h4. <a>Inline Dependency Declaration</a>

p. There is a long time complaint that greenscript does not guarantee the output sequence of resource (js/css) files match the sequence of declaring those files in tags. For example, #{greenscript.js 'a b c'/} does not necessarily output or marge javascript 'a.js', 'b.js' and 'c.js' in a sequence that a.js followed by b.js and then c.js. This is because greenscript output is driven by dependencies (which is defined in greenscript.conf), rather than the sequence declared in tag. Actually greenscript cannot and shouldn't follow the sequence declared in tag at all. The reason is 
1. the sequence of tag declaration might conflict with dependencies declared in greenscript.conf
2. it is hard to tell the sequence of tag declaration when the developer declare resources in multiple templates with inheritance relationships

p. Now (start from v1.2d) greenscript support inline dependency declaration in tags, which basically remove the inconvenience that simple resource file dependencies are also require developer to provide a greenscript.conf file:

bc. #{greenscript.js 'myapp < mylib < jquery-1.5.min'/}

p. The above javascript declaration also setup the dependencies among the declared javascript resources: myapp.js relies on mylib.js which in turn relies on jquery-1.5.min. Therefore you no longer need a greenscript.conf file to define the dependencies among myapp, mylib and jquery-1.5.min javascript files.

p. The limitation of inline dependency declaration is you can't use it across multiple template files. Say you have a javascript A declared in main.html and then you have another javascript B declared in index.html, you can't use inline dependency declaration to declare the dependency relationship between A and B unless you declare them all in index.html: #{greenscript 'A > B'/}

p. Reference

bc. A > B means B relies on A
A < B means A relies on B

h4. <a>Media and Browser</a>

p. GreenScript support media and browser options start from v1.2. Issue tag "<code>#{greenscript.css 'print.css', media: 'printer'}</code>" to declare a css resource target to "printer" media. Later when you output all css files by "<code>#{greenscript.css output:'all'}</code>", one line will be output as: 

<pre><code><link rel="stylesheet" type="text/css" media="printer" href="/compressed/print.css"></code></pre>

p. Declare resource specific to a browser in the following way:

<pre><code>#{greenscript.css 'ie', browser: 'lt IE 8'/}</code></pre>

p. The corresponding output is:

<pre><code>
<!--[if lt IE 8]>
<link rel="stylesheet" type="text/css" media="all" href="/compressed/ie.css">
<![endif]-->
</code></pre>
h3. <a id="dyna-conf">Configuration at runtime</a>

p. 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:

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

p. Once you have done with that, you can reach the configuration page by typing <samp>http://localhost:9000/gsconf</samp> 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 <em>runtime configuration will not be flushed to your configuration file</em>. 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 <a href="#configuration">Configuration</a> section for detail.

p. 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.

h4. <a>About Security</a>
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:

* Option 1: Remove the url mapping entry in your route file in a prod environment
* Option 2: If you are a real hack and reject any manual operations, you will probably implement your own controller extends (or @With) controllers.greenscript.Configurator, and then add security to your controller. You will need to copy the configurator templates to your views folder. Don't worry, GreenScript provides command to help you with that. I will get there now.

h3. <a>Module command</a>

p. 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:

bc. 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:

<pre><code> package controllers;

import play.mvc.*;

@With({Secure.class, controllers.greenscript.Configurator.class})
@Secure(role='developer,admin')
public class MyGSConfigurator extends Controller {
}
</code></pre>

h3. <a>Keep it secret!</a>

p. 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:

bc. play greenscript:cp -a gs

p. 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: 

bc. play greenscript:cp -a .
...
#{js output: 'all'/}
#{js "js1 js2 ..." /}
..
#{css "css1 css2" /}

p. How do you expect anything more simpler than this?

h3. <a>Zero configuration</a>

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:
* The tags. You are free to utilize all the knowledges you've learned from <a href="#using-tags">Using Tags</a> section. 
* Minimize/compress. You can also benefit from minimizing/compressing/cache capability of GreenScript.
* Dynamic configuration. You can also use the dynamic configuration controller.

So what do you lost without any configuration?
* Dependency management. Without dependencies infomation defined in <samp>greenscript.conf</samp> file, you are on your own to take care of js/css file dependencies. When you are declare a javascript or css file in a template, you should also make sure all its dependencies are explicitly declared before that scripts "IN PLACE"! If you failed to do that, you might get a lot of script/css errors in your final rendered html page.
* Dir/URL path bound to play's default. With zero configration, you need to make sure your dir structure (the public) and route mapping of public dir strictly follow Play's convention. Otherwise GreenScript won't be able to locate the javascript/css files. 

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.

h3. <a>Transparent Compression</a>

GreenScript support Transparent Compression start from v1.2b. With Transparent Compression, even you don't use greenscript tag, your js file and css file will automatically get compressed even without your attention (in PROD mode).

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.

h3. <a>CDN Support</a>

Greenscript support CDN start from version 1.1a. 

h4. Configure CDN dependencies

bc. # 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

h4. Load CDN items in tags

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

h2. <a>FAQ</a>

h3. 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:

bc. #{greenscript.css "css files separated by blank", output:'all'/}
#{greenscript.js output:'all'/}

h3. 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'.

h3. 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.

h3. 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 <a href="#dyna-conf">Configuration at runtime</a> section for detail

h3. 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 ;-)
