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
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)
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 at least a Bash shell with the addition of Make providing a layer of user friendliness if necessary.
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
Alternatively if you have
make installed on your system
make 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',
To build using a custom theme simply specify the name with an environment variable.
THEME=valencia grunt css
This assumes the theme css files are available in the
css/theme/$THEME/ directory relative to the project root.
How to build your own jQuery Mobile CSS and JS files
Clone this repo and build the js and css files (you'll need Git and Make installed):
git clone git://github.com/jquery/jquery-mobile.git cd jquery-mobile make
Alternatively if you have node.js installed you can run
npm install node node_modules/.bin/grunt <js|css>
to build either the js or css. This is usefull especially if you're on Windows without support for the make tool and bash.
How to build a self-contained version of the Docs/Demos
Once you have your own cloned repo on your computer:
The docs will be built and available in the compiled/demos folder. You can move this folder to your web server or other location. It has no dependencies on anything other than a basic HTML web server.
If you think you've found a bug, please report it by following these instructions:
- Visit the Issue tracker: https://github.com/jquery/jquery-mobile/issues
- Create an issue explaining the problem and expected result
- Be sure to include any relevant information for reproducing the issue
- Include information such as:
- Browser/device (with version #)
- The version of the jQuery Mobile code you're running
- If you are running from a git version, include the date and/or hash number
- Make sure that the bug still exists at http://jquerymobile.com/test/ as it may be fixed already
- You can use the CDN hosted JS and CSS files to test in your own code by using:
- Include a link to some code of the bug in action. You can use either of these services to host your code
- Submit the issue.
Recommended: JS Bin issue template with instructions
Issues concerning the jQuery Mobile Theme Roller can be submitted at the Theme Roller repo: https://github.com/jquery/web-jquery-mobile-theme-roller
To contribute code and bug fixes to jQuery Mobile: fork this project on Github, make changes to the code in your fork, and then send a "pull request" to notify the team of updates that are ready to be reviewed for inclusion.
Detailed instructions can be found at jQuery Mobile Patching
Running the jQuery Mobile demos & docs locally
To preview locally, you'll need to clone a local copy of this repository and point your Apache & PHP webserver at its root directory (a webserver is required, as PHP and .htaccess are used for combining development files).
If you don't currently have a webserver running locally, there are a few options.
If you're on a Mac, you can try dropping jQuery Mobile into your sites folder and turning on Web Sharing via System Prefs. From there, you'll find a URL where you can browse folders in your sites directory from a browser.
Another quick way to get up and running is to download and install MAMP for Mac OSX. Once installed, just open MAMP, click preferences, go to the Apache tab, and select your local jQuery Mobile folder as the root. Then you can open a browser to http://localhost:8888 to preview the code.
Another alternative is XAMPP (Mac, Windows). You need to actually modify Apache's httpd.conf to point to your checkout: Instructions
You need the following Apache modules loaded:
- Rewrite (mod_rewrite.so)
- Expire (mod_expires.so)
- Header (mod_headers.so)
Alternatively, with the addition of async loading, you can use the python simple http server from the project root:
$ python -m SimpleHTTPServer 8000
And in your browser visit localhost:8000. NOTE: The docs will not load as they are dependent on the "/js/" includes which require php. For other development work such as unit tests and custom test pages using
<script data-main="js/jquery.mobile.docs" src="external/requirejs/require.js"></script>
will allow you to load modules asynchronously without php. Please note that the example above assumes it's inclusion in a page at the root of the directory in which the simple http server was run.
AMD Support in Development
Please bear in mind that async loading is not supported for production and is primarily used for the project's build process. As a result developers should expect an initial flash of unstyled content, which will not occur when the library is compiled.
If you find dependency bugs when using the async loading support for development please log them in the github issue tracker.
Building With A Custom Theme
To use a custom theme in your own build, you'll need Make installed. You can find the themes in the CSS/Themes folder. To create a new theme:
- Copy the
Defaultfolder from CSS/Themes to a new folder in the same location. The name of the folder will be the theme's name. For testing locally, make sure the index.php file is copied as well.
- Edit the
jquery.mobile.theme.cssfile so it contains your custom fonts and colors.
- Once you are done editing your files and saving them, open a terminal.
- Navigate to the jQuery-Mobile folder's root.
Run the following command to build jQuery-Mobile (THEME is the name of the folder for your theme from step 1.):
The compiled files will be located in the "compiled" folder in the root of jQuery-Mobile.