ASP.NET Theme Builder

ASP.NET Theme Builder

ASPxThemeBuilder is a standalone tool designed to help developers create new themes based on shipping DevExpress ASP.NET Themes. The primary objective of the product is to simplify the otherwise cumbersome aspects associated with Theme customization. ASPxThemeBuilder provides numerous options with which to navigate through Theme elements - be it locating a visual element with one click, browsing the element trees of individual controls and exploring hierarchies of the CSS classes used to render a given control.

Use the following links to find more information on DevExpress Theme Builder for ASP.NET.

  • Main Features

    Outlines the essential capabilities provided by ASPxThemeBuilder.

  • Getting Started

    Guides you through a simple scenario of creating, editing, saving and applying a theme in your web application.

  • UI Elements

Note

Make sure that the version of the ASPxThemeBuilder tool conforms with the version of Developer Express components used within the specified web project. If necessary, you can use the Developer Express ProjectConverter tool to update the project, so that it uses the most recent version of Developer Express components.

See Also
ASP.NET WebForms Controls
ASP.NET MVC Controls
Copyright(c) 1998-2023 Developer Express Inc. All rights reserved.
Send Feedback on this topic to DevExpress.


Main Features

Main Features

The DevExpress ASPxThemeBuilder allows you to:

  • Create new or modify previously generated Themes;
  • Select individual controls and their elements using the Control Navigator (left most pane);
  • Activate/Disable selection mode above the Preview pane. If active, you can select control elements within the preview, much like FireBug;
  • View the CSS rules used for rendering the selected control element. You can edit them as text or use the controls below the Preview pane;
  • Edit the skin files for the selected control by using the Skin pane;
  • Modify images (for CSS and skins) using an external editor, which can be specified via the Theme Builder’s Options page;
  • Save modified Themes in the selected folder;
  • Change Theme properties (name, control set) using the Theme Properties form;
  • Build a custom Theme assembly and use it in your web project.


Getting Started

Getting Started

This section consists of the following topics.

  • Launching the Theme Builder
  • Creating a New Theme
  • Generating a Custom Theme Assembly
  • Using a Custom Theme Assembly


Launching the Theme Builder

ASPxThemeBuilder can easily be launched in different ways.

  • From the DEVEXPRESS menu

    In the main menu of Visual Studio, select Extensions | DevExpress | ASP.NET Controls v23.1 | Run ASP.NET Theme Builder…

  • From the ASPxThemeBuilder.exe file

    Run the ASPxThemeBuilder.exe file. Typically, this tool is located in the following path after installation.

    C:\Program Files\DevExpress 23.1\Components\Tools\Asp.net\ASPxThemeBuilder.exe

When launched, the tool displays the following window and a start-up dialog.

In the dialog, you can create a new theme or open an existing one for further modification.

Note

When using ASPxThemeBuilder, ensure that the Microsoft.mshtml.dll primary interop assembly is installed on end-user computers. To deploy this assembly, use the vs_piaredist.exe package installed with Visual Studio. The package can be found in the C:\Program Files\Common Files\Merge Modules folder by default.

Concepts

  • Creating a New Theme
  • Generating a Custom Theme Assembly
  • Using a Custom Theme Assembly


Creating a New Theme

This tutorial will help you learn how to create a new theme based on a DevExpress theme, customize this new theme and save it for further use in your ASP.NET applications.

The tutorial contains the following steps.

  1. Create Theme
  2. Modify Theme
  3. Save Theme
  4. Open Theme

In this lesson, you will create a custom theme based on the DevEx theme. You will customize the presentation of the ASPxNavBar control by making the following adjustments.

  • You will customize the appearance of group headers by changing the font style and modifying the color of expand/collapse glyphs.
  • You will change the spacing between groups and increase side paddings.
  • You will also alter the background color of a hovering item.

Create Theme

  1. Run ASPxThemeBuilder (see the Launching the Theme Builder topic to learn more).

    In the displayed start-up dialog box, click New Theme.

    Note that within an opened ASPxThemeBuilder window, you can click the File menu and New (or use the CTRL+N keyboard shortcut) for the same purpose.

    As a result, the New Theme dialog box will be displayed.

  2. In the Name box, you can enter the name of a newly created theme. In this lesson, type MyDevExTheme.

  3. In the Based on combo box, select a DevExpress theme to be the base for the new theme. In this lesson, leave it set to the DevEx theme.

    Note

    Note that the XafTheme is designed to be used in eXpressApp Framework applications only.

  4. In the Products check box list, select the DevExpress products to which the created theme should be applied. Click to clear the All check box and select just the Navigation and Layout Controls check box.

  5. Click OK to close the dialog.

The DevEx theme will be cloned for the selected products. The cloned copy will be placed into a temporary directory. Later on, you can save the theme files into a custom location by using the Save or Save As… menu item and specifying the path you desire.

Modify Theme

  6. In the leftmost Control Navigator Pane of the opened application window, select the control whose appearance should be modified. Click ASPxNavBar. In the Control Preview Pane, you can see a preview for the control you are customizing.

  7. To change the font of all group headers to bold, do the following.

    • Select the Group Header element (by clicking within the Control Navigator Pane or Control Preview Pane).

    • Click the Bold button in the Text - Decoration section of the Visual Customization Panel.

      Note that the corresponding code is added to the current rules in the CSS Rules Tab. You can modify CSS rules directly in code, typing a similar code.

  8. Change the left and right paddings of a group header using the text editor of the CSS Rules Tab.

    Note

    An element can have several CSS classes. The lower class within the tab, the higher priority it has among other classes.

    • Find the attribute padding and add 10px to the attribute value.
    • Click Apply.

  9. To change the expand/collapse button images, do the following.

    • Click the collapse button ( ASPxThemeBuilder-CollapseButton) in Control Preview.

    • Click the Edit button in the Background - Image section of the Visual Customization Panel.

    • If you edit an image for the first time, select an external graphics editor you would like to use for editing images and click OK. Note that you can change the editor later if you click the Tools menu, and then click Options.

    • An image sprite will be opened in the editor. Change the color of expand/collapse button images (see the image below). Save and close the image.

    • Since the image is modified using an external editor, click the Refresh button ( ASPxThemeBuilder-RefreshButton) to synchronize Control Preview with the modified image.

  10. Some control properties cannot be specified in a CSS, so you should set them in a skin.

    To change spacing between groups, click the Skin Tab. The tab lists navigation bar properties related to ASPxNavBar control properties. In the GroupSpacing box, type 10.

  11. To change a navigation bar item hover color, do the following.

    • Click the Item element in Control Preview or in the Control Navigator Pane.

    • Click the dxnbItemHover_MyDevExTheme CSS class in the Selector Navigation Pane to customize just a hover style.

    • Clear a default image in the Image box of the Visual Customization Panel.

    • Choose an item color in the Color box.

    To see changes in action, click the Selection Mode button ( ASPxThemeBuilder-SelectionModeButton) to turn off the Selection Mode. In this case, you can interact with the control in a standard way as in a web browser.

You can see the result in the image below.

Save Theme

  12. To save your theme, click the Save button ( ASPxThemeBuilder-SaveButton) in the toolbar or on the File menu, click Save or press the CTRL + S keyboard shortcut.

  13. In the opened Save Theme dialog box, select or type the path to a folder where you want to save your theme and click OK.

    Your theme is saved in a folder with the theme’s name (in our case the full path is D:\MyThemes\MyDevExTheme). The theme folder contains CSS files, skin files for all controls of the specified product, and all necessary images. Note that you can change the theme name and the list of included products using the Theme Properties dialog box. To open this dialog box on the File menu, click Theme Properties.

Open Theme

You can open a previously saved theme to modify it.

To open a custom theme, do one of the following.

  • Run ASPxThemeBuilder and click the Open Theme in the displayed start-up dialog box.
  • On the File menu, click Open…
  • Press CTRL + O keyboard shortcut.

As a result, the Open Theme dialog will be displayed.

  • In the Location box, select or type the folder where the theme is placed.
  • The Theme combo box lists themes contained within the selected location. Select a theme you desire to open.
  • Click OK to close the dialog.

Note

We recommend that you use ASPxThemeBuilder to open custom themes, but not shipped DevExpress themes. If you wish to slightly modify one of the predefined DevExpress themes, do not open it directly. Instead, create a new custom theme based on the desired DevExpress one, and then make required changes within this custom theme.

Concepts

To learn how to create a theme assembly, follow the Generating a Custom Theme Assembly topic.

To learn how to apply the created theme assembly, follow the Using a Custom Theme Assembly topic.


Generating a Custom Theme Assembly

In this tutorial, you will learn how to create a theme assembly from your custom theme. To learn how to create a custom theme, see the Creating a New Theme topic.

To create a theme assembly, follow the steps below.

  1. Within ASPxThemeBuilder, click the File menu, and then click Create Assembly… As a result, the Create Theme Assembly dialog box will be displayed.

  2. The Assembly name box allows you to specify the name for the newly created assembly. In this lesson, type MyThemeAssembly.
  3. Leave the Auto-generated check box selected.
  4. In the Location combo box, you can type or select a folder where themes for the assembly are placed. Leave the current D:\MyThemes folder.
  5. The Themes check box list displays a list of themes located within the specified folder. You can select themes to be included to the assembly you create. In this lesson, we have only the MyDevExTheme theme. Select it and click OK to create the assembly.

The assembly will be placed at the selected location.

Note

When you update a DevExpress product version, you should re-create an assembly under the new version of ASPxThemeBuilder.

Concepts

To learn how to apply the created theme assembly, see the Using a Custom Theme Assembly topic.


Using a Custom Theme Assembly

In this topic, you will learn how to use a custom theme to customize the appearance of a website. As an example, we will use a custom MyThemeAssembly assembly that contains the MyDevExTheme theme described in the Creating a New Theme and Generating a Custom Theme Assembly topics.

To apply a custom theme assembly to your application, it is necessary to add a theme assembly to the project’s reference files. All required source files (images, CSS files, and skins) are automatically obtained from the theme assembly.

Start by adding the required file to your application.

  1. Right-click your site in Solution Explorer and select Add | Reference….

  2. Click the Browse tab in the Reference Manager. Then click the Browse… button and add the MyThemeAssembly.dll assembly to the manager. After the assembly appears in the Reference Manager, check it and click OK.

    This adds the assembly to the project.

  3. Assign the assembly name (MyThemeAssembly) to the customThemeAssemblies option within the devExpress section of the web.config file.

    • XML
    <devExpress>
     <themes customThemeAssemblies="MyThemeAssembly" ... />
     ...
</devExpress>

  4. You can now apply the MyDevExTheme theme to a website. For this purpose, set the theme attribute within the devExpress section of the web.config file to MyDevExTheme.

    • ASPX
    <devExpress>
     <themes enableThemesAssembly="true" styleSheetTheme="" customThemeAssemblies="MyThemeAssembly" theme="MyDevExTheme" />
     ...
</devExpress>
  5. Run the application and view your site with the MyDevExTheme theme.

Note

You can use the DevExpress ASP.NET Project Wizard to specify a theme for your site. The Wizard automatically adds a reference to an assembly in your project, and sets the customThemeAssemblies and theme attributes of web.config.

See Also
Apply a Theme with the DevExpress Mechanism
Apply a Theme with the ASP.NET Mechanism


UI Elements

UI Elements

This section consists of the following topics.

  • Start Dialog
  • Main Window
  • New Theme Dialog
  • Open Theme Dialog
  • Theme Properties Dialog
  • Save Theme Dialog
  • Create Theme Assembly Dialog
  • Options Dialog


Start Dialog

The Start Dialog opens when you launch ASPxThemeBuilder. It allows you to create a new theme or open a previously created theme. When the button is pressed, the New Theme Dialog or Open Theme Dialog is invoked.


Main Window

The ASPxThemeBuilder Main Window contains the following main elements.

  • Main Menu
  • Control Navigator Pane
  • Control Preview Pane
  • Visual Customization Panel
  • CSS and Skin Settings Pane


Main Menu

The Main Menu contains various commands grouped in sub-menus. Some commands have keyboard shortcuts written next to them, and duplicated with commands available in a toolbar. To switch focus on the Main Menu, press ALT.

The Tools menu contains “View…” commands that allow you to display the current control preview pane content (i.e., control preview and options panel) in one of installed browsers.


Control Navigator Pane

The Control Navigator pane is placed at the leftmost part of ASPxThemeBuilder and allows you to select a control or control elements for customization. The selected element is shown in Control Preview.


Control Preview Pane

The Control Preview pane is the central pane of the ASPxThemeBuilder Main Window.

It contains the following elements.

  • Mode Selection Button
  • Control Preview
  • Options Panel


Mode Selection Button

The Mode Selection button is placed at the top of Control Preview Pane and allows you to turn on/off the selection mode.


Control Preview

The Control Preview is placed in the central part of the Main Window and shows a control you are customizing. The control layout within the preview can be modified using Options Panel options. The Control Preview allows you to select a control or control elements for customization. This element synchronizes with the selected element within the Control Navigator Pane.


Options Panel

The Options panel is placed at the top right corner of Control Preview Pane and contains the current control properties that allow you to modify its layout within Control Preview.


Visual Customization Panel

The Visual Customization Panel is located in the Control Preview Pane. It contains controls in two tabs.

  • The Base Properties tab contains controls used for editing base CSS rules.

  • The CSS3 Properties tab contains controls used for editing CSS3 standard rules.


CSS and Skin Settings Pane

The CSS and Skin Settings pane is ASPxThemeBuilder Main Window‘s rightmost pane.

It contains two tabs: CSS Tab and Skin Tab.


CSS Tab

The CSS tab is placed on the CSS and Skin Settings Pane and contains two panes.

  • Selector Navigation Pane displays a list of CSS classes that are used for rendering a selected control’s element.
  • The Show Existing CSS Classes Only check box controls whether only classes that exist for the current element are displayed.
  • CSS Edit Pane contains a number of tabs with text presentation of CSS files that are used for rendering a selected control.


Selector Navigation Pane

The Selector Navigation pane is placed at the top of the CSS Tab and displays a list of CSS classes, which are used for rendering a selected control’s element.


CSS Edit Pane

The CSS Edit pane is placed at the bottom of the CSS Tab and contains a number of tabs with text presentation of CSS files, which are used for rendering a selected control.

The CSS Edit pane can contain:

  • One CSS Rules Tab;
  • One or several Sprite.css Tabs;
  • One or several Styles.css Tabs.


CSS Rules Tab

The CSS Rules tab is placed within the CSS Edit Pane, and contains CSS rules related to the CSS class selected in the Selector Navigation Pane. If no CSS class is selected, the pane is not shown.

The CSS Rules tab provides the following command buttons.

Image | Description
 | Finds the next CSS rule
 | Finds the previous CSS rule
 | Finds the current CSS rule in files contained in the CSS Edit Pane
 | Applies changes
 | Cancels changes

Note

An element can have several CSS classes. The lower the class within the CSS Rules tab, the higher priority it has among other classes. Thus, class rules with a lower priority can be overridden.


Styles.css Tabs

A theme can correspond to one or several style CSS files. Every file is shown within a particular Styles.css tab. The tabs are placed within the CSS Edit Pane.

The Merge button allows you to merge the current CSS file with the corresponding original CSS file.


Sprite.css Tabs

A theme can contain one or several sprites. Every sprite CSS file is shown within a particular Sprite.css tab. The tabs are placed within the CSS Edit Pane.

The Merge button allows you to merge the current CSS file with the corresponding original CSS file.


Skin Tab

The Skin tab is placed on the CSS and Skin Settings Pane and contains a property grid for the current control. The tab allows you to change control properties related to its customization that you cannot change through CSS files. By default, the Skin displays appearance and style settings only. Select the Show All Properties check box to display the functional and behavior properties as well.

You can create several skins for a control within one theme. To create or delete a skin, use the Add New Skin or Delete Skin buttons respectively.


New Theme Dialog

The New Theme dialog allows you to create a new theme.

To invoke this dialog, do the following:

Click New Theme in the ASP.NET Theme Builder Start Dialog.

You can also click File | New in the ASP.NET Theme Builder menu, click the New Theme button ( ASPxThemeBuilder-NewButton) on the toolbar, or press the CTRL+N keyboard shortcut.

The dialog box contains the following elements.

  • Name - contains the name of the newly created theme.
  • Based on combo box - contains a list of DevExpress themes that you can use as a base for the new theme.
  • Products check box list - allows you to select the DevExpress products to which the created theme should be applied.
  • Parameters - allows you to change the base theme settings (font and base color).

Note

The theme name and the list of included products can be changed later via the Theme Properties Dialog.


Save Theme Dialog

The Save Theme dialog allows you to save a theme.

To invoke this dialog, do one of the following.

  • Click Save or Save As… on the File menu.
  • Click the Save Theme button ( ASPxThemeBuilder-SaveButton) on the toolbar.
  • Press CTRL + S keyboard shortcut.

The dialog box contains the Location box that allows you to select or type the path to a folder where you wish to save your theme. A theme is saved in a specified location within a folder with the theme’s name. The theme folder contains CSS files, images, and skin files for controls of included products. Note that you can change the theme name and the list of included products using the Theme Properties Dialog.


Theme Properties Dialog

The Theme Properties dialog allows you to change the current theme name and the list of included products.

To invoke this dialog, click File | Theme Properties… in the ASP.NET Theme Builder menu.

The dialog box contains the following elements.

  • Name - contains the name of the newly created theme. You can change it as required.
  • Based on combo box - displays the theme that is the base for the new theme.
  • Products check box list - allows you to select the DevExpress products to which the new theme should be applied.
  • Parameters - allows you to change the base theme settings.


Open Theme Dialog

The Open Theme dialog allows you to open a custom theme to modify it.

To invoke this dialog, do one of the following.

  • Click Open Theme in Start Dialog.
  • Click Open… on the File menu.
  • Click the Open Theme button ( ASPxThemeBuilder-OpenButton) on the toolbar.
  • Press CTRL + O keyboard shortcut.

The dialog box contains the following elements.

  • The Location box allows you to select or type the folder where the theme is placed.
  • The Theme combo box lists themes contained within the specified location. Select the theme you desire to open.

Note

We recommend that you use ASPxThemeBuilder to open only custom themes, but not any shipped DevExpress themes. If you want to slightly modify one of predefined DevExpress themes, do not open it directly. Instead, create a new custom theme basing it on the desired DevExpress one, and then make the required changes within this custom theme.


Create Theme Assembly Dialog

The Create Theme Assembly dialog allows you to create a theme assembly from custom themes.

To invoke this dialog, click Create Assembly… on the File menu.

The dialog box contains the following elements.

  • The Assembly name box allows you to specify the name for the newly created assembly.
  • The Assembly ID spin editor allows you to specify the assembly unique identifier. By default, this identifier is generated automatically. To specify it manually, clear the Auto-generated check box.
  • The Location combo box allows you to type or select a folder where themes for the assembly are placed.
  • The Themes check box list displays a list of themes located within the specified folder. You can select themes to be included in the assembly you create.

The created assembly is placed to the location specified in the Location combo box.


Options Dialog

The Options dialog allows you to select an external graphics editor and merging tool that you would like to use for editing theme images and merging CSS files respectively.

This dialog box is shown in when you edit an image in ASPxThemeBuilder for the first time, and when you merge CSS files for the first time. You can change the tools later if you click the Tools menu, and then click Options.


How to Update a Custom Theme to a Newer Version

How to Update a Custom Theme to a Newer Version

A major update of DevExpress ASP.NET controls usually includes changes to HTML markup. You should update the references to DevExpress assemblies and CSS styles (optionally) to use your custom theme with a newer version of DevExpress ASP.NET controls.

We recommend that you make a backup of your custom theme before you update.

Update References

You can use the Project Converter or Theme Builder to update references to DevExpress assemblies in a custom theme. Click Yes to update references to DevExpress assemblies in the theme’s skin files.

Update References Message

Use the “Save” and “Create Assembly …” menu items to save the theme and recreate the theme assembly.

Important

The Project Converter only updates the DevExpress themes’ .skin files. However, this tool does not apply changes in the new version of CSS styles to custom themes. The next section explains how to update CSS styles in your theme.

Update CSS Styles

You can use any of the following ways to update CSS classes and styles in your custom theme:

Copy Your Theme Settings to New Theme

Use this approach if an update includes numerous changes to DevExpress themes or if your custom theme has minor changes.

Follow the steps below to create a new theme that merges changes in your old custom theme with the new version of the base theme.

  1. Use Theme Builder to create a new custom theme with the same base theme as in your current custom theme.

    Theme Properties - Base Theme Dialog

  2. Launch another instance of Theme Builder and open your old custom theme. Do not update the theme.

  3. For the old custom theme, click the “Merge with original CSS” button to open a merge tool to review style changes between the custom and default themes. The Theme Builder displays a dialog to set the merge tool, if this tool is not set.

    Merge with Original Theme Command

    This tool displays the changes between your old custom and the base themes.

  4. Move these changes to the new custom theme. Use the “Save” and “Create Assembly …” menu items to save the theme and recreate the theme assembly.

Copy Changes to Your Custom Theme

We recommend this solution if your custom theme has numerous modifications in comparison to an original theme, or if you do not want to create a new theme.

Follow the steps below to copy changes from a new version of the base theme to your custom theme:

  1. Open the custom theme in the Theme Builder.

  2. Open the Theme Properties dialog and specify a base theme.

    Theme Properties Command

    Theme Properties - Base Theme Dialog

  3. Click the “Merge with original CSS” button to open a merge tool.

    Merge with Original Theme Command

  4. Merge all the changes between the custom and the base themes. Use the “Save” and “Create Assembly …” menu items to save the theme and recreate the theme assembly.