Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 223 lines (158 sloc) 10.161 kB
3e2d636 first commit
Tobias Bosch authored
1 JQuery Mobile Angular Adapter
2 =====================
3
4 Description
5 -------------
6
60b18bb changed documentation
Tobias Bosch authored
7 Integration between jquery mobile and angular.js. Needed as jquery mobile
a31245e refactoring of the integration logic; integration now covers all jqm …
Tobias Bosch authored
8 enhances the pages with new elements and styles and so does angular. Another reason is
9 that jquery mobile only enhances pages when they are navigated to, and not
10 all at once, as angular does in autoinit mode.
3e2d636 first commit
Tobias Bosch authored
11
a31245e refactoring of the integration logic; integration now covers all jqm …
Tobias Bosch authored
12 Automatically refreshs the jquery mobile widgets when the corresponding
3e2d636 first commit
Tobias Bosch authored
13 values in angular change.
14 E.g. the select tag is enhanced by jquery mobile,
15 and if someone changes it's value programmatically, the refresh-function needs to be called.
16
3518612 extended service and corrected build to include jquery mobile
Tobias Bosch authored
17 Fixes the jquery mobile widgets so that they are correctly removed form the dom,
902fd45 readded paging
Tobias Bosch authored
18 when angular removes them (e.g. in a `ng-repeat`).
3518612 extended service and corrected build to include jquery mobile
Tobias Bosch authored
19
20 Provides special enhancements useful for mobile applications.
21
22 Dependencies
23 ----------------
34dcd16 most parts working
Tobias Bosch authored
24 - angular 1.0
25 - jquery 1.7.1
fb9e1ab released 1.0.6
Tobias Bosch authored
26 - jquery mobile 1.1.0
3518612 extended service and corrected build to include jquery mobile
Tobias Bosch authored
27
0428ada added link to phonecat-mobile
Tobias Bosch authored
28 Sample
29 ------------
a0cb621 updated url of jsfiddle
Tobias Bosch authored
30 - Js fiddle [Todo mobile](http://jsfiddle.net/tigbro/Du2DY/).
31 - Single source app for jquery-mobile and sencha touch: [https://github.com/tigbro/todo-mobile](https://github.com/tigbro/todo-mobile)
0428ada added link to phonecat-mobile
Tobias Bosch authored
32
504d465 added tests for location handling
Tobias Bosch authored
33 Limitations
34 ------------
35 This deactivates angular's feature to change urls via the `$browser` or `$location` services.
36 This was needed as angular's url handling is incompatibly with jquery mobile and leads to
37 unwanted navigations.
38
3e2d636 first commit
Tobias Bosch authored
39 Usage
40 ---------
41
4a4bce4 added some docs
Tobias Bosch authored
42 Include this adapter _after_ angular and jquery mobile (see below).
43
34dcd16 most parts working
Tobias Bosch authored
44 ATTENTION: The directive `ng-app` for the html element is required, as in all angular applications.
3e2d636 first commit
Tobias Bosch authored
45
46
34dcd16 most parts working
Tobias Bosch authored
47 <html xmlns:ng="http://angularjs.org" xmlns:ngm="http://jqm-angularjs.org" ng-app>
3e2d636 first commit
Tobias Bosch authored
48 <head>
49 <title>MobileToys</title>
34dcd16 most parts working
Tobias Bosch authored
50 <link rel="stylesheet" href="lib/jquery.mobile-1.1.css"/>
51 <script src="lib/jquery-1.7.1.js"></script>
52 <script src="lib/jquery.mobile-1.1.0.js"></script>
53 <script src="lib/angular-1.1.0.js"></script>
3e2d636 first commit
Tobias Bosch authored
54 <script src="lib/jquery-mobile-angular-adapter.js"></script>
55 </head>
56
57
3518612 extended service and corrected build to include jquery mobile
Tobias Bosch authored
58 Directory layout
59 -------------------
60 This follows the usual maven directory layout:
61
62 - src/main/webapp: The production code
63 - src/test/webapp: The test code
64 - compiled: The result of the javascript compilation
65 - compiled/min: Contains the minified files.
66
67
de4bc7d build system complete, including documentation
Tobias Bosch authored
68 Build
69 --------------------------
34dcd16 most parts working
Tobias Bosch authored
70 The build is done using maven and node js.
de4bc7d build system complete, including documentation
Tobias Bosch authored
71
7683493 updated build process
Tobias Bosch authored
72 - `mvn clean package`: This will create a new version of the adapter and put it into `/compiled`.
de4bc7d build system complete, including documentation
Tobias Bosch authored
73
1f5c16c added mobileinit support in the standalone build
Tobias Bosch authored
74 The build also creates a standalone library including jquery, jquery-mobile and angular.
75 If you want to do something during the initialization of jquery-mobile, use the following callback:
76 `window.mobileinit = function() { ... }`
77
de4bc7d build system complete, including documentation
Tobias Bosch authored
78 Running the tests
79 -------------------
80
02c0c4d cleaned up the maven configuration
Tobias Bosch authored
81 - `mvn clean integration-test -Ptest`: This will do a build and execute the tests using js-test-driver.
de4bc7d build system complete, including documentation
Tobias Bosch authored
82 The browser that is used can be specified in the pom.xml.
83 - `mvn clean package jetty:run`: This will start a webserver under `localhost:8080/jqmng`.
84 The unit-tests can be run via the url `localhost:8080/jqmng/UnitSpecRunner.html`
85 The ui-tests can be run via the url `localhost:8080/jqmng/UiSpecRunner.html`
86
87
3e2d636 first commit
Tobias Bosch authored
88 Scopes
89 -----------
34dcd16 most parts working
Tobias Bosch authored
90 Every page of jquery mobile gets a separate scope. The `$digest` of the global scope only evaluates the currently active page,
6b4fbb9 readded global scope but with special respect to performance issues
Tobias Bosch authored
91 so there is no performance interaction between pages.
92
902fd45 readded paging
Tobias Bosch authored
93 For communicating between the pages use the `ngm-shared-controller` directive (see below).
6b4fbb9 readded global scope but with special respect to performance issues
Tobias Bosch authored
94
c0c3240 replaced the templating with ngm:define/ngm:switch with ng:if
Tobias Bosch authored
95 Widgets, Directives and Services
3e2d636 first commit
Tobias Bosch authored
96 -----------
97
902fd45 readded paging
Tobias Bosch authored
98 ### Directive ngm-shared-controller="name1:Controller1,name2:Controller2, ..."
3708a03 adds ngm:shared-controller and removes old stuff
Tobias Bosch authored
99 Mobile pages are small, so often a usecase is split up into multiple pages.
100 To share common behaviour and state between those pages, this directive allows shared controllers.
3e2d636 first commit
Tobias Bosch authored
101
3708a03 adds ngm:shared-controller and removes old stuff
Tobias Bosch authored
102 The directive will create an own scope for every given controllers and store it
103 in the variables as `name1`, `name2`, ....
104 If the controller is used on more than one page, the instance of the controller is shared.
105
106 Note that the shared controller have the full scope functionality, e.g. for dependecy injection
107 or using `$watch`.
3e2d636 first commit
Tobias Bosch authored
108
902fd45 readded paging
Tobias Bosch authored
109 ### Directive ngm-event="{event1:'handler1',event2:'handler2',...}"
40d24ba Added ng:event and paging for lists
Tobias Bosch authored
110 General event handler that integrates with jquery events, and also with jquery mobile events.
50a1f3e refactorings to and :event
Tobias Bosch authored
111 The value of the attribute is json and defines the event - handler mapping.
40d24ba Added ng:event and paging for lists
Tobias Bosch authored
112
902fd45 readded paging
Tobias Bosch authored
113 Usage: E.g. `<a href="#" ngm-event="{swiperight:'myFn()'}">`
40d24ba Added ng:event and paging for lists
Tobias Bosch authored
114
902fd45 readded paging
Tobias Bosch authored
115 ### Event-Directives `ngm-click`, `ngm-tap`,`ngm-taphold`,`ngm-swipe`,`ngm-swiperight`,`ngm-swipeleft`,`ngm-pagebeforeshow`,`ngm-pagebeforehide`,`ngm-pageshow`,`ngm-pagehide`
346a954 new event directives added
Tobias Bosch authored
116 For the mentioned events there are special directives to simplify the markup. Each of them is equivalent to
902fd45 readded paging
Tobias Bosch authored
117 using the `ngm-event` directive with the corresponding event name.
3708a03 adds ngm:shared-controller and removes old stuff
Tobias Bosch authored
118
902fd45 readded paging
Tobias Bosch authored
119 Usage: E.g. `<a href="#" ngm-swipeleft="myFn()">`
3708a03 adds ngm:shared-controller and removes old stuff
Tobias Bosch authored
120
902fd45 readded paging
Tobias Bosch authored
121 ### Directive ngm-fadein
122 For smooth fadings between `ngm-if` changes, there is also the directive `ngm-fadein`.
123 This specifies that the display of the coresponding element
124 should be shown via a transition lasting a defined amount of milliseconds (the value of the attribute).
125
126 Usage: E.g. `<div ngm-fadein="700">asdf</div>`
127
128
129 ### Attribute Widget @ngm-if
130 The attribute widget `@ngm-if` allows to add/remove an element to/from the dom, depending on an expression.
131 This is especially useful at places where we cannot insert an `ng-switch` into the dom. E.g. jquery mobile
c0c3240 replaced the templating with ngm:define/ngm:switch with ng:if
Tobias Bosch authored
132 does not allow elements between an `ul` and an `li` element.
133
902fd45 readded paging
Tobias Bosch authored
134 Usage: E.g. `<div ngm-if="myFlag">asdfasdf</div>`
c0c3240 replaced the templating with ngm:define/ngm:switch with ng:if
Tobias Bosch authored
135
3518612 extended service and corrected build to include jquery mobile
Tobias Bosch authored
136 ### Service $navigate('[transition]:pageId'[,activateFn][,activateFnParam1, ...])
137 Service to change the given page.
97f0611 updated to angular 1.0rc3
Tobias Bosch authored
138 - The pageId is the pageId of `$.mobile.changePage`, e.g. `#homepage` for navigation within the current page
139 or `somePage.html` for loading another page.
50a1f3e refactorings to and :event
Tobias Bosch authored
140 - If the transition has the special value `back` than the browser will go back in history to
97f0611 updated to angular 1.0rc3
Tobias Bosch authored
141 the defined page, e.g. `back:#hompage`.
142 - The transition may be omitted, e.g. `$navigate('#homepage')`.
50a1f3e refactorings to and :event
Tobias Bosch authored
143 - To go back one page use `$navigate('back')`.
3518612 extended service and corrected build to include jquery mobile
Tobias Bosch authored
144 - If the `activateFn` function is given, it will be called after the navigation on the target page with
145 `activateFnParam1, ...` as arguments. The invocation is done before the `pagebeforeshow` event on the target page.
1633d5c implement #15: allow custom object to pass through jquery mobile chan…
Tobias Bosch authored
146 - If you want to pass special options to the jquery mobile `changePage` function:
147 Pass in an object to the `$navigate` function instead of a pageId. This object will be forwarded
148 to jqm `changePage`. To define the new pageId, this object needs the additional property `target`.
149
3e2d636 first commit
Tobias Bosch authored
150
7681396 bugfixed typo in readme
Tobias Bosch authored
151 ### Service $waitDialog
152 The service `$waitDialog` allows the access to the jquery mobile wait dialog. It provides the following functions:
af912d4 added new service waitdialog
Tobias Bosch authored
153 - `show(msg, callback)`: Opens the wait dialog and shows the given message (if existing).
154 If the user clicks on the wait dialog the given callback is called.
155 This can be called even if the dialog is currently showing. It will the change the message
156 and revert back to the last message when the hide function is called.
157 - `hide()`: Restores the dialog state before the show function was called.
158 - `waitFor(promise, msg)`: Shows the dialog as long as the given promise runs. Shows the given message if defined.
159 - `waitForWithCancel(promise, cancelData, msg)`: Same as above, but rejects the promise with the given cancelData
160 when the user clicks on the wait dialog.
161
162 Default messages are:
163 - `$.mobile.loadingMessageWithCancel`: for waitForWithCancel
164 - `$.mobile.loadingMessage`: for all other cases
165
3e2d636 first commit
Tobias Bosch authored
166
902fd45 readded paging
Tobias Bosch authored
167 ### Filter `navigate`: Navigation in Expressions
120576c refactored to an expression
Tobias Bosch authored
168 Every expression can now use the `$navigate` as a filter to define the navigation outside of the controlers
8a446f7 added expressions again
Tobias Bosch authored
169 in the html pages. By this, the controllers stay independent of the navigation process and is reusable.
170
120576c refactored to an expression
Tobias Bosch authored
171 Syntax: `test | $activate: 'outcome1:target' : 'outcome2:target' : ...`
172
902fd45 readded paging
Tobias Bosch authored
173 Example: `<button ngm-click="doSomething() | navigate : 'success:successPage' : 'failure:failurePage'">`
120576c refactored to an expression
Tobias Bosch authored
174
175 This navigates to that target whose outcome equals
176 to the test. The special outcomes `success` is applied for any value for `test` that is not `false` (e.g. also `undefined`),
177 and the outcome `failure` is used for the value `false` of test.
178 This also supports promises. In that case, the navivation is done with the first argument of
179 the `done` / `fail` callback of the promise. Also, the `success` outcome is mapped to the `done` callback
180 and the `failure` outcome to the `fail` callback.
8a446f7 added expressions again
Tobias Bosch authored
181
182
902fd45 readded paging
Tobias Bosch authored
183 ### Filter `paged`: Paging for lists
40d24ba Added ng:event and paging for lists
Tobias Bosch authored
184 Lists can be paged in the sense that more entries can be additionally loaded. By "loading" we mean the
185 display of a sublist of a list that is already fully loaded in JavaScript. This is useful, as the main performance
186 problems result from DOM operations, which can be reduced with this paging mechanism.
187
902fd45 readded paging
Tobias Bosch authored
188 To implement this paging mechanism, the angular filter `paged` was created.
189 For displaying a page within a list, simply use:
190
191 list | paged:{pageSize: 12, filter: someFilter, orderBy: someOrder})
40d24ba Added ng:event and paging for lists
Tobias Bosch authored
192
1fafbf9 refactoring of paging mechanism
Tobias Bosch authored
193 This returns the subarray of the given filtered and ordered array with the currently loaded pages.
902fd45 readded paging
Tobias Bosch authored
194 For the `filter` and `orderBy` parameter see the builtin angular filters `filter` and `orderBy`.
195 The parameters `pageSize`, `filter` and `orderBy` are optional and can be combined in any order.
196 If the pageSize is omitted, the default page size is used. This is by default 10, and can be configured using
197
198 module(["ng"]).value('defaultListPageSize', 123);
199
200 To show a button that loads the next page of the list, use the following syntax:
201
202 <a href="#" ngm-if="list | paged:'hasMore'" ngm-click="list | paged:'loadMore'">Load More</a>
1fafbf9 refactoring of paging mechanism
Tobias Bosch authored
203
902fd45 readded paging
Tobias Bosch authored
204 The filter `paged|'hasMore'` returns a boolean indicating if all pages of the list have been loaded.
205 The filter `paged|'loadMore'` loads the next page into the list.
1fafbf9 refactoring of paging mechanism
Tobias Bosch authored
206
902fd45 readded paging
Tobias Bosch authored
207 Note that this will cache the result of the paging, filtering and sorting until something changes.
208 By this, paging should work fine also for large lists.
40d24ba Added ng:event and paging for lists
Tobias Bosch authored
209
210 The following example shows an example for a paged list for the data in the variable `myList`:
211
212
213 <ul data-role="listview">
902fd45 readded paging
Tobias Bosch authored
214 <li ng-repeat="item in list | paged:{pageSize:10}">{{item}}</li>
215 <li ngm-if="list | paged:'hasMore'">
216 <a href="#" ngm-click="list | paged:'loadMore'">Load more</a>
1fafbf9 refactoring of paging mechanism
Tobias Bosch authored
217 </li>
40d24ba Added ng:event and paging for lists
Tobias Bosch authored
218 </ul>
219
220
221
ee13ecc added onActivate and onPassicate callbacks for controllers
Tobias Bosch authored
222
Something went wrong with that request. Please try again.