JCruncher

lesscss and handlebars command line compiler in Java

jcruncherEx.jar is a simple executable jar for compiling .less files to .css, and hanglebars.js template (.hbs) to .js. It is designed to be used as command tool, integrates well with ANT and maven, supports config file (jcruncher.cfg), and have an interactive/continuous mode (with -i) which continously monitor the source files and recompile them as needed.

Example
$ java -jar /path/to/jcruncherEx.jar --less less/ css/ --hbs tmpl/ js/  
Download jcruncherEx.jar
(version 0.9.4)

jCruncher 0.9.4 uses lesscss 1.7.5 compiler, and Handlebars 3.0.1 compiler.
(make sure to use Handlebar Runtime 3.0.1)
jcruncher on github

Change log

Format

$ java -jar /path/to/jcruncherEx.jar [-i] --less|hbs source destination [-e f1;f2]  

There could be as many --less or --hbs 'instruction blocks' as needed.

Tip 1 With -i when coding, without -i when building.

Tip 2 You can put the command line arguments in a jcruncher.cfg to just use java -jar /path/to/jcruncherEx.jar from the same folder (with our without -i). The project root is a good location to put the jcruncher.cfg so it can be easily picked up by ANT, maven, and the command line by all the team members.

LESS examples (--less)

Compile each less/[fileName].less files and save to css/[fileName].css

$ java -jar /path/to/jcruncherEx.jar --less less/  css/ 

Compile all less/[fileName].less files into a single file at css/all.css

$ java -jar /path/to/jcruncherEx.jar --less less/  css/all.css 

Compile all less/[fileName].less files, but "f1.less" and "f2.less", into a single file at css/all.css

$ java -jar /path/to/jcruncherEx.jar --less less/ css/all.css -e f1.less;f2.less 

-i for interactive and continuous mode (will monitor file changes and recompile as needed)

$ java -jar /path/to/jcruncherEx.jar -i --less less/  css/ 

Adding "-i" as a first arg, will turn the command line into an interactive mode that will monitor the source folders and recompile the .less or .hbs as needed. User can also enter "r" for forcing a refresh, or "q" for quitting.

Handlebars.js example (--hbs)

Compile the tmpl/myTemplate.hbs file into tmpl-js/myTemplate.js

$ java -jar /path/to/jcruncherEx.jar --hbs tmpl/myTemplate.hbs  js/myTemplate.js 

As with the other handlebars.js pre-compiler, this will create a handlebars.templates namespace with the following naming convention handleblars.templates[fileNameWithouExtension] to run the template.

Also, one the benefits of this approach, is that on the client, you just need to include runtime version of handlebars.js (handlebars.runtime-...min.js), which is only about 3KB, rather than the 33kb of the full handlebars.js

So, to run the example above, you would something like this:

<html>
  ...
  <head>
      <script type="text/javascript" src="js/handlebars.runtime-1.3.0.js"></script>
      
      <script type="text/javascript" src="js/myTemplate.js"></script>
...

And then, you can just do this in your code

return Handlebars.templates["myTemplate"]({some:"data"});

Compile each tmpl/[fileName].hbs file into the corresponding tmpl-js/[fileName].js

$ java -jar /path/to/jcruncherEx.jar --hbs tmpl/  tmpl-js/ 

Obviously, anything supported in the --less mode are also available with --hbs (file to file, folder to folder, file to folder, and folder to single file)

One more {{cool}} thing (multiple templates in a single .hbs file)

Sometime, having one file per template might be overkilled especially when the templates are small or belong to a same component, so, jcruncher also support putting more than one templates, using the <script id="[templateName]" ..>...template content...</script> syntax.

So, for example, you could have:

tmpl/myTemplateSet1.hbs

<script id="firstTemplate" type="text/html">
  <div>First template {{name}}</div>
</script>
<script id="secondTemplate" type="text/html">
  <div>Second template {{name}}</div>
</script>    

Running this

$ java -jar /path/to/jcruncherEx.jar --hbs tmpl/myTemplateSet1.hbs  tmpl-js/ 

Will create the usual tmpl-js/myTemplateSet1.js file, but this file will have the defintion for the two template.

Handlebars.templates["firstTemplate"]({name:"Mike"});
// will return: <div>First template Mike</div>

Handlebars.templates["secondTemplate"]({name:"Jen"});
// will return: <div>Second template Jen</div>

Combined (--less & --hbs)

Compile all the .less and .hbs files to their respective folder.

java -jar /path/to/jcruncherEx.jar --less less/ css/ --hbs tmpl/ js/ 

Compile with some exception (-e)

java -jar /path/to/jcruncherEx.jar --less less/ css/ -e lesshat.less;variables.less
                                   --hbs tmpl/ js/ -e test.hbs

 

jchruncher.cfg

To ease team development and build process, jcruncherEx.jar allows to put the command line arguments in a jcruncher.cfg

For example, having this file

/myApp/jcruncher.cfg

# This file can have comments
--hbs tmpl/ js/
 
# more comment  
--less less/ css/all.css  

And running this:

/myApp/$ java -jar /path/to/jcruncherEx.jar   

Will process the commands as if there were a single line command line argument list.

To start the interactive mode with these command, just add -i

/myApp/$ java -jar /path/to/jcruncherEx.jar -i   

The jcruncher.cfg can come in handy to normalize pre-compilation instructions accross team members and build process. A good place to put the jcruncher.cfg file could be in the root project, where the pom.xml is for maven project for example.

As ANT

<target name="crunching">
  <exec executable="java">
    <arg line="-jar"/>
    <arg line="/apps/jcruncherEx.jar"/>
    <arg line="--less"/>  
    <arg line="less/"/>
    <arg line="css/all.css"/>
    <arg line="--hbs"/> 
    <arg line="tmpl/"/>
    <arg line="js/templates.js"/>     
  </exec>   
</target>  

As ANT, Maven, & Command line, interactive

To have consistent pre-compile instruction set across development and build for an entire team, the recommended way is to a jcrunher.cfg next to your your build.xml or pom.xml as

/myApp/jcruncher.cfg

# compile the .less files minus the lesshat.less
--less less/ css/all.css -e lesshat.less

# compile the .hbs
--hbs tmpl/ js/templates.js    

Then, just have the simple target in ANT (or in Maven/ANT), without any --less or --hbs 'instruction blocks,' which will force jcruncherEx.jar to look at the jcrunher.cfg

<target name="crunching">
  <exec executable="java">
    <arg line="-jar"/>
    <arg line="/apps/jcruncherEx.jar"/>
  </exec>   
</target>  

During development, you can start the interactive mode as:

/myApp/$ java -jar /path/to/jcruncherEx.jar -i   

And during your build process, the exact same instruction will be taken in consideration (note, in future releases we will allow to specify a .cfg file to allow branching when needed).

Best Practice: render method

It can be very useful to have a little global function in your application that wrap the handlebars logic. This could come in very handy when handling errors or eventual future refactoring.

// --------- Render --------- //
// Just a little indirection to render a template using handlebars.
// This simple indirection allows much flexibility later one, 
// when using pre-compiling or other templating engine are needed.
Handlebars.templates = Handlebars.templates || {}; 
// make all templates partials (very useful)
Handlebars.partials =  Handlebars.templates;

function render(templateName,data){
  var tmpl = Handlebars.templates[templateName];

  if (!tmpl){
    var html = $("#" + templateName).html();
    if (!html){
      throw "Not template found in pre-compiled and in DOM for " + templateName;
    }
    tmpl = Handlebars.compile(html);
    Handlebars.templates[templateName] = tmpl;
  }
  return tmpl(data);
}

// --------- /Render --------- //

Roadmap