|
| 1 | +# Zepto.js – a minimalist JavaScript library |
| 2 | + |
| 3 | +Zepto is a minimalist JavaScript library for modern browsers with a |
| 4 | +largely jQuery-compatible API. If you use jQuery, you already know how to use Zepto. |
| 5 | + |
| 6 | +See [zeptojs.com][] for an extended introduction, downloads |
| 7 | +and documentation. |
| 8 | + |
| 9 | +Zepto.js is licensed under the terms of the MIT License. |
| 10 | + |
| 11 | +Want to give us money or a tip? Don't. |
| 12 | +Instead please donate to [charity: water](http://charitywater.org/). |
| 13 | + |
| 14 | +## Building |
| 15 | + |
| 16 | +[](http://travis-ci.org/madrobby/zepto) |
| 17 | + |
| 18 | +The official site offers a download of the default distribution of Zepto. This |
| 19 | +is good for starting out. However, at some point you might want to add some |
| 20 | +optional modules and remove some of the default ones you don't need, to keep the |
| 21 | +size at a minimum. That's when you need to check out Zepto's source code and use |
| 22 | +the build commands. |
| 23 | + |
| 24 | +You will need Node.js installed on your system. |
| 25 | + |
| 26 | +~~~ sh |
| 27 | +$ npm install |
| 28 | +$ npm run-script dist |
| 29 | + |
| 30 | +# do a custom build |
| 31 | +$ MODULES="zepto event data" npm run-script dist |
| 32 | +~~~ |
| 33 | + |
| 34 | +The resulting files are: |
| 35 | + |
| 36 | +1. `dist/zepto.js` |
| 37 | +2. `dist/zepto.min.js` |
| 38 | + |
| 39 | +If you install CoffeeScript globally, you can run `make` directly: |
| 40 | + |
| 41 | +~~~ sh |
| 42 | +$ coffee make dist |
| 43 | +$ MODULES="zepto event data ..." ./make dist |
| 44 | +~~~ |
| 45 | + |
| 46 | +## Zepto modules |
| 47 | + |
| 48 | +Zepto modules are individual files in the "src/" directory. |
| 49 | + |
| 50 | +<table> |
| 51 | +<thead><tr> |
| 52 | + <th>module</th> <th>default</th> <th>description</th> |
| 53 | +</tr></thead> |
| 54 | +<tbody> |
| 55 | + <tr> |
| 56 | + <th><a href="src/zepto.js#files">zepto</a></th> |
| 57 | + <td>✔</td> |
| 58 | + <td>Core module; contains most methods</td> |
| 59 | + </tr> |
| 60 | + <tr> |
| 61 | + <th><a href="src/event.js#files">event</a></th> |
| 62 | + <td>✔</td> |
| 63 | + <td>Event handling via <code>on()</code> & <code>off()</code></td> |
| 64 | + </tr> |
| 65 | + <tr> |
| 66 | + <th><a href="src/ajax.js#files">ajax</a></th> |
| 67 | + <td>✔</td> |
| 68 | + <td>XMLHttpRequest and JSONP functionality</td> |
| 69 | + </tr> |
| 70 | + <tr> |
| 71 | + <th><a href="src/form.js#files">form</a></th> |
| 72 | + <td>✔</td> |
| 73 | + <td>Serialize & submit web forms</td> |
| 74 | + </tr> |
| 75 | + <tr> |
| 76 | + <th><a href="src/ie.js#files">ie</a></th> |
| 77 | + <td>✔</td> |
| 78 | + <td>Support for Internet Explorer 10+ on the desktop and Windows Phone 8</td> |
| 79 | + </tr> |
| 80 | + <tr> |
| 81 | + <th><a href="src/detect.js#files">detect</a></th> |
| 82 | + <td></td> |
| 83 | + <td>Provides <code>$.os</code> and <code>$.browser</code> information</td> |
| 84 | + </tr> |
| 85 | + <tr> |
| 86 | + <th><a href="src/fx.js#files">fx</a></th> |
| 87 | + <td></td> |
| 88 | + <td>The <code>animate()</code> method</td> |
| 89 | + </tr> |
| 90 | + <tr> |
| 91 | + <th><a href="src/fx_methods.js#files">fx_methods</a></th> |
| 92 | + <td></td> |
| 93 | + <td> |
| 94 | + Animated <code>show</code>, <code>hide</code>, <code>toggle</code>, |
| 95 | + and <code>fade*()</code> methods. |
| 96 | + </td> |
| 97 | + </tr> |
| 98 | + <tr> |
| 99 | + <th><a href="src/assets.js#files">assets</a></th> |
| 100 | + <td></td> |
| 101 | + <td> |
| 102 | + Experimental support for cleaning up iOS memory after removing |
| 103 | + image elements from the DOM. |
| 104 | + </td> |
| 105 | + </tr> |
| 106 | + <tr> |
| 107 | + <th><a href="src/data.js#files">data</a></th> |
| 108 | + <td></td> |
| 109 | + <td> |
| 110 | + A full-blown <code>data()</code> method, capable of storing arbitrary |
| 111 | + objects in memory. |
| 112 | + </td> |
| 113 | + </tr> |
| 114 | + <tr> |
| 115 | + <th><a href="src/deferred.js#files">deferred</a></th> |
| 116 | + <td></td> |
| 117 | + <td> |
| 118 | + Provides <code>$.Deferred</code> promises API. |
| 119 | + Depends on the "callbacks" module. |
| 120 | + </td> |
| 121 | + </tr> |
| 122 | + <tr> |
| 123 | + <th><a href="src/callbacks.js#files">callbacks</a></th> |
| 124 | + <td></td> |
| 125 | + <td> |
| 126 | + Provides <code>$.Callbacks</code> for use in "deferred" module. |
| 127 | + </td> |
| 128 | + </tr> |
| 129 | + <tr> |
| 130 | + <th><a href="src/selector.js#files">selector</a></th> |
| 131 | + <td></td> |
| 132 | + <td> |
| 133 | + Experimental <a href="http://api.jquery.com/category/selectors/jquery-selector-extensions/">jQuery |
| 134 | + CSS extensions</a> support for functionality such as <code>$('div:first')</code> and |
| 135 | + <code>el.is(':visible')</code>. |
| 136 | + </td> |
| 137 | + </tr> |
| 138 | + <tr> |
| 139 | + <th><a href="src/touch.js#files">touch</a></th> |
| 140 | + <td></td> |
| 141 | + <td> |
| 142 | + Fires tap– and swipe–related events on touch devices. This works with both |
| 143 | + `touch` (iOS, Android) and `pointer` events (Windows Phone). |
| 144 | + </td> |
| 145 | + </tr> |
| 146 | + <tr> |
| 147 | + <th><a href="src/gesture.js#files">gesture</a></th> |
| 148 | + <td></td> |
| 149 | + <td>Fires pinch gesture events on touch devices</td> |
| 150 | + </tr> |
| 151 | + <tr> |
| 152 | + <th><a href="src/stack.js#files">stack</a></th> |
| 153 | + <td></td> |
| 154 | + <td>Provides <code>andSelf</code> & <code>end()</code> chaining methods</td> |
| 155 | + </tr> |
| 156 | + <tr> |
| 157 | + <th><a href="src/ios3.js#files">ios3</a></th> |
| 158 | + <td></td> |
| 159 | + <td> |
| 160 | + String.prototype.trim and Array.prototype.reduce methods |
| 161 | + (if they are missing) for compatibility with iOS 3.x. |
| 162 | + </td> |
| 163 | + </tr> |
| 164 | +</tbody> |
| 165 | +</table> |
| 166 | + |
| 167 | +## Contributing |
| 168 | + |
| 169 | +Please read our [contribution guidelines](https://github.com/madrobby/zepto/blob/master/CONTRIBUTING.md) |
| 170 | +for information on how to contribute. |
| 171 | + |
| 172 | +Get in touch: |
| 173 | + |
| 174 | +* @[zeptojs](http://twitter.com/zeptojs) |
| 175 | + |
| 176 | +### Write documentation |
| 177 | + |
| 178 | +Zepto docs are written in Markdown and live in the ["gh-pages" branch][docs]. |
| 179 | +They are published on [zeptojs.com][]. |
| 180 | + |
| 181 | +You can use GitHub's web interface to make quick changes to documentation for |
| 182 | +specific Zepto features |
| 183 | +([example: ajaxSettings](https://github.com/madrobby/zepto/blob/gh-pages/ajax/_posts/1900-01-01-Z-ajaxSettings.md)). |
| 184 | +This will submit a pull request to us that we can review. |
| 185 | + |
| 186 | +### Report a bug |
| 187 | + |
| 188 | +1. Check if the bug is already fixed in the [master branch][master] since the |
| 189 | + last release. |
| 190 | +2. Check [existing issues][issues]. Open a new one, including exact browser & |
| 191 | + platform information. For better formatting of your report, see |
| 192 | + [GitHub-flavored Markdown][mkd]. |
| 193 | + |
| 194 | +### Running tests |
| 195 | + |
| 196 | +You will need to install [PhantomJS][]. On OS X, that's easy: |
| 197 | + |
| 198 | +~~~ sh |
| 199 | +$ brew install phantomjs |
| 200 | +~~~ |
| 201 | + |
| 202 | +To run the automated tests: |
| 203 | + |
| 204 | +~~~ sh |
| 205 | +$ npm test |
| 206 | +~~~ |
| 207 | + |
| 208 | +To run a test server, which you can hit with your browsers and devices: |
| 209 | + |
| 210 | +~~~ sh |
| 211 | +$ npm start |
| 212 | +~~~ |
| 213 | + |
| 214 | +Go to `http://your-ip-address:3000/` on your browser and follow the |
| 215 | +instructions. For your convenience test failures and exceptions will be |
| 216 | +reported to the the console you started the test server in (as well as |
| 217 | +the browser console if available). |
| 218 | + |
| 219 | + [zeptojs.com]: http://zeptojs.com |
| 220 | + [master]: https://github.com/madrobby/zepto/commits/master |
| 221 | + [issues]: https://github.com/madrobby/zepto/issues |
| 222 | + [docs]: https://github.com/madrobby/zepto/tree/gh-pages#readme |
| 223 | + [mkd]: http://github.github.com/github-flavored-markdown/ |
| 224 | + [evidence.js]: https://github.com/tobie/Evidence |
| 225 | + [phantomjs]: http://code.google.com/p/phantomjs/wiki/Installation |
| 226 | + |
0 commit comments