Custom Converter Configuration Settings Pages

Article
10/16/2013

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 Office SharePoint Server 2007.

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 Office SharePoint Server 2007. This approach allows you to use the default document converter configuration settings page, rather than having to develop a replacement form. For more information, see Additional Converter Settings Controls.

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 Office SharePoint Server 2007 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.

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

ctype Represents the content type 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. Also, the ConfiguredPageLocation element is empty, specifying that Office SharePoint Server 2007 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();
```

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

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.

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, as well as 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);
  }
}

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; 
}

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.
  }
}

Converter Configuration Requirement

It is a best practice to include code that determines if the converter requires configuration, and if so, to display the appropriate error message. This code might vary greatly depending on the implementation of the page.

Custom Converter Configuration Settings Pages

Hosting a Custom Converter Settings Control

Converter Configuration Requirement

See Also

Concepts

Additional resources