@maccesar/titools 2.10.1 → 3.2.0

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

@@ -1,1214 +0,0 @@
-# Alloy Models
-
-1. [Overview](#overview)
-2. [Alloy Collection and Model Objects](#alloy-collection-and-model-objects)
-3. [Alloy Data Binding](#alloy-data-binding)
-4. [Alloy Sync Adapters and Migrations](#alloy-sync-adapters-and-migrations)
-5. [Backbone Objects without Alloy](#backbone-objects-without-alloy)
-6. [Alloy Backbone Migration](#alloy-backbone-migration)
-
-## Overview
-
-Alloy uses Backbone.js to provide support for its models and collections. Alloy also borrows the concepts of migrations and adapters from Rails for storage integration.
-
-For models, collections and sync adapters, these guides only provides information on how Alloy uses the Backbone.js functionality and some simple examples of using it.
-
-## Alloy Collection and Model Objects
-
-### Models
-
-In Alloy, models inherit from the [Backbone.Model](https://backbonejs.org/#Model-View-separation) class. They contain the interactive data and logic used to control and access it. Models are specified with JavaScript files, which provide a table schema, adapter configuration and logic to extend the Backbone.Model class. Models are automatically defined and available in the controller scope as the name of the JavaScript file.
-
-The JavaScript file exports a definition object comprised of three different objects. The first object, called `config`, defines the table schema and adapter information. The next two objects `extendModel` and `extendCollection` define functions to extend, override or implement the Backbone.Model and Backbone.Collection classes, respectively.
-
-**Example of the anatomy of a model file**
-
-```
-exports.definition = {
-    config : { // table schema and adapter information
-    },
-    extendModel(Model) {
-        _.extend(Model.prototype, { // Extend, override or implement Backbone.Model
-        });
-
-        return Model;
-    },
-    extendCollection(Collection) {
-        _.extend(Collection.prototype, { // Extend, override or implement Backbone.Collection
-    });
-
-        return Collection;
-    }
-}
-```
-
-To access a model locally in a controller, use the `Alloy.createModel` method. The first required parameter is the name of the JavaScript file minus the '.js' extension. The second optional parameter is the attributes for initializing the model object. For example:
-
-**Basic model usage**
-
-```javascript
-const book = Alloy.createModel('book', {title:'Green Eggs and Ham', author:'Dr. Seuss'});
-const title = book.get('title');
-const author = book.get('author');
-
-// Label object in the view with id = 'label'
-$.label.text = title + ' by ' + author;
-```
-
-The `book` model object is a Backbone object wrapped by Alloy, so it can be treated as a Backbone.Model object. You can use any Backbone Model or Events APIs with this object.
-
-You can also create a global singleton instance of a model, either in markup or in the controller, which may be accessed in all controllers. Use the `Alloy.Models.instance` method with the name of the model file minus the extension as the only parameter to create or access the singleton. For example:
-
-**Working with globally registered models**
-
-```javascript
-// This will create a singleton if it has not been previously created,
-// or retrieves the singleton if it already exists.
-const book = Alloy.Models.instance('book');
-```
-
-#### Configuration Object
-
-The `config` object is comprised of three different objects: `columns`, `defaults` and `adapter`.
-
-The `columns` object defines the table schema information. The key is the record name and the value is the data type. The following data types are accepted and mapped to the appropriate SQLite type: `string`, `varchar`, `int`, `tinyint`, `smallint`, `bigint`, `double`, `float`, `decimal`, `number`, `date`, `datetime` and `boolean`. By default, any unknown data type maps to the SQLite type `TEXT`. Alternatively, the SQLite sync adapter accepts the SQLite keywords.
-
-The optional `defaults` object defines the default values for a record if one or more record fields are left undefined upon creation. The key is the record name and the value is the default value.
-
-The adapter object defines how to access persistent storage. It contains two key-value pairs: `type` and `collection_name`. The `type` key identifies the sync adapter and the `collection_name` key identifies the name of the table in the database or a namespace.
-
-For example, suppose there is a model object called book (`book.js`) defined as:
-
-**book.js**
-
-```javascript
-exports.definition = {
-    config: {
-        "columns": {
-            "title": "String",
-            "author": "String"
-        },
-        "defaults": {
-            "title": "-",
-            "author": "-"
-        },
-        "adapter": {
-            "type": "sql",
-            "collection_name": "books"
-        }
-    }
-}
-```
-
-The code above describes a book object, which has two `string` (or `TEXT`) fields: `title` and `author`. If either field is left undefined, it will be assigned with the default value, a dash ("-"). The `sql` type configures Backbone to use the SQL adapter to sync with the SQLite engine on Android and iOS devices to access a table in the database called "books".
-
-You may add custom properties to the `config` object, which are available to the application as the model or collection's `config` property or can be processed by a custom sync adapter during application initialization.
-
-#### Extending the Backbone.Model Class
-
-The Backbone.Model class can be extended using the `extendModel` object, which implements the Backbone.Model `extend` method. This allows the Backbone.js code to be extended, overridden or implemented.
-
-For example, the `validate` method is left unimplemented by Backbone.js. The model JS file can implement `validate(attrs)`, where the parameter `attrs` are changed attributes in the model. In Backbone.js, if `validate` is implemented, it is called by the `set` and `save(attributes)` methods before changing the attributes and is also called by the `isValid` method. For the `save` method, validate is called if the `attributes` parameter is defined.
-
-In the example code `book.js` below, the JavaScript file implements the validate method, and adds a custom property and function.
-
-**Extending a model**
-
-```javascript
-exports.definition = {
-    config : { // table schema and adapter information
-    },
-
-    extendModel(Model) {
-        _.extend(Model.prototype, {
-            // Implement the validate method
-            validate(attrs) {
-                for (const key in attrs) {
-                    const value = attrs[key];
-                    if (key === "title") {
-                        if (value.length <= 0) {
-                            return "Error: No title!";
-                        }
-                    }
-                    if (key === "author") {
-                        if (value.length <= 0) {
-                            return "Error: No author!";
-                        }
-                    }
-                }
-            },
-            // Extend Backbone.Model
-            customProperty: 'book',
-            customFunction() {
-                Ti.API.info('I am a book model.');
-            },
-        });
-
-        return Model;
-    }
-}
-```
-
-In the controller, to access the model, do:
-
-```javascript
-const book = Alloy.createModel('book', {title:'Green Eggs and Ham', author:'Dr. Seuss'});
-// Since set or save(attribute) is not being called, we can call isValid to validate the model object
-if (book.isValid() && book.customProperty == "book") { // Save data to persistent storage
-    book.save();
-}
-else {
-    book.destroy();
-}
-```
-
-### Collections
-
-Collections are ordered sets of models and inherit from the Backbone.Collection class. Alloy Collections are automatically defined and available in the controller scope as the name of the model. To access a collection in the controller locally, use the `Alloy.createCollection` method with the name of the JavaScript file minus the '.js' extension as the required parameter. The second optional parameter can be an array of model objects for initialization. For example, the code below creates a collection using the previously defined model and reads data from persistent storage:
-
-**Creating collections**
-
-```javascript
-const library = Alloy.createCollection('book');
-library.fetch(); // Grab data from persistent storage
-```
-
-The `library` collection object is a Backbone object wrapped by Alloy, so it can be treated as a Backbone.Collection object. You can use any Backbone Collection or Events APIs with this object.
-
-You can also create a global singleton instance, either in markup or in the controller, which may be accessed in all controllers. Use the `Alloy.Collections.instance` method with the name of the model file minus the extension as the only parameter to create or access the singleton. For example:
-
-**Working with globally registered collections**
-
-```javascript
-// This will create a singleton if it has not been previously created,
-// or retrieves the singleton if it already exists.
-const library = Alloy.Collections.instance('book');
-```
-
-#### Extending the Backbone.Collection Class
-
-Like the Backbone.Model class, the Backbone.Collection class can be similarly extended in the model JavaScript file. For example, the `comparator` method is left unimplemented in Backbone.js. The code below sorts the library by book title:
-
-**Extending a collection**
-
-```
-exports.definition = {
-    config : { // table schema and adapter information
-    },
-    extendModel(Model) {
-        _.extend(Model.prototype, { // Extend, override or implement Backbone.Model methods
-        });
-        return Model;
-    },
-    extendCollection(Collection) {
-        _.extend(Collection.prototype, { // Implement the comparator method.
-            comparator(book) {
-                return book.get('title');
-            }
-        }); // end extend
-
-        return Collection;
-    }
-}
-```
-
-#### Underscore.js Functionality
-
-Also, the Backbone.Collection class inherits some functionality from [Underscore.js](https://underscorejs.org/), which can help simplify iterative functions. For example, to add the title of each book object in the library collection to a table, you could use the `map` function to set the table:
-
-**Iterating over a collection with underscore**
-
-```javascript
-const data = library.map(book => {
-    // The book argument is an individual model object in the collection
-    const title = book.get('title');
-    const row = Ti.UI.createTableViewRow({"title":title});
-    return row;
-});
-// TableView object in the view with id = 'table'
-$.table.setData(data);
-```
-
-### Event Handling
-
-When working with Alloy Models and Collections, use the Backbone.Events `on`, `off` and `trigger` methods. For example:
-
-**Using events with collections**
-
-```javascript
-const library = Alloy.createCollection('book');
-function event_callback (context) {
-    const output = context || 'change is bad.';
-    Ti.API.info(output);
-};
-// Bind the callback to the change event of the collection.
-library.on('change', event_callback);
-// Trigger the change event and pass context to the handler.
-library.trigger('change', 'change is good.');
-// Passing no parameters to the off method unbinds all event callbacks to the object.
-library.off();
-// This trigger does not have a response.
-library.trigger('change');
-```
-
-Alloy Model and Collection objects don't support the Titanium `addEventListener`, `removeEventListener` and `fireEvent` methods.
-
-If you are using Alloy's Model-View binding mechanism, the Backbone add, change, destroy, fetch, remove, and reset events are automatically bound to an internal callback to update the model data in the view. Be careful not to override or unbind these events.
-
-If you want to fire or listen to multiple events, Backbone.js uses spaces to delimit its events in the event string; therefore, do **NOT** name any custom events with spaces.
-
-## Alloy Data Binding
-
-### Introduction
-
-When data in the collection changes, you may want to update the view simultaneously to keep information synchronized. This concept is known as data binding. Both Alloy and Backbone provide some mechanisms to bind model data to a view.
-
-### Alloy Binding
-
-In Alloy, collection data can be synchronized to a view object, or a single model can be bound to a view component. Alloy monitors the Backbone add, change, destroy, fetch, remove, and reset events to update the data in the view.
-
-#### Collection-View Binding
-
-To enable collection-view binding, create a global singleton or controller-specific collection using the [Collection tag](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Views/Alloy_XML_Markup.html#collection-element) in the XML markup of the main view, then add the view object you want to bind data to. The following Titanium view objects support binding to a Collection:
-
-| View Object    | Since Alloy version | Add data binding attributes to...              | Repeater Object to map model attributes to view properties                     |
-| -------------- | ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |
-| ButtonBar      | 1.1                 | `<Labels>`                                     | `<Label/>`                                                                     |
-| CoverFlowView  | 1.1                 | `<Images>`                                     | `<Image/>`                                                                     |
-| ListView       | 1.2                 | `<ListSection>`                                | `<ListItem/>`                                                                  |
-| Map Module     | 1.4                 | `<Module module="ti.map" method="createView">` | None, model attributes will be used as params for createAnnotation() directly. |
-| Picker         | 1.5                 | `<PickerColumn>` or `<Column>`                 | `<PickerRow/>` or `<Row/>`                                                     |
-| ScrollableView | 1.1                 | `<ScrollableView>`                             | `<View/>` May contain children view objects.                                   |
-| TableView      | 1.0                 | `<TableView>`                                  | `<TableViewRow/>` May contain children view objects.                           |
-| TabbedBar      | 1.1                 | `<Labels>`                                     | `<Label/>`                                                                     |
-| Toolbar        | 1.1                 | `<Items>`                                      | `<Item/>`                                                                      |
-| View           | 1.0                 | `<View>`                                       | Any view object except a top-level container like a Window or TabGroup         |
-
-You need to specify additional attributes in the markup, which are only specific to collection data binding. The only mandatory attribute is `dataCollection`, which specifies the collection singleton or instance to render. Note that you can only add these attributes to specific XML elements (refer to the table above).
-
-* `dataCollection`: specifies the collection singleton or instance to bind to the table. This is the name of the model file for singletons or the ID prefixed with the controller symbol ('$') for instances.
-
-* `dataTransform`: specifies an optional callback to use to format model attributes. The passed argument is a model and the return value is a modified model as a JSON object.
-
-* `dataFilter`: specifies an optional callback to use to filter data in the collection. The passed argument is a collection and the return value is an array of models.
-
-* `dataFunction`: set to an arbitrary identifier (name) for a function call. Use this identifier to call a function in the controller to manually update the view. This is not a declared function in the controller. This attribute creates an alias to access the underlying binding function, which is part of the Alloy data-view binding framework.
-
-Next, create a repeater object (refer to the table above) and place it inline with the view object with the `dataCollection` attribute, or place it in a separate view and use the `Require` tag to import it.
-
-To map model attributes, enclose the attribute with curly brackets or braces ('{' and '}'). You can map more than one attribute to a repeater object's property. For example, to assign the Label.text property to the model's title and author attributes, use this notation: `<Label text="{title} by {author}" />.` For more complex transformations, use the `dataTransform` callback to create a custom attribute.
-
-In the controller code of the repeater object, you can use the special variable `$model` to reference the current model being iterated over. This variable is present only in data bound controllers and is a reference to the currently bound model. For example, to get the title attribute of the current model, use `$model.title` to access it.
-
-> **⚠️ ⚠️ Warning**
-> **IMPORTANT:** When using Alloy's data binding in a view-controller, you **MUST** call the `$.destroy()` function when closing a controller to prevent potential memory leaks. The `destroy` function unbinds the callbacks created by Alloy when the collection-view syntax is used. For example:
->
-> ```javascript
-> $.win.addEventListener("close", () => {
->     $.destroy();
-> });
-> ```
->
-> For global singletons, to properly release them you should also remove event handlers with `off()` and set the reference to null:
->
-> ```javascript
-> $.win.addEventListener("close", () => {
->     $.destroy();
->     Alloy.Collections.book.off();
->     Alloy.Collections.book = null;
-> });
-> ```
-
-#### Collection-View Binding Example
-
-The following example demonstrates how to add basic collection-view binding to an application. The example binds a collection of album models to a ScrollableView. In the ScrollableView, each model has its own view, which displays the album cover, title of the album and the artist. The `artist` and `title` attributes are bound to a Label object and the `cover` attribute is bound to an ImageView object.
-
-1. Add the `<Collection>` tag as a child of the `<Alloy>` tag.
-
-    **app/views/index.xml**
-
-    ```xml
-    <Alloy>
-        <Collection src="album" />
-    </Alloy>
-    ```
-
-2. Next, add the view object(s) you want to bind the data to. In this example, data will be bound to a ScrollableView object.
-
-    **app/views/index.xml**
-
-    ```xml
-    <Alloy>
-        <Collection src="album" />
-        <Window backgroundColor="white" onClose="cleanup">
-            <ScrollableView></ScrollableView>
-        </Window>
-    </Alloy>
-    ```
-
-3. Add the `dataCollection` attribute to the appropriate view object. Assign this attribute to the collection you want to use. For a ScrollableView object, add the attribute to the `<ScrollableView>` tag. The element to add the attribute to depends on which view object you want to bind data to.
-
-    **app/views/index.xml**
-
-    ```xml
-    <Alloy>
-        <Collection src="album" />
-        <Window backgroundColor="white" onClose="cleanup">
-            <ScrollableView dataCollection="album"></ScrollableView>
-        </Window>
-    </Alloy>
-    ```
-
-4. Next, create your repeater object and add model attributes. Enclose the model attributes with curly brackets or braces ('{' and '}'). For a ScrollableView, the repeater object can be a View object with additional children objects. The repeater object depends on which view object you are using.
-
-    **app/views/index.xml**
-
-    ```xml
-    <Alloy>
-        <Collection src="album"/>
-        <Window backgroundColor="white" onClose="cleanup">
-            <ScrollableView dataCollection="album">
-                <View layout="vertical">
-                    <ImageView image="{cover}" />
-                    <Label text="{title} by {artist}" />
-                </View>
-            </ScrollableView>
-        </Window>
-    </Alloy>
-    ```
-
-5. In the controller, call the Collection's `fetch()` method to initialize the collection and sync any stored models to the view. Remember to call the `$.destroy()` method when you close the controller to prevent memory leaks.
-
-    **app/controllers/index.js**
-
-    ```javascript
-    $.index.open();
-    Alloy.Collections.album.fetch();
-
-    function cleanup() {
-        $.destroy();
-    }
-    ```
-
-The application is now setup for basic collection-view binding. When any new data is added to the collection, the ScrollableView will be updated with the new data.
-
-#### Model-View Binding
-
-To bind a single model to a component, create a global singleton or controller-specific model using the [Model tag](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Views/Alloy_XML_Markup.html#model-element) in the XML markup of the main view and map the model attribute to the view component. To map the attribute to the view component, prefix the model name or id to the attribute, then enclose it with curly brackets or braces ('{' and '}').
-
-To do complex transformations on the model attributes, extend the model prototype with a `transform()` function. It should return the modified model as a JSON object.
-
-**app/models/album.js**
-
-```javascript
-exports.definition = {
-  config: {}, // model definition
-  extendModel(Model) {
-    _.extend(Model.prototype, {
-      transform() {
-        const transformed = this.toJSON();
-        transformed.artist = transformed.artist.toUpperCase();
-        return transformed;
-      }
-    });
-    return Model;
-  }
-};
-```
-
-A global singleton instance is a single instance of a particular model that is available for use anywhere in your application. When using global instances, they will be in memory for the duration of your application unless you manually release them. The process of manually releasing them should include:
-
-* If any controllers are using data binding that relies on the global instance, they should call their own destroy() function: `$.destroy()`
-* Any other event handlers added to the global instance should be removed with the [off()](http://backbonejs.org/#Events-off) function
-* Set the reference of the model to null: `Alloy.Models.nameOfModel = null;`
-
-Note that you need to call the `$.destroy()` function when closing the controller to prevent potential memory leaks. The `destroy` function unbinds the callbacks created by Alloy when the model-view syntax is used.
-
-#### Model-View Binding Example
-
-The example below demonstrates how to bind a model to view components in the XML markup. Notice that each attribute is prefixed with the model's name and enclosed with braces.
-
-```xml
-<Alloy>
-    <Model src="settings"/>
-    <Window backgroundColor="white" onClose="cleanup">
-        <View layout="vertical">
-            <Label text="Text Size" />
-            <Slider value="{settings.textsize}" max="5" min="1"/>
-            <Label text="Bold"/>
-            <Switch value="{settings.bold}" />
-            <Label text="Italics"/>
-            <Switch value="{settings.italics}" />
-        </View>
-    </Window>
-</Alloy>
-```
-
-#### Collection Example
-
-The example below demonstrates how to display all book models in the collection by the author Mark Twain. It also demonstrates how to use each of the data binding attributes.
-
-**app/views/index.xml**
-
-```xml
-<Alloy>
-    <Collection src="book" />
-    <Window class="container">
-        <TableView dataCollection="book"
-                   dataTransform="transformFunction"
-                   dataFilter="filterFunction"
-                   dataFunction="updateUI"
-                   onDragEnd="refreshTable">
-            <!-- Also can use Require -->
-            <TableViewRow title="{title}" />
-        </TableView>
-    </Window>
-</Alloy>
-```
-
-**app/controllers/index.js**
-
-```javascript
-$.index.open();
-
-// Encase the title attribute in square brackets
-function transformFunction(model) {
-    // Need to convert the model to a JSON object
-    const transform = model.toJSON();
-    transform.title = '[' + transform.title + ']';
-    // Example of creating a custom attribute, reference in the view using {custom}
-    transform.custom = transform.title + " by " + transform.author;
-    return transform;
-}
-
-// Show only book models by Mark Twain
-function filterFunction(collection) {
-    return collection.where({author:'Mark Twain'});
-}
-
-function refreshTable(){
-    // Trigger the binding function identified by the dataFunction attribute
-    updateUI();
-}
-
-// Trigger the synchronization
-const library = Alloy.Collections.book;
-library.fetch();
-
-// Free model-view data binding resources when this view-controller closes
-$.index.addEventListener('close', () => {
-    $.destroy();
-});
-```
-
-As the collection is updated, the view reflects the changes made to the models. If you want to suppress an update, specify `{silent: true}` in the `options` parameters when calling Backbone methods to change model data.
-
-### Collection vs Model Data Binding
-
-You can bind both a collection of models or an individual model. To bind a model attribute the opening curly bracket is first followed by the model name and then the attribute. To bind a collection you add the `dataCollection` attribute to the container using the collection name as value. The generated code will then loop over the collection and add the child elements to the container for each model.
-
-```xml
-<Alloy>
-    <Model src="currentCategory" />
-    <Collection src="book" />
-    <Window>
-        <!-- model data binding -->
-        <Label text="{currentCategory.name}" />
-
-        <!-- collection data binding -->
-        <ScrollView dataCollection="book">
-            <Label text="{title}" />
-        </ScrollView>
-    </Window>
-</Alloy>
-```
-
-### Global Singleton vs Local Instance
-
-In the above code snippet, the model and collection are global singletons under `Alloy.Models.currentCategory` and `Alloy.Collections.book`. You can also use local instances for the current controller by adding `instance="true"` as attribute. You also need to assign them an ID to reference them in the XML and controller.
-
-```xml
-<Alloy>
-    <Model src="currentCategory" instance="true" id="c" />
-    <Collection src="book" instance="true" id="b" />
-    <Window>
-        <!-- model data binding -->
-        <Label text="{$.c.name}" />
-
-        <!-- collection data binding -->
-        <ScrollView dataCollection="$.b">
-            <Label text="{title}" />
-        </ScrollView>
-    </Window>
-</Alloy>
-```
-
-### Simple vs Complex Data Binding
-
-It's important to understand the difference between simple and complex data binding as they were implemented in unique ways which results in different behaviour.
-
-Simple data binding involves one model attribute where complex data binding involves a combination of strings (including white space) and model attributes or even multiple model attributes:
-
-```xml
-<Alloy>
-    <Model src="book">
-    <Window>
-        <!-- simple -->
-        <Label text="{book.title}" />
-
-        <!-- complex -->
-        <Label text="Title: {book.title}" />
-        <Label text="{book.author.name} {book.author.email}" />
-    </Window>
-</Alloy>
-```
-
-### Backbone Binding
-
-The application can monitor Backbone events to trigger updates to the view.
-
-For instance, the code below demonstrates how to update a table when a model object is added to a collection by monitoring the add event:
-
-```javascript
-library.on('add', e => {
-    // custom function to update the content on the view
-    updateFooView(library);
-});
-```
-
-Another method is to selectively monitor changes. For instance, the code below demonstrates how to update data if a title changes in the collection:
-
-```javascript
-library.on('change:title', e => {
-    // custom function to update the content on the view
-    updateFooView(library);
-});
-```
-
-> **⚠️ ⚠️ Warning**
-> This only works if the Backbone method fires the change event and does not enable `{silent: true}` as an option.
-
-If you want to suppress an update, specify `{silent: true}` in the `options` parameters when calling Backbone methods to change model data. The data-bound view will not be updated to reflect the changes.
-
-### Bind Deep Object Properties
-
-You can bind deep object properties:
-
-```xml
-<Alloy>
-    <Model src="book" />
-    <Label text="{book.author.name}" />
-</Alloy>
-```
-
-Before, you needed to use a transformer to create a reference like `authorName`.
-
-Before CLI 7.1.0, the only way to set object properties (e.g. `font.fontFamily` for a Label) was to use TSS. You can use dot notation in XML:
-
-```xml
-<Alloy>
-    <Model src="book" />
-    <Label font.fontFamily="Roboto">Hello</Label>
-</Alloy>
-```
-
-### Use Models and Properties with Special Characters
-
-You can bind models and properties that use names with special characters like dashes and spaces. Simply wrap the names in square brackets and quotes like you'd do in JavaScript:
-
-```xml
-<Alloy>
-    <Model src="my-model">
-    <Label text="['my-model']['my-property']" />
-</Alloy>
-```
-
-### Bind Multiple Models to the Same View
-
-You have the ability to bind multiple models to the same view:
-
-```xml
-<Alloy>
-    <Model src="a" />
-    <Model src="b" />
-    <Label text="{a.hello} {b.world}" />
-</Alloy>
-```
-
-### Define Transformations in the Model
-
-Since Alloy 1.8.1, all types of data binding will generate the following logic to determine what object will be bound to the view:
-
-```javascript
-let t;
-if (_.isFunction(<dataTransform>)) { // only for collection binding
-    t = <dataTransform>(model);
-} else if (_.isFunction(model.transform)) {
-    t = model.transform();
-} else {
-    t = model.toJSON();
-}
-$.myLabel.text = t.author.name;
-```
-
-You'd extend a model with a `transform()` method as such:
-
-```javascript
-exports.definition = {
-    // config
-    extendModel(Model) {
-        _.extend(Model.prototype, {
-            transform() {
-                const t = this.toJSON();
-                t.titleCaps = t.title.toUpperCase();
-                return t;
-            }
-        });
-        return Model;
-    }
-};
-```
-
-> **⚠️ ⚠️ Warning**
-> The `transform` method must return **all** bound properties, not just the transformed ones. Until Alloy 1.8.1, simple collection data binding did not require this and automatically fell back to the model attributes.
-
-### Tips and Tricks
-
-#### Lazy Transformation
-
-The advantage of defining transformations in the model is that you don't need to repeat them in every controller. A possible disadvantage is that everywhere you bind the model all transformations are computed where you might only need some.
-
-You can handle this using `Object.defineProperty()`. Its `get` callback will only be called when the transform key is actually requested:
-
-```javascript
-const moment = require('alloy/moment');
-
-exports.definition = {
-    extendModel(Model) {
-        _.extend(Model.prototype, {
-            transform() {
-                const model = this;
-                const t = this.toJSON();
-
-                Object.defineProperty(t, 'dateFormatted', {
-                  get() {
-                    return moment(t.date).format('LLLL');
-                  }
-                });
-
-                return t;
-            }
-        });
-        return Model;
-    }
-};
-```
-
-#### Populating a Model After Data Binding
-
-When Alloy compiles your views and controllers, the generated view code precedes your controller code. Any models you define for data binding in the XML will also be created at that point. Just like you call `fetch()` to populate the collection, you do the exact same thing for the model.
-
-**index.xml**
-
-```xml
-<Alloy>
-    <Model src="book" instance="true" id="current" />
-    <Window>
-        <Label text="{book.title}" />
-    </Window>
-</Alloy>
-```
-
-**index.js**
-
-```javascript
-$.current.fetch({
-    id: Ti.App.Properties.getString('currentBook')
-});
-
-$.index.open();
-```
-
-> **⚠️ ⚠️ Warning**
-> With the release of CLI 7.1.0, values passed in at creation of a view can be used as values in TSS and XML. For example, if the **foo** property was passed in at creation it can be used on a label:
->
-> ```xml
-> <Alloy>
->     <Label text="$.args.foo" />
-> </Alloy>
-> ```
-
-## Alloy Sync Adapters and Migrations
-
-### Sync Adapters
-
-In Alloy, a sync adapter allows you to store and load your models to a persistent storage device, such as an on-device database or remote server. Alloy relies on the Backbone API to sync model data to persistent storage.
-
-#### Backbone Sync
-
-Backbone syncs your models to persistent storage devices based on the implementation of the [Backbone.sync method](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Models/Alloy_Sync_Adapters_and_Migrations.html). Since Backbone's primary use is for web applications, by default, the Backbone.sync method executes RESTful JSON requests to a URL specified by the Model.urlRoot or Collection.url attribute, when these classes are created.
-
-Models are accessed from persistent storage based on the `id` attribute. To override this, set the `idAttribute` property of the model. The `cid` (client ID) is a special property of models that is automatically assigned when they are first created. Client IDs are useful when the model has not yet been saved to the server and does not have its real `id` yet.
-
-The sync method depends on calls to other Backbone methods as described in the table below.
-
-| **Backbone Method**                                              | **Sync CRUD Method** | **Equivalent HTTP Method** | **Equivalent SQL Method** |
-| ---------------------------------------------------------------- | -------------------- | -------------------------- | ------------------------- |
-| Collection.fetch                                                 | read                 | GET                        | SELECT                    |
-| Collection.create (id == null) or Collection.create (id != null) | create or update     | POST or PUT                | INSERT or UPDATE          |
-| Model.fetch                                                      | read                 | GET                        | SELECT                    |
-| Model.save (id == null) or Model.save (id != null)               | create or update     | POST or PUT                | INSERT or UPDATE          |
-| Model.destroy                                                    | delete               | DELETE                     | DELETE                    |
-
-#### Ready-Made Sync Adapters
-
-Alloy provides a few ready-made sync adapters. In the 'adapter' object, set the 'type' to use one of the following:
-
-* `sql` for the SQLite database on the Android and iOS platform.
-* `properties` for storing data locally in the Titanium SDK context. You do not need to define the `columns` object in the `config` object. If defined, the object is ignored.
-* `localStorage` for HTML5 localStorage on the Mobile Web platform. Deprecated since Alloy 1.5.0. Use the `properties` adapter instead.
-
-These adapters are part of Alloy and are copied to the `Resources/alloy/sync` folder during compilation. These sync adapters assign the `id` attribute of the models, which means if you assign an ID when creating a model, it is overridden by any sync operations.
-
-##### SQLite Sync Adapter Features
-
-The `sql` sync adapter has a few extra features:
-
-**Fetch method accepts SQL Query**
-
-The Backbone.Collection.fetch method supports SQL queries as a parameter. Use `query` as the key in the dictionary object to create a simple query or query with a prepared statement.
-
-```javascript
-const library = Alloy.createCollection('book');
-const table = library.config.adapter.collection_name;
-// use a simple query
-library.fetch({query:'SELECT * from ' + table + ' where author="' + searchAuthor + '"'});
-// or a prepared statement
-library.fetch({query: { statement: 'SELECT * from ' + table + ' where author = ?', params: [searchAuthor] }});
-```
-
-**Fetch method accepts ID attribute**
-
-Since Alloy 1.3.0, to fetch a single model using its ID, pass a dictionary with one key-value pair, where `id` is the key and the model's ID as the value to retrieve that model, to the `fetch` method instead of using a SQL query. For example:
-
-```
-myModel.fetch({id: 123});
-// is equivalent to
-myModel.fetch({query: 'select * from ... where id = ' + 123 });
-```
-
-**Columns accept SQLite keywords**
-
-The columns values accept SQLite keywords, such as AUTOINCREMENT and PRIMARY KEY. For example:
-
-**app/models/book.js**
-
-```javascript
-exports.definition = {
-    config: {
-        "columns": {
-            "title": "TEXT",
-            "author": "TEXT",
-            "book_id": "INTEGER PRIMARY KEY AUTOINCREMENT"
-        },
-        "adapter": {
-            "type": "sql",
-            "collection_name": "books",
-            "idAttribute": "book_id"
-        }
-    }
-}
-```
-
-**Specify columns property as primary ID**
-
-Define the `idAttribute` key-value pair in the `config.adapter` object to use a `config.columns` key as the primary ID for the SQLite table. If this key is not set, Alloy creates the `alloy_id` column in the table and generates a default GUID as the model ID.
-
-**Specify a migration to use**
-
-Define the `migration` key-value pair in the `config.adapter` object to specify the database version to use. The value of this key is the datetime code of the migration file. Alloy upgrades or rolls back the database based on this value. If left undefined, Alloy upgrades the database based on the newest migration file.
-
-**Specify a database to use**
-
-Define the `db_name` key-value pair in the `config.adapter` object to specify the name of the database to use. If left undefined, Alloy uses the default database `_alloy_`.
-
-**Specify a database file to preload**
-
-Define the `db_file` key-value pair in the `config.adapter` object to specify the database file ('myfile.sqlite') to preload. Place this file in the `app/assets` directory of your Alloy project. Alloy creates a database using the name of the database file minus the file extension if one does not exist.
-
-### Custom Sync Adapters
-
-To create a custom sync adapter, create a JavaScript file in either `app/assets/alloy/sync` or `app/lib/alloy/sync`. During compilation, this file is copied to the `Resources/alloy/sync` folder. In the `config` object of the model file, set the `type` in the `adapter` object to the name of the JavaScript file minus the '.js' extension.
-
-The sync adapter exports three functions:
-
-* `module.exports.beforeModelCreate` (optional) - executes code before creating the Backbone.Model class. First passed parameter is the `config` object from the model file. Second passed parameter is the name of the Alloy Model file. Returns a `config` object.
-
-* `module.exports.afterModelCreate` (optional) - execute code after creating the Backbone.Model class. First passed parameter is the newly created Backbone.Model class. Second passed parameter is the name of the Alloy Model file.
-
-* `module.exports.sync` - implement the Backbone.sync method.
-
-### Migrations
-
-A migration is a description of incremental changes to a database, which takes your database from version 1 to version X, with a migration file for each step in the evolution of your database schema. This is helpful to keep different versions of a database in sync. For example, when version 7 of your application is deployed, migrations can successfully update the database from versions 1 through 6. Currently, migrations are only used with the `sql` sync adapter.
-
-The `migration.up` function upgrades the database from the previous version, while the `migration.down` function rolls back the changes to the previous version.
-
-In Alloy, migrations are defined by JavaScript files located in the `app/migrations` folder of the project. The file should be named the same as the model JavaScript file prefixed with 'YYYYMMDDHHmmss_' (datetime code followed by an underscore), for example, `20120610049877_book.js`. Alloy applies the migrations from oldest to newest, according to the datetime code at the beginning of the file name.
-
-The migration file contains two functions that need to be implemented: `migration.up(migrator)` and `migration.down(migrator)`, where `migrator` is a special migration object that provides references to the database and table as well as some convenient functions for table operations:
-
-| Key           | Description                                                                                                                                                      |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `db`          | Handle to a `Ti.Database` instance. Use this handle to execute SQL calls using `db.execute`. DO NOT CLOSE THIS HANDLE OR OPEN A SECOND INSTANCE OF THE DATABASE. |
-| `dbname`      | Name of the database.                                                                                                                                            |
-| `table`       | Name of the table. Same as value of the `config.adapter.collection_name` key.                                                                                    |
-| `idAttribute` | Name of the columns attribute to use as the primary key.                                                                                                         |
-| `createTable` | Function to create a table. Required parameter is the `columns` object.                                                                                          |
-| `dropTable`   | Function to drop the current table from the database.                                                                                                            |
-| `insertRow`   | Function to insert data into the table. Useful for preloading data.                                                                                              |
-| `deleteRow`   | Function to delete data from the table.                                                                                                                          |
-
-For example, the migration file below is the initial version of the database that preloads some data in the table.
-
-**app/migrations/20120610049877_book.js**
-
-```javascript
-const preload_data = [
-  {title: 'To Kill a Mockingbird', author:'Harper Lee'},
-  {title: 'The Catcher in the Rye', author:'J. D. Salinger'},
-  {title: 'Of Mice and Men', author:'John Steinbeck'},
-  {title: 'Lord of the Flies', author:'William Golding'},
-  {title: 'The Great Gatsby', author:'F. Scott Fitzgerald'},
-  {title: 'Animal Farm', author:'George Orwell'}
-];
-
-migration.up = migrator => {
-    migrator.createTable({
-        "columns":
-        {
-            "book": "TEXT",
-            "author": "TEXT"
-        }
-    });
-    for (let i = 0; i < preload_data.length; i++) {
-      migrator.insertRow(preload_data[i]);
-    }
-};
-
-migration.down = migrator => {
-    migrator.dropTable();
-};
-```
-
-#### Migration Rollback Example
-
-Suppose later, you want to include some additional information for your books, such as an ISBN. The below migration file upgrades or rolls back the changes. Since SQLite does not support the DROP COLUMN operation, the migration needs to create a temporary table to hold the data, drop the new database, create the old database, then copy the data back. Note: if `idAttribute` is not specified, Alloy creates the `alloy_id` column and this column needs to be copied over as part of the migration.
-
-**app/migrations/20130118069778_book.js**
-
-```javascript
-migration.up = migrator => {
-    migrator.db.execute('ALTER TABLE ' + migrator.table + ' ADD COLUMN isbn INT;');
-};
-
-migration.down = migrator => {
-    const db = migrator.db;
-    const table = migrator.table;
-    db.execute('CREATE TEMPORARY TABLE book_backup(title,author,alloy_id);')
-    db.execute('INSERT INTO book_backup SELECT title,author,alloy_id FROM ' + table + ';');
-    migrator.dropTable();
-    migrator.createTable({
-        columns: {
-            title:"TEXT",
-            author:"TEXT",
-        },
-    });
-    db.execute('INSERT INTO ' + table + ' SELECT title,author,alloy_id FROM book_backup;');
-    db.execute('DROP TABLE book_backup;');
-};
-```
-
-## Backbone Objects without Alloy
-
-You can use plain Backbone Collection and Model objects in place of the Alloy versions. This does not require any special Alloy or Titanium code. Use the Backbone API to create and control Backbone objects instead of using the `createCollection` and `createModel` methods. Backbone models also do not require a model configuration file.
-
-**app/controllers/index.js**
-
-```javascript
-// Initialize a collection class and implement the comparator method for sorting
-const collection = Backbone.Collection.extend({
-  comparator(model) {
-    return model.get('title');
-  }
-});
-
-// Create a new collection
-const library = new collection([
-  {title: 'To Kill a Mockingbird', author:'Harper Lee'},
-  {title: 'The Catcher in the Rye', author:'J. D. Salinger'},
-  {title: 'Of Mice and Men', author:'John Steinbeck'},
-  {title: 'Lord of the Flies', author:'William Golding'},
-  {title: 'The Great Gatsby', author:'F. Scott Fitzgerald'},
-  {title: 'Tom Sawyer', author:'Mark Twain'},
-  {title: 'Animal Farm', author:'George Orwell'}
-]);
-
-// Initialize a model class
-const modelClass = Backbone.Model.extend();
-
-// Create a new model and add it to the collection
-const book = new modelClass({title:'Bossypants', author:'Tina Fey'});
-library.add(book);
-
-// Remove the very first model from the collection
-const model = library.at(0);
-library.remove(model);
-```
-
-These Backbone objects cannot persist to external storage without implementing the Backbone.sync method, so if you make calls to Collection.fetch, Collection.create, Model.fetch, Model.save and Model.destroy, the application throws an error.
-
-### Using Backbone Objects with Alloy Data Binding
-
-You can use Alloy's Model-View binding mechanism to keep the local Backbone Models and Collections in sync with an Alloy view-controller. Follow the same directions for data binding except instead of using the `Model` or `Collections` XML tag, you need to first initialize your model or collection in the alloy.js initializer file and add it to the `Alloy.Models` or `Alloy.Collections` namespace.
-
-**app/alloy.js**
-
-```javascript
-// Initialize a collection class and implement the comparator method for sorting
-const collection = Backbone.Collection.extend({
-  comparator(model) {
-    return model.get('title');
-  }
-});
-
-// Create a new collection
-const library = new collection([
-  {title: 'To Kill a Mockingbird', author:'Harper Lee'},
-  {title: 'The Catcher in the Rye', author:'J. D. Salinger'},
-  {title: 'Of Mice and Men', author:'John Steinbeck'},
-  {title: 'Lord of the Flies', author:'William Golding'},
-  {title: 'The Great Gatsby', author:'F. Scott Fitzgerald'},
-  {title: 'Tom Sawyer', author:'Mark Twain'},
-  {title: 'Animal Farm', author:'George Orwell'}
-]);
-
-// Add the collection to the global scope
-Alloy.Collections.book = library;
-```
-
-**app/views/index.xml**
-
-```xml
-<!-- Markup the view the same except there is no Collection tag -->
-<Alloy>
-    <Window class="container">
-        <TableView dataCollection="book" dataTransform="transformFunction" dataFilter="filterFunction">
-            <TableViewRow title="{title}" />
-        </TableView>
-    </Window>
-</Alloy>
-```
-
-**app/controllers/index.js**
-
-```javascript
-$.index.open();
-
-function transformFunction(model) {
-    const transform = model.toJSON();
-    transform.title = '[' + transform.title + ']';
-    transform.custom = transform.title + " by " + transform.author;
-    return transform;
-}
-
-function filterFunction(collection) {
-    return collection.where({author:'Mark Twain'});
-}
-
-// Get a reference to the library
-const library = Alloy.Collections.book;
-
-// Trigger the update using the 'change' event instead of the fetch method
-library.trigger('change');
-
-// Initialize a model class
-const modelClass = Backbone.Model.extend();
-
-// Create a new model and add it to the collection
-const book = new modelClass({title:'Bossypants', author:'Tina Fey'});
-library.add(book);
-
-// Remove the very first model from the collection
-const model = library.at(0);
-library.remove(model);
-
-// Do not forget to call destroy to unbind the event handlers created by Alloy
-$.index.addEventListener('close', () => {
-    $.destroy();
-});
-```
-
-## Alloy Backbone Migration
-
-### Overview
-
-Alloy 1.6.0 introduces support for Backbone 1.1.2. Currently, Alloy uses Backbone 0.9.2 to support its Model and Collection objects. This guide covers the changes from Backbone 0.9.2 to 1.1.2 and the modifications you may need to update your application. Note that only changes to the Backbone Collection, Event and Model APIs are discussed in this document.
-
-Due to breaking changes from Backbone 0.9.2 to 1.1.2, Alloy still uses Backbone 0.9.2 as its default Model and Collection implementation. You will need to update the configuration file to use the newer Backbone library.
-
-Alloy 1.10.12 adds support for Backbone 1.3.3. However, due to breaking changes in Backbone, 0.9.2 will remain the default version.
-
-Supported versions of Backbone for Alloy 1.10.12 are 0.9.2, 1.1.2, 1.3.3.
-
-### Setup
-
-To use Backbone 1.1.2 to support Alloy Model and Collections objects, open the project's `./app/config.json` file and add the `backbone` key to the to the file with the value set to `1.1.2` (or `1.3.3`). You may also set this value to `0.9.2` to force support of Backbone 0.9.2.
-
-**app/config.json**
-
-```json
-{
-    "global": {},
-    "env:development": {},
-    "env:test": {},
-    "env:production": {},
-    "os:android": {},
-    "os:blackberry": {},
-    "os:ios": {},
-    "os:mobileweb": {},
-    "dependencies": {},
-    "backbone": "1.1.2"
-}
-```
-
-### Summary of Changes
-
-#### Collection APIs
-
-**Fetch Method Behavior Change**: Backbone Collection objects no longer emit the `reset` event after a `fetch()` call, which means data-bound views may not update automatically. **This could break existing apps.** To use old functionality, pass `{reset: true}` when calling `fetch()` or extend the Collection class:
-
-```javascript
-exports.definition = {
-    config: {
-        // Model configuration
-    },
-    extendModel(Model) {
-        _.extend(Model.prototype, {
-            // extended functions and properties go here
-        });
-        return Model;
-    },
-    extendCollection(Collection) {
-        _.extend(Collection.prototype, {
-            // For Backbone v1.1.2, uncomment the following to override the
-            // fetch method to account for a breaking change in Backbone.
-            /*
-            fetch(options) {
-                options = options ? _.clone(options) : {};
-                options.reset = true;
-                return Backbone.Collection.prototype.fetch.call(this, options);
-            }
-            */
-        });
-        return Collection;
-    }
-};
-```
-
-**New Set Method**: To smartly update the contents of a Collection (adding new models, removing missing ones, and merging those already present), call `set()`.
-
-**Return Value for Methods**: The return values of Collection's `add()`, `push()`, `remove()`, `reset()` and `shift()` methods return the changed model or list of models, instead of `this`.
-
-**Add Method**: When invoking `add()` on a collection, passing `{merge: true}` will now cause duplicate models to have their attributes merged in to the existing models. To improve performance, `options.index` will no longer be set in the `add` event callback — use `collection.indexOf(model)` instead.
-
-#### Event APIs
-
-* All `invalid` events now pass consistent arguments. First the model in question, then the `error` object, then `options`.
-* `Collection.sort()` now triggers a `sort` event, instead of a `reset` event.
-* Both `sync` and `error` events within `Backbone.sync()` are now triggered regardless of the existence of success or error callbacks.
-* While listening to a `reset` event, the list of previous models is now available in `options.previousModels`.
-* The new Event methods `listenTo` and `stopListening` are meant for Backbone View objects. These APIs will not work with an Alloy application.
-
-#### Model APIs
-
-**Validation**: Model validation is now only enforced with the `save()` method. Previously, models were also validated with the `set()` method. To force validation when the `set()` method is called, pass `{validate: true}` to the method or extend the Model class. Also, validation now occurs even during 'silent' changes (passing `{silent: true}` to methods). Previously, it would not. Failed validations return the `invalid` event. Previously, a failed model validation would return the `error` event.
-
-> **⚠️ ⚠️ Warning**
-> To validate Model objects, implement the `validate()` method in the `extendModel` key of the model configuration file.
-
-**Parse Method**: All `parse` methods now run after a `fetch`. You cannot change the `id` of a model during `parse`. The `parse` method receives `options` as a second parameter.
-
-**Other Changes**:
-
-* Calling `destroy()` on a Model will now return `false` if the model's `isNew` is set to `true`.
-* `Model.set()` no longer accepts another model as an argument.
-* `url` and `urlRoot` properties may now be passed as options when instantiating a new Model.
-* If you want to maintain current models in a collection when using `fetch` the property has changed from `{add:true}` to `{remove:false}`.
-
-### Parse Method
-
-After fetching a model or a collection, all defined parse methods will now be run. So fetching a collection and getting back new models could cause both the collection to parse the list, and then each model to be parsed in turn, if you have both methods defined. By default, the parse method is a no-op function that directly passes the JSON response object.
-
-You are no longer permitted to change the `id` of your model during `parse()`. Use `idAttribute` instead.
-
-The parse function now receives the `options` dictionary as its second parameter. Previously, it would only be passed a raw `response` object.
-
-### Silent Option
-
-Passing `{silent:true}` to methods now suppresses the `change:attr` events, thus a data-bound view will not be updated to reflect the changes. The sql sync adapter passed this option by default. It has been updated to no longer pass that option when Backbone 1.1.2 is used (still passed with 0.9.2).
-
-If you want the new behavior where `change` events are suppressed, you will need to pass this option or extend the Model or Collection class. The following sample code extends the Model `set()` method by forcing the silent option to true:
-
-```javascript
-exports.definition = {
-    config: {
-        // Model configuration
-    },
-    extendModel(Model) {
-        _.extend(Model.prototype, {
-            // Forces silent true option when the model is updated
-            set(attributes, options) {
-                options = options ? _.clone(options) : {};
-                options.silent = true;
-                return Backbone.Model.prototype.set.call(this, attributes, options);
-            }
-        });
-        return Model;
-    },
-    extendCollection(Collection) {
-        _.extend(Collection.prototype, {
-            // extended functions and properties go here
-        });
-        return Collection;
-    }
-};
-```
-
-### API Changes
-
-#### New APIs
-
-The following APIs have been added between Backbone 1.1.2 and 0.9.2.
-
-| API                           | Type   | Notes                                                                    |
-| ----------------------------- | ------ | ------------------------------------------------------------------------ |
-| Backbone.request              | event  | Fired whenever a request begins to be made to the server.                |
-| Backbone.Collection.findWhere | method | Same as `where()` but only returns the first result.                     |
-| Backbone.Collection.set       | method | Performs a "smart" update of the collection.                             |
-| Backbone.Event.once           | method | Same as `on()` except after the event is fired, the callback is removed. |
-| Backbone.Model.invert         | method | Returns a copy of the object where keys and values are switched.         |
-| Backbone.Model.keys           | method | Returns an array of the object's keys.                                   |
-| Backbone.Model.omit           | method | Returns a copy of an object without the specified keys.                  |
-| Backbone.Model.pairs          | method | Returns an array of `[key, value]` pairs.                                |
-| Backbone.Model.pick           | method | Returns a copy of an object with the specified keys.                     |
-| Backbone.Model.values         | method | Returns an array of the object's property values.                        |
-
-#### Removed APIs
-
-The following APIs have been removed between Backbone 1.1.2 and 0.9.2.
-
-| API                          | Type   | Notes                                       |
-| ---------------------------- | ------ | ------------------------------------------- |
-| Backbone.Collection.getByCid | method | Pass the CID to the `get()` method instead. |
-| Backbone.Model.change        | method |                                             |