@maccesar/titools 2.0.0

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

@@ -0,0 +1,109 @@
+# Views without Controllers
+
+## Table of Contents
+
+- [Views without Controllers](#views-without-controllers)
+  - [Table of Contents](#table-of-contents)
+  - [Introduction](#introduction)
+  - [XML Markup](#xml-markup)
+  - [Controller Code](#controller-code)
+
+## Introduction
+
+Views can be created without controllers with an optional style sheet. These views can be used as building blocks to create a GUI. After you have defined your controller-less views, the application can either require in these views using markup or can dynamically generate these views in the controller code.
+
+## XML Markup
+
+In XML markup, use the `Require` tag to add controller-less views into another view. Assign the `src` attribute to the name of the view file minus the `.xml` extension and the `type` to `view`. Define the `id` attribute to access each instance of the controller-less view in the controller.
+
+For instance, a button view could be reused repeatedly in a view-controller to construct a dialog box:
+
+**app/views/foo.xml**
+
+```xml
+<Alloy>
+    <Button id='fooButton'>I am a foo button!</Button>
+</Alloy>
+```
+
+This view can be inserted into another view multiple times:
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window layout="vertical">
+        <Require id="button1" src="foo" type="view"/>
+        <Require id="button2" src="foo" type="view"/>
+        <Require id="button3" src="foo" type="view"/>
+    </Window>
+</Alloy>
+```
+
+Then, the controller can use `$.button1`, `$.button2` and `$.button3` to access each instance of the foo view.
+
+## Controller Code
+
+**Starting with Alloy 1.4.0**, you can dynamically create views in the controller code. Each component in the controller-less view needs to be assigned an `id` attribute.
+
+**To create a view without a corresponding controller:**
+
+1. Use the `Alloy.createController()` method to create a controller from the controller-less view.
+2. Use the `updateViews()` method with the created controller. Pass a style dictionary with the `id` of each component as the key and attributes as values.
+3. Use the `getView()` method to retrieve the view.
+4. Use the `add()` method to add the view to a parent component.
+
+::: warning ⚠️ Warning
+Unlike other style dictionaries in Alloy, when using the `updateViews()` method, you can only apply styles using IDs. Class and view component styles do not work with this method.
+:::
+
+For example:
+
+**app/views/profile.xml**
+
+```xml
+<Alloy>
+    <View id="container">
+        <ImageView id="picture"/>
+        <Label id="name"/>
+    </View>
+</Alloy>
+```
+
+**app/controllers/index.js**
+
+```javascript
+const profile = Alloy.createController('profile');
+profile.updateViews({
+  "#container" : {
+        layout : "vertical"
+  },
+  "#picture" : {
+        image : "/appicon.png"
+  },
+  "#name" : {
+        text : "Mr. Man"
+  }
+});
+$.index.add(profile.getView());
+
+$.index.open();
+```
+
+**Prior to Alloy 1.4.0**, to dynamically generate a view:
+
+1. Create a new instance of the controller using `Alloy.createController()`.
+2. Modify the properties directly.
+3. Use `getView()` to retrieve the view.
+4. Use `add()` to add it to a parent.
+
+**app/controllers/index.js** (Alloy < 1.4.0)
+
+```javascript
+const profile = Alloy.createController('profile');
+profile.container.layout = 'vertical';
+profile.picture.image = '/appicon.png';
+profile.name.text = 'Mr. Man';
+$.index.add(profile.getView());
+$.index.open();
+```

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

@@ -0,0 +1,558 @@
+# Alloy XML Markup
+
+## Table of Contents
+
+- [Alloy XML Markup](#alloy-xml-markup)
+  - [Table of Contents](#table-of-contents)
+  - [Introduction](#introduction)
+  - [Collection Element](#collection-element)
+    - [Creating a Singleton](#creating-a-singleton)
+    - [Creating an Instance](#creating-an-instance)
+  - [Model Element](#model-element)
+    - [Creating a Singleton](#creating-a-singleton-1)
+    - [Creating an Instance](#creating-an-instance-1)
+  - [Module Attribute](#module-attribute)
+  - [Module Element](#module-element)
+  - [Require Element](#require-element)
+    - [Including Views](#including-views)
+    - [Importing Widgets](#importing-widgets)
+    - [Passing Arguments](#passing-arguments)
+    - [Binding Events](#binding-events)
+    - [Adding Children Views](#adding-children-views)
+  - [Namespace](#namespace)
+  - [Conditional Code](#conditional-code)
+  - [Property Mapping](#property-mapping)
+    - [Proxy Properties](#proxy-properties)
+    - [Android ActionBar](#android-actionbar)
+    - [iOS Navigation Button Shorthand](#ios-navigation-button-shorthand)
+    - [iOS SystemButton Shorthand](#ios-systembutton-shorthand)
+    - [TextField Keyboard Shorthands](#textfield-keyboard-shorthands)
+  - [Event Handling](#event-handling)
+  - [Data Binding](#data-binding)
+  - [Non-Standard Syntax](#non-standard-syntax)
+
+## Introduction
+
+In Alloy, the XML markup abstracts the Titanium SDK UI components, so you do not need to code the creation and setup of these components using JavaScript and the Titanium SDK API. All view files must be placed in the `app/views` folder of your project with the `.xml` file extension.
+
+The following code is an example of a view file:
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window class="container">
+        <Label id="label" onClick="doClick">Hello, World</Label>
+    </Window>
+</Alloy>
+```
+
+The `Alloy` tag is the root element for the XML markup and is required in all views. The Window element defines an instance of the `Ti.UI.Window` object and within that window instance is the `Label` element which defines an instance of a `Ti.UI.Label` object. Almost all of the Alloy XML tags are the class names of the Titanium UI components without the preceding namespace.
+
+Within a controller, a UI component can be referenced if its ID attribute is defined. For instance, the Label component in the above example has its ID defined as `label` and can be referenced in the controller using `$.label`.
+
+If the top-level UI component does not have an ID defined, it can be referenced using the name of the view-controller prefixed with a dollar sign and period (`$.`). For instance, the Window element in the above example can be referenced in the controller using `$.index`.
+
+The following table lists the attributes for the UI components:
+
+| Attribute      | Description                                                                                        |
+| -------------- | -------------------------------------------------------------------------------------------------- |
+| `id`           | Identifies UI elements in the controller (prefixed with `$.`) and style sheet (prefixed with `#`). |
+| `class`        | Applies additional styles (prefixed with `.` in the TSS file).                                     |
+| `autoStyle`    | Enables the autostyle feature for dynamic styling.                                                 |
+| `formFactor`   | Acts as a compiler directive for size-specific view components (`handheld` or `tablet`).           |
+| `if`           | Use a custom query to apply additional styles to the element.                                      |
+| `module`       | Requires in a CommonJS module.                                                                     |
+| `ns`           | Overrides the default `Titanium.UI` namespace.                                                     |
+| `platform`     | Switches the namespace based on the platform.                                                      |
+| `<properties>` | Assigns values to UI object properties.                                                            |
+| `<events>`     | Assigns callbacks to UI object events.                                                             |
+
+The following table lists the special XML elements besides the Titanium UI components:
+
+| Element      | Description                                                 |
+| ------------ | ----------------------------------------------------------- |
+| `Alloy`      | Root element for all view XML files. Required in all views. |
+| `Collection` | Creates a singleton or instance of a collection.            |
+| `Model`      | Creates a singleton or instance of a model.                 |
+| `Module`     | Imports a module view inside this view.                     |
+| `Require`    | Imports a widget or includes another view inside this view. |
+| `Widget`     | Imports a widget inside this view.                          |
+
+`index.xml` is a special case that only accepts the following view components as direct children of the Alloy tag:
+
+* `Ti.UI.Window` or `<Window>`
+* `Ti.UI.TabGroup` or `<TabGroup>`
+* `Ti.UI.NavigationWindow` or `<NavigationWindow>`
+* `Ti.UI.iOS.SplitWindow` or `<SplitWindow>`
+
+::: warning
+With the release of CLI 7.1.0, you can use platform as a prefix in the XML. For example: `<Label ios:text="Hello iOS!" android:text="Hello Android!" />`
+:::
+
+## Collection Element
+
+The `Collection` XML element creates a singleton or instance of a collection. The `Collection` tag needs to be a child of the `Alloy` parent tag.
+
+### Creating a Singleton
+
+```xml
+<Alloy>
+    <Collection src="book" />
+    <Window>
+        <TableView id="table" />
+    </Window>
+</Alloy>
+```
+
+```javascript
+const library = Alloy.Collections.book;
+library.fetch();
+```
+
+### Creating an Instance
+
+```xml
+<Alloy>
+    <Collection id="localLibrary" src="book" instance="true"/>
+    <Window>
+        <TableView id="table" />
+    </Window>
+</Alloy>
+```
+
+```javascript
+const library = $.localLibrary;
+library.fetch();
+```
+
+## Model Element
+
+The `Model` XML element creates a singleton or instance of a model. The `Model` tag needs to be a child of the `Alloy` parent tag.
+
+### Creating a Singleton
+
+```xml
+<Alloy>
+    <Model src="book" />
+    <Window>
+        <TableView id="table" />
+    </Window>
+</Alloy>
+```
+
+```javascript
+const drama = Alloy.Models.book;
+drama.set('title', 'Hamlet');
+drama.set('author', 'William Shakespeare');
+```
+
+### Creating an Instance
+
+```xml
+<Alloy>
+    <Model id="myBook" src="book" instance="true"/>
+    <Window>
+        <TableView id="table" />
+    </Window>
+</Alloy>
+```
+
+```javascript
+const drama = $.myBook;
+drama.set('title', 'Hamlet');
+drama.set('author', 'William Shakespeare');
+```
+
+## Module Attribute
+
+You can require a CommonJS module in an Alloy view using the `module` attribute of an XML element.
+
+**app/lib/foo.js**
+
+```javascript
+exports.createFoo = args => {
+    const viewArgs = {
+        backgroundColor: args.color || 'white',
+        width: 100,
+        height: 100
+    };
+    const view = Ti.UI.createView(viewArgs);
+    const labelArgs = {
+        color: args.textColor || 'black',
+        text: args.text || 'Foobar'
+    };
+    const label = Ti.UI.createLabel(labelArgs);
+    view.add(label);
+    return view;
+};
+```
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window backgroundColor="white">
+        <Foo module="foo" color="blue" textColor="orange" text="Hello, World!"/>
+    </Window>
+</Alloy>
+```
+
+## Module Element
+
+You can also include a view from a native module using the `Module` XML element.
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+  <Window>
+    <Module id="paint" module="ti.paint" method="createPaintView" eraseMode="false" strokeWidth="1.0" strokeColor="red" strokeAlpha="100" />
+    <Button onClick="eraseMe" bottom="0">Erase</Button>
+  </Window>
+</Alloy>
+```
+
+**app/controllers/index.js**
+
+```javascript
+function eraseMe() {
+  $.paint.clear();
+}
+
+$.index.open();
+```
+
+## Require Element
+
+The `Require` XML element has two uses: including external views and importing widgets into the current view.
+
+### Including Views
+
+Views may be included in other views using the `Require` element. Specify the `type` attribute as `view` and the `src` attribute should be the view file minus the `.xml` extension.
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <TabGroup>
+        <Tab id="leftTab">
+            <Require type="view" src="rss" id="rssTab"/>
+        </Tab>
+        <Tab id="rightTab">
+            <Require type="view" src="about" id="aboutTab"/>
+        </Tab>
+    </TabGroup>
+</Alloy>
+```
+
+To use UI objects from the included views:
+
+```javascript
+const aboutView = $.aboutTab.getView('aboutView');
+aboutView.url = 'http://www.google.com';
+```
+
+### Importing Widgets
+
+Within a view in the regular Alloy project space (`app/views`), use the `<Widget>` tag to import the widget into the application.
+
+**To import a widget:**
+
+1. Copy the widget to the `app/widgets` folder.
+2. Add the `<Widget>` tag in the XML and specify its `src` attribute as the folder name of the widget.
+3. Update the `dependencies` object in the `config.json` file.
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window>
+        <Widget src="mywidget" id="foo" name="foo" />
+    </Window>
+</Alloy>
+```
+
+**app/controllers/index.js**
+
+```javascript
+$.index.open();
+$.foo.myMethod();
+```
+
+### Passing Arguments
+
+You can add any custom attributes to the markup to initialize a widget or controller.
+
+**apps/views/index.xml**
+
+```xml
+<Require id="foobar" src="foo" customTitle="Hello" customImage="hello.png"/>
+```
+
+This is equivalent to:
+
+**apps/controllers/index.js**
+
+```javascript
+const foobar = Alloy.createController('foo', {
+    id: 'foobar',
+    customTitle: 'Hello',
+    customImage: 'images/hello.png'
+});
+```
+
+In the required view's controller:
+
+**apps/controllers/foo.js**
+
+```javascript
+const title = $.args.customTitle || 'Foobar';
+const image = $.args.customImage || 'default.png';
+```
+
+### Binding Events
+
+To bind a callback to an event in a required view using the `on` attribute:
+
+Parent View:
+
+```xml
+<Require id="fooButton" src="button" onClick="doClick" />
+```
+
+Button View:
+
+```xml
+<Alloy>
+    <Button id="button">Click Me!</Button>
+</Alloy>
+```
+
+In the controller of the required view:
+
+```
+$.button.addEventListener('click', e => {
+    $.trigger('click', e);
+});
+```
+
+### Adding Children Views
+
+If your Require element is a parent view, you can add children elements to it. These children elements are passed to the parent controller as an array called `$.args.children`.
+
+**app/views/info.xml**
+
+```xml
+<Alloy>
+    <View backgroundColor="yellow" borderWidth="0.5" borderColor="brown"/>
+</Alloy>
+```
+
+**controllers/info.js**
+
+```javascript
+_.each($.args.children || [], child => {
+    $.info.add(child);
+});
+
+$.info.height = Ti.UI.SIZE;
+```
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window class="container">
+        <Require src="info">
+            <Label>I am an info box.</Label>
+        </Require>
+    </Window>
+</Alloy>
+```
+
+## Namespace
+
+By default, all UI components specified in the views are prefixed with `Titanium.UI` for convenience. However, to use a component not part of the `Titanium.UI` namespace, use the `ns` attribute.
+
+```xml
+<BlurView ns="Ti.UI.iOS" id="blurView"/>
+```
+
+For UI objects that belong to a specific platform, use the `platform` attribute:
+
+```xml
+<SplitWindow platform="ios"/>
+```
+
+Many of the Titanium view proxies not part of the `Titanium.UI` namespace do not require that the `ns` attribute be explicitly set. The following elements are implicitly mapped to a namespace:
+
+| Element          | Namespace     |
+| ---------------- | ------------- |
+| Menu             | Ti.Android    |
+| MenuItem         | Ti.Android    |
+| Annotation       | Ti.Map        |
+| VideoPlayer      | Ti.Media      |
+| MusicPlayer      | Ti.Media      |
+| SearchView       | Ti.UI.Android |
+| AdView           | Ti.UI.iOS     |
+| CoverFlowView    | Ti.UI.iOS     |
+| NavigationWindow | Ti.UI         |
+| TabbedBar        | Ti.UI.iOS     |
+| DocumentViewer   | Ti.UI.iOS     |
+| Popover          | Ti.UI.iPad    |
+| SplitWindow      | Ti.UI.iOS     |
+| StatusBar        | Ti.UI.iOS     |
+
+## Conditional Code
+
+Add the `platform`, `formFactor` and `if` attributes to apply XML elements based on conditionals.
+
+* `platform`: Assign it a platform, such as, `android` or `ios`. Comma separate values to OR them. Prepend with `!` to negate.
+* `formFactor`: Assign it a device size–either `handheld` or `tablet`.
+* `if`: Assign it to a conditional statement in the `Alloy.Globals` namespace or `$.args` namespace.
+
+```xml
+<Alloy>
+    <Window>
+        <Module id="mapview" module="ti.map" method="createView">
+            <Annotation title="Cupertino" platform='ios' formFactor='tablet' latitude='37.3231' longitude='-122.0311'/>
+            <Annotation title="Redwood City" platform='ios' formFactor='handheld' latitude='37.4853' longitude='-122.2353'/>
+            <Annotation title="Mountain View" platform='android' latitude='37.3861' longitude='-122.0828'/>
+            <Annotation title="Palo Alto" platform='android,ios,mobileweb' latitude='37.4419' longitude='-122.1419'/>
+            <Annotation title="San Francisco" platform='mobileweb' latitude='37.7750' longitude='-122.4183'/>
+        </Module>
+    </Window>
+</Alloy>
+```
+
+## Property Mapping
+
+Each Titanium UI object property is defined as an attribute in the XML and TSS file if it accepts a string, boolean, number or Titanium SDK constant.
+
+```xml
+<Label borderWidth="1" borderColor="red" color="red" width="Ti.UI.FILL">Hello, World!</Label>
+```
+
+### Proxy Properties
+
+For properties that are assigned Titanium proxies, such as Views or Buttons, these properties can be declared. Create a child tag under the Titanium UI object tag, using the name of the property with the first character capitalized. Then, declare your Titanium proxy inline with the child property tag.
+
+```xml
+<Alloy>
+    <Window>
+        <RightNavButton>
+            <Button title="Back" onClick="closeWindow" />
+        </RightNavButton>
+    </Window>
+</Alloy>
+```
+
+Currently, the following Titanium proxies and properties implemented using this syntax are:
+
+| Titanium Proxy Object / Alloy tag             | Proxy Property                                                                 | Child Alloy Tag                                                                                   | Since                                   |
+| --------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Ti.Android.MenuItem / `<MenuItem>`            | actionView                                                                     | `<ActionView>`                                                                                    | Alloy 1.6.0                             |
+| Ti.UI.iPad.Popover / `<PopOver>`              | contentView                                                                    | `<ContentView>`                                                                                   | Alloy 1.4.0                             |
+| Ti.UI.Label / `<Label>`                       | attributedString                                                               | `<AttributedString>`                                                                              | Alloy 1.7.6                             |
+| Ti.UI.ListSection / `<ListSection>`           | footerView, headerView                                                         | `<FooterView>`, `<HeaderView>`                                                                    | Alloy 1.3.0                             |
+| Ti.UI.ListView / `<ListView>`                 | footerView, headerView, pullView, searchView                                   | `<FooterView>`, `<HeaderView>`, `<PullView>`, `<SearchBar>` or `<SearchView platform="android">`  | Alloy 1.3.0                             |
+| Ti.UI.OptionDialog / `<OptionDialog>`         | androidView                                                                    | `<AndroidView>` or `<View>`                                                                       | Alloy 1.5.0                             |
+| Ti.UI.TableView / `<TableView>`               | footerView, headerPullView, headerView, search                                 | `<FooterView>`, `<HeaderPullView>`, `<HeaderView>`, `<Search>`                                    | Alloy 1.1.0                             |
+| Ti.UI.TableViewSection / `<TableViewSection>` | headerView                                                                     | `<HeaderView>`                                                                                    | -                                       |
+| Ti.UI.TextArea / `<TextArea>`                 | attributedString, keyboardToolbar                                              | `<AttributedString>`, `<KeyboardToolbar>`                                                         | Alloy 1.7.6, 1.5.0                      |
+| Ti.UI.TextField / `<TextField>`               | attributedHintText, attributedString, keyboardToolbar, leftButton, rightButton | `<AttributeHintText>`, `<AttributedString>`, `<KeyboardToolbar>`, `<LeftButton>`, `<RightButton>` | Alloy 1.7.6, 1.7.6, 1.3.0, 1.3.0, 1.3.0 |
+| Ti.UI.Window / `<Window>`                     | leftNavButton, rightNavButton, titleControl, toolbar                           | `<LeftNavButton>`, `<RightNavButton>`, `<TitleControl>`, `<WindowToolbar>`                        | Alloy 1.6.0                             |
+
+### Android ActionBar
+
+You can set ActionBar properties in the `ActionBar` element.
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <Window title="My App">
+        <ActionBar id="actionbar" platform="android" title="Home Screen" onHomeIconItemSelected="showInfo" />
+        <Menu>
+            <MenuItem id="editItem" title="Edit" onClick="editInfo" />
+            <MenuItem id="viewItem" title="View" onClick="viewInfo" />
+        </Menu>
+        <Label id="label">Use the ActionBar to Perform an Action.</Label>
+    </Window>
+</Alloy>
+```
+
+### iOS Navigation Button Shorthand
+
+When specifying either the `LeftNavButton` or `RightNavButton` element, you can define the `Button` attributes directly.
+
+**app/views/index.xml**
+
+```xml
+<Alloy>
+    <NavigationWindow>
+        <Window>
+            <LeftNavButton title="Back" onClick="goBack" />
+            <Label>I am iOS!</Label>
+        </Window>
+    </NavigationWindow>
+</Alloy>
+```
+
+### iOS SystemButton Shorthand
+
+When specifying the `systemButton` attribute, you do not need to use the `Ti.UI.iOS.SystemButton` namespace.
+
+```xml
+<Button systemButton="CAMERA"/>
+<!-- Instead of -->
+<Button systemButton="Titanium.UI.iOS.SystemButton.CAMERA"/>
+```
+
+### TextField Keyboard Shorthands
+
+When specifying the `keyboardType` or `returnKeyType` for a TextField:
+
+```xml
+<TextField id="txt" keyboardType="DECIMAL_PAD" returnKeyType="DONE"/>
+
+"#txt": {
+  keyboardType: "DECIMAL_PAD",
+  returnKeyType: "DONE"
+}
+```
+
+## Event Handling
+
+In Alloy, events may be added in the views using a special attribute. Capitalize the first character of the event name and prefix it with `on`, so the `Ti.UI.Button` object events `click`, `dblclick` and `swipe` events will become the attributes: `onClick`, `onDblclick`, and `onSwipe`, respectively.
+
+```xml
+<Alloy>
+    <Window>
+        <Button id="confirmButton" onClick="confirmCB">OK</Button>
+    </Window>
+</Alloy>
+```
+
+## Data Binding
+
+If you have a collection of model data that needs to be automatically updated to a view as it changes, you need to use data binding techniques. See [Alloy Data Binding](./MODELS.md#alloy-data-binding) for more details.
+
+## Non-Standard Syntax
+
+Some Titanium view elements use special syntax. Refer to the **Alloy XML Markup** examples in the Titanium API Guides site for the following view objects:
+
+* [AlertDialog](https://titaniumsdk.com/api/titanium/ui/alertdialog.html)
+* [ButtonBar](https://titaniumsdk.com/api/titanium/ui/buttonbar.html)
+* [CoverFlowView](https://titaniumsdk.com/api/titanium/ui/ios/coverflowview.html)
+* [DashboardView](https://titaniumsdk.com/api/titanium/ui/dashboardview.html)
+* [ListView](https://titaniumsdk.com/api/titanium/ui/listview.html)
+* [Map](https://titaniumsdk.com/api/modules/map.html)
+* [Menu](https://titaniumsdk.com/api/titanium/android/menu.html)
+* [OptionBar](https://titaniumsdk.com/api/titanium/ui/optionbar.html)
+* [OptionDialog](https://titaniumsdk.com/api/titanium/ui/optiondialog.html)
+* [Picker](https://titaniumsdk.com/api/titanium/ui/picker.html)
+* [SplitWindow](https://titaniumsdk.com/api/titanium/ui/ios/splitwindow.html)
+* [TabbedBar](https://titaniumsdk.com/api/titanium/ui/ios/tabbedbar.html)
+* [Toolbar](https://titaniumsdk.com/api/titanium/ui/toolbar.html)