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:

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