@maccesar/titools 5.3.0 → 5.4.0

package/skills/alloy-guides/references/CONTROLLERS.md

@@ -1,279 +1,81 @@
-# Alloy Controllers
+# Alloy controllers
 
-## Overview
+A controller runs when `Alloy.createController()` constructs it. XML elements with IDs are available as `$.<id>`. The top-level element uses the controller filename as its ID unless XML supplies another ID: `$.index` is therefore not guaranteed when the root has an explicit ID.
 
-This topic covers how to write controller code as well as other JavaScript files excluding models. Some traditional Titanium development is required, since Alloy controllers make direct calls to the Titanium SDK API to manipulate UI objects and access non-UI APIs.
+## Arguments and events
 
-## Controllers
-
-In Alloy, controllers contain the application logic used to control the UI and communicate with the model. The following code contains the presentation logic (`index.js`) associated with the view (`index.xml`).
-
-**app/controllers/index.js**
+Read arguments at the top of the controller, including arguments received through `<Require>`:
 
 ```javascript
-function doClick(e) {
-    alert($.label.text);
-}
-
-$.index.open();
-```
-
-**app/views/index.xml**
-
-```xml
-<Alloy>
-    <Window class="container">
-        <Label id="label" onClick="doClick">Hello, World</Label>
-    </Window>
-</Alloy>
-```
-
-All UI elements which have an `id` attribute in a view are automatically defined and available as a property prefixed by the special variable `$` in the controller. The `$` is a reference to the controller. For example, the `$.label` prefix in the controller is used to access the `Ti.UI.Label` object instance in the view. This reference is used to directly access properties or methods of this object. For example, calling `$.label.hide()` hides the label from the view or you can change the label text with `$.label.text`.
-
-To access external controllers and views, use the `Alloy.createController` and `Controller.getView` methods, respectively.
-
-If the top-level UI object does not have an ID defined, reference it using the name of the controller prefixed by the `$`. Since the Window object in the view does not contain an ID, the controller uses `$.index` to grab the top-level UI object from the view. However, if an `id` attribute was defined, for example, `<Window id='window'>`, the controller needs to use `$.window` to gain access to the Window object; `$.index` will be undefined and the application will throw an error when calling `$.index.open()`.
-
-### Events
-
-Controllers extend `BackBone.Events` and as such can dispatch events.
-
-For example, our index view could also require another controller to deliver the label and listen to an event:
-
-**app/views/index.xml**
-
-```xml
-<Alloy>
-    <Window class="container">
-        <Require id="label" src="label" onNotify="doSomething" />
-    </Window>
-</Alloy>
+// app/controllers/detail.js
+const noteId = $.args.id;
+$.title.text = `Note ${noteId}`;
 ```
 
-The view of the required label-controller would listen to the `click` event of the label itself:
-
-**app/views/label.xml**
-
-```xml
-<Alloy>
-    <Label id="label" onClick="passClick">Hello, World</Label>
-</Alloy>
-```
-
-And that label-controller would in turn fire the notify event on itself so the index controller will receive it:
-
-**app/controllers/label.js**
+Use a named top-level function for an XML event handler:
 
 ```javascript
-function passClick(e) {
-    $.trigger('notify');
+function doGo() {
+    $.greeting.text = 'Going';
 }
 ```
 
-### Inheritance
-
-Controllers can inherit from other controllers by assigning them as a base (parent) controller: `exports.baseController = 'baseControllerName'`. As in the CommonJS model, the controller inherits any exported functions from the base controller. These functions can also be overwritten.
+The view binds it with `onClick="doGo"`. See [XML views](./VIEWS_XML.md) for a complete screen.
 
-For example, the animal view-controller defines a label object with a speak method:
+## Creating and opening
 
-**app/controllers/animal.js**
+A controller is not a Window. Construct it, then open its top-level Window:
 
 ```javascript
-exports.speak = () => {
-    alert("Yelp!");
-};
-```
-
-**app/views/animal.xml**
-
-```xml
-<Alloy>
-    <Label id="animalLabel">Animal</Label>
-</Alloy>
+const detail = Alloy.createController('detail', { id: 42 });
+detail.getView().open();
 ```
 
-Then, the following code inherits from the animal view-controller and overrides the speak method and label text property to customize it for a dog controller.
-
-**app/controllers/dog.js**
+`getView()` returns the first top-level element. Alternatively, let the controller export the operation:
 
 ```javascript
-exports.baseController = "animal";
-$.animalLabel.text = "Dog";
-exports.speak = () => {
-    alert("Bark!");
+// app/controllers/detail.js
+exports.open = () => {
+    $.detail.open();
 };
 ```
 
-### Conditional Code
-
-Alloy introduces a set of special variables that act like compiler directives. Using these compiler constants optimizes the code at generation/compilation and any non-reachable code is removed.
+The caller uses `detail.open()`. Do not also open the Window at controller top level: the two approaches would open it twice. Anything on `exports` is exposed on the returned controller.
 
-The following are the constants defined by Alloy for use in the controller code:
+## Cleaning up
 
-* `OS_ANDROID` : true if the current compiler target is Android
-* `OS_IOS` : true if the current compiler target is iOS
-* `ENV_DEV` : true if the current compiler target is built for development (running in the simulator or emulator)
-* `ENV_TEST` : true if the current compiler target is built for testing on a device
-* `ENV_PRODUCTION` : true if the current compiler target is built for production (running after a packaged installation)
-* `DIST_ADHOC` (since Alloy 1.4.0) : true if the current compiler target is built for iOS Ad Hoc distribution, for example, if you set the `-T dist-adhoc` option when building with the Titanium CLI. Note that `ENV_PRODUCTION` will be true too since this deployment is only for production builds.
-* `DIST_STORE` (since Alloy 1.4.0) : true if the current compiler target is built for deployment to the Google Play Store or iTunes App Store, for example, if you set the `-T dist-store` option when building with the Titanium CLI. Note that `ENV_PRODUCTION` will be true too since this deployment is only for production builds.
+Alloy does not automatically dispose of controllers. External listeners, timers and geolocation subscriptions can outlive the Window. Remove listeners using the same function reference, clear timers and stop subscriptions when their owner closes. `$.destroy()` removes generated model/view bindings; it does not remove your external listeners.
 
-For example, since iOS devices do not include a back button, the application can conditionally add one to a window controller:
+After completing location setup and authorization through `ti-howtos`, this illustrates listener ownership:
 
 ```javascript
-if (OS_IOS) {
-  const closeButton = Ti.UI.createButton({
-        title: 'Close'
-    });
-
-    closeButton.addEventListener('click', () => {
-        $.window.close();
-    });
-
-    $.window.leftNavButton = closeButton;
+function onLocation(event) {
+    Ti.API.info(event);
 }
-```
-
-### Passing Arguments
-
-When initializing an external controller, you can pass arguments to customize it, for instance, `const controller = Alloy.createController('controller', {args1: 'foo'})`. In the external controller, the special variable `$.args` is used to receive the arguments. Before Alloy 1.6, you needed to use `arguments[0]`. For example, suppose you want to add multiple TableViewRow objects to a TableView object.
 
-For the TableViewRow object, called 'row', the view contains only the object, and the controller contains only a few lines of code to parse the arguments:
-
-**app/views/row.xml**
-
-```xml
-<Alloy>
-    <TableViewRow id="rowView"/>
-</Alloy>
+Ti.Geolocation.addEventListener('location', onLocation);
+$.index.addEventListener('close', () => {
+    Ti.Geolocation.removeEventListener('location', onLocation);
+    $.destroy();
+});
 ```
 
-**app/controllers/row.js (Alloy 1.6+)**
+Here `index.xml` must own a Window addressed as `$.index`. A child controller without that lifecycle needs cleanup coordinated by its owner. Keep each controller's cleanup separate from any shared model still used by another screen.
 
-```
-$.rowView.title = $.args.title || '';
-$.rowView.url = $.args.url || '';
-```
+## Shared code
 
-**app/controllers/row.js (Alloy <1.6)**
+`app/lib/` contains CommonJS modules:
 
 ```javascript
-const args = arguments[0] || {};
+const format = require('/format');
 ```
 
-In a separate controller containing the TableView object, called 'tableView', the code is cycling through an array of data and creating new instances of 'row' to supply it to 'tableView.'
-
-**app/controllers/index.js**
+The slash resolves against the application root, not the filesystem. Modules are available to controllers and widgets. Initialize shared state in `app/alloy.js`, before the first controller:
 
 ```javascript
-const data = [];
-for (let i=0; i<source.length; i++) {
-    const arg = {
-        title: source[i].postTitle,
-        url: source[i].postLink
-    };
-    data.push(Alloy.createController('row', arg).getView());
-}
-$.tableView.setData(data);
+Alloy.Globals.apiRoot = 'https://example.com/api';
 ```
 
-As seen in the example above, the controller is passing different arguments to the 'row' controller, creating unique instances of 'row'.
-
-### Global Namespace
-
-Controllers can store and access global variables using the `Alloy.Globals` namespace. For example, you can store an instance of a parent window in Globals and access it in another window.
-
-Store the parent window:
-
-```
-$.index.open();
-Alloy.Globals.parent = $.index;
-```
-
-Access the parent window in another controller:
-
-```javascript
-const parent = Alloy.Globals.parent;
-parent.close();
-```
-
-Other non-controller JavaScript code can access the Globals variable but need to require the Alloy module. See [Extending Alloy](#extending-alloy-underscorejs-and-backbonejs) below.
-
-## Initializer File (alloy.js)
-
-The initializer file `app/alloy.js` can be used to execute some code near the beginning of the application's lifecycle. The contents of this file will be executed right before the initial `index.js` controller is loaded, allowing you to execute code before any UI components are loaded and to override built-in Alloy functions before they are executed. The code in this file also has access to the `Alloy` namespace.
-
-For instance, the default `isTablet` method returns true if it is identified as an iPad, an Android device in the large or extra large group, or if either dimension exceeds 400 dp for Mobile Web application. To override that behavior, you can add the following code to `alloy.js`.
-
-```
-Alloy.isTablet = () => {
-    return !(Math.min(Ti.Platform.displayCaps.platformHeight, Ti.Platform.displayCaps.platformWidth) < 600);
-}
-```
-
-## Library Code and CommonJS Modules
-
-Some JavaScript code might not be suitable as controller code, since it does not have an associated view, or you want to separate it from the MVC framework for easier reusability. Create a folder called `lib` in the `app` directory of your Alloy project. Add your CommonJS modules or JavaScript code using the CommonJS format into the `lib` folder. These files are copied to the `Resources` folder, when compiling your Alloy project.
-
-To use the library or CommonJS module, require it with the library name or module name without the 'app/lib' path and '.js' extension:
-
-```javascript
-const lib = require('library_name');
-lib.foo();
-```
-
-> **⚠️ ⚠️ Warning**
-> Titanium and Alloy do not support the Node.js concept of "folders as modules". That is, requiring a folder name does not automatically load the `index.js` or `index.json` file inside the folder, or use the `package.json` file to locate the main entry point. You need to explicitly require the file that serves as the main entry point to the library.
-
-### Specs Folder
-
-Starting with Alloy 1.2.0, you can add the `specs` folder to your project. Like the `lib` folder, use the `specs` folder to add files to your project, except the files are only used when the deployment type is **not** production.
-
-Create a folder called `specs` in the `app` directory of your Alloy project. Add your files to the specs folder. These files are copied to the `Resources` folder, when compiling your Alloy project if the deployment type is **not** production.
-
-Use the `ENV_PROD` variable to check if the application is running as a production target or not, before using the files in the `specs` folder.
-
-```
-if (!ENV_PROD) {
-    // Executes the fooFunction from the foo module
-  require('specs/foo').fooFuntion();
-}
-```
-
-### Platform-Specific Library Folders
-
-Starting with Alloy 1.5.0, you can also create platform-specific subfolders in the `lib` directory. Just add a folder named **android** or **ios** under the component folder and add your platform-specific files for Android or iOS into the folder, respectively. Do not include the platform-specific folder name when referencing the file.
-
-```
-app/
-├──lib
-│  ├──ios
-│  │   └── library_name.js
-│  └── library_name.js
-├──models
-├──styles
-└──views
-   └── index.xml
-```
-
-### Extending Alloy, Underscore.js and Backbone.js
-
-To access the Alloy API methods, such as `createController` and `createModel`, as well as Underscore.js and Backbone.js in CommonJS modules and JavaScript files in `app/lib`, you need to load those modules in to the library:
-
-```javascript
-const Alloy = require('alloy'), _ = require("alloy/underscore")._, Backbone = require("alloy/backbone");
-
-// Alloy extended
-Alloy.createController('foo').getView().open();
-
-// Underscore extended
-const even = _.find([1, 2, 3, 4, 5, 6], num => num % 2 === 0);
-Ti.API.info(even);
-
-// Backbone extended
-const Book = Backbone.Model.extend();
-const book = new Book({title: 'Ulysses', author: 'James Joyce'});
-Ti.API.info(JSON.stringify(book));
-```
+For compiler constants, use [configuration](../../alloy-howtos/references/config_files.md#compile-time-constants).
 
-Currently, these modules are automatically available in the global scope and these APIs can be used without loading the modules. Referencing these modules without loading them first with the `require` method is discouraged and this behavior may be deprecated in the future. To ensure compatibility with future releases, always use the `require` method to load and use these modules.
+Source: [controllers](https://titaniumsdk.com/docs/alloy/controllers.md).