7.7 Client API

The Technical Document Editor is implemented using JavaScript classes/methods that provide the ability to, for example, add new Document Elements, update styling, link content to selected Items, manipulate content, etc. The Technical Documentation Client Application Programming Interface (Client API) exposes the same underlying functionality in a simplified interface so that it can be used to add custom features within the Editor. This API is made available in user-developed Methods attached to new toolbar items, menus, or key processing events to customize and extend the operation of the Editor. Toolbars, menus, and key events are configured using the Configurable User Interface (CUI) (see the Configurable User Interface Administrator Guide for more information on CUI and how to use this framework to custom the User Interface within Aras Innovator).

The Client API consists of 3 main classes: Document, Schema, and View (see Figure 17). The Document class provides access to all the existing content within an open Technical Document, provides the ability create new Document Elements, and remove (or move) existing Document Elements. The Schema class provides the ability to query the associated Document Schema to check or validate content operations against the user-defined XML Schema. The View class provides access to selected Elements. When used along with custom logic implemented with JavaScript Methods, the breadth of customization options is extensive.

To get a sense of the possibilities of using the Client API, this section provides some samples that illustrate the ways in which the API can be leveraged for specific Use Cases.

Document Elements can have one or more Attributes that can be used to characterize them, or otherwise provide additional semantic information. Attributes can also be used to distinguish styling (see Section 7.2.4). In the following example, a Note Document Element has 4 Attributes; the values of which help identify its Type and are used to isolate unique Styling so that each Note Type can be rendered appropriately. These enumerations are displayed in the Attributes dialog as valid selections for this Attribute:

This example adds a dropdown list control to the Technical Document Editor toolbar that is enabled when the user selects a Note Document Element. This can be used in lieu of the Attributes Dialog as a more convenient mechanism for settings these values.

A sample of the rendered Note Document Element types are as follows:

Schema

<xs:element name="Note">

<xs:complexType>

<xs:sequence>

<xs:element ref="Text" minOccurs="1" maxOccurs="unbounded"/>

</xs:sequence>

<xs:attribute name="type" type="NoteAttType" default="Note"/>

</xs:complexType>

</xs:element>

<xs:simpleType name="NoteAttType">

<xs:restriction base="xs:string">

<xs:enumeration value="Caution"/>

<xs:enumeration value="Warning"/>

<xs:enumeration value="Danger"/>

<xs:enumeration value="Note"/>

</xs:restriction>

</xs:simpleType>

CSS

…

.Note[type='Note’] { border-top: 1px solid blue; border-bottom: 1px solid blue; }

.Note[type='Caution’] { border-top: 1px solid red; border-bottom: 1px solid red;}

…

The Method logic to make the change is as follows:

const { document, view } = options.contextData;

const selectedElements = view.selection.get();

// Set the ‘type’ Attribute for the selected ‘Note’ Document Element

// based on the chosen value from the dropdown box

selectedElements[0]?.setAttribute(‘type’, target.value);

In general, the selected Element is identified, and the Attribute is set based on the user’s choice. Thus, with two lines of JavaScript, and some CSS, a convenient and data-driven mechanism is provided to the Technical Author to automatically characterize and render Note information in a Technical Document.

When authoring Technical Document content, there may be a set of common manual operations that would be more convenient to automate to increase productivity and provide an increased level of consistency. The following Use Case shows an example of List Item Indentation whereby users can increase (or decrease) indentation by inserting (or removing) List Items to provide a sub-List for selected Text.

Figure 15. Shift Right Custom Function

When using List Document Elements (Section 7.1.2), indentation is a matter of creating ‘sub-lists’: Lists that are children of a List Item. For example, in Figure 15 there is a single List with 4 List Items; each with a single Text Document Element. To indent a List Item, a new child List needs to be added with content added as it’s List Items and so on.

Figure 16. Shift Left Custom Function

Figure 15 and Figure 16 also show a customized Shift Right and Shift Left button that has been added to the Editor toolbar. Toolbar buttons can be configured to be displayed and/or enabled based on the state of the Document (whether it is opened for Edit) and/or depending on what the user has selected. In this example, when the user selects any Document Element that is a List Item or a child of a List Item either the Shift Left or Shift Right Button is displayed.

The logic to enable this capability (not shown):

1. Checks to see if the selected Document Element is either a List Item or is a direct descendant of one and that the List Item is not the first in its List
2. If so, the entire List Item Document Element is removed from its parent List
3. A new List is created and appended to the previous List Item
4. The selected List Item is added to the newly created List

The Client API provides the ability to perform each of these steps (and more). Specifically for this example, it uses the View class to ensure that a single Document Item is selected. It uses the Document class to create a new List Document Element, and it uses the selected List Element (explained later) to remove the selected List Item and reposition it in a new List.

This section provides a detailed description of the Technical Documentation Client API. The Client API consists of several JavaScript classes; a definition of the available properties and methods of each are included.

Each Method used with a CUI Item is passed several input parameters. This is standard design for Methods used with CUI. One of them – options – contains a contextData object that is used to access the Technical Document Document and View objects. Document and View are core objects defining the Client API (see Figure 17). For example, the following code fragment will create local document and view variables to be used to access the Document and View respectively:

const { document, view } = options.contextData;

The Document class is the access point for document content as well as information about the Technical Document Item in which the document content is contained.

The DocumentElements class is a container for Document Elements. Note that this class manages Document Element content as a flat list. However, children of specific Document Elements can be accessed using the ElementChildren class defined later.

The Element class is the base class for all Element Types: List, Table, Item, etc.

The ElementChildren class is a container for Documents Elements that are direct children of an associated Element. Similar to an array, the Element children are managed as a sequence representing the order in which content is displayed in the document.

TextElement extends the Element class by providing content specifically for Text Document Elements. Text Document Elements are composed of one or more string fragments (<aras:emph>) that are used to specify distinct formatting. For example, the following string:

This is a sentence with bold, italics, and underlined content.

…would be decomposed into the following string fragments:

<Text>

<aras:emph>This is a sentence with </aras:emph>

<aras:emph>bold="true">bold</aras:emph>

<aras:emph>, </aras:emph>

<aras:emph italic="true">italics</aras:emph>

<aras:emph>, and </aras:emph>

<aras:emph under="true">underlined </aras:emph>

<aras:emph>content.</aras:emph>

</Text>

The terms ‘string fragment’ and ‘emph’ are used interchangeably in this section.

TextElement objects manage the text content as individual objects that can be created, retrieved, and/or updated using the Client API.

The JavaScript to create the sample sentence above using the Client API:

let formattedText = document.createElement(‘Text’);

formattedText.strings.add({text: ‘This is a sentence with '});

formattedText.strings.add({text: ‘bold’, style: {bold: true}});

formattedText.strings.add({text: ', '});

formattedText.strings.add({text: ‘italics’, style: {italic: true}});

…

document.elements.root.children.insert(formattedText);

TextElements are created using either the Document.createElement() or DocumentElements.create() methods. For TextElement objects, the second parameter is optional and can include the text Property as specified in the TextElementEmph class. For example, the following code sample demonstrates an alternative way of creating a new Text Document Element by including the text:

// Create a new Text Element with a single String Fragment

const text = document.elements.create(‘Text’, {text: ‘test text’});

Like all dynamically created Elements, they must be added to the children list of some existing Element to be included in the document.

The remainder of this section includes a description of the TextElement, TextElementStrings, and TextElementEmph classes.

The TextElement class represents a formatted Text Document Element with all its emph content.

The TextElementStrings class is a container for the formatted string fragments – emphs.

The TextElementEmph class manages each formatted string fragment – emph.

TableElement extends the Element class by providing content specifically for Table Document Elements and its related Table Row, Column, and Cell classes. The row and column content of a Table Document Element is managed by the Client API to ensure that all tables are ‘rectangular’. That is, that all rows have the same number of columns, and all columns have the same number of rows. Thus, Cells should not be added/removed independent of their respective rows and columns.

All Table Document Elements must be constructed with a given row and column count > 0. After, new rows and/or columns can be added and removed using the API. The content hierarchy of a Table Document Element is as defined in the schema. Table Document Elements (aras:table) contain Row Document Elements (aras:tr), which contain Cell Document Elements (aras:td) (see Section 2.3.2.6). Thus, when a Table Element is constructed, it’s children should consist entirely of Row Document Elements. Row Document Elements should consist of Cell Document Elements. The content of a Table is stored as children of Cell Document Elements. The Client API will construct/remove/update the appropriate Row and Cell Document Elements based on the associated Table function applied.

The following code sample shows a newly created table with row additions, added content, and cell merging.

// Create a new 3X4 Table

const table = document.elements.create('Table', {rowCount: 3, columnCount: 4});

// Add it to the beginning of the document

document.elements.root.children.insert(table);

// Get the first cell in the second row

const firstCellRow2 = table.cells.get(1,0);

// Insert a new Text Element

const cellText = document.createElement('Text', {text: 'Cell text'});

firstCellRow2.children.append(cellText);

// Add a new second row

table.rows.add(1);

// Adjust the column width percentages

table.columns.widths = ['20', '20', '20', '40'];

// Merge the cell with added Text with its right neighbor

table.cells.merge(2, 0, 'right');

The resulting table:

The remainder of this section includes a description of the TableElement, TableElementColumns, TableElementRows, and TableElementCells classes.

The TableElement class represents a Table Document Element and is the top-most reference object for updating and accessing all content within a Table. All actions on a table are provided by one of the row, column, or cell classes. Each are accessible through the corresponding Property.

TableElements are created using either the Document.createElement() or DocumentElements.create() methods. For TableElement objects, the second parameter to these methods must be included and identify the number of columns and rows using ‘columnCount’ and ‘rowCount’ respectively. For example, the following code sample demonstrates the only valid way of creating a new Table:

// Create a new 3X4 Table

const table = document.elements.create(‘Table’, {rowCount: 3, columnCount: 4});

Like all dynamically created Elements, they must be added to the children list of some existing Element to be included in the document.

The TableElementRows class is an accessor for table Row Elements and provides the ability to add/remove rows. Note that the Row Elements are types of Elements and thus extend the same functionality as an Element object. For example, the children of a Row Element are the set of Cell Document Elements.

The TableElementColumns class provides the ability to add and remove Columns. The Client API will automatically add or remove the corresponding Cell Elements (and their content) respectively.

The TableElementCells class is an accessor for Table Cell Elements and provides the ability to retrieve and merge/unmerge Table Cells. Note that the Cell Elements are types of Elements and thus extend the same functionality as an Element object. For example, the children of a Cell Element are the set of allowed Document Elements as defined by the schema.

TableElementCells Class Methods
Name	Input	Description
get	Returns the cell at the given index. The given row and cell numbers must be >=0 and less than the count of rows/cell respectively.
	row	Index value (starting from 0) of the Cell row
	column	Index value (starting from 0) of the Cell Column
merge	Merges the cell at the given coordinates based on the given direction. Cells can be merged with other cells of similar spans. This mimics the functionality within the Technical Document Editor. For example, to merge 4 cells (2 rows and 2 columns) the cells in each row or column must be first merged before these merged cells are merged with the other column or row. Thus, 3 merge operations are required:
	row	Index value (starting from 0) of the Cell row
	column	Index value (starting from 0) of the Cell column
	direction	String representing the direction of the cell to merge with. Must be one or ‘left’, ‘right’, ‘top’, ‘bot’.
unmerge	Un-Merges the cell at the given coordinates. Any cell within a cluster of merged cells can be given as a coordinate. All merged cells will be unmerged with this operation.
	row	Index value (starting from 0) of the Cell row
	column	Index value (starting from 0) of the Cell column

The ItemElement class extends Element with capability for setting and retrieving Item data. ItemElement objects represent Item Document Elements (see Section 2.3.2.2), which are containers with a direct link to a referenced Item. This link is maintained as a Relationship between the encompassing Document Item and the referenced Item. Item Document Elements typically have a configured Content Generator that, upon creation, executes custom logic to automatically populate the child content; presumably with data from the referenced Item and/or its related content and so on. The Client API extends the ability of a Content Generator to update existing Item Document Elements.

The following code sample shows the process of creating an ItemElement and setting one of the referenced Item’s Properties:

// Get the reference Item to use

const partItem = window.aras.getItemByKeyedName('Part', 'P-Tmp1')

// Create an Item Document Element and add to the beginning of the document

const itemElement = document.createElement('ItemInfo', {item: partItem});

document.elements.root.children.insert(itemElement);

// Set the referenced Part’s Make/Buy Property – changes set on Save

itemElement.item.setProperty('make_buy', 'Buy');

ItemElement extends Element and contains a handle to the ItemElementItem class, which is a wrapper for the referenced Item and provides accessors/mutators for Property data on the referenced Item. This section includes a description of these classes

The ItemPropertyElement class extends Element with capability for setting and retrieving referenced Item Property data. ItemPropertyElement objects represent Mapped Property Document Elements (see Section 2.3.2.5), which are unformatted Text Document Items that link to a specific Property on an Item referenced by some Item Document Element in its parent lineage. This link is loose in that there’s no established Relationship generated. Property mappings are by configured by Property name only. Changing the associated Item Document Element will cause changes to all descendant Mapped Properties regardless of whether the referenced Items were the same ItemType.

The ItemPropertyElement is an accessor to both the ItemPropertyElementProperty Element – that represents the actual mapped Property in the document – and the ItemElement - that is a handle to the associated Item Document Element. Mapped Properties are either read-only, in which case the ItemPropertyElement provides a view of the actual Property data, or they are writable. Writable Mapped Properties provide a proxy editing mechanism using the Technical Document Editor. The Client API caches updates to writable Mapped Properties until the Technical Document is saved and the referenced Items are updated/synched.

The following code sample shows the process of creating an ItemPropertyElement:

// Create a Mapped Property set to refer to the ‘tmp’ Property

const cellMappedProp = document.createElement(‘ItemProperty’);

cellMappedProp.property.name = ‘tmp';

// Add it to the document

firstCellRow2.children.append(cellMappedProp);

When rendered in the document, the generated Mapped Property will display the Property value of whatever Item Element precedes it in the element ancestry lineage if one exists. Otherwise, the content will be empty.

ItemPropertyElement extends Element and contains a handle to the ItemPropertyElementProperty class, which is a wrapper for the referenced Mapped Property and provides accessors/mutators for Property data on the referenced Item. This section includes a description of these classes

The ImageElement class extends Element with capability for setting and retrieving referenced image Items (tp_Image). The 2D Graphic data must come from a tp_Image Item.

The following code sample shows the process of creating an ImageElement:

// Get the tp_Image Item to use for the image data

const imgItem = window.aras.getItemByKeyedName(‘tp_Image’, ‘G-00016');

// Create the ‘Graphic’ Image Element and set the tp_Image

const imageElement = document.createElement(‘Graphic’);

imageElement.image.node = imgItem;

// Add it to the document

document.elements.root.children.insert(imageElement);

This section includes a description of these classes.

View provides access to the Technical Document Editor selection, scroll, and invalidation capability. This section provides a description of each of these functions and how they can be applied.

View is an accessor to each of the Classes that provide for the functions mentioned above. Its only content (for the Client API) are handles to the Selection, Invalidation, and Editor Controls defined in this Section.

The Selection class provides the ability to get a list of selected Elements or set this list. This is useful for identifying the Element (or Elements) to apply a custom function to or direct the user to an Element (or Elements) by programmatically selecting them.

The following code sample shows the process of selecting a specific Text Element:

// Get the full set of Document Elements

const select = document.elements.root.descendants;

// Restrict to a subset of only Text Elements

const selectText = select.filter((element) => element.is(‘Text’));

if (selectText.length >= 1) {

const lastTextElement = selectText[selectText.length-1];

view.selection.set(lastTextElement);

}

The Invalidation class provides the ability to suspend the updates made visible in the editor so that multiple functions can be applied atomically. Within the Client API, when an Element is added, removed, or modified the UI is simultaneously updated. This may be time-consuming and/or result in unnecessary synchronization operations if there are many updates. In addition, the undo buffer is updated with each of these individual function calls. The Invalidation class provides a suspend and resume method to be used to wrap multiple operations so that they are applied together.

The following code sample will create a table like Figure:

// Temporarily suspend Editor UI operations

view.invalidation.suspend();

// Create a new 3X4 Table

const table = document.elements.create('Table', {rowCount: 3, columnCount: 4});

// Add it to the beginning of the document

document.elements.root.children.insert(table);

// Get the first cell in the second row

const firstCellRow2 = table.cells.get(1,0);

// Insert a new Text Element

const cellText = document.createElement('Text', {text: 'Cell text'});

firstCellRow2.children.append(cellText);

// Add a new second row

table.rows.add(1);

// Merge the cell with added Text with its right neighbor

table.cells.merge(2, 0, 'right');

// Resume to apply changes

view.invalidation.resume();

The suspend and resume method calls must be applied in pairs, or the results are undefined. In this example, there are several operations that would cause an update to the UI. These include the insertion of the newly created Table, the insertion of the newly created Text, the additional Row, and the Merge of two Cells. By wrapping these operations within suspend/resume calls, the entire set of updates are treated as one.

The Controls class provides access to the Editor class for use in programmatically scrolling the View. This is useful when directing the user to a newly selected Element.

The following code sample shows the process of selecting and scrolling to a specific Text Element:

// Get the full set of Document Elements

const select = document.elements.root.descendants;

// Restrict to a subset of only Text Elements

const selectText = select.filter((element) => element.is(‘Text’));

if (selectText.length >= 1) {

const lastTextElement = selectText[selectText.length-1];

// Make sure the selected Element is in view

view.controls.editor.scrollTo(lastTextElement);

view.selection.set(lastTextElement);

}

Note that the Editor class is accessed through a single Property of the Controls class as shown above.

The Schema class provides the ability to access Document Schema information and validate operations on content within a document against the limitations and restrictions specified by the Document Schema. Schemas define restrictions with respect to the type of Document Elements that can be used, allowed Attributes, and cardinality.

The following code sample shows how the schema can be used to check for the addition of an Element.

const { document, view } = options.contextData;

const schema = document.schema;

…

const lastTextElement = selectText[selectText.length-1];

// Check to ensure that a new Text Element can be added to the document

const allowed = schema.checkElementAction(‘append’, lastTextElement, ‘Text’);

if(allowed)

{

// Code to append new content…

}

The logic in the sample retrieves the last Text Element in the document and checks the schema as to whether appending another Text Element is allowed. Actions of ‘append’ and ‘insert’ are permitted. Programmatically validating operations to a document in this manner ensures that the structure of a technical document conforms with the rules designated by the associated schema.

The elements parameter is dynamically generated based on the XML Elements defined in the XML Schema (see Section 2.3.1). Data for each XML Element is accessed using the Element’s name as an index. For example, in the sample below to access data about the XML Element ‘Note’ use elements[‘Note]. The most useful part of this information is the attributes list, which contain the permitted values as defined in the schema if they are defined there. Element attributes provide metadata, which can be used to characterize or classify element instances. The following example shows how you can process the schema example in Section 7.7.3.1 to extract the defined/permitted Attribute values for the Note XML Element:

// Retrieve the Note Document Element Schema Item

const noteElem = schema.elements['Note'];

// Get the Attributes definition for this Element

const attrs = noteElem.declaration.elementAttributes;

// Search for the ‘type’ attribute to get the defined/allowed values

for(const attr of attrs)

{

if(attr.Name === 'type')

{

var restrictions = attr.Restriction !== null ? attr.Restriction : [];

// Use the attribute value setting from the schema

resultSettings.options = restrictions.map(function(restVal) {

return {

label: restVal.Value,

value: restVal.Value

};

});

}

}

Each XML attribute object in elementAttributes has a Name and a Restriction Property array if restrictions were defined in the XML schema. The Restriction Property contains Type/Value pairs.