Skip to content

Commit 5ed7f70

Browse files
skypantherskypanther
committed
Merge pull request tidev#658 from tstatler/TIDOC-2002
Added examples to docs for public Alloy.Controller/Alloy.Controller.UI APIs
2 parents 354cf17 + 91a5a76 commit 5ed7f70

File tree

3 files changed

+182
-8
lines changed

3 files changed

+182
-8
lines changed

‎Alloy/lib/alloy/controllers/BaseController.js

+168-5
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,19 @@ var Controller = function() {
6060
/**
6161
* @method getTopLevelViews
6262
* Returns a list of the root view elements associated with this controller.
63+
64+
* #### Example
65+
* The following example displays the `id` of each top-level view associated with the
66+
* controller:
67+
68+
// index.js
69+
var views = $.getTopLevelViews();
70+
for (each in views) {
71+
var view = views[each];
72+
console.log(view.id);
73+
}
74+
75+
*
6376
*
6477
* @return {Array.<(Titanium.UI.View|Alloy.Controller)>}
6578
*/
@@ -72,6 +85,13 @@ var Controller = function() {
7285
* Returns the specified view associated with this controller.
7386
*
7487
* If no `id` is specified, returns the first top-level view.
88+
*
89+
* #### Example
90+
* The following example gets a reference to a `<Window/>` object
91+
* with the `id` of "loginWin" and then calls its [open()](Titanium.UI.Window) method.
92+
93+
var loginWindow = $.getView('loginWin');
94+
loginWindow.open();
7595
*
7696
* @param {String} [id] ID of the view to return.
7797
* @return {Titanium.UI.View/Alloy.Controller}
@@ -95,6 +115,42 @@ var Controller = function() {
95115
* @method getViews
96116
* Returns a list of all IDed view elements associated with this controller.
97117
*
118+
* #### Example
119+
* Given the following XML view:
120+
121+
<Alloy>
122+
<TabGroup id="tabs">
123+
<Tab title="Tab 1" icon="KS_nav_ui.png" id="tab1">
124+
<Window title="Tab 1" id="win1">
125+
<Label id="label1">I am Window 1</Label>
126+
</Window>
127+
</Tab>
128+
<Tab title="Tab 2" icon="KS_nav_views.png" id="tab2">
129+
<Window title="Tab 2" id="wind2">
130+
<Label id="label2">I am Window 2</Label>
131+
</Window>
132+
</Tab>
133+
</TabGroup>
134+
<View id="otherview"></View>
135+
</Alloy>
136+
137+
* The following view-controller outputs the id of each view in the hierarchy.
138+
139+
var views = $.getViews();
140+
for (each in views) {
141+
var view = views[each];
142+
console.log(view.id);
143+
}
144+
145+
[INFO] : win1
146+
[INFO] : label1
147+
[INFO] : tab1
148+
[INFO] : wind2
149+
[INFO] : label2
150+
[INFO] : tab2
151+
[INFO] : tabs
152+
[INFO] : otherview
153+
98154
* @return {Array.<(Titanium.UI.View|Alloy.Controller)>}
99155
*/
100156
getViews: function() {
@@ -107,9 +163,17 @@ var Controller = function() {
107163
* UI components. It is critical that this is called when employing
108164
* model/collection binding in order to avoid potential memory leaks.
109165
* $.destroy() should be called whenever a controller's UI is to
110-
* be "closed" or removed from the app. For more details, see the
111-
* example app found here:
112-
* https://github.com/appcelerator/alloy/tree/master/test/apps/models/binding_destroy
166+
* be "closed" or removed from the app. See the [Destroying Data Bindings](#!/guide/Destroying_Data_Bindings)
167+
* test application for an example of this approach.
168+
169+
* #### Example
170+
* In the following example the view-controller for a {@link Titanium.UI.Window Window} object named `dialog`
171+
* calls its `destroy()` method in response to the Window object being closed.
172+
173+
174+
$.dialog.addEventListener('close', function() {
175+
$.destroy();
176+
});
113177
*/
114178
destroy: function(){
115179
// destroy() is defined during the compile process based on
@@ -154,12 +218,39 @@ var Controller = function() {
154218
* @method createStyle
155219
* Creates a dictionary of properties based on the specified styles.
156220
*
221+
*
157222
* You can use this dictionary with the view object's
158223
* {@link Titanium.UI.View#method-applyProperties applyProperties} method
159224
* or a create object method, such as {@link Titanium.UI#method-createView Titanium.UI.createView}.
225+
* #### Examples
226+
* The following creates a new style object that is passed as a parameter
227+
* to the {@link Titanium.UI#method-createLabel Ti.UI.createLabel()} method.
228+
229+
var styleArgs = {
230+
apiName: 'Ti.UI.Label',
231+
classes: ['blue','shadow','large'],
232+
id: 'tester',
233+
borderWidth: 2,
234+
borderRadius: 16,
235+
borderColor: '#000'
236+
};
237+
var styleObject = $.createStyle(styleArgs);
238+
testLabel = Ti.UI.createLabel(styleObject);
239+
240+
* The next example uses the {@link Titanium#method-applyProperties applyProperties()} method
241+
* to apply a style object to an existing Button control (button not shown).
242+
243+
var style = $.createStyle({
244+
classes: args.button,
245+
apiName: 'Button',
246+
color: 'blue'
247+
});
248+
$.button.applyProperties(style);
160249
* @param {AlloyStyleDict} opts Dictionary of styles to apply.
250+
*
161251
* @return {Dictionary}
162252
* @since 1.2.0
253+
163254
*/
164255
createStyle: function(opts) {
165256
return Alloy.createStyle(getControllerParam(), opts);
@@ -178,7 +269,29 @@ var Controller = function() {
178269
* @method addClass
179270
* Adds a TSS class to the specified view object.
180271
*
181-
* You can apply additional styles with the `opts` parameter.
272+
* You can apply additional styles with the `opts` parameter. To use this method
273+
* effectively you may need to enable autostyling
274+
* on the target XML view. See [Autostyle](#!/guide/Dynamic_Styles-section-37530415_DynamicStyles-Autostyle)
275+
* in the Alloy developer guide.
276+
* #### Example
277+
* The following adds the TSS classes ".redbg" and ".bigger" to a {@link Titanium.UI.Label}
278+
* object proxy `label1`, and also sets the label's `text` property to "Cancel".
279+
280+
// index.js
281+
$.addClass($.label1, 'redbg bigger', {text: "Cancel"});
282+
283+
The 'redbg' and 'bigger' classes are shown below:
284+
285+
// index.tss
286+
".redbg" : {
287+
color: 'red'
288+
}
289+
".bigger": {
290+
font : {
291+
fontSize: '36'
292+
}
293+
}
294+
182295
* @param {Object} proxy View object to which to add class(es).
183296
* @param {Array<String>/String} classes Array or space-separated list of classes to apply.
184297
* @param {Dictionary} [opts] Dictionary of properties to apply after classes have been added.
@@ -193,6 +306,15 @@ var Controller = function() {
193306
* Removes a TSS class from the specified view object.
194307
*
195308
* You can apply additional styles after the removal with the `opts` parameter.
309+
* To use this method effectively you may need to enable autostyling
310+
* on the target XML view. See [Autostyle](#!/guide/Dynamic_Styles-section-37530415_DynamicStyles-Autostyle)
311+
* in the Alloy developer guide.
312+
* #### Example
313+
* The following removes the "redbg" and "bigger" TSS classes from a {@link Titanium.UI.Label}
314+
* object proxy `label1`, and also sets the label's `text` property to "...".
315+
316+
$.removeClass($.label1, 'redbg bigger', {text: "..."});
317+
196318
* @param {Object} proxy View object from which to remove class(es).
197319
* @param {Array<String>/String} classes Array or space-separated list of classes to remove.
198320
* @param {Dictionary} [opts] Dictionary of properties to apply after the class removal.
@@ -208,6 +330,15 @@ var Controller = function() {
208330
* removing any applied classes that are not specified.
209331
*
210332
* You can apply classes or styles after the reset using the `classes` or `opts` parameters.
333+
* To use this method effectively you may need to enable autostyling
334+
* on the target XML view. See [Autostyle](#!/guide/Dynamic_Styles-section-37530415_DynamicStyles-Autostyle)
335+
* in the Alloy developer guide.
336+
337+
* #### Example
338+
* The following removes all previously applied styles on `label1` and then applies
339+
* the TSS class 'no-style'.
340+
341+
$.resetClass($.label1, 'no-style');
211342
* @param {Object} proxy View object to reset.
212343
* @param {Array<String>/String} [classes] Array or space-separated list of classes to apply after the reset.
213344
* @param {Dictionary} [opts] Dictionary of properties to apply after the reset.
@@ -219,9 +350,41 @@ var Controller = function() {
219350

220351
/**
221352
* @method updateViews
222-
* Applies a set of properties to view elements associated with this controller
353+
* Applies a set of properties to view elements associated with this controller.
354+
* This method is useful for setting properties on repeated elements such as
355+
* {@link Titanium.UI.TableViewRow TableViewRow} objects, rather than needing to have a controller
356+
* for those child controllers.
357+
* #### Example
358+
* The following example uses this method to update a Label inside a TableViewRow object
359+
* before adding it to a TableView.
360+
361+
* View-controller file: controllers/index.js
362+
363+
for (var i=0; i < 10; i++) {
364+
var row = Alloy.createController("tablerow");
365+
row.updateViews({
366+
"#theLabel": {
367+
text: "I am row #" + i
368+
}
369+
});
370+
$.tableView.appendRow(row.getView());
371+
};
372+
373+
* XML view: views/tablerow.xml
374+
375+
<Alloy>
376+
<TableViewRow>
377+
<Label id="theLabel"></Label>
378+
</TableViewRow>
379+
</Alloy>
380+
381+
* XML view: views/index.xml
382+
383+
<TableView id="tableView">
384+
</TableView>
223385
* @param {Object} args An object whose keys are the IDs (in form '#id') of views to which the styles will be applied.
224386
* @since 1.4.0
387+
225388
*/
226389
updateViews: function(args) {
227390
var views = this.getViews();

‎docs/apidoc/collection.js

+4-3
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,16 @@
44
*
55
* Collections can either be created in markup or programmatically in the controller.
66
*
7-
* To create collections in markup, see the 'Collection Element' section in the
8-
* [Alloy XML Markup guide](#!/guide/Alloy_XML_Markup).
7+
* To create collections in markup use a `<Collection/>` element. For
8+
* more information see [Collection Element](#!/guide/Alloy_XML_Markup-section-35621528_AlloyXMLMarkup-CollectionElement)
9+
* in the Alloy developer guide.
910
*
1011
* In the controller code:
1112
*
1213
* - To create a local instance, use the Alloy.createCollection method.
1314
* - To create a global singleton instance, use the Alloy.Collections.instance method.
1415
*
15-
* Previously created collections through markup or using the `instance` method
16+
* Previously created collections through markup or using the `{@link #instance instance()}` method
1617
* are directly accessed as properties of the `Alloy.Collections` namespace,
1718
* using either the name of the model JavaScript file for singletons
1819
* or the ID name for local instances.

‎docs/apidoc/controller.js

+10
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,20 @@
11
/**
22
* @class Alloy.Controller.UI
3+
*
4+
* Provides convenience methods for working with Titanium UI objects.
35
*/
46

57
/**
68
* @method create
79
* Creates a Titanium UI object with the specified styles.
10+
* #### Example
11+
* The following creates a new {@link Titanium.UI.View View} object and assigns the "dialog"
12+
* TSS class (defined elsewhere) to the view, and finally adds it to main window.
13+
14+
var view = $.UI.create("View", {
15+
classes: 'dialog'
16+
});
17+
$.index.add(view);
818
* @param {String} apiName Name of the Titanium object to create. This can either be the full class
919
* name, such as `Ti.UI.Button`, or the XML element, such as `Button`.
1020
* @param {AlloyStyleDict} opts Dictionary of styles to apply. `opts` may also contain any additional properties you would like to apply directly the created Titanium object.

0 commit comments

Comments
 (0)