HTML and CSS Templates in Messages and Dialogs

Mar 10, 2023
4 minutes to read

You can utilize HTML and CSS templates to design completely custom templates for XtraMessageBox and XtraDialog objects.

Default Templates

Messages and Dialogs are modal forms, and their templates are based on the same unique tags as templates for DirectXForms.

Default XtraMessageBox Template

html

<template id="button-template">
    <dx-message-button id="${MessageButtonId}" tabindex="${MessageButtonIndex}"></dx-message-button>
</template>

<dx-form-frame id="frame">
    <dx-form-titlebar id="titlebar">
        <dx-form-text id="text"></dx-form-text>
        <dx-form-closebutton id="closebutton"></dx-form-closebutton>
    </dx-form-titlebar>
    <dx-form-content id="content">
        <dx-message-content>
            <dx-message-icon></dx-message-icon>
            <dx-message-text></dx-message-text>
        </dx-message-content>
        <dx-message-footer>
            <dx-message-checkbox id="message-checkbox"></dx-message-checkbox>
            <dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>
        </dx-message-footer>
    </dx-form-content>
</dx-form-frame>

Tip

You can review and modify this default template in the Syntax Editor of the HtmlTemplateCollection component. To do this, set the “Preview Target” selector (located above the Syntax Editor’s Preview panel) to the “XtraMessageBox” value.

Default XtraDialog Template

html

<template id="button-template">
    <dx-message-button id="${MessageButtonId}" tabindex="${MessageButtonIndex}"></dx-message-button>
</template>

<dx-form-frame id="frame">
    <dx-form-titlebar id="titlebar">
        <dx-form-text id="text"></dx-form-text>
        <dx-form-closebutton id="closebutton"></dx-form-closebutton>
    </dx-form-titlebar>
    <dx-form-content id="content"></dx-form-content>
    <dx-message-footer>
        <dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>
    </dx-message-footer>
</dx-form-frame>

Custom Templates

Unique tags such as dx-form-frame or dx-form-closebutton have built-in styles that you cannot modify. To design a custom message or dialog, you need to replace these tags with regular div elements.

Tip

Utilize the HtmlTemplateCollection component as an external storage for dialog and message templates.

Mandatory Elements

Similar to DirectXForm templates, templates for messages and dialogs require that elements with “frame” and “content” IDs are present. A template without elements that have these IDs is considered invalid.

An element with the “frame” ID specifies the resize area of a form.
An element with the “content” ID specifies the form’s client area (the area where child controls reside).

The sample markup below illustrates custom div elements that replace standard dx-form-frame and dx-form-content tags.

html

<div id="frame">
    <div id="content" >
        <!-- Content Area -->
    </div>
</div>

Title Bar

Default markup:

html

<dx-form-titlebar id="titlebar">
    <dx-form-text id="text"></dx-form-text>
    <dx-form-closebutton id="closebutton"></dx-form-closebutton>
</dx-form-titlebar>

Custom markup (example):

html

<div class='header'>
    <div class='header-text'>${Caption}</div>
    <div id='closebutton' class='close-button'>
        
    </div>
</div>

Bindings:

The XtraBaseArgs.Caption property value replaces the ${Caption} placeholder.

Message Icon and Text (XtraMessageBox)

Default markup:

html

<dx-message-content>
    <dx-message-icon></dx-message-icon>
    <dx-message-text></dx-message-text>
</dx-message-content>

Custom markup (example):

html

<div id='content' class='content'>
    
    <div class='desc'>${MessageText}</div>
</div>

Bindings:

The XtraMessageBoxArgs.Text property value is passed to the ${MessageText} binding.
Values of the MessageBoxIcon property are passed to the ${MessageIcon} binding.
C#
VB.NET

csharp

XtraMessageBoxArgs args = new XtraMessageBoxArgs();
args.HtmlTemplate.Assign(htmlTemplateCollection1[0]);
args.Text = "This message utilizes DevExpress HTML & CSS templates.";
args.ImageOptions.MessageBoxIcon = MessageBoxIcon.Exclamation;
// Other "args" settings
XtraMessageBox.Show(args);

Dim args As New XtraMessageBoxArgs()
args.HtmlTemplate.Assign(htmlTemplateCollection1(0))
args.Text = "This message utilizes DevExpress HTML & CSS templates."
args.ImageOptions.MessageBoxIcon = MessageBoxIcon.Exclamation
' Other "args" settings
XtraMessageBox.Show(args)

The “Do Not Show Again” Checkbox (XtraMessageBox)

Default markup:

html

<dx-message-checkbox id="message-checkbox"></dx-message-checkbox>

Custom markup (example):

html

<div class="checkbox" id="message-checkbox"></div>
<div>${MessageCheckBoxText}</div>

css

.checkbox{
    width:20px;
    height:20px;
    border-radius: 4px;
    background-color: @White;
    background-size: 20px;
    background-repeat: no-repeat;
    background-position: center;
    border: 1px solid @WindowText/0.2;
}
    .checkbox:active {
        background-color: @Highlight/0.8;    
    }
    .checkbox:hover {
        background-color: @Highlight/0.3;    
    }
    .checkbox:focus {
        background-color: @Highlight/0.2;
        border: 1px solid @WindowText/0.4;
    }
    .checkbox:--checked {
        background-image: url('check');    
        background-size: 20px;
        background-repeat: no-repeat;
        background-position: center;
    }

Bindings:

The XtraMessageBoxArgs.DoNotShowAgainCheckBoxText property value is passed to the ${MessageCheckBoxText} binding.

Dialog Buttons

The standard markup utilizes the dx-collection tag to specify a single template that renders “OK”, “Cancel”, “Retry”, and other message and dialog buttons.

html

<template id="button-template">
    <dx-message-button id="${MessageButtonId}" tabindex="${MessageButtonIndex}"></dx-message-button>
</template>

<dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>

To design a custom message or dialog, you can either modify this unified template applied to all buttons…

html

<template id="button-template">
    <div id="${MessageButtonId}" tabindex="${MessageButtonIndex}">${MessageButtonCaption}</div>
</template>

<dx-collection Items="${MessageButtons}" ItemTemplate="button-template"></dx-collection>

…or create all buttons manually as regular div elements.

html

<div class='button' tabindex='1' id='dialogresult-yes'>Save</div>
<div class='button' tabindex='2' id='dialogresult-no'>Don't save</div>
<div class='button' tabindex='3' id='dialogresult-cancel'>Cancel</div>

Bindings:

The ${MessageTimerText} binding allows you to display the remaining AutoCloseOptions.Delay value. See this help article for more information: Auto-Close Message Boxes.

How to Show Templated Messages and Dialogs

To display a message or dialog that utilizes an HTML & CSS template, do the following:

Create an XtraMessageBoxArgs or XtraDialogArgs class instance.
Call this object’s HtmlTemplate.Assign method to select a message/dialog template.
Set up additional XtraMessageBoxArgs or XtraDialogArgs settings, depending on which data bindings are used in your template elements.
Call the XtraMessageBox.Show or XtraDialog.Show method overload, which accepts ~Args objects as its parameter.

C#
VB.NET

csharp

XtraMessageBoxArgs msgArgs = new XtraMessageBoxArgs();
msgArgs.ImageOptions.Icon = this.IconOptions.Icon; // ${MessageIcon}
// Or
//msgArgs.ImageOptions.SvgImage = svgImageCollection1[0];
msgArgs.Caption = "Reminder"; // ${Caption}
msgArgs.Text = "Your meeting starts in 1 hour!"; // ${MessageText}
msgArgs.DoNotShowAgainCheckBoxVisible = true;
msgArgs.DoNotShowAgainCheckBoxText = "Do not notify me again."; // ${MessageCheckBoxText}
msgArgs.AutoCloseOptions.ShowTimerOnDefaultButton = true;
msgArgs.DefaultButtonIndex = 1;
msgArgs.AutoCloseOptions.Delay = 10000; // ${MessageTimerText}
XtraMessageBox.Show(msgArgs);

Dim msgArgs As New XtraMessageBoxArgs()
msgArgs.ImageOptions.Icon = Me.IconOptions.Icon ' ${MessageIcon}
' Or
'msgArgs.ImageOptions.SvgImage = svgImageCollection1[0];
msgArgs.Caption = "Reminder" ' ${Caption}
msgArgs.Text = "Your meeting starts in 1 hour!" ' ${MessageText}
msgArgs.DoNotShowAgainCheckBoxVisible = True
msgArgs.DoNotShowAgainCheckBoxText = "Do not notify me again." ' ${MessageCheckBoxText}
msgArgs.AutoCloseOptions.ShowTimerOnDefaultButton = True
msgArgs.DefaultButtonIndex = 1
msgArgs.AutoCloseOptions.Delay = 10000 ' ${MessageTimerText}
XtraMessageBox.Show(msgArgs)