Item Reference Configuration

Item Reference Configuration provides the ability to assign JavaScript Methods that get invoked when a referenced Item is created through the process of inserting an instance of an Item Document Element (see Section 2.3.2.2) or via file Drag and Drop (as is the case with Image Files). These JavaScript Methods provide the logic to pre-populate Property values on the newly created Item and validate Property values added/updated by the user in the Item Form.

Figure : Generating a New Referenced Item As described in Section 2.3.2.2, Item Document Elements contain a link between a Document Element in a Technical Document and an Item (Business Object) maintained in Innovator. Often, Properties from the associated Item (or related Items) are used to populate content within the Document. In addition to selecting an existing Item, the Technical Document Editor allows the creation of the referenced Item at the time the Item Document Element is placed. Doing so often requires input from the author to populate Properties on the Item before the record is created in the Database. When configuring a Document Element, it is possible to assign a JavaScript Method that will be executed before the Item Form is presented to the author and after the Form is ‘Accepted’ to generate the Item in the database and establish the reference between it and the Technical Document. The process of creating a referenced Item is as follows:

The Authors selects the ‘New Item’ context menu for the Item Document Element. The system will generate a new referenced Item in the client. Note the same process can be initiated when dragging an Image file from the file system on to the canvas of a Technical Document that is opened for Edit. In this case, an tp_Image ItemType will be created and referenced. The configured JavaScript Method is called to pre-populate Properties on the Item The associated Item Form is presented to the Author/User The author visually validates the content and/or updates as required and selects the ‘Accept’ Button The configured JavaScript Method is called to validate the Properties on the Item The Item is stored in the database The reference to the newly created Item is established with the Technical Document once the Technical Document is saved. In the case where an Image File has been dragged onto the Editor canvas, an Image Document Element, of the appropriate type, will be created and added to the document with the image displayed.

The configuration options for Item Reference Configuration allow: The identification of an alternate Form to be used for Property Updates A Method used to pre-populate Item Properties A Method used to validate Item Properties The option to bypass the display of the Item Form This configuration is specified using JSON for the XML Schema Element associated with the Item Document Element.

Figure : XML Schema Element Form The Editor Parameters input form is configured for displaying JSON content. Syntactical errors will be displayed if the text content doesn’t conform to JSON formatting. To set the Item Reference Configuration, a single JSON object is used with the following properties:

{

 “itemCreation": {

 “formId": "<id of Form Item to use as alternate>",

 “onBeforeInit": "<beforeInit Method Name>",

 “onAfterInit": "<afterInit Method Name>",

 “initializerType": "<initializer type>",

 “fileAccept": “<true/false>”,

 “allowedMIMETypes": “<[comma-delimited array of mime type text]>”,

 }

}

Table : Item Reference Configuration Options

Figure : onBeforeInit Method Example The purpose of the onBeforeInit Method is solely to pre-populate selected Properties of the Item being created. It is meant to provide a convenient mechanism to ensure consistent data for Items and should execute quickly, without excessive memory or processing. The onBeforeInit Method is a JavaScript Method that will be passed two parameters – inDom and inArgs – and must return the inDom input object. The context object of the Method is the Item being created. Thus ‘this’ refers to the Item Object and the standard IOM Item API applies. The inDom parameter represents the XML content of the Item being created also. As such, methods like aras.setItemProperty(inDom, …) will work as well. The inArgs parameter is an object with two properties: documentItem and viewModel. documentItem contains the XML representation of the Technical Document Item in which the Document Element is being created. This object can be used to retrieve information about the Technical Document Item. Likewise, methods like aras.getItemProperty(inArgs.documentItem, …) will work. The viewModel object represents the API for the Technical Document Editor.

Figure : onBeforeInit Method Example The purpose of the onAfterInit Method is solely to validate selected Properties of the Item being created. It is meant to provide a convenient mechanism to ensure consistent data for Items and should execute quickly, without excessive memory or processing. The onAfterInit Method is a JavaScript Method that will be passed two parameters – inDom and inArgs – and must return the inDom input object. The context object of the Method is the Item being created. Thus ‘this’ refers to the Item Object and the standard IOM Item API applies. The inDom parameter represents the XML content of the Item being created also. As such, methods like aras.getItemProperty(inDom, …) will work as well. The inArgs parameter is an object with two properties: documentItem and viewModel. documentItem contains the XML representation of the Technical Document Item in which the Document Element is being created. This object can be used to retrieve information about the Technical Document Item. Likewise, methods like aras.getItemProperty(inArgs.documentItem, …) will work. The viewModel object represents the API for the Technical Document Editor.

If there is a validation error, an alert/message should be displayed, and null should be returned. When ‘base’ is used for the initializerType in the configuration, returning null will prevent the Item from being created.