Widgets¶
A widget is a relatively simple and intuitive web UI component within Virto Commerce Platform. It is basically a transient or auxiliary tile, which:
- Occupies just a fraction of a blade
- Provides useful information
- Usually enables opening another blade with extra information and functions
- Is reusable and can be added to as many blades (widget containers) as you want
A widget container is a placeholder control for widgets, which:
- Displays widgets in a rectangular area
- Accepts options like size, widget column and row count, etc.
- Allows the user to manage widget position within designated area
A widget service is a platform level engine for registering widgets and distributing them to the appropriate widget containers.
Here is how we use widgets out of the box in our Catalog module:
Widget container (va-widget-container)¶
You can implement widget containers as the vaWidgetContainer Angular.js directive. We use angular-gridster under the hood, which means our containers support and accept angular-gridster options.
<va-widget-container group="itemDetail" blade="blade" gridster-opts="{columns: 6, minRows: 4}"></va-widget-container>
Parameter | Description |
---|---|
group | Widget group ID. Only widgets from this group will be displayed. The value should be in line with the context of the container, e.g. itemDetail , and be unique among all widget containers. |
blade | Reference to parent blade. Sent to each widget inside the container. |
gridster-opts | Angular-gridster options (optional value). |
Widget registration (registerWidget)¶
You can register widgets through the Platform-level factory, which means any module can register new widgets to any widget container:
- Reference
platformWebApp.widgetService
(aswidgetService
) in your module'srun
method. - Create widget option definition and call
widgetService.registerWidget
.
var variationWidget = {
controller: 'virtoCommerce.catalogModule.itemVariationWidgetController',
size: [2, 1],
isVisible: function (blade) { return !blade.isNew && blade.controller === 'virtoCommerce.catalogModule.itemDetailController'; },
template: 'Modules/$(VirtoCommerce.Catalog)/Scripts/widgets/itemVariationWidget.tpl.html'
};
widgetService.registerWidget(variationWidget, 'itemDetail');
WidgetService.registerWidget
parameters:
Parameter | Description |
---|---|
widget | Widget options. |
containerName | Widget group ID that will be added to the widget container having the same group. |
Widget options:
Option | Description |
---|---|
controller | An Angular.js controller for the widget. Instantiated only on widget rendering, which means parent blade is accessible in the $scope.blade variable. |
size | Widget dimensions: [number of columns, number of rows]. An optional parameter with the default value at [1,1]. |
isVisible | Toggles widget visibility (a widget get invisible if this option is set to false). Set to true by default. |
template | Template URL for the widget. Check our Style Guide for details. |
Widget visibility and permissions¶
Widget visibility is controlled by defining the isVisible
method in widget registration options. There are at least two use cases when limiting visibility is required:
- The widget is appropriate only in some scenarios, e.g., you need to hide order widget while creating a new item or hide inventory widget for a digital product.
- Access to the widget is restricted by security permission, as in the sample piece of code below: