Composite WebPart

The Composite Web Part allows displaying information based on a transformer configuration. This allows creating unique layouts, depending on the requirements of the information to be displayed. The displayed data is aggregated by a data provider.

Important configuration parameters

• The SelectionMode parameter can be used to specify whether users can select rows (one or multiple) from the Composite. Selected rows can be accessed using the ConnectionData expression variable.
• The PageSize parameter specifies whether paging should be enabled. Please note that a value of 0 will disable paging.
• The LoadingMode parameter can be used to specify whether the Composite content should be loaded with the initial page load, after the page is rendered completely or on demand (e.g. by calling $$.InitControl("<Composite Name>") via java script )

Item Templates

Item Templates are an enhancement for the Composite Web Part. The aim is to move the rendering-logic of a result item to a separate configuration-element so it can be reused by different composite configurations. The basic idea is that an item template defines how a specific item should be rendered and the transformer defines the basic HTML-structure of the whole control/web part. Please note that item templates are not a must, you can continue to use the Composite Web Part as before.

There are different kinds of item templates, for example a simple Pattern Item Template, where an HTML-PatternString can be defined which generates the HTML. Or a "User Control Item Template", where a user control can be specified as well as a set of expressions which are evaluated and set to the defined properties on the user control. Custom item templates may be implemented as well. We do this ourselves for example in MatchPoint Snow.

Multiple item templates can be specified per Composite Web Part. Every item template must have aMatchExpression, the first one whose expression evaluates to true is used. This is useful if specific types of result items (e.g. document, task, announcement, etc.) eeds to have their own rendering logic.

When the query is executed, all required columns are extracted from the defined item templates and are retrieved from the data source. Sometimes additional required columns must be specified, for example if they are used internally by expressions which access the DataItem. This can be done in the AdditionalRequiredColumns-member.

In case certain values need to be reused within an item template a VariableDefinition can be added to the Variables-collection.

ItemTemplate Expression Variable

Next to the normal DataItem-ExpressionVariable which has always been available in the scope of a composite transformer, there now is a new ItemTemplateExpressionVariable:

• Use ItemTemplate.GetHtml() to render the HTML
• Use ItemTemplate.Variables.VariableName to access variables defined in the Variables-member
• Use ItemTemplate.Exists to ensure a matching item template has been found

Item Templates can be defined inline or in an own configuration file. To reference an item template defined in an own configuration file, a ReferenceItemTemplate can be used. Variables and the MatchExpression can be overridden here.

Implementing a custom item template

Configuration Class

• Implement IItemTemplate or BaseItemTemplate for a normal item template
• Implement UserControlItemTemplate for an item template which maps on a user control.

Instance class

• Implement IItemTemplateInstance or BaseItemTemplateInstance
• Implement UserControlItemTemplateInstance
  • Override OnBeforeDataBind to perform specific actions

Transformers

Within a Composite Web Part, the Transformer element specifies, how result data from the data provider is transformed into viewable html code. The following transformers are available:

PatternTransformer, XslTransformer and XslFileTransformer can be configured either directly within the configuration of a Composite Web Part, or they can be specified within a dedicated configuration file. This allows specifying a generic configuration, i.e. for displaying SharePoint task items, and then reusing the configuration in various Composite Web Parts with different data providers. Centrally stored transformer configurations can be accessed from a ReferenceTransformer configuration element. Likewise, user controls that might implement custom code for rendering a SharePoint item can be referenced by a UserControlTransformer.

Within the transformer configurations, the DataItem expression variable can be used to access the current result item.

Functionality similar to a Composite Web Part is also available within the CompositeField which can be used in a Form or Workspace Editor Web Part or within a Data Grid Web Part using a CompositeColumn.

PatternTransformer

A PatternTransformer allows specifying plain HTML code for rendering the result item. Within the transformer, HTML can be specified within different template fields:

In these fields, the expression engine can be accessed using the curly bracket operator. Within the templates, the following additional expression variables are available:

• Within the FooterTemplate, the row count of the current result set can be accessed using the RowCount expression variable
• Within the RowTemplate parameter, the RowIndex variable can be used to access the current row index.

To use JavaScript code within a composite pattern field, please escape curly brackets: ``. Furthermore it is required to correctly encode content within a template. Use MPUtility.EncodeHtml, MPUtility.EncodeScript and MPUtility.EncodeUrl accordingly.

If you would like to make items selectable within the Composite Web Part, you can specify a DIV element within the HTML code of the RowTemplate that identifies the selectable elements within your pattern, e.g. <div Selectable='1'>...</div>.

Also, you can add a paging control into the HeaderTemplate or the FooterTemplate: <PagingControl />

This functionality is also available within the XslTransformer, see next section.

XslTransformer

The XslTransformer uses a XSLT template to specify, how results are rendered.

The transformer can be configured with Mapping elements which allow creating mappings between a property on the result item and a XML element available within the XSLT.

XslFileTransformer

The XslFileTransformer implements exactly the same functionality as a XslTransformer. It uses an XSLT template to specify, how results are rendered. The only difference is that the XSLT template is referenced from an external file.

Also, the transformer can be configured with "Mapping" elements which allow creating mappings between a property on the result item and a XML element available within the XSL template.

UserControlTransformer

The UserControlTransformer uses a ASP.NET user control to render result items. This control is referenced using the expression engine.

ReferenceTransformer

A ReferenceTransformer is used to access one of the following transformer configurations:

• PatternTransformer
• XslTransformer
• XslFileTransformer

This allows reusing the same configurations (specified within a separate MatchPoint configuration file) within various Web Parts.