User Controls

MatchPoint provides a mechanism that allows implementation and usage of ASP.NET user controls. These controls can be registered within the MatchPoint configuration file and are then available throughout the MatchPoint environment.

A custom MatchPoint user control is essentially a standard ASP.NET user control (.ascx file), with some additional functionality:

  • By using a MatchPoint base class for a control, the expression engine and the connection framework are available.
  • User controls can easily be referenced from the MatchPoint Web Part Configurations, e.g. within a Composite Web Part, for rendering data within that control.

For general information on ASP.NET user controls, please refer to the corresponding MSDN article.

Implementing User Controls

User controls can be implemented in two different ways:

  • By deploying an .ascx file to the 15 hive. In this case, the solution path has to be registered within the MatchPoint configuration file (see Registering User Controls for more details).
  • By creating a MatchPoint configuration file of the type UserControlConfiguration. These user controls will be compiled and made be available within all MatchPoint controls.

If you are implementing a user control, you might need to change settings within the web.config file regarding compilation settings and assemblies that are to be included. This has to be done for any web applications that are using the control. Please refer to the document MatchPoint Installation Guide for more information.

Generally, an ASP.NET user control is implemented by extending System.Web.UI.UserControl. For information on this class, please refer to the MSDN article.

MatchPoint provides two additional classes that can be extended:

TemplateControl Class Implements functionality for using the expression engine
DataItemTemplateControl Class Implements functionality for using the expression engine
Provides functionality for accessing the DataItem object within ASP.NET code
Extendable classes for UserControls

You can use the expression engine, including the DataItem expression variable, in any user control that extends one of the above classes. For more information on these classes, please refer to the MatchPoint API Reference.

Using Expressions

Any user control that extends one of the classes above can access the MatchPoint expression engine. One basic way of including expressions into a control classes is the Expr method, e.g.:

<%= Expr("SPHelper.GetCurrentUser().Name") %>

Within code, expressions can also be accessed using the Expr method. Alternatively, the object model can be used. The "DataItemTemplateControl" class has a property DataItem that provides access to the current data record:

Accessing DataItem within a DataItemTemplateControl

<%
  object o = Expr("DataItem.Property1.Substring(0,1)");
  string url = (this.DataItem as ISPItem).Url;
%>

Please note that properties from a data item cannot be extracted automatically when using the <%= %> syntax or when using the object model. Therefore, required properties and fields have to be added manually by overriding the AddRequiredColumns method within the ASP.NET control:

Adding fields by overriding AddRequiredColumns:

<script runat="server">
  public override void AddRequiredColumns(string varName, RequiredColumnCollection columns)
  {
    if (varName == "DataItem")
    {
      columns.Add("Column1");
    }
    base.AddRequiredColumns(varName, columns);
  }
</script>

The examples show how to access the DataItem expression variable. Naturally, other expressions can be used as well.

Example, calling an expression variable:

<%#= SPHelper.GetCurrentUser().Name %>

Using the Repeater Element

For configurations with a data source, it is recommended to use the Repeater class within the ASP.NET user control. It provides functionality for a user control that renders a repeating pattern, including a header- and a footer template. Also, this class supports ASP.NET binding.

The Repeater class is not meant to be extended. It can be used, however, from ASP.NET code.

Properties and fields from a result record can be accessed within ASP.NET bindings in two ways:

<a href="<%# Expr("DataItem.Url") %>"><%# Expr("DataItem.Title") %></a>
<a href="<%#MP: DataItem.Url %>"><%#MP: DataItem.Title %></a>

Both examples make use of the ASP.NET <%# %> syntax and provide identical functionality. Using the <%#MP: %> syntax simplifies the declaration of expressions (no quotations are required). However, this syntax will not be recognized by the IDE, e.g. Visual Studio.

MatchPoint will automatically extract the properties/fields used within DataItem expressions of the user control, including any child controls that also use the DataItem expression variable. These fields will automatically be included as query columns on the data source.

The following example illustrates how a "Repeater" element can be used within an ASP.NET control:

<%@ Control Language="C#" Debug="true" AutoEventWireup="true" Inherits="Colygon.MatchPoint.Core.UserControls.Controls.DataItemTemplateControl, Colygon.MatchPoint, Version=4.0.0.0, Culture=neutral, PublicKeyToken=c1901c20b4a53672" %>
<%@ Register TagPrefix="mp" Namespace="Colygon.MatchPoint.Core.UserControls.Controls" Assembly="Colygon.MatchPoint, Version=4.0.0.0, Culture=neutral, PublicKeyToken=c1901c20b4a53672" %>
<%@ Assembly Name="System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" %>
<mp:Repeater runat="server" ID="Repeater">
 <HeaderTemplate>
  <table class="table">
   <tr>
    <td width="300"><b>Title</b></td>
    <td><b>Duration</b></td>
   </tr>
 </HeaderTemplate>
 <RowTemplate>
  <tr>
   <td><%#MP:DataItem.Title %></td>
   <td><a href="<%#MP:DataItem.Url %>">open item</a></td>
  </tr>
 </RowTemplate>
 <FooterTemplate>
  </table>
 </FooterTemplate>
</mp:Repeater>

Please note following details:

  1. The user control extends DataItemTemplateControl, therefore the expression engine and the DataItem expression variable can be used.
  2. The namespace Colygon.MatchPoint.Core.UserControls.Controls is registered as a tag prefix for simplified access to the Repeater control
  3. Within the Repeater control, a HeaderTemplate, RowTemplate and FooterTemplate are used. You can also declare an EmptyDataTemplate that specifies rendering logic if no data item is available.

The usage of the "Repeater" control within an ASP.NET user control is similar to the usage of a "PatternTransformer" within a Composite Web Part, including support for using a paging control and for accessing the row index:

...
<RowTemplate>
 <div style='background-color: <%#MP: RowIndex % 2 == 0 ? "#eee" : "#fff" %>'>...</div>
</RowTemplate>
<FooterTemplate>
 <mp:PagingControl runat="Server"/>
</FooterTemplate>
...

Cascading Repeater

It is possible to create structures with nested repeater elements by a variable name and an expression for the data source. The inner repeater has to use a different identifier for the DataItem expression variable.

<mp:Repeater runat="server">
 <HeaderTemplate>
  <table width="100%">
 </HeaderTemplate>
 <RowTemplate>
  <tr>
   <td><%#MP: DataItem.Title %></td>
   <td>
    <mp:Repeater runat="server" VariableName="rel" Expression="DataItem.Related">
     <RowTemplate><%# MP: rel.Title %></RowTemplate>
    </mp:Repeater>
   </td>
  </tr>
 </RowTemplate>
 <FooterTemplate>
  </table>
 </FooterTemplate>
</mp:Repeater>

Structuring User Controls

Repeating elements within a user control and template controls can be separated into other .ascx files. These inner controls can be referenced using the standard ASP.NET mechanism. This also allows providing values for the inner control using property binding:

<InnerControl Property='<%# Expr("DataItem.Field1") %>'/>
<InnerControl Property='<%#MP: DataItem.Field1 %>' />

Field references (DataItem expressions) within the inner control will be automatically detected and added to the required query columns if used within a Repeater control and if used within bindings (<%# %> syntax).

Registering User Controls

If you are using an ASP.NET user control within MatchPoint, it has to be deployed to the 15 hive, within the LAYOUTS folder. Within the MatchPoint configuration file, the name of the solution folder has to be specified. Within that folder, the following subfolders can be created:

  • The folder \css can contain stylesheets. These files will automatically be included if the solution is registered.
  • The folder \scripts can contain JavaScript files. Again, these files will be available automatically if the solution is registered.
  • The folder \usercontrols can contain custom ASP.NET user controls.

This can be registered manually, via a custom solution or via your own registration logic (e.g. with a feature receiver).

<SolutionPaths><Path>Colygon.MatchPoint.Samples</Path></SolutionPaths>

MatchPoint will automatically detect namespace declarations within the file name (using the . separator) and make solutions (especially user controls) available for the correct namespace.

User Control Configuration File

Instead of implementing a user control and deploying it to the 15 hive, it can be defined within a UserControlConfiguration file. Within the configuration file, a user control is implemented exactly as a standard ASP.NET user control.

This configuration file also provides a simple solution for quick deployment of custom expression variables: any public methods and properties implemented on a user control can be accessed everywhere, where MatchPoint expressions are available. That way, no custom assembly has to be deployed and registered.

Referencing User Controls

User controls can be referenced anywhere using the standard mechanisms of ASP.NET:

  • User controls that are deployed to the 15 hive are referenced from their path within the LAYOUTS directory, i.e. \_layouts\MyUserControls\MyUserControl.ascx
  • User controls that are specified within a UserControlConfiguration file can be referenced by their file name. The path is \_layouts\Colygon.MatchPoint.UserControls\MyUserControl.ascx

MatchPoint provides some additional interfaces for referencing user controls:

results matching ""

    No results matching ""