Using Custom CSS Sprites

  • 3 minutes to read

If you use custom images for DevExpress control elements in your web application, you should manually combine these images into a sprite image to benefit from the CSS sprites technique. Based on the application's logic, you can combine images into a single (application specific) sprite image or multiple (control specific or control group specific) sprite images.

Use one of the following approaches to set the required sprite image (and individual images contained within it) for each DevExpress control.

Use a Control's Properties to Set a Sprite Image

Use the following properties to attach a sprite image to a control to display its images within control elements:

  • SpriteImageUrl - Specifies the path to a sprite image.
  • Height - Specifies an individual element's image height.
  • Width - Specifies an individual element's image width.
  • Top - Specifies the vertical offset within a sprite for an individual element's image.
  • Left - Specifies the horizontal offset within a sprite for an individual element's image.

The following image shows the properties of ASPxNavBar and its CollapseImage:

mySprite2.png

SpriteImageSettings-NB-1.png

NOTE

Note that individual image settings are rendered as inline CSS styles embedded in an image's HTML tag. If too many images are defined in this manner, application performance may be affected due to an increase in page size.

When you use a control's properties to define a sprite and its associated images, markup is added to the page. The code below illustrates HTML markup generated for an ASPxNavBar’s collapse image.

<img class="dxWeb_nbCollapse" 
     style="background: transparent url(Images/mySprite.png) no-repeat scroll -18px -3px; 
         border-width: 0px; height: 12px; width: 11px; -moz-background-clip: -moz-initial; 
         -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" 
     alt="" src="/Projects/ImageSprites_Test1/DXR.axd?r=1_16"/>

Note that individual image settings are rendered as inline CSS styles embedded in an image's HTML tag. If too many images are defined in this manner, application performance may be affected due to an increase in page size.

Use Named CSS Classes to Set a Sprite Image

To define individual image settings, you can use the ImageSpriteProperties.CssClass property to specify a CSS class. A CSS class can be declared within page markup or a linked CSS file.

SpriteImageSettings-NB-2.png

A CSS class should contain attributes that specify the size (width and height, in pixels) and position (horizontal and vertical offsets represented by negative values) of each image within a sprite. This approach is recommended if you use CSS rules to reference a sprite image.

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Custom CSS Image Sprite</title>

    <style type="text/css">
        .imgExpand,
        .imgCollapse {
            background-image: url('Images/nb-custom-sprite.png');
            background-repeat: no-repeat;
            background-color: transparent;
        }
        .imgExpand {
            background-position: -3px -3px;
            width: 11px;
            height: 12px;
        }
        .imgCollapse {
            background-position: -18px -3px;
            width: 11px;
            height: 12px;
        }
    </style>      
</head>
<body>
    <form id="form1" runat="server">

        <dx:ASPxNavBar ID="ASPxNavBar1" runat="server" >
            <Groups>
                <dx:NavBarGroup Text="Group 1">
                    <Items>
                        <dx:NavBarItem Text="Item 1-1"></dx:NavBarItem>
                        <dx:NavBarItem Text="Item 1-2"></dx:NavBarItem>
                    </Items>
                </dx:NavBarGroup>
                <dx:NavBarGroup Text="Group 2" Expanded="False">
                    <Items>
                        <dx:NavBarItem Text="Item 2-1"></dx:NavBarItem>
                    </Items>
                </dx:NavBarGroup>
            </Groups>
            <CollapseImage>
                <SpriteProperties CssClass="imgCollapse" />
            </CollapseImage>
            <ExpandImage>
                <SpriteProperties CssClass="imgExpand" />
            </ExpandImage>
        </dx:ASPxNavBar>

    </form>
</body>
</html>

Sample HTML markup for the ASPxNavBar's collapse image (defined by a named CSS class) is as follows.

<img class="imgCollapse" style="border-width: 0px;" alt="" src="/Projects/ImageSprites_Test1/DXR.axd?r=1_16"/>

This approach uses the control’s SpriteImageUrl property to reference a sprite image instead of defining it with CSS rules. Note that in this case, inline CSS settings are automatically rendered in each HTML image tag to define a sprite image, which increases page size and overrides 'background-position' attributes for custom CSS classes. Be sure to add the '!important;' declaration to the 'background-position' CSS attributes in this case.