1. Developing Widgets
  2. Fragment a Widget into Elements
  3. Create the presentation for an element

Create the presentation for an element

When you create an element, you want to configure settings that allow you to present the element on your site.

To create the presentation for an element on the storefront, you have to do the following:

  • Create the HTML content for the element
  • Modify the widget’s display.template to include the element, thereby creating an element-based widget.
  • Add a widget.template file to manage editing of the element-based widget on the Design page.

Create the HTML for the element

Each element contains a block of HTML in a file called template.txt, located in element-name/templates. The format of this file is pure render-able HTML content without doctypes or non-body sections, for example: 

<h1 data-bind="text: title"></h1>

Modify the display.template and widget.template to use elements

Element-based widgets require two of the following templates:

  • The display.template, already discussed in Create the widget template file, 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 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 user interface 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). For information on Bootstrap, refer to the Bootstrap documentation.

    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.