Widgets are self-contained components that can be easily dropped into an Alloy project. They were conceived as a way to reuse code in multiple projects or to be used multiple times in the same project.

Note that to use the methods list below, the correct namespace is Widget.create* not Alloy.Widget.create*.

For more information on widgets, see Alloy Widgets.

Creating a Widget

Widgets are essentially miniature Alloy projects that contain their own models, views, controllers and assets. They are laid out the same way as an Alloy project.

Use Widget.createController(), Widget.createWidget(), Widget.createModel() and Widget.createCollection() rather than the Alloy.create* methods to create components relative to the widget context rather than the Alloy project.

Using a Widget

To import a widget in to a project:

1. Copy the widget to the app/widgets folder. The widget must be contained within its own folder.
2. Update the dependencies object in the config.json file by adding a key/value pair with the name of the widget as the key and the version number as the value.

3. Add the widget to a view or create an instance of the widget in a controller:

   • To add a widget to a view, add the tag in the XML markup and set the src attribute to the folder name of the widget.
   • To create an instance of a widget in a controller, use the Alloy.createController method.

You can optionally add the id and name attributes to the Widget element:

• The id attribute allows you to reference the widget in the controller code. You can use this reference to call methods exported by the widget.
• The name attribute allows you to import a specific view-controller in the widget rather than the default one (widget.xml/widget.js). Specify the name of the view-controller minus the extension.

For example, to import a widget called mywidget in to a project, copy mywidget to the app/widgets folder, where its assets, controllers, views, etc. are contained in the app/widgets/mywidget folder.

app
└── config.json
└── controllers
│   └── index.js
└── views
│   └── index.xml
└── widgets
    └── mywidget
        └── controllers
        │   └── foo.js
        │   └── widget.js
        └── views
        │   └── foo.xml
        │   └── widget.xml
        └── widget.json

Next, add it as a dependency in your config.json file:

...
"dependencies":{
    "mywidget":"1.0"
}

Finally, either add the widget in the XML markup of the view or create an instance of the widget in the controller.

To add the widget in the view, use the Widget tag, specifying the src attribute as the name of the widget:

<Alloy>
    <Window id="win">
        <Widget id="myWidget" src="mywidget" />
    </Window>
</Alloy>

Since the id attribute is defined, the widget can be referenced in the controller using $.myWidget.

To add the widget in the controller, use the Alloy.createWidget method. The first required parameter is the name of the widget. The second optional parameter can specify the view component to instantiate and the last optional parameter can specify the arguments to instantiate the widget. For example, the following controller code is equivalent to the previous view markup example.

var myWidget = Alloy.createWidget("mywidget");
win.add(myWidget.getView());

A widget can also be added to other widgets. Follow the same procedure as above except the widget configuration file is called widget.json instead of config.json.