This is the main repository for the jQuery Mobile project. From the official website:
A unified, HTML5-based user interface system for all popular mobile device platforms, built on the rock-solid jQuery and jQuery UI foundation. Its lightweight code is built with progressive enhancement, and has a flexible, easily themeable design.
You can find more information about how the library works, and what it is capable of, by reading the documentation.
When submitting issues on github please include the following:
- Issue description
- Sample page using our jsbin template (TODO get link)
- Steps to reproduce
- Expected outcome
- Actual outcome
- Browers tested
- Library version
When submitting a pull request for review there are few important steps you can take to ensure that it gets reviewed quickly and increase the chances that it will be merged (in order of descending importance):
- Include tests (see Development)
- Follow the jQuery Core style guide
- Limit the scope to one Issue/Feature
- Small focused commits, ideally less than 10 to 20 lines
- Avoid merge commits (see Pro Git's chapter on Rebasing, Development)
Taken together, the above reduces the effort that's required of the contributor reviewing your pull request.
css- resolve dependencies, build, concat, and minify all the css, just the structure css, and just the theme css
docs- build the js and css, and make the docs ready for static consumption
zip- package the documentation in zip format for distribution
The build requires node.js and its packaged npm package manager. For other build targets like
zip it also requires Bash. For more information on installing node please see its documentation. For Bash and Make please refer to the appropriate documentation for your opperating system.
With node installed you can run the
css targets by simply issuing the following from the project root:
npm install node node_modules/.gin/grunt js # or css
Note that if you have the appropriate version of grunt, our build tool, installed globally you can substitute
grunt whereever you see
node node_modules/.gin/grunt. For the remainder of the build documentation we will prefer the more concise
If you want to use the
zip targets you will need bash and they can be run with the following
grunt docs # or
For example, if a user wished to exclude the form widgets to reduce the wire weight of their jQuery Mobile include they would first remove them from the meta module:
diff --git a/js/jquery.mobile.js b/js/jquery.mobile.js index 6200fe6..3a4625c 100644 --- a/js/jquery.mobile.js +++ b/js/jquery.mobile.js @@ -19,12 +19,6 @@ define([ './jquery.mobile.listview.filter', './jquery.mobile.listview.autodividers', './jquery.mobile.nojs', - './jquery.mobile.forms.checkboxradio', - './jquery.mobile.forms.button', - './jquery.mobile.forms.slider', - './jquery.mobile.forms.textinput', - './jquery.mobile.forms.select.custom', - './jquery.mobile.forms.select', './jquery.mobile.buttonMarkup', './jquery.mobile.controlGroup', './jquery.mobile.links',
And then run the build:
To create a new theme:
- Copy the
defaultfolder from CSS/Themes to a new folder named after your new theme (eg,
- Add customizations to the
From the project root run the following
THEME=my-theme grunt css
The output will be available in the
Again assumes the theme css files are available in the
css/theme/$THEME/ directory relative to the project root.
The root of the repository is also the root of the documentation and, along with the test suite, acts as the test bed for bug fixes and features. You'll need to set up a server and get the test suite running before you can contribute patches.
Most of the documentation and testing pages rely on PHP 5+, and as a result Apache and PHP are required for development. You can installthem using one of the following methods:
- one-click - MAMP for OSX, XAMP for OSX/Windows
- existing webserver - eg,
~/Sitesdirectory on OSX.
- virtual machine - If Vagrant is installed you can add this remote/branch and
In addition to vanilla Apache the folloing modules are requied:
- Rewrite (mod_rewrite.so)
- Expire (mod_expires.so)
- Header (mod_headers.so)
Once you have your webserver setup you can point it at the project directory.
Automated testing forms the backbone of the jQuery Mobile project's QA activities. As a contributor or patch submitter you will be excpected to run the test suite in for the area which you patches affect. Our continuous integration server will address the rest.
There are two primary ways to run the test suite. First, you can run the tests individually by visiting the different test pages associated with the area in which you are working. For example, to run the tests for
$HOST/tests/unit/slider/. To find out what which test pages are available you can list them with:
JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$HOST grunt test
You can confine the headless run to a single test page or set of test pages using the
TEST_PATH environment variable. For example:
TEST_PATH=slider JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
Will only run the tests whos paths contain the string slider. NOTE That the phantom tests currently require that the webserver be running to access and run the tests properly because of the PHP dependency that many of them share.
Additionally we run the test suite against many version of jQuery using the
JQUERY environment variable. For example if you wanted to run the test suite against both of our currently supported versions 1.6.4, and 1.7.1 the command would take the following form:
JQUERY=1.6.4,1.7.1 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test