Telerik UI for ASP.NET AJAX

RadBinaryImage gives you an easy way of showing an image stored as binary data in a database. The control can be used in any data bound control (Repeater, DataList, GridView, etc.) to display images which originate from binary image field in the data source. The control uses an internal http handler which streams the image from the binary source to the page in which it has to be visualized.The storage of the binary stream when transferred between the control itself and the handler is the HttpContext.Current.Cache object and the image is cached in the browser. Its default expiration time is 2 hours (unless the control in which the RadBinaryImage is nested is rebound or recreated). This means that subsequent loads of the binary image are taken from the browser cache when using the same url for access. In case the browser cache is disabled, the image will be persisted for 2 minutes on the server before it is streamed to the page from the data source.

The most important properties of the RadBinaryImage control are presented in the table from the next paragraph:

 

Property

Description

DataValue

Property which specifies the source field from which the data will be passed as a byte array

Height

Specifies the height of the binary image

Width

Specifies the width of the binary image

AlternateText

The text that will replace the image when it is not available/cannot be streamed

ToolTip

The text that will be displayed in a browser tooltip when you hover the image

AutoAdjustImageControlSize

Scales the image based on explicitly set width/height dimensions to avoid stretch or blur effect when its original dimensions do not fit. The default value is true.

CropPosition

Used when the ResizeMode is set to Crop. Specifies the cropping position, i.e. which part of the image will be cropped. The possible values are: Top, Center, Bottom, Left, Right.

HttpHandlerUrl

Can be used to specify the location of a custom http handler which extends the default RadBinaryImage http handler. When not set, RadBinaryImage has its own handler which is invoked through the common Telerik.WebResource.axd handler.

ImageUrl

Applicable when no DataValue is specified to gracefully degrade to regular ASP.NETImage mode. When null value is returned from the source, the ImageUrl property can be used to specify default image for RadBinaryImage

ImageAlign

Specifies the image alignment inside its container.

ResizeMode

Specifies whether the image should be sized automatically if width and height of the image are set in pixels. Possible values are:

  • Crop (the image will be trimmed)

  • Fill (the image will be sized to fill both given dimensions)

  • Fit (the image will be sized to fit the given dimensions)

  • None (default)

SavedImageName

Sets image’s filename which will appear inside SaveAs browser dialog if image is saved

PersistDataIfNotVisible

If set to true image data persistence is forced if the control is invisible.

VisibleWithoutSource

Specifies whether the image will be rendered if a valid source is not present. The default value is True.

RadBinaryImage Design Time

The RadBinaryImage Smart Tag provides convenient access to the most common used properties for the control. You can display the Smart Tag by right clicking on the RadBinaryImage in the design window, and choosing the "Show Smart Tag" option from its context menu.

radbinaryimagetaskspng
Note

When you want to display transparent .gif images using a RadBinaryImage, you should set its ResizeMode property to None. This is so because image transformations with such files are not supported.

Here is an online demo which demonstrates how to integrate RadBinaryImage as part of ASP.NETRepeater template. The screen shot from the result is available below:

radbinaryimage thumb

CopyASPX
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title></title>
    <link href="stylesheet.css" rel="stylesheet" type="text/css" />
</head>
<body class="BODY">
    <form id="form1" runat="server">
    <div>
        <telerik:RadScriptManager ID="RadScriptManager1" runat="server" />
        <asp:Repeater runat="server" ID="Repeater1" DataSourceID="SqlDataSource2">
            <ItemTemplate>
                <fieldset style="float: left; width: 350px; height: 150px;">
                    <legend><b>Company Name</b>:
                        <%#Eval("CompanyName")%></legend>
                    <div class="details">
                        <div class="photo-container">
                            <telerik:RadBinaryImage runat="server" ID="RadBinaryImage1" DataValue='<%#Eval("Photo") %>'
                                AutoAdjustImageControlSize="false" Width="90px" Height="110px" ToolTip='<%#Eval("ContactName", "Photoof {0") %>'
                                AlternateText='<%#Eval("ContactName", "Photoof {0") %>' />
                        </div>
                        <div class="data-container">
                            <ul>
                                <li>
                                    <label>
                                        Contact Name:</label>
                                    <%#Eval("ContactName")%>
                                </li>
                                <li>
                                    <label>
                                        Title:</label>
                                    <%#Eval("ContactTitle")%>
                                </li>
                                <li>
                                    <label>
                                        City:</label>
                                    <%#Eval("City")%>
                                </li>
                                <li>
                                    <label>
                                        Country:</label>
                                    <%#Eval("Country")%>
                                </li>
                                <li>
                                    <label>
                                        Phone:</label>
                                    <%#Eval("Phone")%>
                                </li>
                            </ul>
                        </div>
                    </div>
                </fieldset>
            </ItemTemplate>
        </asp:Repeater>
        <div style="clearboth;">
        </div>
        <telerik:RadFormDecorator runat="server" ID="radFormDecorator" DecoratedControls="All" />
        <asp:SqlDataSource ID="SqlDataSource2" runat="server" ConnectionString="<$ ConnectionStrings>"
            ProviderName="<$ ConnectionStrings>" SelectCommand="SELECT TOP 6 * FROM [CustomerPhotos]">
        </asp:SqlDataSource>
    </div>
    </form>
</body>
</html>
Note

You need to register the http handler of the RadBinaryImage control either using its SmartTag or manually in the web.config file to ensure that it will be served as expected when the page is rendered. Namely:

Copy[Web.config] Classic mode
<httpHandlers>
    <remove path="*.asmx" verb="*" />
    ...
    <add path="Telerik.Web.UI.WebResource.axd" type="Telerik.Web.UI.WebResource" verb="*" validate="false" />
</httpHandlers>
Copy[Web.config] Integrated mode
<system.webServer>
    ...
    <handlers>
        <add name="Telerik_Web_UI_WebResource_axd" verb="*" preCondition="integratedMode" path="Telerik.Web.UI.WebResource.axd" type="Telerik.Web.UI.WebResource" />
    </handlers>
</system.webServer>

WAI-ARIA Support

The RadBinaryImage control offers WAI-ARIA support which can be easily enabled by setting the EnableAriaSupport server property to true.

RadBinaryImage ARIA attributes are lower case. They are shown in the table below:

 

Control

Attributes

RadBinaryImage

Role: img

Aria-label

Aria-atomic

Note

An issue with the use of WAI-ARIA in HTML documents is that they don’t validate. When you run a HTML document containing ARIA attributes through the W3C Validator it shows errors in the results for any ARIA attributes. The DOCTYPE declarations do not include any information about the WAI ARIA attributes and you cannot have a valid document which includes elements, attributes, and attribute values, not detailed in its DTD’s.

Unsupported scenarios

By default the RadBinaryImage control stores the BinaryImage in the Cache object. In case your application is configured to run in any of the environments, listed below, there will be a problem accessing the binary image:

  • Web Farm - The application runs on more than one web server at the same time.

  • Web Garden - The application runs on a single server, but the server load is divided among many worker processes (more than one process are running the same application).

Usually, every server (or every worker process) has an independent Cache, which means that, when the page request is not handled by the same web server (worker process), the BinaryImage will be null and a gray image will be shown.