About the Visual Designer Multi Entity Grid

The Multi Entity grid displays information about the relationship between the records in two services and allows users to easily add, modify, or delete these relationships. For example, the figure below illustrates the multi entity grid that is included on the Employees form's Skills tab where the Skills records are the rows and the current employee is the single column in the grid. The individual cells in this case identify if the employee is linked to a particular skill (that is, the cells represent actual or potential EmployeeSkills sub-type records). These Employee/Skills relationships can easily be created or deleted by adding or removing a check mark from the appropriate cell.

The features of a multi entity grid include:

• Two Cell Modes: The cells of a multi entity grid can use one of two modes:
  • Check Box: This option identifies if a relationship exists between the row record and the column heading. For example, in the example above, Tim Jones has a check mark in the Management column, which indicates that an EmployeeSkills record exists to track this relationship.
  • Data Entry: This option displays a value from the corresponding record that can be added, edited, or deleted directly within the column's grid. For an example of this implementation, see the Culture Strings form's Local Strings tab. The multi entity grid on this tab displays values from the Local String field of the sub-type record, so a user can easily add new localized content for the Culture String in one or more cultures. See Working with Culture Strings for more information.
     
• Support for Two Display Locations: The Multi Entity Grid control is both a form component and a dashboard component, which means you can add it to dashboard and to forms. See Configuring the Multi Entity Grid Component for information on how to add the multi entity grid to a dashboard.
• Double-click to Open Records: Double-clicking a row heading, column heading, or within a cell opens the corresponding record.
• Toolbar: The multi entity grid contains a toolbar with these options:
  • Open: This button opens the corresponding record for a selected row, column, or cell.
  • Refresh: Clicking this button refreshes the grid. If you make a change to a cell and the change does not reflect immediately, click the Refresh button to display the latest data.

  • Help: If the sub-type entity linked to the grid's cells has on-line help, clicking this button opens the on-line help file in the appropriate location.

    The dashboard implementation of the multi entity grid includes a Refresh button its toolbar. This button is not applicable when the multi entity grid appears as a tab on a form (so the button is not available)

This component supports the following input properties (see the example below; it shows how the input map for the Employee Skills tab has been populated to achieve the grid layout shown in the figure above):

• CellDataSourceEntity (required): Specify the sub-type entity that provides a relationship between the two services you will specify as the grid's rows and columns. Note that one of the services (either the rows or the columns) must be the parent for this sub-type entity.
• CellDisplayField: If you enter Field option for the CellDisplayMode, specify the field from the sub-type entity whose values you want to display in the grid's cells. Users will be able to modify these values directly within the grid.
• CellDisplayMode (required): Enter Exists to display a check box that identifies if a corresponding subtype exists or does not exist. This option is only suitable if the only required fields in the sub-type are links to the row and column services or have a default value specified. Enter Field to display the value of a particular field in the specified sub-type entity.
• ColumnDataSourceEntity: Enter the entity whose records should appear as columns in the grid.
• ColumnDataSourceSQL: If you selected a ColumnDataSourceType of SQL, enter the SQL statement that will return the desired sub-set of records from the specified entity. See the example below where the parent entity is configured to only show the current record as a column since the grid is embedded on a form's tab. The SQL statement uses Aptify's field mark-up convention (<<%field name%>>) to pull in the ID value from the current record.
• ColumnDataSourceDisplayField: Specify the field whose values should display as the column headings.
• ColumnDataSourceOrderByField: Specify the field by which the columns will be sorted (in ascending order).
• ColumnDataSourceType (required): Enter Entity to add a column for each record in the selected entity. If you want to limit the number of columns to a particular sub-set of records, enter the SQL type and specify a SQL statement that returns only the desired records in the ColumnDataSourceSQL field.
• ColumnRelationshipType (required): If the column entity is the cell sub-type entity's parent entity, enter Parent. If the cell sub-type entity has a linked field to the column entity, then enter Field.
• ColumnRelationshipField: Enter the corresponding field from the cell sub-type entity that links it to the column entity (typically, this is a field named [column entity]ID).
• RowDataSourceEntity: Enter the entity whose records should appear as rows in the grid.
• RowDataSourceSQL: If you selected a Type of SQL, enter the SQL statement that will return the desired sub-set of records from the specified entity. See the example below the parent entity is configured to only show the current record as a column since the grid is embedded on a form's tab. The SQL statement uses Aptify's field mark-up convention (<<%field name%>>) to pull in the ID value from the current record.
• RowDataSourceDisplayField: Enter the field whose values should display as the row headings.
• RowDataSourceOrderByField: Enter the field by which the rows will be sorted (in ascending order).
• RowDataSourceType (required): Enter Entity to add a row for each record in the selected entity. If you want to limit the number of rows to a particular sub-set of records, enter the SQL type and enter a SQL statement that returns only the desired records in the RowDataSourceSQL field.
• RowRelationshipType (required): If the row entity is the cell sub-type entity's parent entity, enter Parent. If the cell sub-type entity has a linked field to the row entity, enter Field.
• RowRelationshipField: Enter the corresponding field from the cell sub-type entity that links it to the row entity (typically, this is a field named [row entity]ID).