Use the Add Multiple Existing Objects pattern when a user needs to add multiple objects to a table all at once, using one or more queries. This pattern is not appropriate when a user needs to create new objects. If the user needs to create new objects, use the Create Pattern Set.
|
To search for and select existing valid objects, the user clicks the Select and Add icon button from the table toolbar.
 |
| Figure 1. Clicking the Select and Add icon button from the table toolbar to search for and select existing valid objects |
| Required Screen Elements |
| Component Type |
Required Components |
Customizable or Extendable Components |
|
Icon Button |
Icon button in the table toolbar with a tooltip that should read Select and Add. |
NA |
| Menu |
Corresponding action menu item should read Select and Add. |
NA |
A dialog box appears that contains a query component and a search results list. When a user enters search criteria against valid existing objects and clicks the Search button, the results appear in a table below the query component.
 |
| Figure 2. Entering search criteria and viewing results below |
| Required Screen Elements |
| Component Type |
Required Components |
Customizable or Extendable Components |
| Dialog Box Title |
Use this format: "Select and Add: <Object>" (where the object type is the object being added to the table)
For example: Select and Add: Contacts |
NA |
| Search Panel |
Use this title: Search |
Search panel display is optional if product teams want to fix the query run in this dialog box. The panel appears by default. |
| Results Region Location |
The location of the results region should:
- Appear in the dialog box
- Appear directly below the search region
|
NA |
| Results Region Contents |
Ensure that search results appear in a read-only table.
|
Table components, such as the QBE bar, may optionally be available. Product teams can code the results table to have previously selected items not appear in another query if adding duplicate records is not allowed. If you add an object to the table and then add another existing object, the previously added object should be excluded from the second query's results. |
| Dialog Box Toolbar Buttons |
The following buttons appear in the footer of the dialog box:
- Apply: Adds the currently selected results rows to the base table as new rows without closing the dialog box.
- OK: Closes the dialog box and applies any selected results rows to the base table as new rows. If the user runs only one query and selects one or more items from the results table, clicking OK applies those selected items to the base table and closes the dialog box. If rows were already added by clicking the Apply button, clicking the OK button will not re-add those rows to the base table as new rows.
- Cancel: Closes the dialog box and any uncommitted changes (those applied to the base table after the user clicks the Apply button).
|
The Apply button is not required if the optional query region is not available. |
| Results Table |
|
Product teams can choose to expose on the results table a toolbar from which actions may be performed (such as Create if a result isn't found). |
Users select one or more objects that they want to add to a table and then click the OK button to close the dialog box and return to the originating table. Users may also select objects, click the Apply button, and then run another query to add the selected items to the base table without closing the dialog box. Each time that a user clicks the Apply button, the base table updates. After multiple queries have been run and objects have been added, the user can click OK to close the dialog box. Clicking OK after adding rows using the Apply button will not re-add the selected object to the base table as a new row. Rows are added only once to the base table unless there is a business reason to do otherwise.
 |
| Figure 3. Selecting objects that you want to add to a table |
The user is returned to the originating table, and the selected objects have been added as new rows.
 |
| Figure 4. Selected objects appear as new rows in the table |
| Required Screen Elements |
| Component Type |
Required Components |
Customizable or Extendable Components |
| Table or Tree Table |
The added row should always be visible. Placement of the newly added rows is dependant on what (if any) row is selected.
For more specifics, see the Table Common Actions guideline.
|
NA |
|
