Concepts

This chapter provides detailed information on the concepts related to both MatchPoint Snow and custom MatchPoint Snowflakes.

Logical Architecture

MatchPoint Snow requires a site collection to host the MatchPoint Snow "instance". This site will be used as the landing page for all users. All workspaces created within MatchPoint Snow are created as site collections, located beneath the managed path configuration (as specified within the MatchPoint Snow Configuration).

The My Site Host which is required for Snow can either be on a dedicated web application or on a site collection within the Snow web application.

MatchPoint Snow Physical Architecture
Figure 1: MatchPoint Snow Physical Architecture

Snowflake Configuration Elements

A MatchPoint Snowflake can be created based purely on MatchPoint/MatchPoint Snow configuration files without the need for implementing any custom code. This chapter describes the main configuration elements available with MatchPoint Snow.

Overview

A Snowflake configuration defines the setup of the Snowflake. Below figure shows the most important configuration elements. Namely these are the navigation nodes and the contextual actions, the workspace types provided by this Snowflake and the (unique) Id as well as the name of the Snowflake:

The main configuration elements in a MatchPoint Snowflake
Figure 2: The main configuration elements in a MatchPoint Snowflake

For more details on the MatchPoint Snowflake configuration and all its properties, please refer to Snowflake Configuration.

Workspace Types

Workspaces constitute the central information hub within MatchPoint Snow. This is where content is generated and where users do their work. MatchPoint Snow workspaces are implemented using the functionalities of the MatchPoint workspace concept. From a SharePoint perspective, a Snow workspace is a site collection that contains a root web. The contents of this web (lists, pages and web parts etc.) are defined within the corresponding MatchPoint provisioning configuration file.

A workspace type is the template for a MatchPoint Snow workspace. It defines the SharePoint structure (using a MatchPoint provisioning configuration) as well as roles, permissions and metadata associated with the Workspace. All of functionality is implemented by using regular MatchPoint configuration files.

Workspaces can be created either from the MatchPoint Snow base site or from the Snowflake base site (if configured accordingly). Workspaces (and their content) will be displayed within the MatchPoint Snow base site and within the Snowflake base site (if configured accordingly).

The following configuration files are relevant with regards to workspace types:

Filename / MatchPoint Configuration Type Description
MPSnow.Workspace.Template.xml
(WorkspaceTemplateConfiguration)
The workspace template defines the attributes (meta data) of the workspace, as well as the list location, target, etc.
MPSnow.Workspace.DefaultCreator.xml
(WorkspaceEditorConfiguration)

Each workspace type needs a WorkspaceEditorConfiguration that is used to create a new instance of the workspace.

Either a default configuration (provided with MatchPoint Snow) can be used or a custom configuration can be provided.

MPSnow.Workspace.DefaultEditor.xml
(WorkspaceEditorConfiguration)

Each workspace type requires a WorkspaceEditorConfiguration that is used to edit its attributes.

Either a default configuration (provided with MatchPoint Snow) can be used or a custom configuration can be provided.

MPSnow.Workspaces.BaseProvisioning.xml
(ProvisioningConfiguration)

All ProvisioningConfigurations associated with a WorkspaceType should inherit from the BaseProvisioning configuration file provided with MatchPoint Snow. This configuration ensures:

  • Activation of required features on the Workspace site collection / root web

  • Activation of tagging and rating on all lists

  • Creation of required pages in the Site Pages library (incl. the provisioning of the required web parts)

  • Permission assignments and role definitions

  • Define and apply the composed look "MatchPoint Snow Look"

Additional custom ProvisioningConfiguration or WorkspaceEditorConfiguration that are referenced by the WorkspaceType. In case a custom WorkspaceEditorConfiguration is implemented, the file MPSnow.Workspace.Template.xml needs to be referenced.

Contextual Actions

MatchPoint Snow defines actions that are displayed to the user on the right hand side of the content. It differentiates between actions that depend on the current context and actions that are always displayed. Actions can be configured by the administrators/MatchPoint Snowflake implementers. There are three places on which the contextual actions can be configured:

Displayed in... Configured in...
MatchPoint Snow ("global") MatchPointSnowConfiguration.xml
Instances of a specific WorkspaceType ("workspace")

WorkspaceType(s) within the global MatchPointSnowConfiguration.xml

WorkspaceType(s) within the current MatchPoint Snowflake configuration

A sub-workspace-type

Note: Currently, only meetings are available.

In MatchPointSnowConfiguration.xml (node: MatchPointSnowConfiguration/SubworkspaceTypes/MeetingSubWorkspaceType)

Contextual Actions can also be displayed on a page by adding a ContextualActions Web Part and binding a ContextualActionsWebPartConfiguration configuration file to it. This should be used mainly when a set of Contextual Actions are desired just in one place. For more details, please refer to Contextual Actions WebPart

Additional String Resources

A Snowflake developer can add an extra StringResourcesConfiguration in which he can place the string resources required for the Snowflake. This is configured within the Snowflake configuration.

In case certain string resources defined by MatchPoint Snow need to be overridden, a StringResource with the same key can be added to the Snowflake string resources file. MatchPoint Snow will always consider the Snowflake string resources before using its own.

Another reason when this file should be used, is when MatchPoint Snow loads string resources based on dynamic keys. An example where this is done is the workspace navigation, where the name of the navigation nodes is used as key for the string resources file. In case the Snowflake adds additional navigation nodes to the workspace, a StringResource where the key is the name of the node needs to be added to the Snowflake string resources.

To use such StringResources the expression MPSUtility.GetSnowString(string key) can be used.

MatchPoint Snow StatusBar

Since MatchPoint Snow 1.0.4 a StatusBar is used to display status messages / results of operations in a unified and user-friendly way. The StatusBar is a slightly modified version of the default SharePoint StatusBar and is shown right below the top navigation of MatchPoint Snow. The user can close the StatusBar with an icon, which is on the top right. It's also possible to automatically hide messages after a certain amount of time.

There are four different StatusBars which differ in their color and their icon:

Type Color Screenshot
Success green
Info blue
Warning yellow
Error red

How to use the StatusBar

The StatusBar can either be used in some ContextualActions or programmatically via the API.

ContextualActions

For some ContextualActions, namely the DialogCallback and the GenericWebPartPage actions, the success StatusBar (green) can be used without doing any programming work.

In the configuration of these contextual actions there is a field called SuccessMessage. This message will be displayed as a success StatusBar, if the Dialog is closed with the value SP.UI.DialogResult.OK (or the value 1). This value is normally automatically passed when a dialog is closed via the "Save" / "OK" button (and not when it's closed via the "X").

It's also possible to programmatically close the dialog with JavaScript:

SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, data);

The data parameter can contain callback data (in the form of a JSON-object) and is optional. You can content of the callback data in your SuccessMessage. The values can be accessed with [variableName].

For a better understanding please see following example, taken from MatchPoint Snow.

The configured SuccessMessage:

"Your workspace <a href='[url]'>[title]</a> has been created successfully."

The dialog is then closed with the following JavaScript:

var options = {
  "url": "http://server/snow/myWorkspace",
  "title": "MyWorkspace"
};
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, options);

MatchPoint Snow will replace the placeholders with the actual values and display the message in a success StatusBar.

A complete example, which is implemented in MatchPoint Snow, can be found in the following files:

  • MatchPointSnowConfiguration.xml (search for WorkspaceCreatedSuccessfully)
  • MPSnow.Workspace.DefaultCreator.xml (field SuccessMessage)
  • StatusBar.js

API

A StatusBar can either be created with JavaScript (recommended, since there are currently more possibilities / methods available) or with C#.

The following methods exists in JavaScript:

MP.Snow.StatusBar.AddSuccess(msg, title, hideAfter)
MP.Snow.StatusBar.AddInfo(msg, title, hideAfter)
MP.Snow.StatusBar.AddWarning(msg, title)
MP.Snow.StatusBar.AddError(msg, title)
MP.Snow.StatusBar.AddStatus(color, msg, title, hideAfter, hideCloseButton)
MP.Snow.StatusBar.AddStatusOnNextPageLoad(color, msg, title, hideAfter, hideCloseButton)

Please note that for all methods only the first parameter is mandatory (however for the last two methods the message parameter must also be specified, if the "color" is not an object, see below). The other parameters can be omitted.

The specific methods (AddSuccess, AddInfo, AddWarning, AddError) are only overloads for the AddStatus method.

Also the color parameter of the AddStatus and the AddStatusOnNextPageLoad method can either be a color (green, blue, yellow, red) or an object which contains all or some of the real parameters. The parameters are then extracted from this object and the function calls itself recursively with the found parameters. For details you can have a look at the "StatusBar.js" file in MatchPoint Snow.

In C# there are the following methods:

MPSHelper.AddStatusBarSuccessMessage(Page page, string msg, string title, int hideAfter)
MPSHelper.AddStatusBarInfoMessage(Page page, string msg, string title, int hideAfter)
MPSHelper.AddStatusBarWarningMesssage(Page page, string msg, string title)
MPSHelper.AddStatusBarErrorMessage(Page page, string msg, string title)
MPSHelper.AddStatusBarMessage(Page page, SPPageStatusColor color, string msg, string title,
                              int hideAfter, bool hideCloseButton)

These methods will write a JavaScript startup script to the page which then will call the corresponding JavaScript methods (which are described above). Moreover the methods itself are documented and should therefore be self-explanatory.

MatchPoint Snow Tags

In order to associate content (e.g. documents, list items, etc.) with their workspaces (and their Snowflakes), MatchPoint Snow automatically creates following tags which are inherited to all content stored in tagging-enabled lists:

  • MatchPoint Snowflake tag
  • WorkspaceType tag
  • Workspace tag

The following sub-sections provide information on these tags.

MatchPoint Snowflake Tag

MatchPoint Snowflake tags are created for all instances of configuration files inheriting the ISnowflakeConfiguration interface. Therefore, each MatchPoint Snowflake installed on a system will result in a MatchPoint Snowflake tag.

The tag uses the Id as the tag key and the MatchPoint Snowflake name as the display. Both values are extracted from the MatchPoint Snowflake configuration file.

WorkspaceType Tag

Workspace type tags are based on all WorkspaceType instances within MatchPointSnowConfiguration.xml or any Snowflakes configuration files. Therefore, each workspace type used within the environment will result in a workspace type tag.

The tag uses the Id of the workspace type as the tag key and the Name property as the display name. Both values are extracted from the workspace type configuration file.

Workspace Tag

The workspace tag is automatically created once a new workspace is created. The parent tag of the workspace tag is the workspace type tag. This structure enables searches based on workspace type (e.g. find all content created within any project workspace).

Tag Structure

Following list illustrates Snowflake/workspace type tag structure:

  • MatchPoint Snowflake Alpha (MatchPoint Snowflake Tag)
    • WorkspaceType One (WorkspaceType Tag)
      • Instance A Of WorkspaceType One (Workspace Tag)
      • Instance A Of WorkspaceType One (Workspace Tag)
  • MatchPoint Snowflake Beta (MatchPoint Snowflake Tag)
    • ...

Timer Jobs

Once a new MatchPoint Snowflake configuration or a new workspace type has been added, the timer job MPSnow.Tags.System.xml needs to be executed. This timer job will import the tags according to the defined Snowflakes/workspace types.

It is required to execute this timer job before instances of the WorkspaceType are created. Otherwise, the Workspace tag cannot be created since the parent tag will not be available.

Extensions and Expressions

MatchPoint Snow provides a set of MatchPoint expression variables. They enable MatchPoint Snowflake implementers to use specific functionality in ExpressionString and PatternString properties within the configuration files, as well as from the API when they are developing custom code.

Expression Variables

Following main expression variables are provided by MatchPoint Snow:

Name Description
MPSTimelineHelper The timeline helper provides access to the social functions of MatchPoint Snow. Methods like AddPost, GetReplies and CommentUrl are available.
MPSUserHelper The user helper provides access to information related to a specific user and his/her user profile..
MPSWorkspaceHelper The workspace helper provides access to functionality and information related to workspaces and Snowflakes. Use this variable to check whether the current user can create workspaces or to retrieve the MatchPoint Snowflake configuration of an SPWeb instance.

Extensions

MatchPoint Snow provides some extensions for the MatchPoint Workspace class. For example, these extensions enable you to add users to a role or to subscribe/unsubscribe.

Hybrid

MatchPoint Snow Hybrid solution extends standard Snow Workspace Types with Remote Workspace Type. This type is similar to the standard Snow Workspace Types - it represents the template for MatchPoint Remote workspace. Unlike standard Workspace Types, Remote workspace type doesn't define web structure (Provisioning configuration) and metadata associated with the Workspace. Roles and permissions are still defined and managed by it.

Remote Workspace can be created like standard Snow workspace - depends on configuration - from the MatchPoint Snow base site or from the Snowflake base site. Remote Workspaces (and their content) will be displayed within the MatchPoint Snow base site and within the Snowflake base site.

The following configuration files are relevant with regards to remote workspace type:

Filename / MatchPoint Configuration Type Description
MPSnow.Hybrid.RemoteWorkspace.Template
(RemoteWorkspaceTemplateConfiguration)
The workspace template defines the attributes (meta data) of the workspace, as well as the list location, target, etc.
MPSnow.Workspace.Remote.DefaultCreator.xml
(WorkspaceEditorConfiguration)

Each workspace type needs a WorkspaceEditorConfiguration that is used to create a new instance of the workspace. Either a default configuration (provided with MatchPoint Snow) can be used or a custom configuration can be provided.

MPSnow.Workspace.Remote.DefaultEditor.xml
(WorkspaceEditorConfiguration)

Each workspace type requires a WorkspaceEditorConfiguration that is used to edit its attributes. Either a default configuration (provided with MatchPoint Snow) can be used or a custom configuration can be provided.

results matching ""

    No results matching ""