What's New in TX Text Control .NET Server 24.0

Version 24.0 let MailMerge merge JSON data and gave its events the location in the template where they occur. It also added user-defined document properties, colored paragraphs, typed exceptions and the DataSourceManager class, and it changed the handler type of an event that the Document Editor's server side uses, which can require a change to existing code.

Version 24.0 was released on November 30, 2016, as TX Text Control X14, together with TX Text Control .NET for Windows Forms, TX Text Control .NET for WPF and TX Text Control ActiveX. Its last full installer, that of Service Pack 2, is dated June 13, 2017. The features below are the ones added since version 23.0.

Version 24.0 at a Glance

Mail Merge

MailMerge creates documents from a template and data.

• JSON data. MailMerge.MergeJsonData merges JSON data: a single object or an array of objects with the same structure. See Data Sources.
• Where an event occurred. Most events of a merge run tell where in the template they occurred. FieldMergedEventArgs, ImageMergedEventArgs and ImageFieldMergedEventArgs received MergeBlockName, NestingDepth and, depending on the class, TableCell and DataRow.
• Merge block prefix. MailMerge.MergeBlockNamePrefix is new.
• Data source information. DataSourceManager loads data from data sets, data tables, JSON, XML, objects and assemblies, describes its tables, columns and relations, inserts merge blocks and merges. The classes DataTableInfo, DataColumnInfo, DataRelationInfo, MergeBlockInfo and MergeBlockSettings came with it. See Template Assistant.
• JSON parser errors. The DocumentServer.Json namespace has exceptions such as ParserException for invalid JSON data.

Documents

• User-defined document properties. SaveSettings.UserDefinedDocumentProperties takes a UserDefinedPropertyDictionary of properties with values of the types String, Boolean, Int32 and Double. They are saved with the TX Text Control format, RTF, DOC and DOCX, and after loading, LoadSettings.UserDefinedDocumentProperties returns them. See Document Metadata.
• Colored paragraphs. ParagraphFormat.BackColor sets the background color of a paragraph and ParagraphFormat.FrameLineColor the color of its frame lines. All text filters support both. See Paragraphs.
• Text fields by type. IFormattedText.GetTextFields and ServerTextControl.GetTextFields return the text fields of one or more types. With several types, the fields are in the order of the document. PageNumberFieldCollection.GetItem gets one page number field.
• Input formatting. InputFormat received TopAligned, BottomAligned and VerticallyCentered for the text alignment, FrameFillColor and FrameLineColor for the background of table cells and the frame color, and FrameLineWidth.
• Paper sizes. ServerTextControl.GetSupportedPaperSizes returns the names and sizes of the supported paper sizes as PaperSize objects. They depend on the FormattingPrinter. See Printing.
• More. Selection.RemoveInlineStyles, FormattingStyle.BaseStyle, LoadSaveSettingsBase.ReportingMergeBlockFormat and the DocumentLoaded event of ServerTextControl are also new.

Error Handling

New exception classes tell what went wrong:

• A TextEditorException is thrown when an error occurs while text is edited.
• A FilterException is thrown when a text filter fails to convert a document to or from another format. Reason gives the cause.
• A LicenseLevelException is thrown when a feature isn't part of the licensed product level.
• A wrong parameter or property value throws an ArgumentException, an ArgumentNullException or an ArgumentOutOfRangeException, and a call that is invalid in the object's current state throws an InvalidOperationException.

See Troubleshooting for the errors of today's version.

PDF Import

Encrypted PDF documents can be loaded. The password to open the document is set with LoadSaveSettingsBase.UserPassword. See Load and Modify a PDF.

Document Editor

In version 24.0, the Document Editor was the ASP.NET Web Forms control Web.TextControl and the ASP.NET MVC extension Web.MVC.TextControl. Both are legacy technologies today, which ASP.NET on .NET Framework describes.

• Drag and drop. Selected text can be dragged to another position. TextViewGenerator.AllowDrag and AllowDrop have to be true. See Editing Text.
• Clippings of the view. View.GetImage received overloads that return a clipping of the view's image, and the Changed event of the View reports the clipping's position and size. When the view scrolls, because its location is set or because the input position leaves the visible part, ViewChangedEventArgs gives the scroll distance and orientation.
• Zoom and ruler bars. TextViewGenerator.Zoom zooms by a factor or with the options WholePage, PageWidth and TextWidth, which show the whole page, the width of a page or the text of a line, and RulerBarViewGenerator.ReadOnly shows the attributes in a ruler bar without letting users change them.
• Data for the editor. Besides XML files and data sets, the Web Forms editor Web.TextControl loads merge data from JSON with LoadDataFromJson and from objects with LoadDataFromModel, each also as an asynchronous method.
• JavaScript API. The API grew substantially: it loads an XML database with loadXMLDatabase, loads and saves the selection, returns the text parts, sets the colors of the control and raises new events, which addEventListener attaches. The Ribbon object expands and minimizes the ribbon.

Document Viewer

An ASP.NET MVC version of the Document Viewer came with the namespace Web.MVC.DocumentViewer: the DocumentViewer extension, configured with DocumentViewerSettings and SignatureSettings. In the browser, the TXDocumentViewer object loads, saves, prints and searches documents. See Document Viewer.

Upgrade to Version 24.0

• View.Changed has a new handler type. The handler type of ServerVisualization.View.Changed changed from System.EventHandler to ViewChangedEventHandler, which passes a ViewChangedEventArgs object to the handler. Code that attaches an EventHandler to the event has to change its handler's signature.
• Update notes. DrawingFrame.Refresh received an overload that refreshes part of a drawing. MailMerge.MergeObjects also merges collections of System.Collections.Generic.Dictionary objects with string keys. View.GetImage received two overloads for clippings. CursorKind has the new values DragDropCopy, DragDropMove and No for the cursors of drag and drop, and DrawShapeEventArgs.Shape the value DropCaret, the rectangle that marks where dropped text is inserted.
• JavaScript members marked obsolete. Several JavaScript members that version 24.0 added, such as TXTextControl.editMode and getTextParts, are marked obsolete in the current reference. The list below marks them.
• Other breaking changes. Breaking Changes starts with version 30.0.

New Classes, Properties, Methods and Events

These are the classes and members that the What's New documentation of version 24.0 lists for TX Text Control .NET Server. .NET names are relative to the TXTextControl namespace. Each name links to its current reference page, and "(obsolete)" marks the members that are obsolete today.

New Classes

• DocumentServer.DataSources.DataColumnInfo
• DocumentServer.DataSources.DataColumnInfoCollection
• DocumentServer.DataSources.DataRelationInfo
• DocumentServer.DataSources.DataRelationInfoCollection
• DocumentServer.DataSources.DataSourceManager
• DocumentServer.DataSources.DataTableInfo
• DocumentServer.DataSources.DataTableInfoCollection
• DocumentServer.DataSources.MergeBlockInfo
• DocumentServer.DataSources.MergeBlockSettings
• DocumentServer.Json.InvalidCodePointException
• DocumentServer.Json.InvalidNumberFormatException
• DocumentServer.Json.ParserException
• DocumentServer.Json.UnexpectedEndOfInputException
• DocumentServer.Json.UnexpectedTokenException
• DocumentServer.Json.UnknownLiteralNameTokenException
• DocumentServer.Json.UnknownParseErrorException
• Drawing.ViewChangedEventArgs
• FilterException
• FrameEventArgs
• LicenseLevelException
• PaperSize
• ParagraphFormat
• ServerVisualization.ViewChangedEventArgs
• TextEditorException
• UserDefinedPropertyDictionary
• Web.MVC.DocumentViewer.ControlBase
• Web.MVC.DocumentViewer.ControlsFactory
• Web.MVC.DocumentViewer.DocumentViewer
• Web.MVC.DocumentViewer.DocumentViewerSettings
• Web.MVC.DocumentViewer.HtmlHelperExtension
• Web.MVC.DocumentViewer.SignatureSettings

.NET Members by Class

Document Editor JavaScript API

Document Viewer JavaScript API

Next Steps

• Version 25.0: the features of the next version.
• Version 23.0: the features of the previous version.
• Older Versions: all versions from 29.0 back to 10.1.
• TX Text Control X14 for Windows Forms, WPF, ASP.NET and ActiveX Released: the release announcement on the Text Control Blog.