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.templateprovides 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 layouttag tells Commerce Cloud to start parsing this section of the template for use on the Design page. Any code that resides before or after theoc layouttag 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-idattribute to identify each panel. This custom attribute was created so that a page developer can alter the class or ID attributes of the paneldivwithout 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 sectiontags identify the individual draggable UI elements. Everything contained in anoc sectiontag 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 adata-bindis used withelementas 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 foreachas 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.
