Export (0) Print
Expand All

Additional Converter Settings Controls in SharePoint Server 2010 (ECM)

Last modified: March 08, 2010

Applies to: SharePoint Server 2010

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 SharePoint Server 2010 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 in SharePoint Server 2010 (ECM).

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
    Inherits UserControl
    Implements IDocumentConverterControl
  ''' <summary>
  ''' XSLT asset selector control
  ''' </summary>
  Public assetSelectedXsl As AssetUrlSelector

  ''' <summary>
  ''' Validator to make sure user picks XSLT
  ''' </summary>
  Public fileExtensionValidator As FileExtensionValidator

  ''' <summary>
  ''' Input form section, used only to get the display title of the 
  ''' section.
  ''' </summary>
  Public inputSection As InputFormSection

  Protected Overrides Sub OnLoad(ByVal e As EventArgs)
    MyBase.OnLoad(e)
    Me.fileExtensionValidator.ControlToValidate = Me.assetSelectedXsl.ID
  End Sub

  Private Const ConverterSettingsXmlName As String = "XslApplicatorConverterSettings"

  ''' <summary>
  ''' Property that is the interface to the outer world - get/set a 
  ''' string 
  ''' that persists the settings
  ''' </summary>
  Public Property ConverterSettings() As String
    Get
      Dim sb As New StringBuilder("<", 256)
      sb.Append(ConverterSettingsXmlName)
      sb.Append(" Version=""1"" >")

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

      sb.Append("</FilePlaceHolder>")

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

      Return sb.ToString()
    End Get

    Set(ByVal value As String)
      If Not String.IsNullOrEmpty(value) Then
        Dim xmlDoc As New XmlDocument()
        xmlDoc.LoadXml(value)

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

        If cl.Count > 0 Then
          Dim node As XmlNode = cl(0)
          Dim attribute As XmlAttribute = node.Attributes("Url")
          Dim fileUrl As String = String.Empty

          If attribute IsNot Nothing AndAlso attribute.Value IsNot Nothing Then
            fileUrl = attribute.Value
          End If

          Me.assetSelectedXsl.AssetUrl = fileUrl
        End If
      End If
    End Set
  End Property

  ''' <summary>
  ''' Implement setter to fulfill the interface
  ''' </summary>
  Public Property ContentType() As SPContentType
    Set(ByVal value As SPContentType)
    End Set
    Get
      Return Nothing
    End Get
  End Property

  ''' <summary>
  ''' This control always requires configuration
  ''' </summary>
  Public ReadOnly Property RequiresConfiguration() As Boolean
    Get
      Return True
    End Get
  End Property

  ''' <summary>
  ''' Display title, used to direct user to this section in the page in 
  ''' case of validation errors
  ''' </summary>
  Public ReadOnly Property SectionDisplayTitle() As String
    Get
      Return Me.inputSection.Title
    End Get
  End Property

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. As a result, 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);
Dim fileContent() As Byte = 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 in SharePoint Server 2010 (ECM).

Show:
© 2014 Microsoft