Element-based widgets require two templates:

  • The display.template, already discussed in the Create the widget template file section, provides the default presentation in the storefront for an element-based widget before any changes are made via the Design page. It is located in <extension-name>/widget/<widget-type>/templates.

  • The widget.template provides the starting point for editing the widget’s template in the Design page. It is located in <extension-name>/widget/<widget-type>/layouts/<layout-name>/widget.template.

Both templates are required and they must have identical contents.

When designing an element-based widget, you need to add some additional tags to both the display.template and widget.template files that enable elements to be rendered as part of the output page and to be edited on the Design page. An example of the tags is shown below:

  <!-- oc layout: panels -->
    <div class="row">

      <div class="col-md-12" data-oc-id="panel-1">

        <!-- oc section: product-image -->
          <div data-bind="element: 'product-image'"></div>
        <!-- /oc -->

        <!-- oc section: product-image-carousel -->
          <div data-bind="element: 'product-image-carousel'"></div>
        <!-- /oc -->

      </div>

    </div>
  <!-- /oc -->

The tags that support breaking a widget into elements include the following:

  • The oc layout tag tells Commerce Cloud to start parsing this section of the template for use on the Design page. Any code that resides before or after the oc layout tag is ignored by the Design page. Code within the tag is editable on the Design page.

  • The outer div, <div class="row">, creates a standard Bootstrap row to contain the elements. A widget template can have multiple rows to contain its elements.

  • The inner div, <div class="col-md-12" data-oc-id="panel-1">, creates a panel within the row (note that this is a Design page panel, not a traditional Bootstrap panel). Panels contain draggable UI elements that can be repositioned when editing the widget on the Design page. A row can contain multiple panels but their widths must add up to 12 (this is a requirement of the underlying Bootstrap grid).

    Note: The Design page uses the data-oc-id attribute to identify each panel. This custom attribute was created so that a page developer can alter the class or ID attributes of the panel div without breaking the Design page’s functionality. Also, the Design page is currently restricted to Bootstrap’s desktop grid classes, for example, col-md-x.

  • The oc section tags identify the individual draggable UI elements. Everything contained in an oc section tag is repositionable as one atomic unit, even though there may be multiple lines of code or many sub-elements within the section.

    To specify an element within a panel, a <div> block is created and a data-bind is used with element as the binding attribute and the name of the element as a string. This name corresponds to the element’s directory.

    Important: When you use the element binding, you must ensure that the current binding context is the widget, or that you can return easily to the widget. There are currently problems if you try to use the element binding within a ko foreach as each iteration of the loop is bound to a list item.

The tags described above all use HTML comment syntax. This syntax is useful because the tags do not need to be removed before being sent to the browser as they have no visible effect on the storefront pages. Also, this format is familiar to Knockout developers.


Copyright © 1997, 2017 Oracle and/or its affiliates. All rights reserved. Legal Notices