The Drawer widget provides a sliding panel of buttons to pull up from the bottom of the screen. As an option, the drawer can automatically close after it has been used. On Android, the drawer manifests itself as the activity menu, unless the developer wants to specifically override that capability.
"dependencies": {
"com.appcelerator.drawer":"1.0"
}
You can add a drawer to a view by requiring the Drawer widget.
<Require type="widget" src="com.appcelerator.drawer" id="drawer"/>
Assign it an ID that you can use in your controller. E.g. id="drawer" You can now access the drawer via $.drawer in your controller.
The drawer doesn’t have any buttons in it until you initialize it in your controller. Before you open your window, you will want to call the drawer with the init method. For example:
$.drawer.init({
mainWindow: $.index,
buttons: [
{ id: 'One', text: 'One', click: function (e) { alert("One"); } },
{ id: 'Two', text: 'Two', click: function (e) { alert("Two"); } },
{ id: 'Three', text: 'Three', click: function (e) { alert("Three"); } }
],
autoClose: true,
gutter: 5
});
| Parameter | Type | Description |
|---|---|---|
| mainWindow | TiUIWindow | You must supply a window for your drawer so that it can create menu items for the menu attached to the window’s activity on Android. Typically, you’ll pass in $.<yourwindowid> If you haven’t changed the main window id then the Alloy default will be $.index. |
| buttons | array | The buttons array is an array of button objects each of which describes a button to create in the drawer. |
| Parameter | Type | Description |
|---|---|---|
| id | string | Unique id for this item. This id also selects the image icons for this button. The drawer expects to find the image at app/assets/images/<id>Enabled.png and app/assets/images/<id>Disabled.png. Default icon size is 48x48 pixels. |
| title | string | The text that describes this button that will appear underneath the icon (Android activity menu version only). |
| click | function | Optional. The callback to call when the button is clicked. The function has an event parameter similar to that used for regular buttons. If you don’t specify a click callback then the button does nothing. |
| enabled | function | Optional. The callback to call to determine whether the button should be enabled. This callback should return true (enabled) or false (disabled). Default is for the buttons to always be enabled. |
There are number of aspects of the Drawer that you can change, you can include these in your parameters when you call the init method.
| Parameter | Type | Affects | Description |
|---|---|---|---|
| animationDuration | integer | iOS, MW | The duration, in milliseconds, of the animation to close/open the drawer. Default: 500 |
| autoClose | boolean | iOS, MW | If true, automatically closes the drawer after a button has been pressed. Default: false |
| closeOpacity | number | iOS, MW | A number between 0 (transparent) and 1 (opaque) that denotes the opacity of the drawer when it is closed. Default: 0.75 |
| gutter | integer | iOS, MW | The offset, in pixels, used to space buttons from each other in the drawer. Default: 0 |
| iconSize | integer | iOS, MW | Size of the icon, in pixels, to used on buttons in the drawer. Default: 48x48 |
| openOpacity | number | iOS, MW | A number between 0 (transparent) and 1 (opaque) that denotes the opacity of the drawer when it is open. Default: 0.9 |
| overrideMenu | boolean | Android | Override the use of the activity menu in Android and use a drawer like in iOS/MobileWeb. In this case, the above parameters do affect Android. Default: false |
With Android, if overrideMenu is not true, the enable() callback is called automatically before the menu is shown. In all other cases, you will need to explicitly call the drawer’s checkEnabled() method in order to get those callbacks to fire.
You should call this function whenever a state change could affect the enable state of buttons in the drawer. For example, if your main window displays a web view and you want to enable some forward/back buttons based on the properties of that web view after it has loaded, you might create the following callback attached to the onLoad event:
function webviewLoad(e) {
$.index.title = $.webview.evalJS("document.title");
$.drawer.checkEnabled();
};
Because you are passing in functions to be called when a button is clicked, be aware of your binding. The this object is not the same when the click() and enable() callbacks are called as when they are defined. There are many excellent articles that talk about this issue:
It’s recommended that you use the underscore library’s bind function to bind your callbacks when needed.
$.drawer.init({
buttons: [
{ id: 'Fancy', text: 'Fancy', click:
_.bind(function FancyClick(e) { alert(this.one); }, this)
}
]
});
There are lots of features that can be added to the Drawer: