Grid Browser - Administration Guide

The same system requirements as the Structure Browser defines are also applicable to the Grid Browser.

When installing the Grid Browser, you must also ensure that the Structure Browser is installed.

The Structure Browser has a large number of features, but not all of them are available from within a Grid Browser view.

The following list shows features that are not supported in the Grid Browser UI:

The user interface of the grid browser contains much information and a rich set of functionality. All of this differs depending on how your particular instance is configured but the picture below illustrates and describes commonly used parts.

The configuration declares the possible actions that can be performed on an element in a particular state. These actions are available in a menu after right clicking with the mouse over an element in the intersection area.

Depending on what state the element is in and the user’s access rights, different amount of actions can be made available.

A confirmation message can be set for element actions as well as global actions.

Examples of available built-in functions that easily can be made available are:

If none of the above actions solves your use-case, it is possible to plug-in a custom action written in Java / JPO.

An action can be made available to a user having a particular role, or is assigned to a particular group.

The grid browser can be configured to show tooltips for the objects on both the row- and column- axis and also for the elements/intersections.

By default the tooltip is shown, if the user holds down the *shift* key and moves the mouse pointer over one of the tooltip enabled sections. You can turn off the need for holding shift to display tooltips by the init parameter tvc.gridbrowser.holdShiftForTooltips

What actually is being shown within the tooltip is defined by the configuration that controls the Grid Browser instance.

When clicking on either a row object on the left side or on a column object at the top, with the *shift* button combination, the grid can be configured to open a popup window with some content. What actually is being shown is configurable, but typically this will be that the object details page (emxTree.jsp) is opened.

The object id of the clicked item is passed to the configured href.

There is a set of built-in mass operations available to use. Depending upon the configuration, these can be enabled or disabled for a particular grid browser instance.

These operations are global operations, and are shown within the toolbar as context buttons.

The built-in functions available are:

A mass operation action can be configured in two different ways. For example, one can say that an action is available for all elements/intersections that are not connected, while another action is available for all elements/intersections that are connected.

The other approach is to enable an action depending on what state an element/intersection is satisfying. These two alternate setups can not be mixed. Once such action is invoked, only the selected elements that are satisfying that condition are part of the action.

A mass-action can be made available to a user having a particular role, or is assigned to a particular group.

The Grid Browser can be exported into various printable formats that allow it to be printed. The most commonly used format is the PDF format. The printer friendly button is available within the toolbar as a context button, see screenshot below.

The user will be able to select paper format, page orientation, font-size and margins in order to configure the generated PDF document.

Please note that in some situations, the amount of data/information is too large to fit on a certain paper size setup. The user will then have to change some of the settings, for example decrease the font-size, increase the paper size, change the page orientation or a combination of these.

The generated PDF document will contain following sections:

The Grid Browser can be exported into an Excel™ document. This is either done from the printer friendly button by choosing the Excel format, or via the Export button next to the printer friendly button within the toolbar.

The exported file is a HTML document with special mark-up, which is specific for Excel. An example export is shown below.

It is possible to enable the column filtering functionality. The filter can be defined in a number of different ways and combinations, for example filter by type, current state or name. It is also possible to create several filter groups, in order to allow the user to choose.

Once enable, the dialog is opened via the button (1) shown in the picture below. The dialog is opened in the side panel (2) as shown below.

Each filter group is related to a select statement that is applied on the column objects. Each unique value among the select values represents an item within the filter group.

All objects that is matching the particular filter-group-item is visible or hidden according to the selections made in the column filter dialog.

See this chapter for configuration details.

In many cases, the Grid Browser needs an object as input; e.g. it is context sensitive. In that case you need to provide the id to this object, and pass it using the "objectId" parameter. If you attach the command to the "category tree" in your AEF based application, the object-id is automatically added to the HREF.

If you are launching the Grid Browser from another place, you must ensure that the object id is appended to the link.

If you launch the Grid Browser from a command within the TVC Structure Browser, you must consider following:

If the first alternative is what you are looking for, then your command should have following settings:

If the second alternative is what you are looking for, then your command should have the following setting:

If the Grid Browser instance is displayed in a "TVC Tabbed Page" or within a Portal channel, then you can enable the portal mode. This can be done in two ways.

In portal mode, the header and sub-header are removed.

If the Grid Browser instance is displayed in a popup window, it can have the standard popup dialog colours by enabling the "dialog mode". This can be done in two ways.

Within the Grid Browser configuration, there are two sections called "Columns" and "Rows". These sections control the appearance of the column and row axis.

Within each of these sections, you will define a "DataLoader" section. The "DataLoader" defines everything regarding the initial load of each axis.

This is illustrated in the configuration snippet below:

The format of the data can vary. The column axis typically shows a flat-list of objects. The row axis could show a flat-list, a structure with one root node or a structure with multiple root nodes.

The following values are accepted in the format attribute:

A dataset is a powerful way to express complex data-retrieval by XML configuration, which normally would require implementing a Java class.

To use a dataset, one specifies the name of the dataset within the Data Loader as shown below:

For additional information about data-sets, see the ”TVC Core Administration Guide”.

An inquiry typically contains a MQL statement that returns a set of objects. In some cases the returned data could represent a structure.

To use an inquiry, one specifies the name of the inquiry within the Data Loader, like below:

It is also possible to pass arguments to the inquiry, this is done by:

Remember to specify the parameter also on the inquiry.

If the data format is set to indented, the specified inquiry will be used for loading the root nodes (unless the inquiry is constructed to return hierarchical data).

It is possible to use a custom loader written in Java that populates the Grid Browser.

The class must implement the following interface:

This interface has one method that you need to implement:

It is also possible to invoke a JPO to load the data. Just specify the name of the JPO and the method to be invoked.

The method being invoked must return a "java.util.List" instance containing "java.util.Map" instances representing each row. At minimum, each Map must contain an "id" key pointing to an object-id. Additionally, the "id[connection]" key can contain a connection id.

If the data format is set to indented, the specified JPO will be used for loading the root nodes within the structure.

When the Grid Browser is installed, a program called "TVCGridBrowserSample" is installed to the database. This program contains some examples that illustrate the JPO usage.

It is also possible to provide arguments to the method being invoked. This is done by:

The row axis allows showing a structure and allows the user to collapse and expand the structure using the navigation buttons, unless this has been disabled (see this chapter)

What data is retrieved once the user expands a node in the structure is configured within the "Expand" element below the "DataLoader".

There exists a number of different ways to do the expansions, for example:

The loaded data can be sorted. Note that when you for example is displaying a structure on the row axis, or the column axis objects are grouped, the sorting behaviour is differs.

If you rely on the data being shown in the order they are returned from for example a JPO, or if they already are sorted, you can disable the sorting by applying the following attribute:

The column objects can be grouped together based upon some condition.

The example below illustrates objects being grouped into two categories:

To accomplish this, use the <Hierarchy> element within the <Columns> element, see this chapter for configuration details.

This example was created with the following configuration:

An intersection path defines how to traverse from an object on the row or column axis to the object on the other axis. The path can be as simple as just one relationship between these, but can also be more complicated like having several levels or using relationship that starts from a relationship or ends on a relationship.

Below are some examples how to construct the intersection path depending on the data model.

Example 1:

Assuming that object A is shown on the row axis and object C is shown on the column axis

Example 2:

Assuming that object A is shown on the row axis and object C is shown on the column axis

This example illustrates how we to traverse from a relationship into another relationship that is connected from a relationship to a businessobject.

Example 3:

Assuming that object A is shown on the row axis and object C is shown on the column axis

This example illustrates how we to traverse from a relationship that points to a relationship that is connected between two business objects.

Example 4:

Assuming that object A is shown on the row axis and object C is shown on the column axis

This example illustrates how we to traverse from a relationship that points to a relationship that is connected between two business objects.

Example 5:

Assuming that object A and B including R1 (or only B+R1) is shown on the row axis and object D is shown on the column axis and R2 is a connection from R1 pointing to object D.

This example illustrates how we to traverse from relationship R1 via relationship R2 to object D.

Example 6:

Assuming that object A and B including R1 (or only B+R1) is shown on the row axis and object D and R2 is shown on the column axis and R3 is a connection from R1 pointing to relationship R2.

This example illustrates how we to traverse from relationship R1 via relationship R3 to relationship R2.

Note the special use of the attribute "targetQualifier" here. In case we end on a relationship, this should be empty.

Each intersection can satisfy one or more states. Each state is typically shown with a different color, and each state typically has its own set of element actions available.

You can have as many cell states as you wish, however, an intersection that satisfies more than one state will only use the last defined cell state (according to the order they are defined within the configuration).

A simple cell state definition example below:

The configuration defines the direction of the relationship. E.g. whether to start looking from the row object or the column object. At the bottom line, this will result in at least two select statements that are applied to either the row objects or the column objects.

Consider following example:

On the column axis, objects of type Organization are loaded. On the row axis, objects of type Part are loaded. A Part can be associated to an Organization via the relationship "Supplied By". This relationship is routed from the Part to the Organization (see picture below).

Depending on how the Grid Browser is configured, one will start on the "Organization object" and traverse in the "to" direction and find the "Part object" OR start on the "Part object" and traverse in the "from" direction and find the "Organization object".

This would be configured within the Grid Browser configuration as:

Or:

E.g. the first approach results in the following statements to be selected on the Organization objects:

The second approach results in the following statements to be selected on the Part objects.

The end result will be the same. The problem will become visible if/when an Organization object has a larger amount of Part objects connected; e.g. the number of connections pointing to the Organization object are large.

With the first approach, the select statements will return a larger data-set, which results in degraded performance.

The conclusion is that one should avoid traversing in a direction where the amount of possible connections is high. If you aren’t able to predict this or the number of connections is same or similar independent of the direction, you should strive to make your IntersectionPath going in the "from" direction.

As of 2011.3.0, it is possible to allow the user (in edit mode) to modify intersection information directly in the table (in cell edit).

The fields being open for edit is configured in the Grid Browser configuration and an example of how it could look like in the user interface is shown below:

The configuration to enable editable fields in the intersection area is shown below:

The configuration details are described in this chapter.

If you are enabling edit to a field that changes the state of an intersection (see this chapter), then you can apply the setting “Update UI" with the value set to true. That will cause the field to be completely updated upon edit. The reason for not doing this by default is due to performance reasons.

Also, if you want to disable edit of fields in particular states, then you can use the setting “Editable States". The value should be a comma separated list of state-id’s, which the field is editable in.

See the following code example for how such a JPO could be written:

It is possible to disable a complete row or column based upon some condition that is checked against the object on the row-axis. This could for example look like this:

To configure this, look at the following configuration example.

These statements are evaluated per object on the axis they are defined for. Such a statement should typically return TRUE or FALSE in order to work properly. To test if an expression is valid and correct is easiest done from MQL, like this example:

This must return either TRUE or FALSE in order to be useful.

A toolbar can be made available within a Grid Browser page. To add a toolbar apply this to your configuration:

Any command that is invoked will, if the setting "Submit" is set to true, get all the selected rows and all selected elements/intersections available as request parameters.

The toolbar can contain a number of so called context buttons. These are displayed to the right of the "mass-operation" actions (if present). See screenshot below:

It is possible to assign a context menu (available on right click) for the row axis objects. An example how this could look is shown below:

The context menu is defined by:

The objects on the row axis can contain additional columns showing meta-data related to these objects and/or connections.

These columns are defined within the "Rows" section of the Grid Browser configuration. Example:

Actions that apply to the row-objects can be enabled by defining so called Row Actions.

The row actions are displayed in the last column on the left side, as the screenshot below illustrates:

These can be used for quickly launching a particular action for the object on the row.

The configuration snippet below illustrates how to add these:

The counter showing the row number can be enabled or disabled through:

The header for the columns header can be rotated in an arbitrary angle. See screenshot below.

This is configured on the "Columns" element, as shown below:

It is also possible to specify the vertical alignment of the column header. See configuration example below:

It is possible to customize the rendering of the Grid Browser. This is accomplished by specifying the fully qualified class name to a class that extends from com.technia.tvc.gridbrowser.render.GridBrowserRenderer.

This classname is registered within the configuration like shown below:

The capability of customize the rendering requires in many cases the need for having access to additional data from the intersections. A similar concept to datahandlers exists also in Grid Browser, however, in the Grid Browser this is called "Intersection Evaluator". To register a custom intersection evaluator, you can do so as shown below:

The class name you register here must point to a class that extends from com.technia.tvc.gridbrowser.model.IntersectionEvaluator.

There are several methods that can be overridden from this base class, but to solve the case when you need to select additional data from the intersection connections, you should override the following methods:

The first method is used to specify the select statements you want to be evaluated over the connections. The latter method is used to return an object that holds these values. Note that the return value must be a class that extends the base class called "IntersectionData".

To use this data later on in your renderer, you will simply do something like shown below:

Choosing the objects are done by either selecting objects from a search result, a collection, the clipboard or a combination of the previous mentioned possibilities (by using "revise query"). See screenshots further below.

Also, a filtering mechanism has been added that ensures that the selected objects aren’t illegal to use in the particular Gridbrowser use case. Use of "illegal" objects could potentially result in an inconsistent database, were objects that shouldn’t be connected to each other becomes connected etc.

Also, in order to not face a situation where the server becomes unstable due to out-of-memory errors etc, because a user selects 1000+ objects to be loaded into the grid; you can define a maximum limit.

In some use-cases it is required to be able to add an object to the Gridbrowser. The easiest way to do this is to use the search tool from the Structure browser. Below are some descriptions how to do this.

The SubmitURL calls a JavaScript function in the Gridbrowser. This JavaScript takes two arguments; the first is the "window" and the second is a Boolean parameter where true means "column-axis".

In order to allow modifying/working with the objects on the column-axis, the objects on the row-axis or the connections that represents the intersection between the row/column objects; a convenient action has been added that allows loading these into a structure browser instance.

This URL accepts/requires some parameters:

For example, having a toolbar with the following commands:

Gives a toolbar in the Gridbrowser UI that looks like this:

Choosing one of them opens the structure browser window in a popup window. Depending on how it has been configured, it will have different look. This example just opens a simple table that is open for edit directly.

All labels, headers, sub-headers and tooltips are locale aware, i.e. they can be configured differently for different languages. The way to do this is shown in the examples below:

All labels and headers also support localization using string resources.

The Grid Browser definition contains several sections that control the Grid Browser instance. All these XML elements are described in the subchapters.

Attributes

Child Elements

Attributes:

Child Elements:

The DataLoader element defines how to populate the specific axis with objects.

Attributes:

Child Elements:

Defines the intersection rules.

Attributes:

Child Elements:

The EditableFields element contains the Fields that is open for edit on the intersections.

Child Elements:

The CellStates element contains a set of CellState elements where each CellState element define the state an element may have.

A cell state could be fulfilled by a simple condition saying that the element has a connection or not.

More sophisticated states could be defined, for example that the element relationship must have its Quantity attribute larger than 1, besides being connected, to fulfil the state requirements.

The CellStates element is just a container for CellState elements.

Child Elements:

The label element is used to define a label in many places, for example to the element, the row object and the column object.

A label can be locale aware, i.e. the value could be different depending on the users preferred browser language. It also supports localization using string resources.

Moreover, the Label element may contain a macro – which means that the label could contain data that is selected from the specific object (or connection in case of elements). The label can in some places also be divided across several lines, and each line can be formatted individually.

Attributes:

Child Elements:

A simple label consists of a string, containing either dynamic value(s) or not.

A label can be locale aware, i.e. the value could be different depending on the users preferred browser language. It also supports localization using string resources.

Attributes:

Below are some examples.

The header element is used to define a header for the row object, the column object, and the page where the grid is shown.

A header could be locale aware, i.e. the value could be different depending on the users preferred browser language. It also supports localization using string resources.

Moreover, for the page header, the value may contain a macro, which means that the page header could contain data that is selected against from object, which the grid was launched from. However, this is not always the case, and varies depending on from where the grid was launched.

Attributes:

The content of the Header is the text that should be displayed. Below are some examples:

The sub header element is used to define a sub header for the page where the grid is shown, or for a form page.

Attributes:

The content of the SubHeader is the text that should be displayed. Below are some examples:

Column header rotation can now be achieved using pure CSS as opposed to the exisiting action call and generating an image. The rotated headers will render the column labels vertically. The existing method of generating rotated header using as an image can be achieved by using the below configuration in web.xml :-

The default value for this setting is set to false.

The ToolTip element defines what data that is to be shown when the user displays the tooltip for either an object on the row axis, an object on the column axis or an element within the intersection area.

The ToolTip element contains nested elements. These elements are:

The nested elements, either the Basic or the Attribute element, are associated with a property that could be selected from the object or relationship. The labels for each of these selected values are automatically retrieved from the string resource files in the AEF.

However, under some circumstances, this label cannot be retrieved, especially if one is selecting data from a related object (for example from.name), or if the resolved label is not suitable. In this case, a label can explicitly be defined for a particular tooltip value.

Child Elements:

Tooltip example:

The Cols element can be used to declare additional column(s), for the row, that displays additional information. The Cols element is a container for Col elements

The Actions element contains Action elements.

This element defines the actions available when right-clicking the mouse on an element.

Child Elements:

The For-State element defines the id of the states that must be satisfied before this action is displayed. One action can be applicable for several states. In this case, just add more For-State elements containing the id of the state to be satisfied.

Example:

The refresh behaviour element defines what to refresh after an action has been performed (a right click action).

Example:

The possible values are (case insensitive):

Each action can be made available to users assigned to a certain role or group, or specific named users.

Child Elements:

This element defines the global actions available as context buttons within the toolbar.

Child Elements:

Attributes:

This element defines a form that is used when editing intersection (relationship) attributes.

Child Elements:

An example of how a form could be created is shown below:

Used to define an expression that will disable a complete row or column. The content within this element is a standard Matrix expression.

Attributes:

There are a number of elements that affects the user interface of the Grid Browser.

Child Elements:

Below is an example configuration that will enable all the different buttons and define a toolbar + context menu.

There are some other elements, which control how a Grid Browser instance is displayed.

For example, the page may have a header and a sub header. See the chapters Header and SubHeader for information how to define such elements.

Moreover, the grid browser may have a toolbar attached and a context menu (for the row axis objects). This is accomplished by adding a ToolBar element, which contains the name of the menu that acts as a toolbar.

See the example below on how to define header, sub header and a toolbar for the grid browser.