Formatting/Changing Data Before Loading

Basic Formatting Methods

In case you need to update values which were returned from database table or set some specific formatting before sending them to the client side, you can use the ItemPrerender event.

A common use-case will be similar to the following:

dhtmlxGridConnector connector = new dhtmlxGridConnector(/*...*/);
connector.ItemPrerender += new EventHandler<ItemPrerenderEventArgs<dhtmlxGridDataItem>>
(connector_ItemPrerender);
 
void connector_ItemPrerender(object sender,ItemPrerenderEventArgs<dhtmlxGridDataItem> e)
   {
      if (e.DataItem.Index % 2 == 0)
      e.DataItem.BgColor = "gray";
   }

Here, we have an event handler attached to the ItemPrerender event that sets background color for each second row. Each connector manipulates its own data item objects inherited from dhtmlxDataItem class. E.g. dhtmlxGridConnector uses dhtmlxGridDataItem, dhtmlxTreeConnector uses dhtmlxTreeDataItem, etc. Each data item class has its own specific properties that you can change. E.g. FolderClosedImage, FolderOpenedImage for dhtmlxTreeDataItem, Selected for dhtmlxComboItem or ChildRows for dhtmlxTreeGridDataItem.

In the same way you can change the appearance of the items and data they will display. The following example will add row indexes to "countries" grid:

public override IdhtmlxConnector CreateConnector(HttpContext context)
{
   dhtmlxGridConnector connector = new dhtmlxGridConnector(
      "Country",
      "ISO, PrintableName",
      "UID",
      dhtmlxDatabaseAdapterType.SqlServer2005, 
      ConfigurationManager.ConnectionStrings["SamplesDatabase"].ConnectionString
   );
 connector.ItemPrerender += new EventHandler<ItemPrerenderEventArgs<dhtmlxGridDataItem>>
 (connector_ItemPrerender);
 return connector;
}
 
void connector_ItemPrerender(
    object sender,
    ItemPrerenderEventArgs<dhtmlxGridDataItem> e
)
{
   e.DataItem.DataFields["PrintableName"] = (e.DataItem.Index + 1).ToString() + ". " + 
   e.DataItem.DataFields["PrintableName"];
}

DataFields dictionary contains a collection of selected fields for the current data item. The index property gets the position of an item in all items collection.

More complex formatting rules can be defined by using "extra" fields in configuration, the fields that won't be outputted to the client but can be used inside of events.

public override IdhtmlxConnector CreateConnector(HttpContext context)
{
   dhtmlxTreeGridConnector connector = new dhtmlxTreeGridConnector(
      "Folders", "item_nm,item_order,item_desc", "item_id", "item_parent_id",
      dhtmlxDatabaseAdapterType.SqlServer2005,
      ConfigurationManager.ConnectionStrings["SamplesDatabase"].ConnectionString
      "is_hidden"//extra field
   );
connector.RootItemRelationIDValue = "0";//set ParentID value for root items
connector.ItemPrerender += new EventHandler
<ItemPrerenderEventArgs<dhtmlxTreeGridDataItem>>(connector_ItemPrerender);
return connector;
}
 
void connector_ItemPrerender(
    object sender,
    ItemPrerenderEventArgs<dhtmlxTreeGridDataItem> e
)
{
   if (e.DataItem.DataFields["is_hidden"] == "1")
   e.DataItem.Skip = true;//do not render folders that have is_hidden attribute
}

In addition to all other fields we request the "is_hidden" field as an extra one. This one will not be rendered, but we can access it via the DataFields collection. The skip property is available in all dhtmlxDataItem class descendants and being set to true indicates that the item will not be rendered.

Userdata

Starting from version 1.5 you get the possibility to set userdata for items.

public override IdhtmlxConnector CreateConnector(HttpContext context)
{
    dhtmlxGridConnector connector = new dhtmlxGridConnector(
    ....
    );
connector.BeforeRender += new EventHandler<ItemPrerenderEventArgs<dhtmlxGridDataItem>>
(connector_ItemPrerender);
return connector;
}
 
void connector_ItemPrerender(object sender,ItemPrerenderEventArgs<dhtmlxGridDataItem> e)
{
    //name - the user data name, value - user data string
 e.DataItem.UserData.Add("name", "value");
 
}

Formatting in Combo

dhtmlxComboDataItem has only 3 properties available for changing: Value, Text and Selected

Formatting in Grid and TreeGrid

Both grid and treeGrid have the CssClass, BgColor, Style properties available for customization in the Prerender event. The CssClass property allows assigning row's CSS class name, whereas the Style property allows separating the style properties assignment. The BgColor property allows you to set row's background color. Additionally, dthmlxTreeGridDataItem has Image, HasChildren and ChildRows. The last two properties allow child rows manipulation. The first one lets to assign a custom image to the first column.

void connector_ItemPrerender(
    object sender,
    ItemPrerenderEventArgs<dhtmlxTreeGridDataItem> e
)
{
   if (e.DataItem.HasChildren)//tree grid row has child rows - output it like a folder
   e.DataItem.Image = "folder.gif";
}

Formatting in Tree

As well as dhtmlxTreeGridDataItem, dhtmlxTreeDataItem has HasChildren and ChildNodes properties. What's more, tree allows assigning FolderOpenedImage, FolderClosedImage and LeafImage images, Checked, Text and Value properties.

In the example below we analyze data passed into the data item and assign the "lock.gif" image to an item if it has the "is_hidden" value.

void connector_ItemPrerender(object sender,ItemPrerenderEventArgs<dhtmlxTreeDataItem> e)
{
   if (e.DataItem.DataFields["is_hidden"] == "1")
   e.DataItem.LeafImage = "lock.gif";
}

The ItemPrerender event also might be used to check if Tree or TreeGrid item has child items. Assigning to the HasChildren property of true or false values changes the way the item will be rendered.