Expression Engine

An expression in computer science is a combination of functions, operators and values (including variables), which can be evaluated according to the programming language's rules.

MatchPoint provides an expression engine that allows the execution of C# statements at runtime. This mechanism allows direct access to the object models of both SharePoint and MatchPoint. Expressions can be used in various places within the MatchPoint configuration files. In combination with the configuration framework, they allow a generic architecture of all MatchPoint components and great flexibility without having to write custom code. In general, MatchPoint expressions follow concepts of object oriented programming. This means, that every object accessible via the MatchPoint Expression Console is of a specified type.

The connection framework, which connects different MatchPoint controls (either Web Parts or fields within Web Parts) is based on the expression engine.

Expression Console

The design of the Expression Console is visually following concepts known from Visual Studio; e.g. there is an IntelliSense-like feature, providing an auto-completion popup on-type.

When a complex expression is formulated, it is usually advisable to test it, before it is used within a configuration. A very comfortable way to do this, is using the expression console. The combination [Ctrl-E] will open the console on any page or dialog box, in the top left corner of the window.

The expression console is available only, if the Colygon.MatchPoint.Core.Infrastructure feature is enabled on the web application, and only for users, that are site collection administrators on the Instance Administration site.
The expression console can be deactivated for all usery by setting the parameter DisableExpressionConsole within the MatchPoint configuration file.

Built-In Expression Variables

MatchPoint provides a number of expression variables that can be accessed from all configuration files. These general variables are listed below. More expression variables that provide functionality for a specific MatchPoint module are described within the corresponding chapters.

Depending on the context of a MatchPoint configuration file, there might be additional expression variables available. For instance, within a Composite Web Part, the current data item can be accessed by using the DataItem expression variable. If a contextual expression variable is available, it is mentioned within the description of the configuration property.

In addition to expression variables, the expression engine supports standard C# features such as static extensions for .NET classes. Further, the engine provides supports for dynamic extensions, which allow accessing to properties and methods on specific instances of a type.

• An example for a static extension is the method SPWeb.GetTags(). It provides access to tags that are applied to that SharePoint site.
• An example for a dynamic extension is the Workspace expression variable. It provides direct access to any metadata field that has been configured for that workspace, i.e. Workspace.Description will return the value of a "Description" metadata field.

Expressions in Configuration Files

Within a Matchpoint configuration file, expressions can be used for a variety of functionalities. For instance, they can be used to access a contextual value (like the current user's name or the current date) and use it for a condition value. Or they can be used to create a pattern where different properties from a result item are combined into one value to be displayed to the user.

Expressions can be used within two kinds of configuration parameters:

• ExpressionString: Evaluates an expression directly and provides the result object for the configuration field.
• PatternString: Uses a placeholder pattern that allows combining expressions with string input

Within a PatternString field, expressions have to be surrounded by curly brackets:

{SPHelper.GetCurrentUser().Name} // evaluates to: "Peter Sample"
Hi, my name is {SPHelper.GetCurrentUser().Name}. // evaluates to: "Hi, my name is Peter Sample."

A PatternString is automatically evaluated when casted to a string.

To simplify the usage of expressions within configuration files, the expression console will be automatically displayed within the configuration editor. For an ExpressionString property, this happens as soon as the field has focus and for a PatternString, the console is displayed when the opening bracket is typed. Please note that it is also possible to call expression variables client side using JavaScript, you can find more information in the chapter Client Side API.

Custom Expression Variables

Custom Expression Variables can be defined using the ExpressionVariable attribute, which is applied to a class. All methods in the class will then be available in the Expression Console. You can define a static or a non-static class. If you define a non-static class you can define a constructor with an argument of type SPWeb. In this case the Expression Variable is initialized with the current web if available.

You can define custom Expression Extensions as well. Define a static class and and decorate it with the ExpressionExtension attribute. The rest works the same as with regular .NET extension methods.

Methods visible in the Expression Console are available from client-side using the $$.Eval or $$.InvokeMethod JavaScript method. Due to security you should disable all client-side calls to Expression Variables. This can be configured in the MatchPoint Configuration. If you have disabled client-side calls you can still override this behavior and all calls to specific custom methods by decorating the methods with the ClientCallableAttribute Class. More information can be found in the Client Side API chapter.

After the class is deployed and registered, it can be used just like the standard MatchPoint expression variables wherever expressions or placeholder patterns are evaluated. When expression variables or -extensions are used within custom code, the assemblies that contain the functionality need to be added as a reference to the project and linked to any code file that uses such functionality.

It is also possible to have dynamic expression variables. These variables are provided through an expression variable factory. The factory makes the variables available depending on the context where an expression is evaluated. In order to provide custom dynamic expression variables, a custom class has to be created, which implements the interface IExpressionVariableFactory.

For more information on how to implement a custom expression variable or -extension, please refer to the MatchPoint API Reference and to the code samples Colygon.MatchPoint.Samples.zip provided with every MatchPoint Release.

Connecting Web Parts

MatchPoint controls – this can be either Web Parts or fields within Web Parts – can access data from other controls using a connection mechanism that is based on MatchPoint's expression engine. The ConnectionData expression variable provides access to all controls available on a page.

To establish a connection, both controls need to be configured with a Name parameter. Therefore, it is required that values for this property are unique within the context of a page. The "consumer" control can then access the "producer" control using a ConnectionData expression. Dependencies are resolved automatically and the dependent control will be refreshed whenever the "source" control changes its value.

The Name property is not required in most cases. If you do not need your Web Part to provide data for another control, you can leave this parameter empty. Also, the connection framework automatically detects whether "consumer" controls are registered for a "producer" control. Therefore, you might not be able to access the values of a "producer" control unless you have configured a "consumer" control.

Within a SharePoint dialog window, you can access ConnectionData objects from the main form in addition to the objects within the dialog. Please keep in mind that this also might lead to naming conflicts.

All MatchPoint Web Parts can be connected to each other, using the Ajax Connection Framework. This allows you for example to easily create master / detail views of your SharePoint content, or to use a selected value of one control as a condition in another control. The configuration of a connection is done using the MatchPoint Expression Engine, where each Web Part / control can be accessed by its name, in the ConnectionData object.

Hence, all connection framework related tasks can easily be tested using the MatchPoint Expression Console.

To prevent accidental deletion of SharePoint webs or other unwanted operations the MatchPoint expression engine suppresses all methods provided by SharePoint.
All operations within the expression engine are evaluated using the credentials of the current user.

ConnectionData Expression Variable

The ConnectionData expression variable provides access to the values of other MatchPoint controls and Web Parts on the same page. Any controls are provided as dynamic properties on the ConnectionData object and can be accessed by using their specified Name parameter. If, for instance, a Data Grid Web Part has been configured with the name DG1, a field of the selected row of that grid could be accessed like this:

ConnectionData.DG1.SelectedRow.Title

Return Types

MatchPoint controls will return different values when they are used as an input field for another control, depending on their general functionality. The following return values are possible:

Accessing SharePoint Fields in Expressions

When SharePoint content (i.e. a SharePoint list item or document) is accessed from the expression engine, any properties/fields that are available on the item can be accessed. For some properties, MatchPoint provides simplified access. The following table gives an overview on extension methods and properties available from the API and the MatchPoint expression engine.

* Only available with Enable30Compatibility (MatchPoint configuration file)
** The SPListItem URL (list-relative) can be obtained using the string indexer []
*** It is recommended not to use EditFormUrl in solutions, because not every user has edit item permissions. Use DisplayFormUrl instead.
**** ListItem.GetFieldValue("Field") will return the same value as ListItem.Field in expressions.

Field Types:

• ListItem is of type SPListItem, SPListItemVersion, SPList or SPWeb
• ResultRecord is of type ISPItem
• Updatable is of type ISPUpdatable