Customize Widget Element Appearance

You may often encounter the need to customize widget appearance. In the most simple cases, widget elements (title, content, collection item) have a simple textual presentation. But in most cases, widget elements require a more complex structure. Moreover, an element appearance may depend on values held in a data model associated with the current view.

If a widget contains elements available for customization, it includes the corresponding options that end with "Template". For instance, the dxPopover widget enables you to customize its content and title. For this purpose, it includes the contentTemplate and titleTemplate options.

Similar article is available for MVVM approach.

Read below to learn how to customize the required element appearance.

Use a Default Template

A default template for a widget is defined out-of-the-box. Default templates are based on a predefined set of fields in the widget. For example, every widget has a field that allows you to modify textual representation of the widget.

  • text
    Specifies the text inserted into the widget element.

Different widgets can have other additional fields (for example, icon field).

Collection widgets have default templates for item representation.They are based on a predefined set of fields in the widget data source, requiring you to provide the required set of fields for your widget's data source, so that widget items are displayed using a default template. The following are the fields that are used in a default item template of any widget.

  • disabled
    Specifies whether or not the list item is disabled.
  • visible
    Specifies whether or not the list item is visible.
  • html
    Specifies the html code inserted into the item element.
  • template
    Specifies an item template that should be used to render this item only.
  • text
    Specifies the text inserted into the item element.

However, additional fields can be required for item templates of certain widgets. For instance, a default template for the dxList widget is based on the set of fields above. However, the key field is also required to specify the group to which an item is related. To learn what set of fields is required for a specific widget, refer to the Default Item Template reference section of this widget.

In certain scenarios, it is enough to specify a simple array as a widget data source. In this instance, a default item template contains text binding associated with the current array value.

Use Custom CSS styles

You can apply custom CSS styles to widget elements. For this purpose, assign a custom class name to the widget element and use this class name when defining styles for widget elements.

HTML
<div id="myPopup" class="custom-popup">
    Popup content
</div>
JavaScript
$("#myPopover").dxPopup({
    visible: true,
    title: 'My Popup'
});
CSS
.custom-popup .dx-popup-title {
    padding: 0px 10px;
}
.custom-popup .dx-popup-title .dx-toolbar-label {
    font-size: 12px;
    text-transform: uppercase;
}
.custom-popup .dx-popup-content {
    background: lightgray;
}

Implement a Rendering Function

You can render widget elements using a custom rendering function. For this purpose, assign the required function to the appropriate option that specifies the template for the required element (e.g., titleTemplate for title element, contentTemplate for content element and so on). Note that the function should not return a value in this case. Otherwise, the returned string or element will be rendered using the current template engine.

JavaScript
var popoverData = {
    name: "John Doe",
    city: "Glendale",
    phone: "(626) 555-9248"
};
var popoverOptions = {
    contentTemplate: function(contentElement){
        contentElement.append("<p>Name: <i>" + popupData.name + "</i></p>");
        contentElement.append("<p>City: <i>" + popupData.city + "</i></p>");
        contentElement.append("<p>Phone: <i>" + popupData.phone + "</i></p>");
    }
};

Customize Rendered Markup Element

When a customizable widget element is rendered, the widget fires the corresponding event, which enables you to modify the rendered element for your requirements. You can assign the function which handles the required event to the onElementRendered option, where Element is a name of the rendered widget element. For instance, pass the event handling function to the onTitleRendered option to handle the event that occurs when the widget title is rendered. If a widget contains customizable content, the option holding a function called when widget content is rendered is called onContentReady.

JavaScript
var popoverOptions = {
    onTitleRendered: titleRenderedHandler
}

The object passed to the handler function enables you to access the rendered markup element and the data model associated with the current view.

JavaScript
var myTitle = "Popover Title";
var titleRenderedHandler = function(e) {
    // Use the 'e' object to access the widget markup element, rendered element and data model
    e.titleElement.append("<h1>" + myTitle + "</h1>");
}

Refer to the required event description for detailed information on the supported fields of the parameter object.

Note that rendered (for example onItemRendered, onGroupRendered) event handlers for collection items have other parameters. For more information, refer to the Customize Collection Item Appearance article.

See Also

Use an Alternative Template Engine

DevExtreme enables you to use an alternative template engine to customize the appearance of widget elements. Pass the name of the required template engine to the DevExpress.ui.setTemplateEngine(name) method to define which engine to use. DevExtreme supports the following template engines out of the box.

JavaScript
DevExpress.ui.setTemplateEngine("underscore");

If DevExtreme does not support your required template engine, call the DevExpress.ui.setTemplateEngine(options) method to define a custom template engine. The options argument should be an object containing the following fields.

  • compile
    Holds a function that compiles a template.

  • render
    Holds a function that renders a template.

NOTE
To define a template in the jQuery approach, use the script element. The div element can be used only with Knockout and AngularJS built-in template engines.

You can define a template out of the widget element. For example, if you use a single template in several widgets.

HTML
<div id="gallery"></div>
<script type="text/html" id="item-template">
    <div>
        <img src="<%= Image %>" />
        <div class="item-price">
            <%= Globalize.format(Price, "c0") %>
        </div>
        <div>
            <%= Address %>
        </div>
    </div>
</script>
JavaScript
DevExpress.ui.setTemplateEngine("underscore");

$("#gallery").dxGallery ({
    dataSource: gallery,
    itemTemplate: $("#item-template")
});

If a template is used only in a single widget, you can define it within the widget element using the dxTemplate markup component.

<div id="gallery">
    <script type="text/html" id="item-template" data-options="dxTemplate: {name: 'galleryItem'}">
        <div>
            <img src="<%= Image %>" />
            <div class="item-price">
                <%= Globalize.format(Price, "c0") %>
            </div>
            <div>
                <%= Address %>
            </div>
        </div>
    </script>
</div>
JavaScript
DevExpress.ui.setTemplateEngine("underscore");

$("#gallery").dxGallery ({
    dataSource: gallery,
    itemTemplate: "galleryItem"
});