3.6 CustomReportItem

  • Article

The following is an example RDL definition of a CustomReportItem for Schema version RDL 2008/01 of the element, with its data. The example is based on the Microsoft Polygons example available at [MSDN-RDLDT]. The rendered snippet is pictured in the following figure.

A data source is defined as embedded XML.

Figure 15: A data source is defined as embedded XML.

 <DataSources>
   <DataSource Name="PolygonsData">
     <ConnectionProperties>
       <DataProvider>XML</DataProvider>
       <ConnectString />
     </ConnectionProperties>
   </DataSource>
 </DataSources>

A single DataSet element is defined with five Fields elements, named in both the Query and the Report as "Object", "Color", "Point", "X", and "Y".

 <DataSets>
   <DataSet Name="DataSet1">
     <Fields>
       <Field Name="Object">
         <DataField>Object</DataField>
       </Field>
       <Field Name="Color">
         <DataField>Color</DataField>
       </Field>
       <Field Name="Point">
         <DataField>Point</DataField>
       </Field>
       <Field Name="X">
         <DataField>X</DataField>
       </Field>
       <Field Name="Y">
         <DataField>Y</DataField>
       </Field>
     </Fields>
     <Query>
       <DataSourceName>PolygonsData</DataSourceName>

The Query.CommandText element contains the XML. Note that the XML brackets ("<" and ">") have had to be replaced with encoded versions ("&lt;" and "&gt;") to avoid confusing an RDL reader. The following table illustrates the data.

Query.CommandText data table example

Figure 16: Query.CommandText data table example

       <CommandText>
 &lt;Query&gt;
   &lt;XmlData&gt;
     &lt;Rows&gt;
       &lt;Row&gt;
         &lt;Object&gt;1&lt;/Object&gt;&lt;Color&gt;Red&lt;/Color&gt;
         &lt;Point&gt;1&lt;/Point&gt;&lt;X&gt;75&lt;/X&gt;&lt;Y&gt;75&lt;/Y&gt;
       &lt;/Row&gt;
       &lt;Row&gt;
         &lt;Object&gt;1&lt;/Object&gt;&lt;Color&gt;Red&lt;/Color&gt;
         &lt;Point&gt;2&lt;/Point&gt;&lt;X&gt;75&lt;/X&gt;&lt;Y&gt;175&lt;/Y&gt;
       &lt;/Row&gt;
       &lt;Row&gt;
         &lt;Object&gt;1&lt;/Object&gt;&lt;Color&gt;Red&lt;/Color&gt;
         &lt;Point&gt;3&lt;/Point&gt;&lt;X&gt;175&lt;/X&gt;&lt;Y&gt;175&lt;/Y&gt;
       &lt;/Row&gt;
       &lt;Row&gt;
         &lt;Object&gt;1&lt;/Object&gt;&lt;Color&gt;Red&lt;/Color&gt;
         &lt;Point&gt;4&lt;/Point&gt;&lt;X&gt;175&lt;/X&gt;&lt;Y&gt;75&lt;/Y&gt;
       &lt;/Row&gt;
       &lt;Row&gt;
         &lt;Object&gt;2&lt;/Object&gt;&lt;Color&gt;Blue&lt;/Color&gt;
         &lt;Point&gt;1&lt;/Point&gt;&lt;X&gt;75&lt;/X&gt;&lt;Y&gt;25&lt;/Y&gt;
       &lt;/Row&gt;
       &lt;Row&gt;
         &lt;Object&gt;2&lt;/Object&gt;&lt;Color&gt;Blue&lt;/Color&gt;
         &lt;Point&gt;2&lt;/Point&gt;&lt;X&gt;25&lt;/X&gt;&lt;Y&gt;112&lt;/Y&gt;
       &lt;/Row&gt;
       &lt;Row&gt;
         &lt;Object&gt;2&lt;/Object&gt;&lt;Color&gt;Blue&lt;/Color&gt;
         &lt;Point&gt;3&lt;/Point&gt;&lt;X&gt;125&lt;/X&gt;&lt;Y&gt;112&lt;/Y&gt;
       &lt;/Row&gt;
     &lt;/Rows&gt;
   &lt;/XmlData&gt;  
 &lt;ElementPath&gt;Rows/Row{Object(Integer),Color(String),Point(Integer),X(Integer),Y(Integer)}&lt;/ElementPath&gt;
 &lt;/Query&gt;
       </CommandText>
     </Query>
   </DataSet>
 </DataSets>

The CustomReportItem element has its CustomReportItem.Name attribute set to "customReportItem1". It is set to 0.125 inches from the top of its containing object (either the Body or a report item) and, because no CustomReportItem.Left element is defined, the position of its left is the position of the left of its containing object. The custom report item will be 2 inches high and 10 centimeters wide.

 <CustomReportItem Name="customReportItem1">
  
   <Top>0.125in</Top>
   <Height>2in</Height>
   <Width>10cm</Width>

The CustomReportItem.Type of the element is set to a name recognizable by the rendering engine, so that custom code to render this item can be utilized. The CustomData.DataSetName element points to the prepared data.

   <Type>Polygons</Type>
   <CustomData>
     <DataSetName>DataSet1</DataSetName>

A CustomData.DataColumnHierarchy element is required to be defined, although this example only has one column hierarchy, which covers all rows.

     <DataColumnHierarchy>
       <DataMembers>
         <DataMember />
       </DataMembers>
     </DataColumnHierarchy>

The DataRowHierarchy element is also mandatory and in this case uses a two-level hierarchy to separate the two objects, so that the lower hierarchy is processed for each object in turn.

     <DataRowHierarchy>
       <DataMembers>

The outer DataMember element is specified with a Group that is named "Object", which groups on the value of the Object field. The DataMember has two CustomProperty elements defined. The name of these custom properties is only relevant to the custom code, which looks for and matches "poly:Color" and "poly:Hyperlink". The value of the first custom property is set to the value of the Color field from the data set; the value of the second custom property is set to a URL that is intended to be set as the Action of an Image that the custom code will create.

         <DataMember>
           <Group Name="Object">
             <GroupExpressions>
               <GroupExpression>=Fields!Object.Value</GroupExpression>
             </GroupExpressions>
           </Group>
           <CustomProperties>
             <CustomProperty>
               <Name>poly:Color</Name>
               <Value>=Fields!Color.Value</Value>
             </CustomProperty>
             <CustomProperty>
               <Name>poly:Hyperlink</Name>
               <Value>http://microsoft.com</Value>
             </CustomProperty>
           </CustomProperties>

Within the outer DataMember element, an inner DataMembers collection is specified. A single DataMember descendant is specified.

           <DataMembers>
             <DataMember>

A Group element is specified so that a sort can be defined. Since the data is known to be good, no grouping expression is specified. The data is sorted on the value of the Point field.

               <Group Name="Point" />
               <SortExpressions>
                 <SortExpression>
                   <Value>=Fields!Point.Value</Value>
                 </SortExpression>
               </SortExpressions>
             </DataMember>
           </DataMembers>
         </DataMember>
       </DataMembers>
     </DataRowHierarchy>

There is only one leaf DataMember in the DataRowHierarchy, so there is only one DataRow element specified. The row has two cells in it, specifying X and Y data based on the value of the X and Y fields.

     <DataRows>
       <DataRow>
         <DataCell>
           <DataValue>
             <Name>X</Name>
             <Value>=Fields!X.Value</Value>
           </DataValue>
           <DataValue>
             <Name>Y</Name>
             <Value>=Fields!Y.Value</Value>
           </DataValue>
         </DataCell>
       </DataRow>
     </DataRows>
   </CustomData>

Further values are specified for the custom code by using a CustomProperties element to define four name/value pairs. Again, the value of the Name element is required to be matched in code and has no relevance to any namespace. The value of each Value element could be expressed as a literal or as an expression.

   <CustomProperties>
     <CustomProperty>
       <Name>poly:MaxX</Name>
       <Value>200</Value>
     </CustomProperty>
     <CustomProperty>
       <Name>poly:MinX</Name>
       <Value>0</Value>
     </CustomProperty>
     <CustomProperty>
       <Name>poly:MaxY</Name>
       <Value>200</Value>
     </CustomProperty>
     <CustomProperty>
       <Name>poly:MinY</Name>
       <Value>0</Value>
     </CustomProperty>
   </CustomProperties>

A Style element specifies a background color that the custom code can use. It also specifies a default foreground color for the custom code to use. The empty Border element has no effect.

   <Style>
     <Border />
     <BackgroundColor>Yellow</BackgroundColor>
     <Color>Red</Color>
   </Style>
  
 </CustomReportItem>