The first Alpha release of the jQuery Mobile framework has been released for a while now and more and more people are getting involved logging bugs and providing feedback. But some of us might want to get involved even more by actually contributing fixes to code as well as documentation, demos etc. The jQuery Mobile project has set-up the project in such a way that it is pretty straight forward for anyone to start contributing but, I have seen quite a few comments from people not entirely sure where to begin and how to get their environment successfully set-up.

With that, I decided to put together this article to get you up and running and contributing quickly. In this article I will point you to quite a few external resources that discuss getting a specific part of the development environment set-up. I feel confident that if you follow these steps you will not have any difficulty but, should you run into any problems, please do not hesitate to post your questions in the comments. Also note, that in this article I will be focusing on the Windows platform however, the steps to get this up and running on Linux and Mac is pretty much the same, just easier and you can find just about all the information you require from the Github help pages.

With that, let’s get started setting up the environment. jQuery Mobile, as with all the other parts of jQuery, is hosted on Github.com so the very first thing you would want to do, is go ahead and register an account for yourself on Github. After you are registered and up and running we need to install Git on Windows. Thanks to the work done by the folks behind mSysGit, getting Git up and running on Windows is not the nightmare it used to be. Head over to the mSysGit project page and download the installer. After the download is complete, simply run the installer and follow the steps.

Next step is to generate your SSH keys that will be used when interacting with repositories on Github, follow the instructions here. Next you will need to set your username, email and Github token if required. Now that Git is installed and configured go to the jQuery Mobile project on Github. On the project page create a new fork of the project and then proceed to create a local clone thereof.

Great, so we have accomplished a lot already. We have a forked version of jQuery Mobile, have git installed, and have a copy of the code locally. The way the project is set-up is going to require us to have a local PHP capable server. Now setting up Apache with PHP is not the most daunting of tasks but, for our purposes, we are going to use a prebuilt stack to speed this process up. Head over to the XAMPP website and download a copy of the latest version. Simply download the .exe for quick and simple installation once the download completes.

Now you have your server but, it needs a couple of little tweaks before we are ready to roll. Go to the following location inside the installation directory: xampp\apache\conf and open up the httpd.conf file. We need to enable a couple of modules for the PHP files inside the jQuery Mobile project to work correctly. Search for the following entries:

LoadModule rewrite_module modules/mod_rewrite.so
LoadModule expires_module modules/mod_expires.so
LoadModule headers_module modules/mod_headers.so

For each of these entries, ensure that they are not commented out i.e. the line does not start with a #. If the Apache server is already running you will need to restart it using the Control Panel located at Start > All Programs > XAMPP for Windows > XAMPP Control Panel. The next step is to configure our server’s document root to point to our repository. Open up the http.conf file again and search for DocumentRoot and change it to the following:

DocumentRoot "C:/path/to/jquery-mobile"

Next find the Directory entry and change it to:

<Directory "C:/path/to/jquery-mobile">

You can now fire up your browser and navigate to http://localhost/ and you should see the following:

One of the things that is happening behind the scenes here is that when you load the page there is some rewriting happening in the background that brings the whole PHP thing into play. If you open up the source you will see the following two lines:

<link rel="stylesheet" href="themes/default" />
<script src="js/all"></script>

Now open up the .htaccess file in the root directory. The following lines are the important one’s:

RewriteEngine On
RewriteRule ^themes/([a-zA-Z\-\_\0-9]+)\/$ combine.php?type=css&theme=$1
RewriteRule ^js/all combine.php?type=javascript

So as you can see from the above, the links in the above CSS and JavaScript imports will be rewritten and be handled by the combine.php file. From the name you can tell that this will combine a set of either CSS or JavaScript files and return the combined file. I am not going to go into to much detail regarding the PHP file but, what you need to understand is where the files are located that will be combined and how to tell the combine script what to include.

At the top of the combine.php file you will find these two lines:

$cssdir = dirname(__FILE__) . '/themes/' . $theme;
$jsdir = dirname(__FILE__) . '/js';

So all your JavaScript will always be located in the js directory at the root of the project folder and your CSS will be inside the specified theme, in our case above the default theme, in the themes folder. Now say you wish to add another JavaScript or CSS file to the set that is combined, how do you go about that? This is governed by a manifest.php file that lives inside each of the directories. The manifest file is a comma separated list of file names to be included so, whenever you add a new file, copy it to the appropriate folder and add it to the manifest and that’s it.

One question you may have is that, “What if I want to test against my own application? How do I get access to the newly combined CSS and JS file?”. Well currently you can create a cache folder in the project root directory and a gzipped version of both the CSS and JavaScript files will be written there. With that said, I am not entirely convinced that you can simply link these in the head of your document and at the same time, if errors are thrown it will most likely be a nightmare to debug.

At the moment your best bet therefor is to open the source of the document, click on the link to the CSS file theme/default and/or the JavaScript file in the browser and copy and paste the results into your own files that you can then link to in your own app. I have added a function to the combine.php, and submitted a pull request, that will write the CSS and JavaScript files to a folder called ‘combined’ and hopefully this will be pushed into the master branch.

So, you’re environment is set-up and you are ready to start squishing bugs but, what do you do once you have fixed a bug? Fire up the Git Bash from Start > All Programs > Git > Git Bash. First move into our repo using cd jquery-mobile. We now need to commit the changes locally. To do this run the command:

git commit -a -m "Your commit message"

Once this command completes you need to push your changes to Github:

git push origin master

Once the command completes, your changes will be committed to your fork of jQuery Mobile. Now you need to get your changes merged into the master branch. To do this, you need to initiate a pull request. You can read the details about pull requests on the Github site but basically, this will send a notification to the required people that you have some changes you wish to be pulled into the master branch. Once the pull request is initiated, someone from the core team will review your changes and merge them into the master repo if appropriate. That’s it, you are all set to start contributing to jQuery Mobile.

As an alternative, if you simply want to grab a copy of the latest source, make your fixes and generate a combined version of the JS and CSS to test against your own application and confirm that you fixes works, you might not want to go about setting up a XAMPP server, doing the configuration and load up the index file to have these generated. If you have Java and Ant currently on your system, I have written a simple Ant build file that will achieve the above, which you can download from here. I have also added a pull request to add this to the master of jQuery Mobile so keep an eye out for that. To use the Ant build file, simply copy the build.xml to the root of your project folder and edit the XML file as appropriate. There is basically four items you would want to edit and those are:

<property name="cssdir" location="themes/default"/>
<property name="jsdir" location="js"/>
<property name="css-sources" value="comma, list, of, css, files"/>
<property name="js-sources" value="comma, list, of, javascript, files"/>

I hope you find this information useful and I look forward to everyone’s comments and seeing your contributions to jQuery Mobile.