Telerik Extensions for ASP.NET MVC

This help topic discusses the client-side API and events exposed by Telerik Chart for ASP.NET MVC.

Prerequisites

Important

All Telerik UI components need a ScriptRegistrar component in order to output their JavaScript objects and register their JavaScript files. The ScriptRegistrar component should be defined *after* all other UI components in the page. If you create the components on the client-side and do not use the MVC extensions, you need to manually register all requried JavaScript files. For further information check this help topic (Step 4 - Register Scripts)

Client object

How to get the Chart client object

The Chart client object is preserved in the data store for the Chart element.

Here is a code snippet showing how to retrieve the client object of the Chart.

CopyView
<%= Html.Telerik().Chart(Model)
    .Name("chart")
    .Theme("Black")
    .Series(series => {
            series.Bar(s => s.RepSales).Name("Representative Sales");
    })
%>
CopyJavaScript
<script type="text/javascript">
    function getChart(){
        // #chart is a jQuery selector based on the "id" attribute of the Chart.
        // The id is set using Name()
        var chart = $("#chart").data("tChart");
        return chart;
    }
</script>

Client object options

The Chart configuration, including the declared series, are available through the options object.

Changes to the options will be applied when calling refresh.

CopyJavaScript
<script type="text/javascript">
    function setTitle(){
        var chart = $("#chart").data("tChart");
        chart.options.title.text = "Stats for May '11";
        chart.refresh();
    }
</script>

The full set of options is accessible through the Chart MVC extension method.

The following options are commonly accessed on the client-side:

theme

Sets Chart theme.

title

The chart title configuration options.

text

The title of the chart.

valueAxis

The value axis configuration options.

axisCrossingValue

Value at which the first perpendicular axis crosses this axis.

min

The minimum value of the axis.

max

The maximum value of the axis.

majorUnits

The interval between major divisions.

categoryAxis

The category axis configuration options.

categories

Array of category names.

axisCrossingValue

Category index at which the first perpendicular axis crosses this axis.

series

Array of series definitions.

name

The series name visible in the legend.

data

Array of inline data points. The type of each item depends on the type of series.

bar, column and line

A number

scatter, scatter line

Array of two numbers [x, y]

pie

Object with the following members:

value

The sector value.

category

The sector category that is shown in the legend.

color

The sector color.

explode

A boolean value indicating whether to explode the sector.

CopyJavaScript
<script type="text/javascript">
    function addXYPoint(){
        var chart = $("#chart").data("tChart");
        var data = chart.options.series[0].data;
        data.push([1, 2]);
        chart.refresh();
    }
</script>

Client events

Telerik Chart for ASP.NET MVC exposes the following client-side events

  • OnLoad - raised when the Chart is initialized.
  • OnDataBound - raised when the Chart has received data via Ajax binding and is about to render it.
  • OnSeriesClick - raised when the user clicks a data series point.
  • OnError - raised when the data binding operation has failed.

OnLoad

The OnLoad event is raised when the Chart is initialized. Here is a short example showing how to handle that event:
CopySubscribing to the OnLoad event
<%= Html.Telerik().Chart(Model)
    .Name("chart")
    .Theme("Black")
    .Series(series => {
            series.Bar(s => s.RepSales).Name("Representative Sales");
    })
    .ClientEvents(events => events
        .OnLoad("onLoad")
    )
%>
CopyHandling the OnLoad event
<script type="text/javascript">
    function onLoad(e) {
        // The chart is now initialized
    }
</script>

OnDataBound

The OnDataBound event is raised when the Chart has received data via Ajax binding and is about to render it. Here is a short example showing how to handle that event:
CopySubscribing to the OnDataBound event
<%= Html.Telerik().Chart(Model)
    .Name("chart")
    .Theme("Black")
    .Series(series => {
            series.Bar(s => s.RepSales).Name("Representative Sales");
    })
    .ClientEvents(events => events
        .OnDataBound("onDataBound")
    )
%>
CopyHandling the OnDataBound event
<script type="text/javascript">
    function onDataBound(e) {
        // Series data is now available
    }
</script>

OnSeriesClick

The OnSeriesClick event is raised the user clicks a data series point.

Event arguments:

  • value - the data point value
  • category - the data point category
  • series - the clicked series. An object containing the following fields:
    • type - the series type
    • name - the series series
    • data - the series data points
    • other, series-specific properties
  • element - the DOM element of the data point
  • dataItem - the data source object corresponding to the point

Here is a short example showing how to handle that event:
CopySubscribing to the OnSeriesClick event
<%= Html.Telerik().Chart(Model)
    .Name("chart")
    .Theme("Black")
    .Series(series => {
            series.Bar(s => s.RepSales).Name("Representative Sales");
    })
    .ClientEvents(events => events
        .OnSeriesClick("onSeriesClick")
    )
%>
CopyHandling the onSeriesClick event
<script type="text/javascript">
    function onSeriesClick(e) {
        alert("Clicked value: " + e.value);
    }
</script>

OnError

The OnError event is raised when the Ajax binding has failed.

Event arguments:

  • XMLHttpRequest - the current XMLHttpRequest object

Here is a short example showing how to handle that event:
CopySubscribing to the OnDataBound event
<%= Html.Telerik().Chart(Model)
    .Name("chart")
    .Theme("Black")
    .Series(series => {
            series.Bar(s => s.RepSales).Name("Representative Sales");
    })
    .DataBinding(dataBinding => dataBinding
        .Ajax().Select("_SalesData", "Chart")
    )                                
    .ClientEvents(events => events
        .OnError("onError")
    )
%>
CopyHandling the OnDataBound event
<script type="text/javascript">
    function onError(e) {
        // Supress error message
        e.preventDefault();
    }
</script>

Client Methods

Telerik Chart for ASP.NET MVC exposes the following client-side methods:

refresh

The refresh method repaints the chart.
CopyJavaScript
<script type="text/javascript">
    var chart = $('#chart').data('tChart');
    chart.refresh();
</script>

rebind

The rebind method rebinds a client-side bound chart. You can pass additional arguments to the action method method using rebind.
CopyJavaScript
<script type="text/javascript">
    var chart = $('#chart').data('tChart');
    chart.rebind({ userId: 42 }});
</script>

svg

The svg exports the current view in SVG format. The returned string is a self-contained SVG document that can be used as is or converted to other formats using tools like Inkscape and ImageMagick . Both programs provide command-line interface suitable for backend processing.
CopyJavaScript
<script type="text/javascript">
    var chart = $('#chart').data('tChart');
    var svg = chart.svg();

    $.post("/myapp/export-service", svg, function(data) {
        $(document.body).append(
            $("<img />", { src: data })
        );
    });
</script>