Adding Document Elements

Technical Documents consists of a collection of one or more Document Elements arranged in a hierarchy and sequence governed by the associated Technical Document Type. Each Document Element contains some type of content, e.g., text, images, or other Document Elements. Once the Document Element is created, the author can then proceed to add its content.

Document Elements are typically created, removed, or updated through an explicit action executed by the selection of context-sensitive menus attached to each node in the navigation pane or set of content in the editor. Only changes that are allowed at each location will have corresponding menus included. For example, given the Document Structure defined in Figure 3, once a Title is added to a Document Element of type ‘Standard-Doc’ the author can only add a Subtitle or a Section. In this case the context menu for adding content to the document after the Title Document Element is placed will be at Subtitle or a Section.

Figure 17.

When a Document Element is selected in the content editor/viewer, selecting the <Enter> key will display a context-sensitive context menu displaying the options associated with adding content at that location. For example, instead of using the right-mouse button display the context menus in Figure 4 if the author selects the Enter key the following context menu will be displayed:

Figure 18.
The menu options displayed are for Adding content. Recall that the term ‘Add’ refers to adding peer Document Elements. The top menu item (‘Go up’) is used to display the ‘Add’ menu items for the parent Document Element. This functionality is most useful when adding content within a List.

A Technical Document consists of a hierarchy of Document Elements that collectively form a lineage of Document Elements with potentially multiple branches of arbitrary depth. There can be one or more root (or top-most) elements each containing child elements, which can in turn contain child elements and so on. The complete document element tree is exposed in the navigation pane in the editor.

The addition of Document Elements to a Technical Document is usually done in the context of another, existing Document Element. A new Document Element is either a peer or a child of the existing element. In the nomenclature of Technical Documentation ‘Adding’ refers to the addition of a peer and ‘Inserting’ refers to the addition of a child. For each existing Document Element in a document if it can have peer elements an Add sub-menu will exist in the context menu with sub-menus items for each allowed Document Element. Likewise, if an existing Document Element can have child elements, an ‘Insert’ sub-menu will exist in the context menu.

All text-based content for a Technical Document is included in one or more Document Elements. These Document Elements are configured to either include formatted or unformatted text. Note that most of the style and positioning rules for text-based content should be defined for the Document Element as part of the Technical Document Type Style. In this case, authors simply add the text, and the system applies the appropriate style (color, size, position, margin, etc.) automatically.

Once any Document Element that is of type formatted text or unformatted text is added to a document, a text entry area is added to the Content Editor with the default ‘Text…’ displayed as a placeholder. Once the author begins typing text characters, they are displayed in succession in the entry area for the element. As text is typed the text for the Document Element node in the navigation pane is updated. Any text that is too long to display in the navigation pane is truncated with an added ellipsis. When typing Text content, selecting the Enter key will result in the automatic creation of a Text Document Element and subsequent characters will be added to the new Document Element accordingly.

Formatted text can have a limited set of styling applied by the author. In general, style for text-based content should be specified by the style associated with the Technical Document Type. When any formatted text-based document is selected the toolbar for the Editor is updated to display additional buttons that can be used to apply the following style to the currently selected text (if any text is highlighted) or will apply to newly typed characters starting at the location of the cursor in the text area:

Figure 19.

Other than symbols, the formatting options are toggles; they either are applied to newly typed text or not. Each of these can be applied collectively. For example, text can be both bold and italics. Un-applying any of these formats is simply a matter of selecting the text and selecting the appropriate format button to undo the application of the format.

Unformatted Text cannot have any additional style applied by the author. It can, however, have style automatically applied as defined by the style associated with the Document Type.

A set of additional character symbols is added to the editor and accessed by selecting the Symbol button in the editor and selecting the character button in the pop-up tooltip. These additional characters can only be applied individually to formatted text Document Elements.

In any given Document Element context, if there exists a child Document Element of type formatted or unformatted text (as defined by the Technical Document Type definition) it will be automatically inserted when the author begins to type in the editor. For example, using the document structure as defined by Figure 16, when the author places a Standard-Doc Document Element in the document and subsequently begins typing text, a Title Document Element will automatically be added, and the typed text automatically added as content. In this case, the system ‘knows’ which document element to automatically insert because the rules of the Technical Document Type describe it - a Title Document Element must exist as the first child element under the Standard-Doc element. Because this element is a text-based element, the typed text is added to the Title document element after it is added by the system. As a second example, a List Document Element contains one or more List Item Document Elements. After a List Item is added and the author begins to type text, a Text Document Element is automatically inserted, and the typed text added as content. In this case, the Text Document element is the only text-based document element for the List Item. The system assumes that when the author begins typing text that a Text Document Element should be placed.

To a certain extent, this automated behavior helps to streamline the authoring process and attempts to emulate (as much as possible) common word-processing behavior. Since the Technical Documentation Framework is a structured document application, all content must be attributed with specific Technical Document Types. Thus, any text must be included within a Document Element.

Text-based content does not include newlines/line breaks by default. This assumes that any paragraph will exist within its own Document Element. The default handling of the Enter key is to display a context menu (see section Handling the Enter Key) or to automatically place a new Document of the same type when such a Document Element is allowed by the associated schema. The method for embedding a line break within a text-based Document Element is to use the Shift-Enter key combination. Doing so will result in a newline/carriage return added at the current location of the cursor.

Text content can be cut/copied from one Document Element and pasted within another. In this case, all formatting will be retained in the pasted text. In addition, text can be copied from another application and pasted within a Document Element. Text content copied from an external application will not retain its formatting. Any copied text content is pasted within the system’s copy buffer and can thus be used as a transfer mechanism to and from a Technical Document.

To copy text, select and drag the cursor using the left mouse button over the text to be copied in the content Editor/Viewer. The selected text will be highlighted. The Ctrl-C key combination will copy the highlighted text to the copy buffer. Note the Copy menu item in the document element’s context menu is used for copying the Document Element, not the selected text.

To place copied text, place the cursor within the text area of an existing Document Element and use the Ctrl-V key combination. The text in the copy buffer will be inserted at the cursor location. Note the Paste menu item in the document element’s context menu is used for pasting a copied Document Element, not the text in the copy buffer.

Lists within a Technical Document are implemented using Document Elements based on a List Type. Lists are essentially containers with an unlimited number of List Item Document Elements.

When a List Document Element is created its List Items can be rendered as either bulleted, numeric, or alpha. The default is bulleted. Selecting either a List or List Item Document Element will expose the following toolbar menu buttons. The selected option will have a box around it. All List Document Elements displayed in the navigation pane will be displayed with the List icon.

Figure 20.

List Document Elements are expected to have child List Item Document Elements as the only element content. List Item Document Elements act as the container for all content that can be included. For example, the document structure defined in Figure 3 identifies the Document Elements that can be included in a List Item: Text, Graphic, other Lists, and Tables in any order and in any number. All List Item Document Elements displayed in the navigation pane will be displayed with the List item icon.

Tables within a Technical Document are implemented using Document Elements based on a Table Type. Tables are essentially containers with an unlimited number of Row Document Elements.

Tables in Technical Documents are restricted to be ‘rectangular’. That is, every row must contain the same number of cells/columns and every column must contain the same number of rows. This restriction is supported in the table-specific context sub-menus that are displayed in the content editor. For example, a Cell Document Element cannot be added to one Row without a new Cell being added to all Rows. As a result, only Row and Column operations are displayed in the context menus.

When a Table Document Element is added the author is presented with a dialog to choose the number of rows and columns.

Figure 21. The default number of rows and columns is 2, with a maximum of 10 rows and columns for each initial value.

Tables are rendered in the content viewer/editor based on the Style settings for the associated Technical Document Type. The out-of-the-box Style configuration uses a single black border with alternating background colors for the cells in even/odd rows.

Table Document Elements have specific context menus for adding and removing columns and rows. The Table context menu will only be displayed when either a Table, Row, or Cell Document Element is selected.

Figure 22.

When adding a row or a column to a table a row/column is always added below or to the right respectively. Note that the Table context menu will be different depending on which type of Document Element is selected. In Figure 22, a Cell Document Element was selected in the content editor. In this case, the Insert context sub-menu will display a list of Document Elements that can be inserted into the cell. The Table sub-menu (as shown) displays menu items for modifying the table at that selected location in the table. For example, adding a column would add a new column between the columns with header titles ‘Heading A’ and ‘Heading B’. Adding a row would add a new row to the bottom of the table.

The Content Editor supports the ability to merge and unmerge cells in a table. Merge/Unmerge functions are applied one cell at a time. That is, to create one cell across all columns in one row, the author must first merge two adjoining cells and then merge that with neighboring cells and so on. Also, merging cells that are already merged with a neighboring row or column requires the adjoining cells to have been merged prior. Using Figure 23 as an example, to achieve the table configuration in the last step the first two cells in the second row are merged, followed by the first two cells in the third row. At this point, the first (merged) cell in the second row can be merged with the first (merged) cell in the third row.

Figure 23.

The Unmerge function will unmerge all cells that are merged for the selected cell. That is, to apply an Unmerge function to the merged cells in the last table in Figure 23 would return the table to the original state as shown in the first table.

Text content within a Technical Document can be linked to any Document Element within the same Technical Document or within a separate Document Element. In addition, text content can also be associated with a URL, like a hyperlink in an HTML document. Both types of links behave similarly when the content with these links are exported/published (see section Publishing / Exporting). Once the link is created, the Content Editor can be used to explore the linked content. Links between Document Elements establishes a Relationship between the two corresponding Technical Document Items. Thus, linked Document Items cannot be removed if they are the target of an existing link.

To create a link to a Document Element:

1. Select the text from within an open Technical Document in Edit mode.

2. Place the cursor over the beginning of the text and drag with the left mouse button pressed to dynamically select all text characters/words associated with the link.
3. Select the Create Link button in the toolbar.

The Link Editor Dialog will be open and display the contents of the currently opened Technical Document at the top.

Figure 24.

4. Select the Document Element from the current document to set as the link target or search for another document using the search grid at the lower portion of the Link Editor Dialog

Document Elements are selected the same as in the Editor; either by selecting a node in the Navigation Pane or selecting the element in the content viewer. If another document is searched, select the Open Document button (green check mark) above the search grid to display the selected document.

5. Select the Accept button (green check mark) at the top of the dialog to accept the link target

Doing so, will close the Link Editor Dialog. The text used for the link in the source document will be highlighted to indicate that the text is associated with a link.

1. To create a link to a URL:
   Select the text from within an open Technical Document in Edit mode.
2. Place the cursor over the beginning of the text and drag with the left mouse button pressed to dynamically select all text characters/words associated with the link.
3. Select the Create Link button in the toolbar
4. Select ‘URL’ from the Link Type combo box in the top portion of the Link Editor (Figure 11)
5. Type the URL for the link in the text edit box.
6. (Optional) Select the Check URL button to open a separate browser window using the URL that was typed

Once a link has been created, the target content can be modified by selecting the Edit Link button on the toolbar. This button, along with the Test Link and Remove Link buttons, will be displayed when text containing a link is selected in the content editor.

Figure 25.

When the Edit Link button is selected, the Link Edit Dialog is displayed. At this point, the author can select the Document Element (or URL) to use like the steps in section Creating a Link to a URL and section Modifying and Testing a Link.

To test a link, select text containing a link and select the Test Link Button. The Link Edit Dialog is displayed with the Technical Document (containing the target Document Element) shown and the Document Element target selected. If a URL was used for the target, a browser will be opened to the selected URL.

Item Document Elements are Document Elements with a Relationship to an Item within Innovator. A Relationship (of type tp_ItemReference) is created between the Technical Document and the selected Item. A referenced Item can be either a Part, Document, or CAD Document.

When an Item Document Element is added to a Technical Document, the author is prompted to select an existing Item. Adding Document Elements of this type to a Technical Document enables the author to establish a direct relationship to Items that, presumably, the document is written for. Once included in a Document, the author can view the associated Item by selecting the node of the Item Document Element instance in the Navigation Pane and select the ‘View Item’ sub-menu. Doing so will open the main Form associated with the Item. Nodes of this type will be displayed in the Navigation Pane using the icon associated with the related Item.

Item Document Elements typically have Content Generators associated with them (see section Storing and Viewing Content in Separate Languages). In this case, the content created by the Content Generator is added to the document automatically. Item Document Element instances together with Content Generators allow authors to quickly and efficiently created document content dynamically and enable the synchronization between the two.

Figure 26.

Mapped Property Document Elements are a type of Unformatted Text Document Element that are used to reference a Property of an Item referenced by an ancestor Item Document Element. When authors place instances of a Mapped Property Document Element, the system will automatically apply the content of the associated Property of the referenced Item.

Mapped Properties are configured with Document as part of the associated Document Type. Mapped Property Document Element have two Attributes: ‘Property’ and ‘Mode’. The Property attribute specifies the name of the Property that is mapped. The Mode attribute specifies whether the Property (and thus the related Item) can be modified within the Technical Document.

Figure 1: Attributes Dialog for Mapped Property Document Elements

Mapped Property Document Elements are edited using a pop-up Form in the Technical Documentation Framework. To edit a value, select the Document Element in the Editor or Tree View and/or double-click to display the Property Editor Form. Document Elements with a grey, dotted border can be edited. Document Elements with a red, solid border are read-only. For example:

Figure 2: Mapped Property Editor Form

Values can only be changed using this Form. Selecting the ‘Check’ button will update the Mapped Property Document Element in the technical Document only. Authors will see a pencil icon ( ), signifying that the Property of the referenced Item has not been updated, next to the Document Element in the Tree View. The referenced Item will be updated when the technical document is saved, in which case the pencil icon will be hidden. Selecting the ‘X’ button will cancel the update without any changes to the technical document.

The following Property Value Types are supported:

• String
• Text
• Numeric (Integer, Decimal, etc.)
• Date
• Boolean
• Item (Display only - Editor not available)
• List (Display only - Editor not available)
• Image (Display only - Editor not available)

The Editor can display multiple Property Types, as shown above, but not all can be edited with the Technical Documentation Framework. Authors will be presented with an error if an attempt is made to edit an unsupported Type:

Figure 3: Mapped Property Editor Error Dialog

The Edit Field in the Property Edit Form is based on the Property Type. For Text and Numeric Fields, an attempt to set a value that does not match the type will result in an Error being displayed in a Dialog.

Figure 4: Mapped Property Edit Forms

Modifying a versionable Item vis-à-vis Mapped Property Document Elements will result in the referenced Item to be versioned automatically. Since Technical Documents refer to Items via fixed Relationships, the Item Document Element will show as stale since it will refer to the previous generation of the Item.

Image Document Elements refer to any 2D raster or vector-based image that is supported by Innovator. All graphical content for a Technical Document must be stored as a separate Graphic Item. The Technical Document Application includes a ‘Graphics’ TOC folder that includes Graphic instances. Graphics have the following Form:

Figure 27.

To add an image to a Technical Document, Add or Insert any Image Document Element Type. The user will be presented with a Search Grid for Graphics. Selecting an instance will add the corresponding image content at the selected location with the document. In addition, a Relationship is added between the Technical Document and the selected Graphic.

Image Document Elements can be added, and the corresponding Graphic Item automatically created, while pasting an image into the Editor View. The process is as follows:

1. Select an image and copy it to the clipboard. Note that the image itself needs to be copied; not the image file
2. Select Document Element after which you wish to place the new Graphic. Note that if a Container Document Element is selected, the system will check whether a Graphic Document Element can be added as a first child. If so, the new Graphic will be added as a child.
3. Select Ctrl+V (Paste) to start the process
4. The system will display a Graphic Item Form Element with the image was selected
5. Fill out the Form as required
6. Select Ok to create the Graphic Item and place the new Image Document Element
7. Select Cancel to cancel the operation. In this case, a new Graphic Item will not be created.

Image Document Elements can be added, and the corresponding Graphic Item automatically created, while dragging an Image File from the local file system into the Editor View. The process is as follows:

1. Select an image an image file from the local file system and drag (with left mouse button held down) the file onto the Editor View.

2. The system will display a thumbnail image with the cursor as the file is moved/dragged over the contents in the Editor View. A blue or orange will display between the content to identify valid or invalid drop locations respectively.

   

   

   

   

3. Lift the left mouse button when the desired location is found.
4. The system will display a progress dialog showing the file upload operation. Selecting Cancel within this dialog will cancel the operation and no Graphic Item will be created. Once the image file has uploaded the system will display a Graphic Item Form Element.
5. Fill out the Form as required
6. Select Ok to create the Graphic Item and place the new Image Document Element
7. Select Cancel to cancel the operation. In this case, a new Graphic Item will not be created.