Structure is an alternative way to retrieve a set of Navigation menu sub-items. Structures serve the same purpose as the enabled in the application's navigation search filters with the main difference that the menu sub-items of a Structure are retrieved dynamically. Structures are more flexible and optimized for any changes, for example, when a new item is added to a specified in the structure data it is automatically retrieved to the application's navigation structure if it matches structure filtering criteria.
- Data relevance: once created and configured manually, further the structures are retrieved and maintained automatically by the system. Structures are retrieved dynamically so that any changes in the database or the data source are automatically reflected in structures and result in the latest and up-to-date menu sub-items.
- Instant integration: assign the Structure to a Navigation Item for automatic integration in the navigation tree.
- Hierarchic arrangement: structure sub-items are arranged and hierarchically organized automatically.
- Flexibility: categorize data in the navigation area according to freely definable rules and displayed menu sub-items filtering criteria.
- Non-customizable: unlike regular Navigation Items or Search filters, the automatically retrieved sub-items of the menu Structure cannot be manually customized or modified by a regular user and depends entirely on the source of the data for the generated structure and the structure settings defined by the application Administrator.
- Single filtering criterion: the structure displays data according to one specific criterion only. This criterion is used to group data into sub-menu items of the structure, for instance, group all services that can be ordered on the portal by service category or group all incidents by all available on the portal incident statuses.
Data source particularities
Structures allow configuring dynamically generated navigation menu structure based on specific data stored locally in the application's database or retrieved from a web service.
Structures are based on a specific data source:
- Data Definition: the source of the retrieved data is stored in the Matrix42 platform;
- Service operation: processed data is retrieved from a web service which returns a JSON of a strictly defined structure.
The structure is used in the Navigation Item settings and serves as a navigation item's sub-menus in the following way:
- Filters: a set of automatically retrieved menu sub-items filtered by specified criteria (do not confuse them with Search filters);
- Multi-level sub-menus: automatically retrieved and hierarchically organized menu sub-items.
Structure displaying example: "Locations" Navigation Item with assigned Structure consists of multi-level sub-menus
Structures are configured in Administration application → User Interface → Navigation Items → Structures → Add structure page by defining:
- Data source (mandatory): sub-items can be retrieved to the navigation menu from:
- Data Definition available in the Matrix42 platform;
- Web service that returns data of a specific format and content, that can be processed by the Application.
- Data relation (mandatory): specified ASQL expression defines the set of items which are retrieved to the Dataset view of the clicked in the navigation item's structure sub-menu (available for the Data Definition data source only);
- Parent (optional): specify an ASQL expression resulting in the source field for the navigation items nesting levels (available for the Data Definition data source only). Displayed data will have a tree structure as a result of the applied composite pattern;
- Filter (optional): set ASQL expression is applied to a selected for the Structure Data Definition data source and define which menu sub-items are actually displayed to the end users;
- Navigation Item: structure can be assigned to the Navigation Items which are intended for Dataset view displaying.
Creating a Structure
To create a structure in the New Structure form configure the following fields and choose one of the provided data sources for the structure:
|General||Name||internally used title of the created structure|
|Description||internally used description of a created structure|
|Data source||Data Definition||
choose from a list of available in the system data definitions.
In this case, the source of the data for a structure is stored in the application.
specify a web service operation name from a list of suggested items.
Data is retrieved from a web service, previously saved and configured in the Administration application of the Matrix42 platform.
Web service must return a JSON of a strictly defined structure.
Each Structure is based on one specific data source. The follow-up settings differ based on the selected data source.
Data Definition data source
Set up the Item Configuration fields as follows:
Mandatory: provide an ASQL expression for the selected in the structure settings Data Definition which returns the name of the item.
Specified in the name field data is retrieved directly to the navigation menu's structure and shown to the end-users of a corresponding application:
The field can contain a simple or a complex ASQL expression:
A mandatory field which defines the set of items retrieved to the grid of the clicked in the navigation item's structure sub-menu:
The ASQL expression for each data object results in an ID which is compared with the IDs available in a specified for the structure Data Definition. Matched items will be retrieved to the Dataset view as shown on the example.
optional field for configuring a hierarchically organized Structure.
Company's organizational structure may serve as an example of a hierarchically organized data. This is a one-to-many parent-child relationship whereby each organizational unit reports to a single organizational unit above them and may have zero or more organizational units below them.
an optional filter specified as an ASQL expression applied to a selected for the Structure Data Definition data source.
Allows retrieving to the navigation menu structure a set of items which match the filtering criteria.
Click DONE to save the settings.
Service operation Data source
Service operation settings have only several configurable fields and require a strict format of a returned JSON file.
- Operation: specify the web operation endpoint from the list of pre-configured in the application web-services.
- Data relation: service operation cannot have any common field with the data stored in the application, but this field is mandatory. This field is used as a stub so you can fill out any data to enable the "Save" settings button.
- Filter: leave empty to show all sub-items retrieved from the web service or specify filtering criteria for displayed in the structure sub-items. (Unclear format/syntax as it has nothing to do with the database and ASQL filtering).
Service operation settings example
Service operation JSON format sample:
JSON fields and naming
For menu sub-items listed on the same nesting level it is enough to specify:
- Name: display name of the menu sub-item in the application's navigation structure;
- NodeId: ID of an item to display.
For multi-level menu sub-items specify:
- Name: menu sub-item name shown to the application users;
- NodeId: ID of a displayed item;
- Children: a set of nested sub-menu items;
- Parent: an ID of the parent sub-menu item;
- Name: name to display;
- NodeId: ID of a current item;
- Children: the same set of Parent, Name and NodeId fields for another nesting level in the navigation menu structure.
Assigning a Structure to a Navigation Item
A structure must be assigned to a navigation item in order to be displayed in the application's user interface.
The Structure can be assigned only to a Navigation Item that opens a Dataset View as an action on click and this setting is optional.
To assign a Structure to a Navigation Item:
- Open for editing the Navigation Item which opens a Dataset View;
- Specify the structure in the Structure field;
- SAVE the changes.