HTML and CSS Templates in Messages and Dialogs
- 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
<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 Html
Default XtraDialog Template
<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 Html
#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.
<div id="frame">
<div id="content" >
<!-- Content Area -->
</div>
</div>
#Title Bar
Default markup:
<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):
<div class='header'>
<div class='header-text'>${Caption}</div>
<div id='closebutton' class='close-button'>
<img class='close-button-img' src='close'>
</div>
</div>
Bindings:
- The XtraBaseArgs.Caption property value replaces the
${Caption}
placeholder.
#Message Icon and Text (XtraMessageBox)
Default markup:
<dx-message-content>
<dx-message-icon></dx-message-icon>
<dx-message-text></dx-message-text>
</dx-message-content>
Custom markup (example):
<div id='content' class='content'>
<img class='success-img' src='${MessageIcon}'>
<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.
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);
#The “Do Not Show Again” Checkbox (XtraMessageBox)
Default markup:
<dx-message-checkbox id="message-checkbox"></dx-message-checkbox>
Custom markup (example):
<div class="checkbox" id="message-checkbox"></div>
<div>${MessageCheckBoxText}</div>
.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.
See also:
#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.
<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…
<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.
<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
orXtraDialogArgs
settings, depending on which data bindings are used in your template elements. - Call the
XtraMessageBox.Show
orXtraDialog.Show
method overload, which accepts~Args
objects as its parameter.
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);