Configuration Framework

MatchPoint uses a unified configuration mechanism that is based on a XML schema and a proprietary XML serializer for storing and reading MatchPoint configuration files. Configurations are used to configure either the MatchPoint Web Parts or a general feature/functionality of MatchPoint that is used throughout the system. While Web Part configurations can alternatively use the standard SharePoint mechanism with a "local" configuration, general feature configurations are always stored within a "central" configuration file. Changes on a central configuration file take effect on all Web Parts that refer to this configuration file.

All administrative operations of MatchPoint, including the management interface for configuration files, are bundled within the feature Colygon.MatchPoint.Core.Administration. This feature needs to be enabled on one site collection that will be used as the "Instance Administration site".

For information on the general installation of MatchPoint and the "Administration" feature, please refer to the MatchPoint Installation Guide.

Configuration File Management

The configuration files used to control MatchPoint are all located within a document library "MatchPoint Configuration", which is automatically created on the Instance Administration site. This document library provides versioning and item-level security for all configuration files. Files are organized in folders according to the type of configuration. For instance, the folder "Data GridConfiguration" contains configuration files for the Data Grid Web Part.

Configuration files can be accessed directly from the "MatchPoint Configuration" document library therefore all MatchPoint configuration files can be edited within a standard XML editor. Also, backing up configuration files or migrating files from one MatchPoint enabled system to another can be done very easily by copying the configuration files from the document library. Another convenient functionality of MatchPoint allows packaging a number of configuration files (and other content) into a SharePoint solution file for easy deployment, i.e. from a staging environment to the productive farm.

The suggested way for editing configuration files is using MatchPoint's integrated configuration editor. It provides a comfortable interface for creating and editing configurations. Also, the created XML code will automatically be verified. The configuration editor can be accessed in different ways:

  • For Web Parts, the editor for a specific configuration file can be accessed directly on the Web Part page, see next section of this chapter.
  • By pressing Ctrl+M on any page within a MatchPoint instance, a management interface can be accessed. This interface provides quick access to all configuration files (This functionality is only available for site collection administrators on the Instance Administration site). The combination Ctrl+Shift+M will open the management interface in a new browser window.
  • The same interface is also available from the "Site Settings" page of the Instance Administration site. The link Manage Configuration Files opens a page that provides access to all configuration files.

On the configuration management page, the following functionalities are available:

  1. The Configuration Files button brings up a list of all configuration files.
  2. The button Timer Jobs opens a form that allows managing the timer jobs on the current MatchPoint instance.
  3. The Provisioning Configurations button opens a form where the MatchPoint provisioning configuration files are listed.
  4. The button Web Application Associations opens a form where additional web applications can be added to the current MatchPoint instance.
  5. The Solution Configurations button opens a form for managing the solution configuration of the current MatchPoint instance.
  6. The Favorite Tag Sets button opens a form for managing favorite tag sets.
  7. The Search Definitions button opens a form that allows managing search definitions for the current MatchPoint instance.
  8. The Create button allows creating new configuration files for all functionalities of MatchPoint, including custom configuration file types that are deployed to the system.
  9. The Singleton Configurations section provides links to configuration files that determine the instance-wide behavior of MatchPoint:
    1. MatchPoint Configuration file, see section "MatchPoint Configuration File".
    2. Credential Store Configuration file, see section "Credential Store Configuration File".
    3. License Configuration file, see section "License Configuration File"
    4. Search Box Configuration and Search Scope Configuration file, see section "Search Related Settings"
  10. Below the ribbon buttons, a list of all configuration files is displayed. This list can be easily filtered and sorted to quickly find a specific configuration.

Web application associations are persisted on the content database of the Instance Administration site and NOT within a MatchPoint configuration file. For more information on the setup of a MatchPoint instance with multiple web applications, please refer to the document MatchPoint Installation Guide.

Configuration Editor

The MatchPoint configuration editor is opened either as a dialog window within the current page (if Ctrl +M is used or for Web Parts, if accessed from the Web Part page) or within its own page (for all configuration files opened on the MatchPoint Administration.

The general usage of the configuration editor is always the same, regardless of purpose or functionality of the current configuration file.

  1. If the current configuration is stored within a central configuration file, the file name is displayed within the title of the editor.
  2. From the ribbon, various operations can be accessed:
    1. The current configuration file can be saved, closed and renamed.
    2. Previous versions can be accessed.
    3. The "Toggle view" button allows switching to the XML schema view of the configuration.
    4. Elements within the tree view can be sorted, new elements can be added to the tree (i.e. "SortColumns") or elements can be deleted
  3. A tree view displayed on the left side displays the main configuration elements. An element can be accessed by selecting it from the tree. Complex elements with child elements can be expanded.
  4. On the right main area, parameters of the currently selected configuration element can be modified. Parameters are explained with a short description. Required parameters are marked with a *. Moreover, the title of the current configuration element is displayed.
  5. On the bottom of the configuration editor, the currently installed MatchPoint version is displayed, as well as a button to save the configuration and exit the editor.

For security reasons, the "Toggle View" switch is only available for MatchPoint instance administrators.

Web Part Configurations

The MatchPoint Web Parts can be configured in two ways:

  1. A "Local Configuration" uses the standard SharePoint configuration mechanism for Web Parts. This means the configuration is stored directly on the Web Part page.
  2. By using a centrally stored configuration file, it is possible to use one configuration for multiple instances of a Web Part. This also allows the quick implementation of changes in all Web Parts by changing the configuration file.

MatchPoint Web Parts provide a "Configuration" section within the SharePoint ribbon that is displayed when the current page is in "Edit" mode:

  • Both local and central configurations can be edited with the MatchPoint configuration editor by clicking on the Configuration icon.
  • The "Local Configuration" menu item will change the configuration mode of the current Web Part to a local configuration.
  • The "Choose Configuration..." menu item will open a dialog window where all compatible configuration files for the current Web Part will be listed.
  • The "Add Configuration..." menu item will create a new configuration file.

MatchPoint Configuration File

The configuration file Colygon.MatchPoint.xml contains the basic preferences that determine the system-wide behavior of a MatchPoint installation. The following sub sections describe the different main configuration elements within the MatchPoint configuration.

Registering Assemblies, Solutions and Event Handlers

Within the MatchPoint configuration file, extensions can be registered for a MatchPoint installation. These extensions can be

  • Assemblies, that contain functionality like custom timer jobs, expression variables etc.
  • Solutions, that are deployed to the 15 hive of the SharePoint server.
  • Event handlers, which are part of a registered assembly.

Assemblies

Custom code can be deployed to the system by deploying an assembly that contains the functionality to the global assembly cache (GAC) or by using User Controls.

Within the MatchPoint configuration file, the ExternalAssemblies parameter allows registering assemblies (deployed to the SharePoint farm) that contain interfaces that make use of the MatchPoint API, e.g. custom expression variables, timer jobs etc.

External Assembly Registration

<ExternalAssemblies>
  <Assembly>
    Colygon.CustomAssembly, Version=0.9.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c
  </Assembly>
</ExternalAssemblies>

Solutions

MatchPoint allows registering custom solutions that are deployed to the 15 hive of the SharePoint farm. These solutions have to be placed 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. These controls will be available within the MatchPoint expression framework as well as within any controls where user controls can be referenced, e.g. within the Composite Web Part.

Within the MatchPoint configuration file, the SolutionPathsField parameter allows registering custom solutions (deployed to the 15 hive).

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

Event Handlers

A ListItemEventHandler is triggered when a SPListItem object is changed within a list that is enabled for MatchPoint. The event handlers are found automatically within all registered external assemblies, but they have to be specified separately to ensure that only required event handlers are active on a system. Event handlers are registered with a "ListItemEventHandlerConfiguration" element. All of these elements register one event handler.

Please be aware that if a custom ListItemEventHandler is not implemented with good performance, this will likely affect the general system performance of any MatchPoint enabled list!

Icon Mappings

MatchPoint uses icons for various properties and values. This allows users to easily identify a property when it is used within a MatchPoint control (e.g. in a Search Definition Web Part). Examples for icons are MatchPoint tags, SharePoint terms and regular SharePoint properties like content type, file extension etc.

Icons are specified within the MatchPoint configuration using an IconMapping element. It is also possible to define icon mappings for SharePoint terms and for MatchPoint tags.

Icon mappings defined within the MatchPoint configuration file will only effect the behavior of the property within MatchPoint controls, e.g. within the Search Definition Web Part. Icons for OOB SharePoint controls have to be specified separately.

Context Menus

MatchPoint allows the definition of context menus that are available within the MatchPoint Web Parts. There are two different kinds of context menus:

  • Tag context menus are displayed for MatchPoint tags and available in any MatchPoint control.
  • Data Grid context menus are displayed only within a MatchPoint Data Grid Web Part.

Menu entries within a context menu can be simple hyperlinks that navigate to an external system or complex functionalities implemented within an external assembly. Three different kinds of menu entries can be specified:

  • A ClientContextMenuProvider specifies a JavaScript method that is called on the client when the menu is rendered.
  • A ServerContextMenuProvider specifies a class within an external assembly that provides a context menu for the tag.
  • Without implementing custom code, a context menu item can be configured directly within the configuration file. This can be a ContextMenuItem (for tag context menus) or a DataItemContextMenuItem (for Data Grid context menus).

For more information on how to implement a custom context menu, please refer to the MatchPoint API Reference and to the code samples Colygon.MatchPoint.Samples.zip provided with every MatchPoint Release.

Data Grid Context Menus

For context menus that are displayed within the context of a MatchPoint Data Grid Web Part, a "Data GridContextMenuConfiguration" can be specified within the MatchPoint configuration. A Data Grid context menu can be configured with a number of criteria. They determine, for which items a context menu should be displayed, i.e. only for a specific content type or for items with a specific URL prefix.

To display Data Grid context menus within a Data Grid Web Part, the parameter "ShowCustomContextMenu" has to be enabled within relevant column definition of the Web Part.

Tag Context Menus

A tag context menu is configured using a TagContextMenuConfiguration element and is always registered for a specific tag provider.

Credential Store Configuration File

See section Credential Store.

License Configuration File

The MatchPoint license key is specified with the configuration file LicenseConfiguration.xml. MatchPoint requires an environment-specific key (depending on the URL of the MatchPoint instance administration site). The key also specifies the number of CALS, servers, web applications and site collections that can use MatchPoint.

A MatchPoint license is valid for one MatchPoint instance and linked to the URL of that instance. Therefore, a new license key has to be requested if the URL of the MatchPoint instance is changed.

On the configuration management site, some links for search related settings are available:

  • The button Favorite Tag Sets link opens a page that allows managing the favorite tag sets. Favorite tag sets provide quick access for end-users to often-used combination of MatchPoint tags from the tagging interface.
  • The button Search Definitions opens a page that allows administrating search definitions. Search Definitions provide quick access for end-users to often-used combinations of search criteria from the Search Definition Web Part.
  • The Search Scope Configuration link opens the configuration editor for MatchPoint search scopes. It allows specifying search filters that are available within the Search Definition Web Part.

Favorite tag sets and search definitions are persisted in two SharePoint lists on the Instance Administration site and NOT within a MatchPoint configuration file. The general search settings, however, are managed within the configuration file `SearchScopesConfiguration.xml`.

Search Definitions

The MatchPoint settings for search definitions for the Search Definition Web Part are administrated from the Search Definitions page.

A search definition is a set of predefined search filters that can be quickly accessed from a Search Definition Web Part. They are organized in categories and have an owner. Usually, users can create search definitions only for themselves. It is also possible to publish search definitions for all users. A search definition is always targeted for a specific search definition scope. Search definitions are stored within a hidden SharePoint list "SearchDefinition" on the Instance Administration site.

Search Scope Configuration File

The link Search Scope Configuration opens the file SearchScopesConfiguration.xml. Within this configuration, the available search filters forSearch Definition Web Parts are specified:

  • The BaseSearchFilterConfiguration element specifies a property (tags, terms or SharePoint properties) that will be available as search filters. Values can be displayed "on type" or they are displayed for browsing in a tree. Selected values are converted into a search condition that can be used by a data provider for searching items.
  • The SearchDefinitionScopeConfiguration element specifies which of the configured search filters are available within a specific search scope and thereby within a specific Search Definition Web Part.

A MatchPoint Search Definition Web Part is configured to use one specific search scope. It aggregates the suggested values for all filters configured for a search scope.

Custom Configuration Files

It is possible to utilize the configuration interface of MatchPoint and implement custom configuration classes. Data is stored and managed like any other MatchPoint configuration file, within the configuration document library.

A configuration class has to implement the IConfiguration interface so it becomes available as a MatchPoint configuration file. The interface does not specify methods/properties. Since configuration classes are serialized into XML files, they also have to be marked with the XML [Serializable] attribute.

For more information on how to implement custom configuration files, please refer to the MatchPoint API Reference and to the code samples Colygon.MatchPoint.Samples.zip provided with every MatchPoint Release.

Custom configuration classes are also used by various interfaces, e.g.custom MatchPoint timer jobs, data providers, data adapters etc. The IConfiguration interface is the root level for custom configuration files, the following interfaces and classes can be used to implement a more specific configuration file:

results matching ""

    No results matching ""