Telerik blogs

Intro

You might have already noticed the change in Telerik's ASP.NET Chart based on HTML5 in Q2 2013 Beta - the introduction of the new SeriesItems collection, which is used for creating series items that are specific for the chosen chart type. This property comes as a replacement for the obsolete Items collection. Follow through this blog post to find out how easy it is to do the transition to the new and improved SeriesItems!

Why did we introduce the SeriesItems collection?

There are many reasons why we introduced the new SeriesItems collection. The main points are:

  • Making the configuration of the RadHtmlChart a lot easier.
  • Creating series items which are specific for the corresponding series type – this means that you are able to set only the necessary data properties you want. As the obsolete Items collection is populated with only one series item type (SeriesItem), you should always ask yourself “Do I need this property in my case? Can I use the Open, Close, High and Low properties in a Bar chart or they are only applicable for a Candlestick chart?” Now that you have the new SeriesItems collection, you should not worry about answering these questions.

I want to switch to the new SeriesItems collection. How can I do that?

Using the SeriesItems collection in the markup.

Let’s say we have created our RadHtmlChart entirely in the markup and we have used the obsolete Items property to populate the series items in BarSeries. This should look like this:

<telerik:BarSeries>
    <Items>
        <telerik:SeriesItem YValue="35" />
        <telerik:SeriesItem YValue="60" />
        <telerik:SeriesItem YValue="40" />
    </Items>
</telerik:BarSeries>   

In order to convert this example, all we need to do is to replace the obsolete Items property with the SeriesItems collection and use the new telerik:CategorySeriesItem item type. This results in:

<telerik:BarSeries>
    <SeriesItems>
        <telerik:CategorySeriesItem Y="35" />
        <telerik:CategorySeriesItem Y="60" />
        <telerik:CategorySeriesItem Y="40" />
    </SeriesItems>
</telerik:BarSeries>

So what’s the benefit after all? Well, the main difference is that the IntelliSense of the telerik:SeriesItem gives us a big list of  properties, which might not be applicable for the BarSeries’ items:

IntelliSense-Items

Fortunately, the telerik:CategorySeriesItem’s IntelliSense shows us only the necessary properties that we can use:

IntelliSense-SeriesItems

Populating the SeriesItems collection programmatically.

Replacing the obsolete Items collection with the new SeriesItems property in the code-behind is also very easy. Suppose that we have created a ColumnSeries in the markup:

<telerik:RadHtmlChart runat="server" ID="ColumnChart">
    <PlotArea>
        <Series>
            <telerik:ColumnSeries></telerik:ColumnSeries>  
        </Series>
    </PlotArea>
</telerik:RadHtmlChart>

In order to create the series items programmatically, we should cast the type of the series explicitly to get access to its SeriesItems collection as it is specific for the corresponding series type:

ColumnSeries firstColumnSeries = ColumnChart.PlotArea.Series[0] as ColumnSeries;

Now, let’s populate some data in three different ways:

firstColumnSeries.SeriesItems.Add(new CategorySeriesItem(10));
firstColumnSeries.SeriesItems.Add(20, System.Drawing.Color.Green);
firstColumnSeries.SeriesItems.Add(30);

Do you see anything new? That’s right, we can add a CategorySeriesItem (which is specific for the ColumnSeries) instead of the old SeriesItem, but we get something more as well–the ability to set the item’s background color. This is also a new feature introduced in the Q2 2013 Beta release, so go ahead - colorize you chart, colorize yourself!

In addition, if we want to add one more ColumnSeries, then we can go this way:

ColumnSeries secondColumnSeries = new ColumnSeries();
secondColumnSeries.SeriesItems.Add(new CategorySeriesItem(15));
secondColumnSeries.SeriesItems.Add(25, System.Drawing.Color.Blue);
secondColumnSeries.SeriesItems.Add(5);
ColumnChart.PlotArea.Series.Add(secondColumnSeries);

As you probably expected, the code snippet uses the previous approach of populating CategorySeriesItems. Finally, we simply add the ColumnSeries to the chart’s PlotArea and we are done! This is our final result:
Chart-Preview

The new series item types on the horizon

The SeriesItems collection allows you to set only the necessary series items for your RadHtmlChart. The full list of the new series items and the corresponding series type looks like this:

Series type

Series item

Candlestick

telerik:CandlestickSeriesItem

Bar, Column, Area, Line

telerik:CategorySeriesItem

Scatter, ScatterLine

telerik:ScatterSeriesItem

Bubble

telerik:BubbleSeriesItem

Pie, Donut

telerik:PieSeriesItem


Introducing these series item types in your code is very intuitive so the transition to the new SeriesItems property takes as little effort as possible.

Migrate to the new SeriesItems collection!

We encourage you to take advantage of the new SeriesItems collection and start using it today.  As the Items property has become obsolete in Q2 2013 Beta, this is the best way to stay up-to-date with the latest functionality!


About the Author

Stamo Gochev

Stamo Gochev is a software developer at Telerik's ASP.NET AJAX division, where he is responsible for the development of the RadHtmlChart. His main interests include ASP.NET, JavaScript, TDD and applying agile practices in his work. In his free time, Stamo likes to go out with friends and watch quiz shows.

Related Posts

Comments

Comments are disabled in preview mode.