Widgets
Widget is a UI element that is placed inside a widget container. Most widgets are backend actions.
Examples of widgets are: contact information, opportunity information, address book, add address form, import form, workflow transitions, etc.
Widget container is part of UI where widgets are shown. A Widget Container can show different types of widgets.
Examples of implemented BAP widget containers:
- Dialog windows
- Buttons
- Content blocks
Goals
Widgets are created to give developers the ability to use one content inside different containers on frontend.
HTML can be used as content (a fragment of a page or the whole page) generated separately by the method of a controller.
System may have different containers: dialog windows, blocks, etc. Also widgets provides additional functionality around widget content: remote content loading, widget actions handling, embedded forms processing. Widget manager adds the ability of widget-to-widget, widget-to-page and page-to-widget interaction based on Backbone events and direct usage of widgets API. Each widget on page has a unique widget identifier.
JS Modules Services
- oroui/js/widget-manager - Widget manager
- oro/block-widget - Block widget
- oro/buttons-widget - Buttons widget
- oro/dialog-widget - Dialog widget
- oroui/js/widget/abstract-widget - Abstract widget, cannot be used standalone
Widgets
Widget is any controller/action or static content rendered inside the widget container.
@Template annotation supports the \_widgetContainer
request variable, based on which an appropriate template is chosen by the following rule:
\<widgetContainer\>/\<action\>.\<format\>.\<templateEngine\> (dialog/example.html.twig)
.
When no template for a specific container is found, the widget/\<action\>.\<format\>.\<templateEngine\> (widget/example.html.twig)
template is rendered.
If no such template is found, then the default template for action is rendered (example.html.twig).
Widgets may be rendered with twig function oro_widget_render($options)
.
Frontend Widget Container
Responsibilities
A widget container is responsible for displaying a widget, and loading widget data from the server. Widget containers are Backbone views, so you can use all Backbone views features, like events. You need to place widget content inside element with class widget-content. Widget container adds AJAX handling for included form. A widget container provides the functionality for actions with different action areas. All form actions are moved to the adopted actions section if they are placed in an element with class widget-actions.
Widget container adds \_widgetContainer=\<widgetContainerType\>&\_wid=\<widgetIdentifier\>
to all requests.
- _widgetContainer variable is used to determine the proper template for the current container;
- _wid variable can be used by widget to get an instance of a widget container from the widget manager.
Containers
- Dialog window showns widget content in a dialog window
- Button shows only included content without a title or actions
- Block displays embedded widget content on a page
API
abstract-widget.js options
- type - widget type name
- el - widget element selector (inherit from Backbone.View options)
- actionsEl - selector or element from which widget actions will be adopted
- url - URL used to load remote content
- elementFirst - flag, if set and both element and url are given then on first load element content will be used to render widget without AJAX request
- title - widget title
- alias - widget alias
- wid - unique widget identifier
- loadingMaskEnabled - flag, indicated enabled state of loading mask
- loadingElement - element, hidden under loading mask. By default el is used. To hide the whole page, use the ‘body’ selector.
abstract-widget.js events
Widget container events:
- widgetRemove - triggered when widget is removed
- adoptedFormSubmitClick - triggered when adopted form submit button is clicked
- adoptedFormResetClick - triggered when adopted form reset button is clicked
- adoptedFormSubmit - triggered when adopted form is submitted
- reset - triggered when adopted form is reset
- beforeContentLoad - triggered before content loading started
- contentLoad - triggered on content load
- contentLoadError - triggered in case of content loading error
- widget:add:action:<section>:<action_key> - triggered when action is added, <section> is action section name passed to addAction method, <action_key> is action name passed to addAction method
- renderStart - triggered before widget rendering
- widgetRender - triggered on widget rendering
- renderComplete - triggered on widget rendering complete
Global events triggered on mediator:
- widget_remove - triggered on mediator when widget is removed
- widget_initialize - triggered on mediator when widget is created
- widget:render:<wid> - triggered on widget render
- <wid> is widget identifier string
abstract-widget.js Methods
addAction(key, section, actionElement)
Add action element to specified section
Parameters:
Name | Type | Description |
---|---|---|
key | string | action name |
section | string | section name |
actionElement | HTMLElement |
getAction(key, section, callback)
Get action element when after render.
Parameters:
Name | Type” | Description |
---|---|---|
key | string | action name |
section | string | section name |
callback | function | callback method for processing action element |
getActions() → {Object}
Get all registered actions
Returns: Type: Object
getActionsElement()
Get actions container element
getAlias() → {string|null}
Get widget alias
Returns: Type: string or null
getWid() → {string}
Get unique widget identifier
Returns: Type: string
hasAction(key, section) → {boolean}
Check action availability.
Parameters:
Name | Type | Description |
---|---|---|
key | string | action name |
section | string | section name |
Returns: Type: boolean
initializeWidget()
Initialize
loadContent(data, method)
Load content
Parameters:
Name | Type | Description |
---|---|---|
data | Object or null | |
method | String or null |
remove()
Remove widget
removeAction(key, section)
Remove action from section
Parameters:
Name | Type | Description |
---|---|---|
key | string | action name |
section | string | section name |
render()
Render widget
setTitle(title)
Set widget title.
Parameters:
Name | Type | Description |
---|---|---|
title | string |
setUrl(url)
Set url
Parameters:
Name | Type | Description |
---|---|---|
url | string |
setWidToElement(el)
Add data-wid attribute to the given element.
Parameters:
Name | Type | Description |
---|---|---|
el | HTMLElement |
show()
General implementation of show logic.
block-widget.js options
- titleContainer - selector for title container inside template
- contentContainer - selector for content container inside template
- contentClasses - additional CSS classes added to content element
- template - widget underscore template
dialog-widget.js options
- dialogOptions - Extended ui.dialog options
- stateEnabled - flag, enables window state saving, enabled by default
- incrementalPosition - flag, enables window incremental positioning, enabled by default
- mobileLoadingBar: flag, enables loading bar for dialog on mobile devices, enabled by default
- desktopLoadingBar: flag, enables loading bar for dialog on desktop, disabled by default
Frontend Widget Manager
Responsibilities
Widget manager is a mediator that allow different parts of system, including widgets them self, interact with widget container instances by unique widget identifier or by widget alias. Widget manager contains registry of all widget container instances present on page. Widget instance registering/removing performed automatically on widget_initialize/widget_remove events.
Interaction Example
Let’s assume that a widget needs to trigger a formSave event when a form is successfully saved.
Page content
<div id="poll-widget" {{ UI.renderPageComponentAttributes({
'module': 'your/widget/creator'
})></div>
Create a js module that creates widget 'your/widget/creator'
as shown in the example below; please remember to add this module to the list of dynamic-imports
in jsmodules.yml
.
import widgetManager from 'oroui/js/widget-manager';
import BlockWidget from 'oro/block-widget';
export default function(options) {
var widgetInstance = new BlockWidget({
el: '#poll-widget',
url: '/my-poll-widget',
title: 'Satisfaction survey'
});
addWidgetInstance.render();
widgetInstance.on('formSave', function() {
alert('Form saved');
});
}
Widget content
<div class="widget-content">
<form action="/my-poll-widget" method="post">
<label for="variant">Are you satisfied</label>
<select name="variant" id="variant">
<option value="yes">Yes</option>
<option value="no">No</option>
</select>
<div class="widget-actions">
<button type="submit">Vote</button>
</div>
</form>
{% if isSaved %}
<div {{ UI.renderPageComponentAttributes({
'module': 'your/widget/handler',
'options': {wid: app.request.get('_wid')}
})></div>
{% endif %}
</div>
Create a js module with the handler definition 'your/widget/handler'
as shown in the example below; please remember to add this module to the list of 1`dynamic-imports1` in 1jsmodules.yml1.
import widgetManager from 'oroui/js/widget-manager';
export default function(options) {
widgetManager.getWidgetInstance(options.wid, widget => {
widget.trigger('formSave');
});
}
API
widget-manager.js Events
Global events triggered on mediator:
- widget_registration:wid:<wid> - triggered when widget instance added <wid> is widget identifier string
widget-manager.js Methods
- resetWidgets() - Reset manager to initial state.
- addWidgetInstance(widget) - Add widget instance to registry.
Parameters:
Name | Type | Description |
---|---|---|
widget | oroui.widget.AbstractWidget | widget instance |
- getWidgetInstance(wid, callback) - Get widget instance by widget identifier and pass it to callback when became available.
Parameters:
Name | Type | Description |
---|---|---|
wid | string | unique widget identifier |
callback | function | widget handler |
- getWidgetInstanceByAlias(alias, callback) - Get widget instance by alias and pass it to callback when became available.
Parameters:
Name | Type | Description |
---|---|---|
alias | string | widget alias |
callback | function | widget handler |
- removeWidget(wid) - Remove widget instance from registry.
Parameters:
Name | Type | Description |
---|---|---|
wid | string | unique widget identifier |
Backend
Widget Context Provider
Widget Context Provider provides the possibility to know the current context of the application during rendering. It enables you to customize the application based on the current context. It is registered as DI service named oro_ui.provider.widget_context1. You can inject it as a global variable for twig templates.
API
isActive
Returns whether current widget context is in active state.
getWid
Returns unique widget identifier if widget context is active or FALSE otherwise.