Fundamental Concepts: Programming API

The Web.TextControl editor offers an API that helps to manipulate the content programmatically. In combination with a server-side ServerTextControl instance, a Web.Selection object can be edited and passed back the editor.

Additionally, several client-side events are available to interact with merge fields. This allows the insertion and manipulation of merge fields using your own interface.

Server-side API (Selection class)

Server-side, the Web.TextControl provides a Web.Selection object that is used to get and set the current selection in the document. A Selection object is available for each TextPart object including the Web.MainText, Web.TextFrame and Web.HeaderFooter objects.

In order to activate the HeaderFooter of a document, the following code can be used:

[C#]
foreach (IFormattedText textPart in TextControl1.TextParts)
{
    if (textPart.GetType() == typeof(TXTextControl.Web.HeaderFooter))
    {
        TextControl1.TextParts.Activate(textPart);
        break;
    }
}
[Visual Basic]
For Each textPart As IFormattedText In TextControl1.TextParts
    If textPart.[GetType]() = GetType(TXTextControl.Web.HeaderFooter) Then
        TextControl1.TextParts.Activate(textPart)
        Exit For
    End If
Next

The following code shows the combination of the Web.Selection and the ServerTextControl. A new ServerTextControl instance is created and a new MergeField is added to the document. The results are loaded back into the current selection of the Web.TextControl.

[C#]
using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl())
{
    tx.Create();

    MergeField newField = new MergeField();
    newField.Name = "TextField1";
    newField.Text = "New TextField";

    tx.ApplicationFields.Add(newField.ApplicationField);

    byte[] data;
    tx.Save(out data, TXTextControl.BinaryStreamType.InternalUnicodeFormat);
    TextControl1.Selection.Load(data, TXTextControl.Web.BinaryStreamType.InternalUnicodeFormat);
}
[Visual Basic]
Using tx As New TXTextControl.ServerTextControl()
    tx.Create()

    Dim newField As New MergeField()
    newField.Name = "TextField1"
    newField.Text = "New TextField"

    tx.ApplicationFields.Add(newField.ApplicationField)

    Dim data As Byte()
    tx.Save(data, TXTextControl.BinaryStreamType.InternalUnicodeFormat)
    TextControl1.Selection.Load(data, TXTextControl.Web.BinaryStreamType.InternalUnicodeFormat)
End Using

In order to manipulate a Selection, the content is loaded into a temporary ServerTextControl, manipulated and loaded back into the Web.TextControl. The following code shows how to format an existing range of text:

[C#]
using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl())
{
    byte[] data = null;
    TextControl1.Selection.Save(out data, BinaryStreamType.InternalUnicodeFormat);

    tx.Create();
    tx.Load(data, TXTextControl.BinaryStreamType.InternalUnicodeFormat);

    tx.SelectAll();
    tx.Selection.Bold = true;

    tx.Save(out data, TXTextControl.BinaryStreamType.InternalUnicodeFormat);
    TextControl1.Selection.Load(data, TXTextControl.Web.BinaryStreamType.InternalUnicodeFormat);
}
[Visual Basic]
Using tx As New TXTextControl.ServerTextControl()
    Dim data As Byte() = Nothing
    TextControl1.Selection.Save(data, BinaryStreamType.InternalUnicodeFormat)

    tx.Create()
    tx.Load(data, TXTextControl.BinaryStreamType.InternalUnicodeFormat)

    tx.SelectAll()
    tx.Selection.Bold = True

    tx.Save(data, TXTextControl.BinaryStreamType.InternalUnicodeFormat)
    TextControl1.Selection.Load(data, TXTextControl.Web.BinaryStreamType.InternalUnicodeFormat)
End Using

In order to select a range of text in the Web.TextControl, a new Selection object is created and passed to the Selection property.

[C#]
TextControl1.Selection = new Selection(1, 5);
[Visual Basic]
TextControl1.Selection = New Selection(1, 5)

Client-side, Javascript events

In order manipulate merge fields and to provide your own interface to insert and interact with merge fields, client-side Javascript events are available:

Event name Description
textFieldEntered Is fired when the input position enters a text field.
textFieldLeft Is fired when the input position leaves a text field.

These events can be easily attached using Javascript in your ASPX page:

[JavaScript]
<script>
    TX.addEventListener('textFieldEntered', function (e) {
        fieldEntered(e.fieldName, e.fieldType);
    });

    function fieldEntered(fieldName, fieldType) {
        alert(fieldName);
    }

    TX.addEventListener('textFieldLeft', function (e) {
        fieldLeft();
    });

    function fieldLeft() {
        alert('Field left');
    }
</script>

<< Previous Next >>