Skip to content

Commit

Permalink
Merge branch 'new-readme'
Browse files Browse the repository at this point in the history
  • Loading branch information
@johnbender
johnbender committed Jun 12, 2012
2 parents 34567dd + 95a6dc8 commit 1e83051
Show file tree
Hide file tree
Showing 4 changed files with 151 additions and 99 deletions.
195 changes: 115 additions & 80 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,121 +1,156 @@
jQuery Mobile Framework
=======================
[Official Site: http://jquerymobile.com](http://jquerymobile.com)
# jQuery Mobile

[Demos and Documentation](http://jquerymobile.com/test/)
This is the main repository for the jQuery Mobile project. From the [official website](http://jquerymobile.com):

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):
> 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.
git clone git://github.com/jquery/jquery-mobile.git
cd jquery-mobile
make
You can find more information about how the library works, and what it is capable of, by reading the [documentation](http://jquerymobile.com/demos/).

A full version and a minified version of the jQuery Mobile JavaScript and CSS files will be created
in a folder named "compiled". There is also now a Structure only css file so you can add your own theme on top of it.
## Issues

Alternatively if you have node.js installed you can run
When [submitting issues on github](https://github.com/jquery/jquery-mobile/issues/new) please include the following:

1. Issue description
2. Sample page using our [jsbin template](http://jsbin.com/awoluv/edit#html)
3. Steps to reproduce
4. Expected outcome
5. Actual outcome
6. Browsers/platforms tested
7. Library version/Location (eg, CDN or `jquerymobile.com/test/`)

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).

## Pull Requests

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):

1. Include tests (see [Testing](#testing))
2. Follow the [jQuery Core style guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
3. Limit the scope to one Issue/Feature
4. Small focused commits, ideally less than 10 to 20 lines
5. Avoid merge commits (see Pro Git's [chapter on rebasing](http://git-scm.com/book/ch3-6.html), section [Rebasing](#rebasing) below)

Taken together, the above reduces the effort that's required of the contributor reviewing your pull request.

## Build/Customization

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:

* `js` - resolve dependencies, build, concat, and minify the JavaScript used for jQuery Mobile
* `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 all the JavaScript and all the css into a zip archive

### Requirements

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).

### Commands

With node installed you can run the `js` and `css` targets by simply issuing the following from the project root:

npm install
node node_modules/.bin/grunt <js|css>
node node_modules/.gin/grunt js # or css

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`.

to build either the js or css. This is usefull especially if you're on Windows without support for the make tool and bash.
If you want to use the `docs` and `zip` targets you will need bash and they can be run with the following

How to build a self-contained version of the Docs/Demos
=======================================================
Once you have your own cloned repo on your computer:
grunt docs # or `grunt zip`

make docs
### JavaScript

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.
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`.

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
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',
```

Submitting bugs
===============
If you think you've found a bug, please report it by following these instructions:
And then run the build:

1. Visit the [Issue tracker: https://github.com/jquery/jquery-mobile/issues](https://github.com/jquery/jquery-mobile/issues)
2. 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:
* [JS](http://code.jquery.com/mobile/latest/jquery.mobile.min.js)
* [CSS](http://code.jquery.com/mobile/latest/jquery.mobile.min.css)
- Include a link to some code of the bug in action. You can use either of these services to host your code
* [jsbin](http://jsbin.com)
* [jsfiddle](http://jsfiddle.net)
3. Submit the issue.
grunt js

### CSS

To create a new theme:

Recommended: [JS Bin issue template with instructions](http://jsbin.com/awoluv/edit)
1. Copy the `default` folder from CSS/Themes to a new folder named after your new theme (eg, `my-theme`).
2. Add customizations to the `jquery.mobile.theme.css` file.
3. From the project root run the following `grunt` command:

Issues concerning the jQuery Mobile Theme Roller can be submitted at the [Theme Roller repo: https://github.com/jquery/web-jquery-mobile-theme-roller](https://github.com/jquery/web-jquery-mobile-theme-roller)
THEME=my-theme grunt css

Submitting patches
==================
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.
4. The output will be available in the `$PROJECT_ROOT/compiled`

Detailed instructions can be found at [jQuery Mobile Patching](https://gist.github.com/1294035)
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.

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).
## Development

If you don't currently have a webserver running locally, there are a few options.
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.

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.
### Server

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.
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:

Another alternative is XAMPP (Mac, Windows). You need to actually modify Apache's httpd.conf to point to your checkout:
[Instructions](http://www.apachefriends.org/en/xampp.html)
* one-click - [MAMP](http://www.mamp.info/en/downloads/index.html) for OSX, [XAMP](http://www.apachefriends.org/en/xampp.html) for OSX/Windows
* existing web server - eg, `~/Sites` directory on OSX.
* 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`

You need the following Apache modules loaded:
In addition to vanilla Apache the following modules are required:

* 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:
Once you have your web server setup you can point it at the project directory.

$ python -m SimpleHTTPServer 8000
### Testing

And in your browser visit [localhost:8000](http://localhost:8000/tests/unit/core/). 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
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.

<script data-main="js/jquery.mobile.docs" src="external/requirejs/require.js"></script>
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 which test pages are available you can list them with:

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.
grunt config:test:pages

AMD Support in Development
==========================
_NOTE_ See the [build requirements](#requirements) for node/grunt install information.

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.
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:

If you find dependency bugs when using the async loading support for development please log them in the github issue tracker.
JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test

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:
You can confine the headless run to a single test page or set of test pages using the `TEST_PATH` environment variable. For example:

TEST_PATH=slider JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test

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:

JQUERY=1.6.4,1.7.1 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test

### Rebasing

1. Copy the `Default` folder 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.
2. Edit the `jquery.mobile.theme.css` file so it contains your custom fonts and colors.
3. Once you are done editing your files and saving them, open a terminal.
4. Navigate to the jQuery-Mobile folder's root.
5. Run the following command to build jQuery-Mobile (THEME is the name of the folder for your theme from step 1.):
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 requests 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`:

make THEME=YourThemeName
git checkout new-feature
git fetch upstream
git rebase upstream/master
## ... here you may have to resolve some conflicts ... ##

6. The compiled files will be located in the "compiled" folder in the root of jQuery-Mobile.
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.
45 changes: 31 additions & 14 deletions build/tasks/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,43 @@ module.exports = function( grunt ) {
});
});

grunt.registerTask( 'config:test:pages', 'glob and log all possible tests', function( a, b ) {
var test_paths = [], global_config = grunt.config.get( 'global' ), env = process.env;

// TODO move the glob to a legit config or pull the one from the qunit config
test_paths = glob.glob( 'tests/unit/*/' );
test_paths = test_paths.concat( glob.glob('tests/unit/**/*-tests.html') );

// append the jquery version query param where defined
var paths_with_jquery = [];
if( env.JQUERY ){
test_paths.forEach(function( full_path ) {
env.JQUERY.split( "," ).forEach( function( version ) {
paths_with_jquery.push(full_path + "?jquery=" + version);
});
});

test_paths = paths_with_jquery;
}

// if this test is not a dependency log pages
if( this.name.indexOf('config:test:page') > -1 ) {
test_paths.forEach(function( path ) {
grunt.log.writeln( path );
});
}

global_config.test_paths = test_paths;
grunt.config.set( 'global', global_config );
});

// TODO could use some cleanup. Eg, can we use grunt's parameter passing functionality
// in place of environment variables
grunt.registerTask( 'config:test', 'glob all the test files', function() {
var done = this.async(), test_paths, server_paths = [], env = process.env;

// TODO move the glob to a legit config or pull the one from the qunit config
test_paths = glob.glob( 'tests/unit/*/' );
test_paths = test_paths.concat( glob.glob('tests/unit/**/*-tests.html') );
test_paths = grunt.config.get( 'global' ).test_paths;

// select the proper domain + paths
test_paths.forEach( function( file_path ) {
Expand All @@ -46,18 +75,6 @@ module.exports = function( grunt ) {
}
});

// append the jquery version query param where defined
var paths_with_jquery = [];
if( env.JQUERY ){
server_paths.forEach(function( full_path ) {
env.JQUERY.split( "," ).forEach( function( version ) {
paths_with_jquery.push(full_path + "?jquery=" + version);
});
});

server_paths = paths_with_jquery;
}

grunt.config.set( 'qunit', { all: server_paths });
done();
});
Expand Down
4 changes: 0 additions & 4 deletions build/tasks/legacy.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,6 @@ module.exports = function( grunt ) {
grunt.registerMultiTask('legacy_tasks', 'support for old build targets', function() {
var done = this.async(), name = this.name, self = this;

( this.data.deps || [] ).forEach(function(dep) {
self.requires( 'legacy_tasks:' + dep );
});

child_process.exec( (this.data.env || '') + ' bash build/bin/' + this.target + '.sh', function (error, stdout, stderr) {
if( error !== null ) {
grunt.log.error( stderr );
Expand Down
6 changes: 5 additions & 1 deletion grunt.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,11 @@ module.exports = function( grunt ) {
grunt.loadNpmTasks( "grunt-junit" );

// A convenient task alias.
grunt.registerTask('test', 'config:test junit');
grunt.registerTask('test', 'config:test:pages config:test junit');

// Ease of use aliases for users who want the zip and docs
grunt.registerTask('docs', 'js css legacy_tasks:docs');
grunt.registerTask('zip', 'js css legacy_tasks:zip');

// load the project's default tasks
grunt.loadTasks( 'build/tasks');
Expand Down

0 comments on commit 1e83051

Please sign in to comment.