Adding Rows for New or Existing Objects to the Structure

You can define a structure browser to use toolbar buttons to add new rows (for new objects or to connect existing objects) to the structure browser.

The following topics are discussed:

Parameters for Adding Rows

These URL parameters are used:


  • lookupJPO. Defines the JPO:method used to find the needed object to connect, based on search criteria entered by the user. The user clicks the Lookup Entry button to invoke the JPO.
  • insertNewRow. Accepts a true or false value. If used, you must also use the connectionProgram URL parameter. When the user clicks the Apply button, the connectionProgram is called to create and connect the object.
  • applyURL. Defines the URL to which all newly-added and modified rows are posted as an XML element with the parameter name postDataXML. The user clicks the Apply button to submit the defined URL. When used, the applyURL is used in place of the default AEF Apply action. Also, any postProcessURL or postProcessJPO will not be invoked.

The structure browser uses to indicate a new row used to create a new object, and to indicate a new row for connecting an existing object.



When creating a new row, if the attribute shown in a column has a schema-defined default value, that value is automatically populated in the column. However, if that column has the Default Program and Default Function settings defined, the value returned by the Default_AddNewRow or Default_ExistingRow key from the JPO overrides the schema-defined default value.

The user has the option of adding the new row above or below a selected row. If the structure browser does not contain any rows, the user can still insert new rows:

  • For flat list: new rows are added to the empty structure browser. The user can add as many empty rows as needed as long as the rows are not saved and checked.
  • Multi-root nodes: a single new row can be added to the empty structure browser. The user must enter data in the row and save it before adding more rows.

See the Editing a Structured Data Page for details on how the user works with this tools.

The display of these toolbar buttons is controlled by which URL parameters are passed to the structure browser:


  • (create new object) displays if insertNewRow=true or applyURL is passed
  • (connect existing object) displays if lookupJPO is passed
  • (remove inserted row) displays if any of these parameters is passed: insertNewRow=true, applyURL, or lookupJPO

If the indicated URL parameter is not passed, then that toolbar button does not display on the structure browser.

Location of Inserted Rows

When using or , the location of the inserted row depends on whether the structure browser is defined to use flat table mode, single root object, or multiple root objects. If the user selects a row first, the user can click the arrow in the button to define where the new row is inserted:

or

These menu commands do not work with a flat structure browser. When using these menu commands, only one row can be selected.

If the user clicks the icon instead of the arrow, these rules apply:


  • When inserting a row in a structure browser in flat table mode (see Structure Browser in Flat Table Mode), the row is inserted at the top of the structure browser. The user cannot change this location by selecting any rows in the structure browser.
  • When inserting a row in a structure browser defined with a single root object, the placement depends on whether any rows are selected:
    • If no row is selected, the new row is added to the top of the first level of children (the level immediately below the root node).
    • If one row is selected, the new row is added as a child to the selected row, at the top of that node's list of children.
    • If more than one row is selected, an error message displays.
  • When inserting a row in a structure browser defined with multiple root nodes, the placement also depends on whether any rows are selected:
    • If no row is selected, the new row is added as a root node at the top of the listing for the page.
    • If one row is selected, the new row is added as a child to the selected row, at the top of that node's list of children.
    • If more than one row is selected, an error message displays.

The (Remove) button can be used to remove any selected rows inserted using or prior to the Apply button being clicked.

Column Settings for In-Line Creation/Connection

To enter data inline for a new object (see Add a Row for a New Object) or for connecting an existing object (see Connect an Existing Object (Lookup)), these settings for the column are used:


  • Lookup Input Type. The input control used to enter search criteria when connecting an existing object. A column with this setting is mandatory.
  • Add Input Type. The input control used to enter values when creating a new object. A column with this setting is mandatory.
  • autoNumber. Used for Name columns. When autonaming is used for objects, this setting allows the user to choose the auto number series. The value for this setting is the symbolic name for the type, for example: autoNumber=type_HardwarePart.
  • Show Clear Button. Use with a textbox input control configured with a chooser.
  • Default Program. This setting specifies a JPO name used to populate the default value when using the add existing row functionality.
  • Default Function. This setting specifies the method within the JPO specified by the Default Program setting. The string value defined for the keys Default_AddNewRow and Default_ExistingRow is used to populate rows for creating a new object or connecting an existing object. The same or different defaults can be used for these keys.

The Lookup Input Type and Add Input Type settings can take any of these values:


  • textbox (default)
  • combobox
  • radiobutton
  • listbox
  • listboxmanual

These input controls work the same as describe in In-cell Editing.

As with other list boxes, if the user selects multiple values (using the control key), only one value is saved unless you define a custom JPO to process multiple values.

If the autoNumber setting is defined for a column (usually a Name column), the user can select a series or manually enter a name.



For structure browsers that may have different object types in a column, the OnChange Handler or OnFocus Handler settings must be used to select the appropriate autonumbering for the current row.

If a column has different input controls defined for any combination of the Input Type, Add Input Type, or Lookup Input Type settings, then that column can not be used for mass update. If the input controls for these settings are all the same, then the column can be used for mass update.

Add a Row for a New Object

Users can add a blank row to the structure browser to create a new object. This new row is equivalent to creating a new object using a create form. To support this function, the structure browser must display all columns that are defined as required on the equivalent create form. When the user adds a row, the structure browser automatically populates any fields defined with default values in the schema. In addition, the Default Program and Default Fucntion settings can be used to populate default values for new rows. The user can change any of these values as needed.

After the user enters the data for the new object, the Apply button invokes the JPO:method specified by the connectionProgram URL parameter to create the object. The user can add any number of rows prior to clicking the Apply button.

The page passes all newly-created rows to the JPO as input parameters. The JPO returns a list of the created objects. If the data entered for any row did not define a unique object (or another error occurs), the JPO returns an error. The structure browser indicates the error (user can see text of message by mousing over the ).



See the JavaDocs for details of the JPO.

Connect an Existing Object (Lookup)

Users can also add a blank row used to load an existing object from the database. The user enters search criteria in the row, then clicks Lookup Entries. The system first validates the criteria (using the validation method defined by the OnChange Handler setting on the column), then invokes the JPO defined by the lookupJPO URL parameter passed to the structure browser.

The OnChange Handler for the column is invoked with these parameters:


  • cell value
  • New or Lookup

For the second parameter, Lookup is used for inserted rows and New is used for the normal apply function.

The page passes the search criteria entered in the added rows to the JPO as input parameters. The JPO returns the matching objects, or an error message if more than one or no matching object was found. The structure browser indicates the error (user can see text of message by mousing over the ).



If a column does not have the Lookup Input Type setting defined, the user may still enter a value although it is not used as search criteria. When the object is found, if the database value is different from the user-entered value, the cell shows as though the user edited the value: the original database value is shown in red, strikethrough text, with the value the user entered shown in bold italic text. This also applies for columns populated based on a relationship to the object (not as an attribute of that object).

In addition, if a column does not have the Lookup Input Type setting defined but has the Default Program and Default Function settings defined, the value returned by the Default_AddNewRow or Default_ExistingRow key from the JPO shows as though the user had entered that value. That is, if the database value is different from the user-entered value, the database value is shown in red, strikethrough text and the user-entered value is shown in bold, italic text.

Once all rows inserted using have been verified and the page is updated by the JPO:method defined by the lookupJPO, the button on the structure browser changes to Apply.

Apply Modifications to a Structure Browser

When the user clicks Lookup Entries, the JavaScript validation functions defined by the Validate setting is invoked with the cell value passed as the first parameter, and either lookup or new as the second parameter indicating the type of validation test -- looking for a match or creating a new object.

When the user clicks the Apply button, the structure browser either:


  • invokes the JPO:method specified by the connectionProgram URL parameter
  • submits the URL defined by the applyURL parameter

For the applyURL, the URL can be any configurable component or custom JSP page. The newly-added and modified rows are submitted as an XML element with the parameter name data to the specified URL. The posted data can be accessed from the specified URL using request parameters.

If the URL specifies a custom JSP page, that page should invoke the API emxEditableTable.refreshStructureWithOutSort() to refresh the view (see Appendix: JavaScript APIs). If an error occurs in the JSP page, the custom page should invoke the API emxEditableTable.displayValidationError(); with an XML containing the rowId and error message. See Displaying Validation Errors.

When the applyURL parameter is passed, any URLs or JPOs defined by the postProcessURL or postProcessJPO URL parameters are not invoked.