Skip to content
This repository
Newer
Older
100644 180 lines (113 sloc) 11.147 kb
33c5a679 »
2012-06-11 start to the new readme
1 # jQuery Mobile
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
7 You can find more information about how the library works, and what it is capable of, by reading the [documentation](http://jquerymobile.com/demos/).
8
9 ## Issues
10
11 When [submitting issues on github](https://github.com/jquery/jquery-mobile/issues/new) please include the following:
12
13 1. Issue description
49cbb17e »
2012-07-22 Readme: updated the jsbin template to use jQuery 1.7.2
14 2. Sample page using our [jsbin template](http://jsbin.com/orucec/edit#html) which uses latest code
33c5a679 »
2012-06-11 start to the new readme
15 3. Steps to reproduce
16 4. Expected outcome
17 5. Actual outcome
672d4ee4 »
2012-07-08 Readme: Added a line about checking existing tickets before opening a…
18 6. jQuery Mobile version
19 7. Browsers/platforms tested
33c5a679 »
2012-06-11 start to the new readme
20
706268b2 »
2012-06-21 [README.md] Removed comma
21 Also, in the interest of creating more readable issues please include code snippets inside a triple backtick box appropriate for the JavaScript/HTML/CSS snippet you wish to discuss. More information is available at the [introduction page](http://github.github.com/github-flavored-markdown/) for github flavored markdown (see Syntax Highlighting).
33c5a679 »
2012-06-11 start to the new readme
22
672d4ee4 »
2012-07-08 Readme: Added a line about checking existing tickets before opening a…
23 Before opening a new ticket check if the same or a similar issue already has been reported. Tip: Besides the search tool of the issue tracker you can filter issues by label.
24
383cc1ad »
2012-07-11 Readme: Added note about reporting ThemeRoller and Download Builder i…
25 The jQuery Mobile [ThemeRoller](https://github.com/jquery/web-jquery-mobile-theme-roller) and [Download Builder](https://github.com/jquery/jquery-mobile-builder) have their own repo where you can report issues.
26
33c5a679 »
2012-06-11 start to the new readme
27 ## Pull Requests
28
7c8e8e60 »
2012-06-16 readme: few := a few
29 When submitting a pull request for review there are a 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):
33c5a679 »
2012-06-11 start to the new readme
30
a0e897d8 »
2012-06-11 wording and spelling corrections
31 1. Include tests (see [Testing](#testing))
33c5a679 »
2012-06-11 start to the new readme
32 2. Follow the [jQuery Core style guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
33 3. Limit the scope to one Issue/Feature
34 4. Small focused commits, ideally less than 10 to 20 lines
9913124b »
2012-06-12 corrections coutesy of @uGoMobi
35 5. Avoid merge commits (see Pro Git's [chapter on rebasing](http://git-scm.com/book/ch3-6.html), section [Rebasing](#rebasing) below)
47e9bda8 »
2012-06-30 Readme: added info regarding what a commit message should include
36 6. Add the appropriate commit message (see below)
fee9cde5 »
2012-06-30 Readme: added a necessary new line for formatting
37
33c5a679 »
2012-06-11 start to the new readme
38 Taken together, the above reduces the effort that's required of the contributor reviewing your pull request.
39
a33ff15c »
2012-07-11 clarify web server ref in README
40 ### Commit messages
47e9bda8 »
2012-06-30 Readme: added info regarding what a commit message should include
41
42 Commit messages should include four components:
43 * The WHERE - a single word that categorizes and provides context for the commit and its message, followed by a colon (:). This is typically the name of the plugin being worked on, but sometimes might be something like Build: or Docs:
44 * The WHAT - a sufficient summary of the fix or change made (example: modified the foo to no longer bar), followed by a period (.)
45 * The WHY #Num - the ticket number with a #sign so Trac creates a hyperlink (example: #1234), followed by a hyphen/dash (-)
46 * The WHY Name - the name of the ticket. Notice this is different than summary of the fix. This is a short description of the issue (example: dialog: IE6 crashed when foo is set to bar)
47
48 Combined into one, here's a full example:
517b3c47 »
2012-06-30 readme: trying again to fix indentation of commit message content
49
f84a4344 »
2012-06-30 Readme: trying to fix indentation of commit message content
50 "Dialog: modified the foo to no longer bar. Fixed #1234 - dialog: IE6 crashed when foo is set to bar"
51 \WHERE/:\------------- WHAT -------------/.\ WHY #Num /-\---------------- WHY Name ----------------/
a33ff15c »
2012-07-11 clarify web server ref in README
52
47e9bda8 »
2012-06-30 Readme: added info regarding what a commit message should include
53
33c5a679 »
2012-06-11 start to the new readme
54 ## Build/Customization
55
56 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:
57
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
58 * `js` - resolve dependencies, build, concat, and minify the JavaScript used for jQuery Mobile
59 * `css` - resolve dependencies, build, concat, and minify all the css, just the structure css, and just the theme css
60 * `docs` - build the js and css, and make the docs ready for static consumption
12a1ab14 »
2012-06-11 spelling
61 * `zip` - package all the JavaScript and all the css into a zip archive
33c5a679 »
2012-06-11 start to the new readme
62
d207905c »
2012-08-14 readme update with download builder link
63 ### Download Builder
64
65 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.
66
33c5a679 »
2012-06-11 start to the new readme
67 ### Requirements
68
15666d5f »
2012-06-12 too many 'other's
69 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).
33c5a679 »
2012-06-11 start to the new readme
70
71 ### Commands
72
73 With node installed you can run the `js` and `css` targets by simply issuing the following from the project root:
74
75 npm install
f11bd34e »
2012-06-17 Fixed typo on build command: .gin x .bin
76 node node_modules/.bin/grunt js # or css
33c5a679 »
2012-06-11 start to the new readme
77
f11bd34e »
2012-06-17 Fixed typo on build command: .gin x .bin
78 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`.
33c5a679 »
2012-06-11 start to the new readme
79
80 If you want to use the `docs` and `zip` targets you will need bash and they can be run with the following
81
a4d1c96b »
2012-07-10 Readme: added missing backticks.
82 `grunt docs #` or `grunt zip`
33c5a679 »
2012-06-11 start to the new readme
83
84 ### JavaScript
85
86 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`.
87
88 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:
89
90 ```diff
91 diff --git a/js/jquery.mobile.js b/js/jquery.mobile.js
92 index 6200fe6..3a4625c 100644
93 --- a/js/jquery.mobile.js
94 +++ b/js/jquery.mobile.js
95 @@ -19,12 +19,6 @@ define([
96 './jquery.mobile.listview.filter',
97 './jquery.mobile.listview.autodividers',
98 './jquery.mobile.nojs',
99 - './jquery.mobile.forms.checkboxradio',
100 - './jquery.mobile.forms.button',
101 - './jquery.mobile.forms.slider',
102 - './jquery.mobile.forms.textinput',
103 - './jquery.mobile.forms.select.custom',
104 - './jquery.mobile.forms.select',
105 './jquery.mobile.buttonMarkup',
106 './jquery.mobile.controlGroup',
107 './jquery.mobile.links',
108 ```
109
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
110 And then run the build:
33c5a679 »
2012-06-11 start to the new readme
111
112 grunt js
113
114 ### CSS
115
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
116 To create a new theme:
33c5a679 »
2012-06-11 start to the new readme
117
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
118 1. Copy the `default` folder from CSS/Themes to a new folder named after your new theme (eg, `my-theme`).
119 2. Add customizations to the `jquery.mobile.theme.css` file.
120 3. From the project root run the following `grunt` command:
33c5a679 »
2012-06-11 start to the new readme
121
15ac8d64 »
2012-06-12 clarifying custom theme info
122 THEME=my-theme grunt css
33c5a679 »
2012-06-11 start to the new readme
123
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
124 4. The output will be available in the `$PROJECT_ROOT/compiled`
33c5a679 »
2012-06-11 start to the new readme
125
15ac8d64 »
2012-06-12 clarifying custom theme info
126 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.
33c5a679 »
2012-06-11 start to the new readme
127
128 ## Development
129
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
130 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.
11dbc577 »
2011-11-01 Added link to JS Bin template
131
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
132 ### Server
2b4a29c9 »
2012-04-16 Update README.md
133
12a1ab14 »
2012-06-11 spelling
134 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:
a51adb98 »
2011-01-31 updated the readme with more helpful information
135
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
136 * one-click - [MAMP](http://www.mamp.info/en/downloads/index.html) for OSX, [XAMP](http://www.apachefriends.org/en/xampp.html) for OSX/Windows
12a1ab14 »
2012-06-11 spelling
137 * existing web server - eg, `~/Sites` directory on OSX.
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
138 * 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`
a51adb98 »
2011-01-31 updated the readme with more helpful information
139
12a1ab14 »
2012-06-11 spelling
140 In addition to vanilla Apache the following modules are required:
a51adb98 »
2011-01-31 updated the readme with more helpful information
141
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
142 * Rewrite (mod\_rewrite.so)
143 * Expire (mod\_expires.so)
144 * Header (mod\_headers.so)
00f86c83 »
2011-07-14 update docs regarding running demos
145
12a1ab14 »
2012-06-11 spelling
146 Once you have your web server setup you can point it at the project directory.
5c86ca64 »
2011-10-17 Readme changes
147
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
148 ### Testing
5c86ca64 »
2011-10-17 Readme changes
149
95a6dc8c »
2012-06-12 in for => for
150 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.
a51adb98 »
2011-01-31 updated the readme with more helpful information
151
ddec4647 »
2012-07-11 add protocol requirement to webserver reference
152 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:
a51adb98 »
2011-01-31 updated the readme with more helpful information
153
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
154 grunt config:test:pages
6bc5c659 »
2011-10-18 Update to include instructions on how to build using a custom theme.
155
bf74dfaa »
2012-06-12 link to build requirements
156 _NOTE_ See the [build requirements](#requirements) for node/grunt install information.
157
96c6179a »
2012-06-12 removed extra 'the'
158 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:
e26d7de1 »
2012-01-04 added note about local server support for development
159
12a1ab14 »
2012-06-11 spelling
160 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
e26d7de1 »
2012-01-04 added note about local server support for development
161
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
162 You can confine the headless run to a single test page or set of test pages using the `TEST_PATH` environment variable. For example:
c97e4d10 »
2012-02-21 corrected docs to reflect revert to /js/
163
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
164 TEST_PATH=slider JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
c97e4d10 »
2012-02-21 corrected docs to reflect revert to /js/
165
e3c173e2 »
2012-06-30 replaced uppercase with lowercase
166 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 both of the currently supported versions 1.6.4, and 1.7.1 the command would take the following form:
e26d7de1 »
2012-01-04 added note about local server support for development
167
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
168 JQUERY=1.6.4,1.7.1 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
db42f18e »
2012-01-04 note about fouc
169
2719b181 »
2012-06-11 added page listing for testers, removed old readme content, expanded …
170 ### Rebasing
e26d7de1 »
2012-01-04 added note about local server support for development
171
324d1e6e »
2012-06-16 readme: tiny typo: requests := request
172 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`:
16ea3fae »
2011-10-18 Update README.md
173
29705a1e »
2012-06-12 small snippet on rebasing
174 git checkout new-feature
175 git fetch upstream
176 git rebase upstream/master
177 ## ... here you may have to resolve some conflicts ... ##
6bc5c659 »
2011-10-18 Update to include instructions on how to build using a custom theme.
178
4f56b512 »
2012-06-12 removed another extra 'the'
179 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.