ColumnChartComponent

Introduction

ColumnChartComponent is a view component that renders column charts (i.e., vertically oriented bars) with a single data series. It takes only one parameter, "properties" of type Castle.Monorail.ViewComponents.ChartProperties. ChartProperties holds the chart's data source along with various settings that control how the chart is rendered. The data source can be of type IDictionary<object, decimal> or IList<Castle.Monorail.ViewComponents.ChartDataItem>. The appearance of the chart is controlled using a combination of ChartProperties, CSS classes and view component sections.

A Simple Example

The view:

#component(ColumnChart with "properties=$myChart")

The controller code:

IDictionary<object, decimal> data = new Dictionary<object, decimal>();
data.Add("East", 45m);
data.Add("Central", 18m);
data.Add("South", 38m);
data.Add("West", 29m);

ChartProperties props = new ChartProperties(data);

PropertyBag["myChart"] = new ChartProperties(data);

There's one more thing we must do to make the bars visible. Add a CSS class that sets the bar color, like so:

.chart .bar
{
   background-color: #0000ff;
}

Controlling The Chart With Properties

You can control the a ColumnChartComponent using the ChartProperties parameter. The members are:

• Data (read only, set via the constructor)
• Title
• LabelFormat
• EmptyMessage
• BarWidthPixels
• BarSpacingPixels
• ShowDataLabels
• PlotHieghtPixels
• XUnitLabel
• YUnitLabel
• ItemCount (read only)
• CssClass
• ShowGridlines
• LabelInterval

Detailed descriptions of these properties and their defaults are provided via intellisense. Note that Title and EmptyMessage can contain HTML as well plain text.

Also note, the constructor takes either an IDictionary<object, decimal> or an IList<ChartDataItem>. With the former, each item's key represents the 'X' axis label corresponding to the value. Duplicate keys are not allowed in a generic IDictionary; therefore, take care to use this constructor only if you are certain the data source will never contain duplicate labels.

Styling The Chart

Using CSS you can control several aspects of chart appearance. By default the chart is contained within a div element with the CSS class of "chart." However, you may wish to alter this. For example, your application may have several types of charts, each with a different look. You can specify the class for any chart using the CssClass property of ChartProperties. You can also specify the CSS class in the containerStart section (discussed below).

ColumnChartComponent assigns certain CSS classes to certain elements. You cannot change these. They are:

Probably the trickiest aspect of using ColumnChartComponent is setting the CSS styles correctly. Some trial and error is inevitable. See A More Advanced Example below for some guidance. Also, the sample website contains some helpful examples:

http://svn.castleproject.org:8080/svn/castlecontrib/viewcomponents/trunk

Tips

• To set the background of the plot area, set the background-color attribute of the plot-area-column, plot-area-left-margin and plot-area-right-margin classes.

• To set the color of the borders around the plot area, set the border-color attribute of the plot-area-column, plot-area-left-margin and plot-area-right-margin classes.

• To achieve a line at the top of the plot area, set the border-top-style attribute of the plot-area-column, plot-area-left-margin and plot-area-right-margin classes.

• To achieve a line at the right of the plot area, set the border-right-style attribute of the plot-area-right-margin class.

• Without any styling, the X and Y axis unit labels will appear close to the axis, probably interfering with the axis labels. To position them appropriately set the padding-top attribute of the x-unit-label class and the and padding-right attribute of the y-unit-label.

Controlling The Chart Using Sections

For even more flexibility, you can use sections to control the chart. ColumnChartComponent supports the following sections:

• containerStart
• containerEnd
• title
• empty
• xUnitLabel
• yUnitLabel

NOTE: Sections trump corresponding properties in all cases. For example, if you set the chartProps.Title = "My Title" then have a title section that contains "Some Title" then the title of the chart will be "Some Title."

For examples of using sections, take a look at the sample website here:

http://svn.castleproject.org:8080/svn/castlecontrib/viewcomponents/trunk

A More Advanced Example

You might want to reuse a chart at various places in you application. Lets say that a certain kind of chart should always be the same except for the data, the label interval and the title. One approach is to subclass ChartProperties and also use sections.

The subclass:

public class BurndownChartProperties: ChartProperties
{
    public BurndownChartProperties(IDictionary<object, decimal> data)
    {
        BurndownChartProperties(data, 7);
    }

    public BurndownChartProperties(IDictionary<object, decimal> data, int labelInterval) : base(data)
    {
        DataFormat = "#,##0";
        CssClass = "burndown";
        GridUnit = 20;
        BarSpacingPx = 1;
        PlotHeightPixels = 300;
        LabelFormat = "M/dd/yy (ddd)";
        BarWidthPixels = 10;
        LabelInterval = 7;
        Title = "Burndown";
        XUnitLabel = "Day";
        YUnitLabel = "Rem-<br/>aining";
    }
}

Then in the controller:

BurndownChartProperties props =
     new BurndownChartProperties(project.BurndownData());
PropertyBag["burndownProps"] = props;
PropertyBag["projectName"] = project.Name;

Notice that we assign a "default" title in the BurndownChartProperties class. However, suppose in some instances we want a different title with some special formatting. Use a section in the view:

#blockcomponent(ColumnChart with "properties=$burndownProps")
   #title
      <div style="font-size:19px; color:red;">Burndown</div>
      <div style="font-size:8px; color:blue;">For Project $projectName</div>
   #end
#end

Notice also, in BurndownChartProperties we specified a CssClass of "burndown." We need to add some CSS. For example:

/* set columns green */
.burndown .bar
{
   background: #009900;
}

/* set gridlines light gray and dotted */
.burndown .gridline
{
   border-top-style: dotted;
   border-color: #999;
}

/* set plot area ghost white */
.burndown .plot-area-column,
.burndown .plot-area-left-margin,
.burndown .plot-area-right-margin
{
   background-color: #f8f8ff;
}

/* set axis labels and unit labels a bit small */
.burndown .x-unit-label,
.burndown .y-unit-label,
.burndown .x-label,
.burndown .y-label
{
   font-size: 0.8em;
}

/* set axis unit labels bold */
.burndown .x-unit-label,
.burndown .y-unit-label
{
   font-weight: bold;
}

/* move the x unit label down from the X axis */
.burndown .x-unit-label
{
   padding-top: 4em;
}

/* move the Y unit label left from the Y axis */
.burndown .y-unit-label
{
   padding-right: 2.5em;
}

In this manner, "burndown chart" will have a consistent look across the application.

Known Limitations

• ColumnChartComponent does not accurately handle negative values. Negative items will appear with no bar. The data label, if displayed, will show the correct value, however.

• A ColumnChartComponent chart cannot be placed inside of a horizontally scrolling container. The X axis labels will not appear inside the container and will not scroll with the rest of the chart.

Future

Just a note to potential contributors. ColumnChartComponent already begs for certain enhancements:

• full support for negative values
• support for multiple data series (side-by-side bars and/or stacked bars)

It would be nice to be able to flip the orientation of the bars (horizontal bars). This might probably be a whole different component, call it BarChartComponent.