Data Adapters

A Data Adapter is used in combination with the Form WebPart. A Data Adapter allows to read and write fields of a specific object. The ListItemDataAdapter Class for example allows you to read from and write to a SPListItem. This enables you to use the Form WebPart instead of the Edit Form Page for example.

The following Data Adapters come with MatchPoint:

• BdcDataAdapter: A Form Web Part can be configured with a BdcDataAdapter to allow viewing, editing and creating of new elements on an external content type
• ListItemDataAdapter: Allows accessing a SharePoint list item or document
• ModelDataAdapter: A Form Web Part can be configured with a ModelDataAdapter to allow viewing, editing and creating of new elements within an entity model

If you want to build your own Data Adapter you should extend BaseDataAdapter Class. The Custom Data Adapter chapter shows how this can be done.

Data Adapter Fields

If a Form Web Part is configured with a data adapter, any fields and properties that are available on the item (i.e. a SPListItem) can be configured as input fields for the form. In this case, the Name parameter of the form field has to correspond to the field name of the item.

Supported Field Types

Data adapters support any fields that are supported by the items that are viewed/edited/created. Therefore, depending on the data adapter, some fields might not be supported. The following table provides an overview. Furthermore it is possible to implement custom field types by extending FormField.

* The Workspace Editor can be used for accessing workspaces in the same way as a Form Web Part with a Workspace Data Adapter.
** Field values are stored internally split into two fields (for display name and key). Internal Field Names can be retrieved using the ModelLookupField and SPBusinessDataField, respectively.

Transport Classes Overview

Following image illustrates how values are transported between the different components involved in a configuration that uses a Form Web Part with a data adapter. The example uses a ListItemDataAdapter, but the same general behavior is also used within the other data adapters.

The following types are used for transporting values between the different components:

IUpdatable and ISPUpdatable

The objects that are accessed within a data adapter have to implement the IUpdatable interface. For SharePoint objects, the ISPUpdatable interface is used. This interface implements an indexer operator that allows access to properties on the underlying list item. When accessing a SharePoint list item or document using the ListItemWrapper class, values can be assigned directly using the functionality of the SPFieldValueConverter class.

The SPFieldValueConverter class can handle the following values:

When accessing SharePoint items within custom code, i.e. an ASP.NET control, you can access field values using either the method SPListItem.SetFieldValue(fieldname, value) or the indexer operator on the ISPUpdatable interface, ISPUpdatable\["Field"\] = value.

Using the Expression Engine

Within the Form Web Part, the expression engine can be used i.e. for evaluating default values, for determining the display mode (read-only/editable) or for field validation. Fields can be accessed by their Name, using the expression ConnectionData.FieldName.

Also, the Form Web Part itself can be configured with a Name property. If a name is specified, the form can be accessed from the expression engine. For instance, a form with the name "Form" can be accessed like this:

ConnectionData.Form

The return object of this expression provides two properties:

• Record provides access to the item that is loaded within the data adapter
• ReadOnly returns true, if the form is currently displayed in read-only mode.

The Record object provides access to all properties that are available on the current item. It is only available, if a data adapter has been configured and an item is available. The ReadOnly property can be used for instance to dynamically display or hide fields, depending on whether the form is displayed in "edit" or in "read-only" mode.

Note that there is an important difference between accessing fields from the Form Web Part (using ConnectionData.FieldName) and accessing fields from the current data record (ConnectionData.Form.Record.FieldName). The first expression will return the current user input for that field and the latter will return the "original" value from the item that is currently displayed within the form.

Please also be aware that there are possible naming conflicts if multiple Form Web Parts with the same name are placed on a page.

Using a Form Web Part for Editing List Items

The MatchPoint Form Web Part (configured with a ListItemDataAdapter) can be used to replace the standard SharePoint "List Form Web Part":

• Navigate to the SharePoint list/document library.
• In the "List/Library" ribbon, select "Form Web Parts" from section "Customize Library"
• Select either "Default Display Form" or "Default Edit Form", depending on the form that should be replaced.
• On the page, close the "List Form Web Part" and add a MatchPoint Form Web Part.
• Configure the Web Part with a ListItemDataAdapter and for the ItemExpression property, select "Use current item".
• Configure the form fields on the Web Part.

Alternatively, the page can be edited using the SharePoint designer. It is suggested to use a central configuration file to configure the Form Web Part.

Custom Data Adapters

Custom data adapters can be used to provide read/write access to external systems that cannot be connected using the out-of-the-box data adapters of MatchPoint. A custom data adapter needs to inherit from BaseDataAdapter.

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