09/09/2015 12:55 AM Widgets
Virto Commerce

Widgets

Updated:

Introduction and glossary

widget is a relatively simple and intuitive web UI component in Virto Commerce platform. It has the role of a transient or auxiliary tile, meaning that:

  • it occupies just a portion of a blade;
  • provides some useful information displayed in place;
  • usually enables opening additional blade with extra information and functionality;
  • is reusable and can be added to many blades (widget containers) in various places.

widget container is a placeholder control for widgets. It's allows for the following:

  • display widgets in a rectangular area;
  • accept options like size, widget column and row count, etc.;
  • allow the user to manage widget position within designated area.

widget service is a platform level engine for registering widgets and distributing them to appropriate widget containers.

Add widget container

Widget container is implemented as vaWidgetContainer angularJS directive. We're using angular-gridster under the hood, therefore our container supports and accepts angular-gridster's 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. Value should resemble the context of the container, e.g. 'itemDetail' and be unique among all widget containers.
blade Reference to parent blade. Passed to each widget inside container.
gridster-opts Angular-gridster options. (optional)

Register a widget

Widget registration is done in JavaScript. Reference to 'platformWebApp.widgetService' as widgetService, create widget options and call 'registerWidget' on the service:

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. Will be added to widget container having the same group.

Widget options:

Member Description
controller AngularJS controller for the widget. Instantiated only on widget rendering, therefore parent blade is accessible in $scope.blade variable.
size Widget dimensions: [number of columns, number of rows]. Optional. Default value of [1,1] is applied if not specified.
isVisible Function to control widget visibility. Widget gets visible only if function returns true. Optional. Widget is always visible if not specified.
template Template URL for the widget. Check the Rules and styles guide for details.

Widget visibility and permissions

Widget visibility is controlled by defining isVisible method in widget registration options. There are at least 2 use-cases when visibility limiting is needed:

  • widget is appropriate only in some scenarios (e.g., hide orders widget while creating new item, hide inventory widget for a digital product);
  • access to widget is restricted by security permission. Check sample code below:
isVisible: function (blade) { return authService.checkPermission('pricing:query'); },