Additional Converter Settings Controls

If you need to create a custom document converter, you might also need to gather more information from the administrator than the options that are presented on the default Microsoft Office SharePoint Server 2007 document configuration settings page. To collect this information, you can specify a custom .ascx control to host on an existing converter page.

To specify a custom configuration settings control, set the ConverterSpecificSettingsUI element of the document converter definition to the file name of the .ascx control you want to use. This is an optional element. You must specify a converter configuration settings page in the ConverterSettingsForContentType element to host the control.

For more information about the document converter definition, see Document Converter Definition Schema.

The configuration settings page you specify must contain code that implements the IDocumentConverterControl interface, as shown in the following example.

In addition, the string that the control returns must be valid as an XML node.

public class XslApplicatorSettingsControl : UserControl, 
             IDocumentConverterControl
{
  /// <summary>
  /// XSLT asset selector control
  /// </summary>
  public AssetUrlSelector assetSelectedXsl;

  /// <summary>
  /// Validator to make sure user picks XSLT
  /// </summary>
  public FileExtensionValidator fileExtensionValidator;

  /// <summary>
  /// Input form section, used only to get the display title of the 
      section
  /// </summary>
  public InputFormSection inputSection;

  protected override void OnLoad(EventArgs e)
  {
    base.OnLoad(e);
    this.fileExtensionValidator.ControlToValidate = 
      this.assetSelectedXsl.ID;
  }

  private const string ConverterSettingsXmlName = 
      "XslApplicatorConverterSettings";

  /// <summary>
  /// Property that is the interface to the outer world - get/set a 
      string 
      that persists the settings
  /// </summary>
  public string ConverterSettings
  {
    get
    {
      StringBuilder sb = new StringBuilder("<", 256);
      sb.Append(ConverterSettingsXmlName);
      sb.Append(" Version=\"1\" >");

      sb.Append("<FilePlaceHolder Url=\");
      sb.Append(this.assetSelectedXsl.AssetUrl);
      sb.Append("\">");

      sb.Append("</FilePlaceHolder>");

      sb.Append("</");
      sb.Append(ConverterSettingsXmlName);
      sb.Append(">");

      return sb.ToString();
    }

    set
    {
      if (!String.IsNullOrEmpty(value))
      {
        XmlDocument xmlDoc = new XmlDocument();
        xmlDoc.LoadXml(value);

          RcaUtilities.FilePlaceHolderElementName;
        XmlNodeList cl = xmlDoc.SelectNodes("//FilePlaceHolder");

        if (cl.Count > 0)
        {
          XmlNode node = cl[0];
          XmlAttribute attribute = node.Attributes["Url"];
          string fileUrl = String.Empty;

          if (attribute != null && attribute.Value != null)
          {
            fileUrl = attribute.Value;
          }

          this.assetSelectedXsl.AssetUrl = fileUrl;
        }
      }
    }
  }

  /// <summary>
  /// Implement setter to fulfill the interface
  /// </summary>
  public SPContentType ContentType
  {
    set
    {
    }
    get
    {
      return null;
    }
  }

  /// <summary>
  /// This control always requires configuration
  /// </summary>
  public bool RequiresConfiguration
  {
    get
    {
      return true;
    }
  }

  /// <summary>
  /// Display title, used to direct user to this section in the page in 
      case of validation errors
  /// </summary>
  public string SectionDisplayTitle
  {
    get
    {
      return this.inputSection.Title;
    }
  }

External File Settings

An .ascx control that lets the user point to a file presents a special challenge: The converter runs in its own process, and so does not have access to files on the server. So the contents of any files must be read into the configuration information that is passed to the converter. The document converter infrastructure includes a mechanism by which a reference to a file actually pulls the contents of the file into the configuration settings information when the converter is invoked.

To read the contents of a file into the configuration settings information, add a FilePlaceholder element to the configuration settings XML. This element has a single attribute, Url, which represents the URL of the file whose contents you want read into the configuration settings information passed to the converter.

For example:

<FilePlaceHolder Url="myUrlHere"><\FilePlaceHolder>

When a document conversion is initiated, the document conversion infrastructure does the following for each FilePlaceHolder element in the configuration settings:

• Resolves the URL.

• Opens the specified file.

• Encodes the file content with base64 encoding and places the encoded content into the FilePlaceHolder element node.

When the converter receives the configuration settings, it must convert the contents of the file. To do so, the converter must access the FilePlaceHolder node and convert its content. For example:

byte[] fileContent = System.Convert.FromBase64String(node.InnerXml);

For more information about the configuration settings XML that is passed to the converter, see Document to Page Converter Configuration Settings Schema.

See Also

Concepts

Document Converters Overview
Document Converters
Document Converter Deployment
Document Converter Definition Schema
Document to Page Converter Configuration Settings Schema