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

Last modified: March 08, 2010

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 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();
      

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

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

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