jMaki Ajax Performance Enhancer

What problem are we trying to solve?

Using Ajax components in a web page can make slow the performance of your web pages as they load resources over the network and as a page is rendered by the browser.

Network Performance

Like many Ajax applications jMaki includes many CSS and JavaScript resources which can increase the number of HTTP requests and slow down the initial load of a page. The contents of CSS and JavaScript can be large and require a lot of bandwidth to transfer to a client. Subsequent calls from a browser for resources can result in the resources being re-sent to the browser.

Page Rendering

Page rendering in all the modern browsers will stop as JavaScript and CSS resources are loaded over a network causing a pages to render slower. While some of this is perceived slowness by an end user it can lead to frustration.

A solution is needed that will improve both the network performance and browser loading of Ajax based applications

jMaki Performance Enhancer

jMaki was designed to manage the rendering of Ajax resources and has been modified as of jMaki 1.8 to do the following:

These features require a server runtime to perform because they be done before a page is returned to the client. jMaki already promotes a model where CSS and JavaScript resources are externalized so adding these capabilities to the server runtime was not difficult given the jMaki server runtime manages the resources rendered to a page.


Here are some under the hood details on what jMaki does to improve the performance.

Combined Resources

Widget names are aggregated for a given page and used to generate MD5 hashes representing all the component.css or component.js files (different hashes for each). The runtime will look to see if a combined resource has been generated and create one if it does not exist. There is one combined CSS file and one combined JavaScript file for all the widgets in a given page. Two pages containing the same set of widgets will only result in one combined resource. The CSS resources for all widgets in a given page are rendered at the correct time and still respect the jMaki theming model which follows the standard CSS cascade.

Minified Resources

jMaki can automatically load a minified component-min.js in place of component.js if the resource is provided. The minified resources will be used in the combined JavaScript resource that is generated if this feature is turned on.

It is still the developers responsibility to generate the minified resource. There are many tools for minifiying code which include Dojo ShrinkSafe, Dean Edwards Packer, and Yahoo Compressor.


Max Age Header

The combined JavaScript and CSS resource files are stored in memory (Java) or file (PHP) for the max age of the specified resource (default is 24 hours). The max age is used as a bases for the expires and cache control headers which are also written out automatically. See the configuring below for more information.

Entity Header

This header is sent by clients to verify if the resource the client has matches what is on the server. The MD5 hash is used as the entity header JavaScript of CSS resource file. Given that if your files are updated frequently you may want to consider reducing configuring max age to be a shorter duration.

jMaki Performance Enhancer Setup and Configuration

You will need to have version 1.8 of better of jMaki to use this feature. Currently we only provide this for PHP / JSP /JSF. Get the latest jMaki from the downloads page.



In PHP you will need to create a "cache" directory in the same directory as your jMaki.php. The permissions on the cache directory must be set such that the process running PHP can write files to the cache directory. You also need to make sure that the Cache.php file is located in the same directory as your jMaki.php file.

Enabling Combined Resources

Configuration of the performance options is done by modifying the following variables that appear at the top of the in the jMaki.php file.

combineScriptsCombine all JavaScript resources.false
combineStylesCombine all CSS resources.false
combineResourcesMaxAgeMax age to keep content in seconds.345,600
useMinimizedJSUse minified JavaScript.false

Further customization could be done by modfiying the Cache.php which manages the chached content.

Java (JSP / JSF)


In Java a servlet needs to be configured in your web.xml file to serve cached resources which are kept in memory. The servlet class is included in the jmaki library is:


You will need to add the servlet mapping should be:


If you use a servlet mapping other than the one above you will need to configure the jMaki runtime with the new location.

Enabling Combined Resources

Configuration of the performance options in Java is done by modifying the following context parameters in the web.xml:

jmaki-combined-resources-serviceURL mapping to the Serlvet that renders the cached content./cr
jmaki-combinescriptsCombine all JavaScript resources.false
jmaki-combinestylesCombine all CSS resources.false
jmaki-combined-resources-maxageMax age to keep content in seconds.345,600
jmaki-useminifiedUse minified JavaScript.true

The cached content is stored in the Servlet context and is flushed when an application is re-deployed.

The following snippet is the minimal set of things you need in your web.xml.

        <servlet-name>Combined Resource Servlet</servlet-name>
        <servlet-name>Combined Resource Servlet</servlet-name>

If you have any problems or issues with the caching please direct questions to the jMaki Forums.


Yahoo has provided a great set of guidelines and client tooling for analyzing performance issues. See the Yahoo Performance page for more details and resources.