Additional Converter Settings Controls in SharePoint Server 2010 (ECM)
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 : 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;
}
}
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
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. 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).
See Also
Concepts
SharePoint Server 2010 Document Converter Development Overview (ECM)
Document Converters in SharePoint Server 2010 (ECM)
Document Converter Deployment in SharePoint Server 2010 (ECM)
Document Converter Definition Schema in SharePoint Server 2010 (ECM)
Document to Page Converter Configuration Settings Schema in SharePoint Server 2010 (ECM)