libs/js/jquery-mobile-1.2.0/README.md

   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 jQuery Mobile 1.2 (1.2.0) works with versions of jQuery core from 1.7.0 to 1.8.2. 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 ## Contributing
  10
  11 You can contribute to the project by reporting issues, suggesting new features, or submitting pull requests.
  12 Please read our [Contributing Guidelines](https://github.com/jquery/jquery-mobile/blob/master/CONTRIBUTING.md) before submitting.
  13
  14
  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
  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
  22 * `zip` - package all the JavaScript and all the css into a zip archive
  23
  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
  28 ### Requirements
  29
  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).
  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
  37     node node_modules/.bin/grunt js # or css
  38
  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`.
  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
  43    `grunt docs #` or `grunt zip`
  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
  71 And then run the build:
  72
  73     grunt js
  74
  75 ### CSS
  76
  77 To create a new theme:
  78
  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:
  82
  83         THEME=my-theme grunt css
  84
  85 4. The output will be available in the `$PROJECT_ROOT/compiled`
  86
  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.
  88
  89 ## Development
  90
  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.
  92
  93 ### Server
  94
  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:
  96
  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
  98 * existing web server - eg, `~/Sites` directory on OSX.
  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`
 100
 101 In addition to vanilla Apache the following modules are required:
 102
 103 * Rewrite (mod\_rewrite.so)
 104 * Expire (mod\_expires.so)
 105 * Header (mod\_headers.so)
 106
 107 Once you have your web server setup you can point it at the project directory.
 108
 109 ### Testing
 110
 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.
 112
 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:
 114
 115     grunt config:test:pages
 116
 117 _NOTE_ See the [build requirements](#requirements) for node/grunt install information.
 118
 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:
 120
 121     JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
 122
 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:
 124
 125     TEST_PATH=slider JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
 126
 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.8.2, the command would take the following form:
 128
 129     JQUERY=1.7.2,1.8.2 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
 130
 131 ### Rebasing
 132
 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`:
 134
 135     git checkout new-feature
 136     git fetch upstream
 137     git rebase upstream/master
 138     ## ... here you may have to resolve some conflicts ... ##
 139
 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.