Custom Converter Configuration Settings Pages in SharePoint Server 2010 (ECM)

Article
07/24/2014

Applies to: SharePoint Server 2010

If your custom document converter requires a custom configuration interface, you can create and specify a custom .aspx page for that purpose. This page would replace the default document configuration settings page included in Microsoft SharePoint Server 2010.

Note

If you need to gather additional information from the administrator only during configuration, you can specify a custom .ascx control to host on the default document configuration settings page included in SharePoint Server 2010. This approach enables you to use the default document converter configuration settings page, instead of having to develop a replacement form. For more information, see Additional Converter Settings Controls in SharePoint Server 2010 (ECM).

Administrators can use your custom page to specify the configuration settings for each content type that uses the converter. Those content type-specific converter settings are passed to the document converter when the user selects to convert a document of that content type. The default converter configuration settings page that is included with SharePoint Server 2010 contains code that passes the content type-specific converter settings.

To specify a custom converter configuration settings page, set the ConverterSettingsForContentType element of the document converter definition to the file name of the .aspx page you want to use. This is an optional element; if you do not include it in your converter definition, no converter configuration page is available for that converter.

For more information about the document converter definition, see Document Converter Definition Schema in SharePoint Server 2010 (ECM).

SharePoint Server 2010 passes the following information to the converter configuration settings page when a user navigates to it:

ctype Represents the content type identifier (ID) of the content type for which the user wants to configure this converter.
Converter Represents the GUID of the converter the user wants to configure.
OriginalSource Represents the URL of the page from which the user navigated. This parameter is not used in this context and may be ignored.

For example:

http://example-ts/_layouts/ConverterSettings.aspx?ctype=0x0101&Converter=6dfdc5b4%2D2a28%2D4a06%2Db0c6%2Dad3901e3a807&OriginalSource=http%3A%2F%2Fexample%2Dts%2FDocuments%2FForms%2FAllItems%2Easpx

The page you specify must contain code to do the following:
1. Format the configuration settings gathered by the page into an XML document.
  
  For your converter to provide the necessary configuration information for document conversion post-processing, it must store its configuration settings in the specified content type according to the following schema.
```
<rca:RCAuthoringProperties xmlns:rca="urn:sharePointPublishingRcaProperties">
  <rca:Converter rca:guid="6dfdc5b4-2a28-4a06-b0c6-ad3901e3a807">
    <rca:property rca:type="InheritParentSettings">True</rca:property>
    <rca:property rca:type="SelectedPageLayout">30</rca:property>
    <rca:property rca:type="SelectedPageField">f55c4d88-1f2e-4ad9-
      aaa8-819af4ee7ee8</rca:property>
    <rca:property rca:type="SelectedStylesField">a932ec3f-94c1-48b1-
      b6dc-41aaa6eb7e54</rca:property>
    <rca:property 
      rca:type="CreatePageWithSourceDocument">True</rca:property>
    <rca:property 
      rca:type="AllowChangeLocationConfig">True</rca:property>
    <rca:property rca:type="ConfiguredPageLocation"></rca:property>
    <rca:property rca:type="CreateSynchronously">True</rca:property>
    <rca:property 
      rca:type="AllowChangeProcessingConfig">True</rca:property>
    <rca:property rca:type="ConverterSpecificSettings"></rca:property>
  </rca:Converter>
</rca:RCAuthoringProperties>
```
  In the preceding example, the elements represent the various options available on the default converter configuration settings page. The ConverterSpecificSettings element represents the configuration settings written out by the converter-specific .ascx control, if there is one. For more information, see Additional Converter Settings Controls in SharePoint Server 2010 (ECM). Also, the ConfiguredPageLocation element is empty, specifying that SharePoint Server 2010 should use the current site.
2. Write that configuration XML to the appropriate content type definition as an XMLDocument node.
  
  For example, the following code updates the site content type definition, after having constructed the appropriate XML document, as shown previously.
```
// Delete the previous instance of this document if it already exists.
myContentType.XmlDocuments.Delete(RcaPropertiesNamespaceUri);
myContentType.XmlDocuments.Add(this.myXmlDocument);
myContentType.Update();
```
```
' Delete the previous instance of this document if it already exists.
myContentType.XmlDocuments.Delete(RcaPropertiesNamespaceUri)
myContentType.XmlDocuments.Add(Me.myXmlDocument)
myContentType.Update()
```

The configuration settings data can be any well-formed XML that the document converter can parse. SharePoint Server 2010 does not parse the information itself, but merely enables you to store this XML within the content type definition so that it can be passed to the document converter later.

Be aware that if you specify a converter configuration settings page, you must also specify a custom .aspx page for the user interface for invoking this document converter. The default page for invoking document conversions does not pass any configuration settings to the selected converters. For more information, see Custom Conversion Settings Pages in SharePoint Server 2010 (ECM).

Hosting a Custom Converter Settings Control

To enable custom converter settings controls, the page that invokes the document converter must contain code to do so.

For example, the following code, placed in the OnLoad function of the page, adds a custom converter settings control to the page, if a custom control is specified.

The following example requires two members in the code-behind file:

A member named customControl of type System.Web.UI.Control

A member named customConverterControl of type System.Web.UI.WebControls.PlaceHolder, and a corresponding placeholder on the .aspx page

if (!String.IsNullOrEmpty(myTransformer.ConverterSpecificSettingsUI))
{
  this.customControl = 
    LoadControl(myTransformer.ConverterSpecificSettingsUI);
  this.customConverterControl = this.customControl as 
    IDocumentConverterControl;
  if (this.customConverterControl != null)
  {
    this.converterSpecificControl.Controls.Add(this.customControl);
  }
}

If Not String.IsNullOrEmpty(myTransformer.ConverterSpecificSettingsUI) Then
  Me.customControl = LoadControl(myTransformer.ConverterSpecificSettingsUI)
  Me.customConverterControl = TryCast(Me.customControl, IDocumentConverterControl)
  If Me.customConverterControl IsNot Nothing Then
Me.converterSpecificControl.Controls.Add(Me.customControl)
  End If
End If

Next, the code applies the existing settings of the custom converter settings control.

// Set up the converter-specific control and retrieve the settings.
if (this.customConverterControl != null)
{
  this.customConverterControl.ContentType = this.CurrentContentType;
  this.customConverterControl.ConverterSettings = 
      this.effectiveRcaProperties.ConverterSpecificSettings; 
}

' Set up the converter-specific control and retrieve the settings.
If Me.customConverterControl IsNot Nothing Then
  Me.customConverterControl.ContentType = Me.CurrentContentType
  Me.customConverterControl.ConverterSettings = Me.effectiveRcaProperties.ConverterSpecificSettings
End If

Finally, the following code example, placed in the OnOK function of the page, persists the custom converter settings back to the site content type definition. Notice that the code sets the content type to provide the control with more context information.

// Persist the converter-specific settings.
if (this.converterSpecificControl.Controls.Count > 0)
{
  if (this.customConverterControl != null)
  {
    this.customConverterControl.ContentType = this.CurrentContentType;
    this.myRcaProperties.ConverterSpecificSettings = 
      this.customConverterControl.ConverterSettings; 
// Store this string in the content type properties as converter specific settings.
  }
}

' Persist the converter-specific settings.
If Me.converterSpecificControl.Controls.Count > 0 Then
  If Me.customConverterControl IsNot Nothing Then
Me.customConverterControl.ContentType = Me.CurrentContentType
Me.myRcaProperties.ConverterSpecificSettings = Me.customConverterControl.ConverterSettings
' Store this string in the content type properties as converter specific settings.
  End If
End If

Custom Converter Configuration Settings Pages in SharePoint Server 2010 (ECM)

Hosting a Custom Converter Settings Control

See Also

Concepts

Additional resources