Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 141 lines (86 sloc) 8.743 kb
14cd0af Ghislain Seguin Updated version to 1.3.0 and added Travis CI image
gseguin authored
1 # jQuery Mobile [![Build Status](https://travis-ci.org/jquery/jquery-mobile.png?branch=1.3-stable)](https://travis-ci.org/jquery/jquery-mobile)
33c5a67 John Bender start to the new readme
johnbender authored
2
3 This is the main repository for the jQuery Mobile project. From the [official website](http://jquerymobile.com):
4
5 > 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.
6
870a1ac Alexander Schmitz Readme: update version in readme.md
arschmitz authored
7 jQuery Mobile 1.3 (1.3.2) works with versions of jQuery core from 1.7.0 to 1.9.0. You can find more information about how the library works, and what it is capable of, by reading the [documentation](http://jquerymobile.com/demos/).
33c5a67 John Bender start to the new readme
johnbender authored
8
04a1ec9 Jasper de Groot Updated the contributing section in Readme
jaspermdegroot authored
9 ## Contributing
33c5a67 John Bender start to the new readme
johnbender authored
10
c252132 Jasper de Groot Update Readme to core 1.8.2
jaspermdegroot authored
11 You can contribute to the project by reporting issues, suggesting new features, or submitting pull requests.
04a1ec9 Jasper de Groot Updated the contributing section in Readme
jaspermdegroot authored
12 Please read our [Contributing Guidelines](https://github.com/jquery/jquery-mobile/blob/master/CONTRIBUTING.md) before submitting.
a33ff15 John Bender clarify web server ref in README
johnbender authored
13
47e9bda Anne-Gaelle Colom Readme: added info regarding what a commit message should include
agcolom authored
14
33c5a67 John Bender start to the new readme
johnbender authored
15 ## Build/Customization
16
17 Currently the library is shipped on the jQuery CDN/download as a single monolithic JavaScript file that depends on jQuery Core (not included) and a similarly bundled CSS file. For users we support the following build targets:
18
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
19 * `js` - resolve dependencies, build, concat, and minify the JavaScript used for jQuery Mobile
20 * `css` - resolve dependencies, build, concat, and minify all the css, just the structure css, and just the theme css
21 * `docs` - build the js and css, and make the docs ready for static consumption
12a1ab1 John Bender spelling
johnbender authored
22 * `zip` - package all the JavaScript and all the css into a zip archive
33c5a67 John Bender start to the new readme
johnbender authored
23
d207905 John Bender readme update with download builder link
johnbender authored
24 ### Download Builder
25
26 The easiest way to obtain a custom build is to use the [download builder](http://jquerymobile.com/download-builder/). With it, you can select the parts of the library you need and both the CSS and JavaScript dependencies will be resolved for you as a packaged/minified whole.
27
33c5a67 John Bender start to the new readme
johnbender authored
28 ### Requirements
29
15666d5 John Bender too many 'other's
johnbender authored
30 The `js` and `css` build targets require [node.js](http://nodejs.org/) and its packaged NPM package manager. For the other build targets, `docs` and `zip`, bash is also required. For more information on installing node please see its [documentation](http://nodejs.org/#download). As for bash it's generally installed as the default shell in many POSIX compliant environments (OSX, Linux, BSD, etc).
33c5a67 John Bender start to the new readme
johnbender authored
31
32 ### Commands
33
34 With node installed you can run the `js` and `css` targets by simply issuing the following from the project root:
35
36 npm install
f11bd34 Fixed typo on build command: .gin x .bin
Darío Javier Cravero authored
37 node node_modules/.bin/grunt js # or css
33c5a67 John Bender start to the new readme
johnbender authored
38
f11bd34 Fixed typo on build command: .gin x .bin
Darío Javier Cravero authored
39 Note that if you have the appropriate version of [grunt](https://github.com/cowboy/grunt), our build tool, installed globally you can substitute `grunt` wherever you see `node node_modules/.bin/grunt`. For the remainder of the build documentation we will prefer the more concise `grunt`.
33c5a67 John Bender start to the new readme
johnbender authored
40
41 If you want to use the `docs` and `zip` targets you will need bash and they can be run with the following
42
a4d1c96 Jasper de Groot Readme: added missing backticks.
jaspermdegroot authored
43 `grunt docs #` or `grunt zip`
33c5a67 John Bender start to the new readme
johnbender authored
44
45 ### JavaScript
46
47 As of version 1.1 the library uses dependency management in the JavaScript build by providing [AMD modules](https://github.com/amdjs/amdjs-api/wiki/AMD) which can be added or removed from the core mobile meta module `js/jquery.mobile.js`.
48
49 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:
50
51 ```diff
52 diff --git a/js/jquery.mobile.js b/js/jquery.mobile.js
53 index 6200fe6..3a4625c 100644
54 --- a/js/jquery.mobile.js
55 +++ b/js/jquery.mobile.js
56 @@ -19,12 +19,6 @@ define([
57 './jquery.mobile.listview.filter',
58 './jquery.mobile.listview.autodividers',
59 './jquery.mobile.nojs',
60 - './jquery.mobile.forms.checkboxradio',
61 - './jquery.mobile.forms.button',
62 - './jquery.mobile.forms.slider',
63 - './jquery.mobile.forms.textinput',
64 - './jquery.mobile.forms.select.custom',
65 - './jquery.mobile.forms.select',
66 './jquery.mobile.buttonMarkup',
67 './jquery.mobile.controlGroup',
68 './jquery.mobile.links',
69 ```
70
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
71 And then run the build:
33c5a67 John Bender start to the new readme
johnbender authored
72
73 grunt js
74
75 ### CSS
76
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
77 To create a new theme:
33c5a67 John Bender start to the new readme
johnbender authored
78
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
79 1. Copy the `default` folder from CSS/Themes to a new folder named after your new theme (eg, `my-theme`).
80 2. Add customizations to the `jquery.mobile.theme.css` file.
81 3. From the project root run the following `grunt` command:
33c5a67 John Bender start to the new readme
johnbender authored
82
15ac8d6 John Bender clarifying custom theme info
johnbender authored
83 THEME=my-theme grunt css
33c5a67 John Bender start to the new readme
johnbender authored
84
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
85 4. The output will be available in the `$PROJECT_ROOT/compiled`
33c5a67 John Bender start to the new readme
johnbender authored
86
15ac8d6 John Bender clarifying custom theme info
johnbender authored
87 Again this assumes the theme css files are available in the `css/themes/$THEME/` directory relative to the project root, `css/themes/my-theme/` in the example.
33c5a67 John Bender start to the new readme
johnbender authored
88
89 ## Development
90
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
91 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.
11dbc57 Todd Parker Added link to JS Bin template
toddparker authored
92
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
93 ### Server
2b4a29c Jasper de Groot Update README.md
jaspermdegroot authored
94
12a1ab1 John Bender spelling
johnbender authored
95 Most of the documentation and testing pages rely on PHP 5+, and as a result Apache and PHP are required for development. You can install them using one of the following methods:
a51adb9 updated the readme with more helpful information
scottjehl authored
96
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
97 * one-click - [MAMP](http://www.mamp.info/en/downloads/index.html) for OSX, [XAMP](http://www.apachefriends.org/en/xampp.html) for OSX/Windows
12a1ab1 John Bender spelling
johnbender authored
98 * existing web server - eg, `~/Sites` directory on OSX.
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
99 * virtual machine - If [Vagrant](http://vagrantup.com) is installed you can add [this remote/branch](https://github.com/johnbender/jquery-mobile/tree/vagrant) and `vagrant up`
a51adb9 updated the readme with more helpful information
scottjehl authored
100
12a1ab1 John Bender spelling
johnbender authored
101 In addition to vanilla Apache the following modules are required:
a51adb9 updated the readme with more helpful information
scottjehl authored
102
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
103 * Rewrite (mod\_rewrite.so)
104 * Expire (mod\_expires.so)
105 * Header (mod\_headers.so)
00f86c8 update docs regarding running demos
Matt authored
106
12a1ab1 John Bender spelling
johnbender authored
107 Once you have your web server setup you can point it at the project directory.
5c86ca6 Eddie Monge Readme changes
eddiemonge authored
108
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
109 ### Testing
5c86ca6 Eddie Monge Readme changes
eddiemonge authored
110
95a6dc8 John Bender in for => for
johnbender authored
111 Automated testing forms the backbone of the jQuery Mobile project's QA activities. As a contributor or patch submitter you will be expected to run the test suite for the code your patches affect. Our continuous integration server will address the remainder of the test suite.
a51adb9 updated the readme with more helpful information
scottjehl authored
112
ddec464 John Bender add protocol requirement to webserver reference
johnbender authored
113 There are two primary ways to run the test suite. Both of them require a server configured in the previously prescribed manner. The location of which will hereafter be referred to as `$WEB_SERVER` and should include the protocol. First, you can run the tests individually by directing your browser to the different test pages associated with the area in which you are working. For example, to run the tests for `js/jquery.mobile.forms.slider.js` visit `$WEB_SERVER/tests/unit/slider/`. To find out which test pages are available you can list them with:
a51adb9 updated the readme with more helpful information
scottjehl authored
114
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
115 grunt config:test:pages
6bc5c65 Eddie Monge Update to include instructions on how to build using a custom theme.
eddiemonge authored
116
bf74dfa John Bender link to build requirements
johnbender authored
117 _NOTE_ See the [build requirements](#requirements) for node/grunt install information.
118
96c6179 Anne-Gaelle Colom removed extra 'the'
agcolom authored
119 Second you can run the tests using the [PhantomJS](http://phantomjs.org/) headless Webkit browser which must be [installed](http://code.google.com/p/phantomjs/wiki/Installation). Once `phantomjs` is in your `PATH` the following will execute the whole test suite:
e26d7de John Bender added note about local server support for development
johnbender authored
120
12a1ab1 John Bender spelling
johnbender authored
121 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
e26d7de John Bender added note about local server support for development
johnbender authored
122
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
123 You can confine the headless run to a single test page or set of test pages using the `TEST_PATH` environment variable. For example:
c97e4d1 John Bender corrected docs to reflect revert to /js/
johnbender authored
124
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
125 TEST_PATH=slider JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
c97e4d1 John Bender corrected docs to reflect revert to /js/
johnbender authored
126
6c12402 Alexander Schmitz Update to jQuery core 1.9
arschmitz authored
127 will only run the tests where the path contains the string `slider`, eg `tests/unit/slider/`. *NOTE* that the phantom tests currently require that the web server be running to access and run the tests properly because of the PHP dependency that many of them share. Additionally the test suite is run against many versions of jQuery using the `JQUERY` environment variable. For example if you wanted to run the test suite against two of the currently supported versions, 1.7.2 and 1.9.0, the command would take the following form:
e26d7de John Bender added note about local server support for development
johnbender authored
128
6c12402 Alexander Schmitz Update to jQuery core 1.9
arschmitz authored
129 JQUERY=1.7.2,1.9.0 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
db42f18 John Bender note about fouc
johnbender authored
130
2719b18 John Bender added page listing for testers, removed old readme content, expanded css...
johnbender authored
131 ### Rebasing
e26d7de John Bender added note about local server support for development
johnbender authored
132
324d1e6 Maurice Gottlieb readme: tiny typo: requests := request
MauriceG authored
133 Often times when working on a feature or bug fix branch it's useful to pull in the latest from the parent branch. If you're doing this _before_ submitting a pull request it's best to use git's rebase to apply your commits onto the latest from the parent branch. For example, working on `new-feature` branch where `upstream` is the remote at `git://github.com/jquery/jquery-mobile.git`:
16ea3fa Eddie Monge Update README.md
eddiemonge authored
134
29705a1 John Bender small snippet on rebasing
johnbender authored
135 git checkout new-feature
136 git fetch upstream
137 git rebase upstream/master
138 ## ... here you may have to resolve some conflicts ... ##
6bc5c65 Eddie Monge Update to include instructions on how to build using a custom theme.
eddiemonge authored
139
4f56b51 Anne-Gaelle Colom removed another extra 'the'
agcolom authored
140 You can now push to your own fork and submit the pull request. Keep in mind that it's only a good idea to do this if you _haven't_ already submitted a pull request unless you want to create a new one because your origin remote (your fork) will report a discrepancy. Again, please refer to the [chapter](http://git-scm.com/book/ch3-6.html) in Pro Git on rebasing if you're new to it.
Something went wrong with that request. Please try again.