To create a widget, you should pass a specification object with its desired properties. This document details the available properties.
Properties
| Property | Description |
| id | the ID of the widget (required). |
| type | a string indicating the type of widget. Possible types are
|
| viewId | Only useful for views (and required there): the id of the that should be shown when clicking the widget. |
| tooltiptext | string to use for the tooltip of the widget |
| label | string to use for the label of the widget |
| removable | whether the widget is removable (optional, default: true).NB: if you specify false here, you must provide a defaultArea, too. |
| overflows | whether widget can overflow when in an overflowable toolbar (optional, default: true) |
| defaultArea | default area to add the widget to (optional, default: none; required if non-removable) |
| shortcutId | id of an element that has a shortcut for this widget (optional, default: null). This is only used to display the shortcut as part of the tooltip for builtin widgets (which have strings inside customizableWidgets.properties). If you're in an add-on, you should not set this property, and should instead include the shortcut as part of the tooltiptext you pass in yourself. |
| showInPrivateBrowsing | whether to show the widget in private browsing mode (optional, default: true) |
Event handlers
You can also define several event handlers which will be called at various stages in a widget's lifetime:
| Event handler name | Description |
| onBuild(aDoc) | Only useful for custom widgets (and required there); a function that will be invoked with the document in which to build a widget. Should return the DOM node that has been constructed. NB: the DOM node you construct should have the same ID as the id property described above, so that CustomizableUI can find the node again later. |
| onBeforeCreated(aDoc) | Attached to all non-custom widgets; a function that will be invoked before the widget gets a DOM node constructed, passing the document in which that will happen. This is useful especially for 'view' type widgets that need to construct their views on the fly (e.g. from bootstrapped add-ons). |
| onCreated(aNode) | Attached to all widgets; a function that will be invoked whenever the widget has a DOM node constructed, passing the constructed node as an argument. |
| onDestroyed(aDoc) Firefox 46 | Attached to all non-custom widgets; a function that will be invoked after the widget has a DOM node destroyed, passing the document from which it was removed. This is useful especially for 'view' type widgets that need to cleanup after views that were constructed on the fly. |
| onCommand(aEvt) | Only useful for button widgets; a function that will be invoked when the user activates the button. |
| onClick(aEvt) | Attached to all widgets; a function that will be invoked when the user clicks the widget. |
| onViewShowing(aEvt) | Only useful for views; a function that will be invoked when a user shows your view. |
| onViewHiding(aEvt) | Only useful for views; a function that will be invoked when a user hides your view. |
Document Tags and Contributors
Contributors to this page:
kmaglione,
GijsKruitbosch
Last updated by:
kmaglione,