Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 150 lines (92 sloc) 8.223 kB
33c5a67 @johnbender start to the new readme
johnbender authored
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
12a1ab1 @johnbender spelling
johnbender authored
14 2. Sample page using our [jsbin template](http://jsbin.com/awoluv/edit#html)
33c5a67 @johnbender start to the new readme
johnbender authored
15 3. Steps to reproduce
16 4. Expected outcome
17 5. Actual outcome
12a1ab1 @johnbender spelling
johnbender authored
18 6. Browsers tested
a0e897d @johnbender wording and spelling corrections
johnbender authored
19 7. Library version/Location (eg, CDN or `jquerymobile.com/test/`)
33c5a67 @johnbender start to the new readme
johnbender authored
20
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).
22
23 ## Pull Requests
24
25 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):
26
a0e897d @johnbender wording and spelling corrections
johnbender authored
27 1. Include tests (see [Testing](#testing))
33c5a67 @johnbender start to the new readme
johnbender authored
28 2. Follow the [jQuery Core style guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
29 3. Limit the scope to one Issue/Feature
30 4. Small focused commits, ideally less than 10 to 20 lines
a0e897d @johnbender wording and spelling corrections
johnbender authored
31 5. Avoid merge commits (see Pro Git's [chapter on rebasing](http://git-scm.com/book/ch3-6.html), [Rebasing](#rebasing))
33c5a67 @johnbender start to the new readme
johnbender authored
32
33 Taken together, the above reduces the effort that's required of the contributor reviewing your pull request.
34
35 ## Build/Customization
36
37 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:
38
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
39 * `js` - resolve dependencies, build, concat, and minify the JavaScript used for jQuery Mobile
40 * `css` - resolve dependencies, build, concat, and minify all the css, just the structure css, and just the theme css
41 * `docs` - build the js and css, and make the docs ready for static consumption
12a1ab1 @johnbender spelling
johnbender authored
42 * `zip` - package all the JavaScript and all the css into a zip archive
33c5a67 @johnbender start to the new readme
johnbender authored
43
44 ### Requirements
45
12a1ab1 @johnbender spelling
johnbender authored
46 The `js` and `css` build targets require [node.js](http://nodejs.org/) and its packaged NPM package manager. For other the other build targets, `docs` and `zip`, bash is 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 @johnbender start to the new readme
johnbender authored
47
48 ### Commands
49
50 With node installed you can run the `js` and `css` targets by simply issuing the following from the project root:
51
52 npm install
53 node node_modules/.gin/grunt js # or css
54
12a1ab1 @johnbender spelling
johnbender authored
55 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/.gin/grunt`. For the remainder of the build documentation we will prefer the more concise `grunt`.
33c5a67 @johnbender start to the new readme
johnbender authored
56
57 If you want to use the `docs` and `zip` targets you will need bash and they can be run with the following
58
1567656 @johnbender simplify to grunt docs and grunt zip
johnbender authored
59 grunt docs # or `grunt zip`
33c5a67 @johnbender start to the new readme
johnbender authored
60
61 ### JavaScript
62
63 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`.
64
65 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:
66
67 ```diff
68 diff --git a/js/jquery.mobile.js b/js/jquery.mobile.js
69 index 6200fe6..3a4625c 100644
70 --- a/js/jquery.mobile.js
71 +++ b/js/jquery.mobile.js
72 @@ -19,12 +19,6 @@ define([
73 './jquery.mobile.listview.filter',
74 './jquery.mobile.listview.autodividers',
75 './jquery.mobile.nojs',
76 - './jquery.mobile.forms.checkboxradio',
77 - './jquery.mobile.forms.button',
78 - './jquery.mobile.forms.slider',
79 - './jquery.mobile.forms.textinput',
80 - './jquery.mobile.forms.select.custom',
81 - './jquery.mobile.forms.select',
82 './jquery.mobile.buttonMarkup',
83 './jquery.mobile.controlGroup',
84 './jquery.mobile.links',
85 ```
86
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
87 And then run the build:
33c5a67 @johnbender start to the new readme
johnbender authored
88
89 grunt js
90
91 ### CSS
92
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
93 To create a new theme:
33c5a67 @johnbender start to the new readme
johnbender authored
94
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
95 1. Copy the `default` folder from CSS/Themes to a new folder named after your new theme (eg, `my-theme`).
96 2. Add customizations to the `jquery.mobile.theme.css` file.
97 3. From the project root run the following `grunt` command:
33c5a67 @johnbender start to the new readme
johnbender authored
98
15ac8d6 @johnbender clarifying custom theme info
johnbender authored
99 THEME=my-theme grunt css
33c5a67 @johnbender start to the new readme
johnbender authored
100
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
101 4. The output will be available in the `$PROJECT_ROOT/compiled`
33c5a67 @johnbender start to the new readme
johnbender authored
102
15ac8d6 @johnbender clarifying custom theme info
johnbender authored
103 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 @johnbender start to the new readme
johnbender authored
104
105 ## Development
106
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
107 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 @toddparker Added link to JS Bin template
toddparker authored
108
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
109 ### Server
2b4a29c @jaspermdegroot Update README.md
jaspermdegroot authored
110
12a1ab1 @johnbender spelling
johnbender authored
111 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
112
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
113 * 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 @johnbender spelling
johnbender authored
114 * existing web server - eg, `~/Sites` directory on OSX.
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
115 * 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
116
12a1ab1 @johnbender spelling
johnbender authored
117 In addition to vanilla Apache the following modules are required:
a51adb9 updated the readme with more helpful information
scottjehl authored
118
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
119 * Rewrite (mod\_rewrite.so)
120 * Expire (mod\_expires.so)
121 * Header (mod\_headers.so)
00f86c8 update docs regarding running demos
Matt authored
122
12a1ab1 @johnbender spelling
johnbender authored
123 Once you have your web server setup you can point it at the project directory.
5c86ca6 @eddiemonge Readme changes
eddiemonge authored
124
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
125 ### Testing
5c86ca6 @eddiemonge Readme changes
eddiemonge authored
126
12a1ab1 @johnbender spelling
johnbender authored
127 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 in for the area 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
128
12a1ab1 @johnbender spelling
johnbender authored
129 There are two primary ways to run the test suite. 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 what which test pages are available you can list them with:
a51adb9 updated the readme with more helpful information
scottjehl authored
130
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
131 grunt config:test:pages
6bc5c65 @eddiemonge Update to include instructions on how to build using a custom theme.
eddiemonge authored
132
12a1ab1 @johnbender spelling
johnbender authored
133 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 the your `PATH` the following will execute the whole test suite:
e26d7de @johnbender added note about local server support for development
johnbender authored
134
12a1ab1 @johnbender spelling
johnbender authored
135 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
e26d7de @johnbender added note about local server support for development
johnbender authored
136
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
137 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 @johnbender corrected docs to reflect revert to /js/
johnbender authored
138
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
139 TEST_PATH=slider JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
c97e4d1 @johnbender corrected docs to reflect revert to /js/
johnbender authored
140
12a1ab1 @johnbender spelling
johnbender authored
141 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:
e26d7de @johnbender added note about local server support for development
johnbender authored
142
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
143 JQUERY=1.6.4,1.7.1 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
db42f18 @johnbender note about fouc
johnbender authored
144
2719b18 @johnbender added page listing for testers, removed old readme content, expanded …
johnbender authored
145 ### Rebasing
e26d7de @johnbender added note about local server support for development
johnbender authored
146
16ea3fa @eddiemonge Update README.md
eddiemonge authored
147
6bc5c65 @eddiemonge Update to include instructions on how to build using a custom theme.
eddiemonge authored
148
c9eed4e @johnbender whitespace in readme
johnbender authored
149
Something went wrong with that request. Please try again.