Master & Details

IFML Modeling with WebRatio Platform
2,828 views Published on Apr 28, 2014 | Time 25 min
Applies to: 7.2 or higher

The ability to show a list of elements and the details of each listed element is one of the most common patterns in Web applications, the so-called "Master and Details" pattern. This lesson shows you how to build several variants of this pattern in WebRatio Platform, and illustrates related basic "IFML" concepts.

Transcript

Table of contents

Master & Details Overview

The "Master & Details" pattern includes at least two objects. The first object, the "Master", is a set of elements usually characterized by a large number of instances, for example the companies that are customers of a manufacturing industry. Since there are many elements to be shown, it's a very common practice to reduce the information reported for each element in the data set. Let's assume there are 150 companies. The most important pieces of information to show may be the "VAT Code" and the "Name". It's a very widely adopted practice to avoid having information such as long texts, big images and secondary data in the master. The remaining information is considered to be details, which will be shown in the second element of the pattern, the Details. In the "Details" of companies you will find the information shown by the master plus what information was left out of the master. Let's now look at the IFML "Master and Details" pattern. The two sides of the pattern are translated into "View Components". The "Master" is usually built by using a "List" view component, while the "Details" are realized with the "Details" view component. Before going on with the presentation of the "View Components" used in this pattern, please review the lesson about "View Components".

List View Component

Let's start the "View Components" overview with the "List" view component. The "List" component is a View Component used to display a list of object instances. This is the most used component when you want to show a list of elements in a page. The retrieved information items, instances, are shown inside the page and in a list. Each instance is treated as a single object, as rows in the list. From the list, you can manage single rows; for example you can see the company details, or delete or update a company. The list of elements to be shown can be defined by using a "Data Binding". The expected input parameters of the "List" component are the values necessary to evaluate the "Conditional Expression" defined in it. The input parameters would also include the additional "Current Object" value, namely the object key that defines the current selected object (for instance, in the company list, there can be a currently selected company, which is defined by providing its key in input to the "List" component). The output of the "List" consists of all the attributes of the object selected by the user from the list itself.

Since the "List" is a "View Component", it shares all the "Data Binding" properties of "View Components" and some other important properties. Let's see each option in detail.

How to Display a Multiple Choice on Lists

Let’s suppose that you want the user to be able to select different rows at the same time to perform operations on a group of data. For example, you might want to let the user delete several companies at the same time. You will need checkboxes on the web page to make the selection, and a button for each "group operation" defined, to trigger the operation. The solution is to check the "Checkable" property. This flag specifies whether the user is able to perform group operations on items, and shows on the Page one checkbox for each row and a button for each defined operation. When the user selects a number of items through the checkboxes and then clicks on a button describing an operation, the operation is applied to all the selected items.

How to Retrieve Distinct Values

Let’s assume that you have duplicate companies in your database and you want to show each company only once. To remove duplicates you must use the "Distinct" property. When this property is enabled, it hides instances having duplicate attribute values. The attributes taken into account when calculating the distinct properties are only those specified in the "Display Attributes" and "Sort Attributes" properties.

How to Split the Results into Pages

Suppose you have a large number of companies in your database. If you want a list that shows all of them, without compromising the usability of the page and while reducing the computational cost, you can split the result list into several pages. This can be done easily by using the "Block Factor" property. This is a numerical value specifying how many results will be shown on the same page (e.g., 10).

For example, if there are 330 companies and the "Block Factor" is set to 10, your result list will be split into 33 pages.

Once the "Block Factor" property is set, then the list in the page is shown along with a set of anchors named "First", "Previous", "Next" and "Last" that allows the user to reach the first page, the previous page, the next page and the last page. Moreover, you find the anchors to jump from one page to another. The number of anchors available can be defined by using the "Block Window" numeric property.

How to Sort a List Dynamically

The "List" view component lets the user dynamically sort a list. This means that the user can change the default order of the result list on the page, using anchors. To define the sorting criteria for the query, refer to the "Sort Attributes" property mentioned earlier. To let the user sort the result set dynamically, check the "Sortable" property in the Properties View of the Component. If this property is checked, the attributes defined as "Sort Attributes" will be used to let the user reorder the list. If you want to differentiate the default sorting from the one that can be done by the user, you can use "Dynamic" sorting, which is shown inside the page, by means of anchors applied to the header labels of the table containing the list of objects. If the "Sortable" property is set to true, another option is available inside the Properties View: the "Sort History Size". This is a numeric value that lets you decide how many dynamic reorders you want to track.

How to Define the Sort Order

Suppose that you want to sort the list of companies by name, in alphabetical order. It's a good practice to select for the "Sort Attributes" the same attributes selected for the "Display Attributes" property. After placing the "List" Component inside a Page, select it and move to the Properties View. First of all, press the "Select" button next to the "Display Attribute" property and in the opening dialog. Select the attributes you want to display, for example "Name" and "VAT Code" and press the "OK" button to confirm. Then, press the "Sort" button next to the "Sort Attribute" property to define the sort criteria. Then compose the rule for sorting the list. For example, click next to the "Name" attribute and choose "ascending" from the dropdown menu. You can specify more than one sort criterion (i.e., one or more sorting attributes). Just remember that the order in which the sorting attributes are listed defines the priority of the sorting attribute. You can change the priority using the "Up" and "Down" buttons. When the configuration is complete, press the "OK" button to confirm your choices.

How to Limit the Number of Retrieved Rows

Assume that your database stores a large number of companies and you want to show only the first 10 companies that satisfy the conditional expression applied on the View Component. The "Max Results" property does the work for you. This property is a numerical value that specifies the maximum number of instances to be retrieved. Additional instances are ignored by the Component. By default this maximum number is not specified, so no row number limit is applied. Select the "Component" from the page and move to the Properties View. Type the desired value in the "Max Result" property.

Details View Component

The "Details" View Component displays the information of a single instance of a given Entity. When you add the "Details" View Component to the model, it has by default a "Key Condition" applied. Remember to carefully choose the "Condition" for this View Component, so that only one instance is extracted. If your "Condition" is supposed to retrieve more than one instance, the "Details" Component will show only the first result of the query. An example of usage of the "Details" Component is to display the information related to a specific train ticket, or the user profile.

How to Model a Basic Master & Details

In order to apply the basic "Master & Details pattern", let’s refer to the "CRM" web project. Take a look at the Domain Model and the "Company" entity. We will start by showing all the "Companies" in a list, giving the user the ability to see the "Details" of each company.

Let's open the "Public" site view of the project and start adding a Page to it. Select the "Page" from the "Containers" section of the toolbar and click on the "Site View" work area to add it. Type a name for the Page, such as "Companies". Be sure that your page can be reached from the other points of the "Site View". An option is to make it a landmark; select the "Page" and from the "Properties View" check the "Landmark" property.

To show the list of all the "Companies", let's use the "List" view component. Select the "List" view component from the toolbar section related to "View Components". It is the second component of the second column. Click on the "Page" to add it and type a name for it, such as "Companies List". Let's now define the "Data Binding" connection. Select the "Companies List" Component and go to its "Properties View". Click on the "Select" button for the "Entity" property and choose the "Company" entity. Click on the "OK" button to confirm your choice. Now add the Display Attributes to your "List", click on the "Select" button and choose the "Name", "Nationality" and "VAT Code" attributes. Click on the "OK" button to confirm your choice. Choose the desired "Sort Attributes" for the list by clicking on the "Sort" button of the "Sort Attributes" property. For example, choose the "Name" with an ascending order and press the "OK" button to confirm.

Let's now add the "Details" of the pattern. Choose the "Details" component from the toolbar section of "View Components". Click on the page to add it next to the "Simple List" component, and type a name for it. Set up the "Data Binding" properties of the "Details" from the Properties View. Use the "Select" button to explore all the available entities and choose "Company". Press the "OK" button to confirm. Retrieve all the attributes of the Entity by clicking on the "Select" button next to the "Display Attributes" property, and use the "Select All" button from the right side of the window. Press the "OK" button to confirm.

Now the "View Components" are configured correctly but we need to do more to let the pattern work correctly.

Flow

In the modeled page, there are two components that do not communicate with each other, no parameters are passed between them. The generated page will show only the list of companies and no details. To this end, IFML defines a concept called "Flow", which is used to define the behavior of the user interaction and to let parameters be passed among components. Let's see the concept of "Flow".

Normal Interaction Flow

A "Normal Interaction Flow" is a "Navigation Flow" or "Data Flow". Examples of "Normal Interaction" Flow are the selection of an item from a "List" and the submission of a "Form".

Parameter Binding Group

A "Flow" may be associated with a "Parameter Binding Group", which is a set of "Parameter Bindings". The "Parameter Binding" is a connection between an "Output Parameter" of the "Source Component" of a "Flow", and an "Input Parameter" of the "Target Component" of that "Flow". "Parameter Bindings" are available for all flow types, and are composed of different parameters. A "Parameter" has a name, a target element, and a source element. You can set the binding between two model elements by using the "Binding Dialog". The "Binding Dialog" can be opened by double-clicking on a "Flow". The dialog is organized in two columns. The left column shows the "Output Parameters" of the "Source Component". The right column shows the "Input Parameter" of the "Target Component". The "Binding" can be done manually, by associating an "Output Parameter" with each "Input Parameter", or by setting a constant value. Alternatively, you can let WebRatio infer the binding by enabling the "Default Binding" property.

How to Complete the Basic IFML Master & Details

Add a "Normal Navigation Flow" by selecting the "Flow" icon from the toolbar from the "Flow" section. Click on the "List" component and then on the "Details" component, to define the "Source" and "Target" of the "Flow." Type the name of the "Flow" and call it "Details". Double-click on the "Flow" to open the "Parameters Binding" dialog to check the binding between the "Source" and the "Target" Component. Since the Entity of the "Source" and "Target" are the same, WebRatio Platform automatically infers the binding, and couples the "oid" outgoing from the "Simple List" with the "Key Condition" of the "Details".

To check that the pattern is working, save and launch the generation procedure using the "Generate and Run" button.

Master & Details pattern variants

Let's see now how to build several variants of this pattern in WebRatio Platform, in order to improve the basic version we have seen until now.

Master & Details with Default Selection

You can change the default behavior of the "Master & Details" pattern by changing the type of flow used to connect the "List" and the "Details" Components. Normally, with the "Normal Navigation Flow", the user is obliged to click on the details link to see the "Details". Setting the type to "Automatic Navigation Flow" will automatically show, when the page loads, the details of the first "Instance" of the "List". To do this, simply select the "Flow" from the "Model". From the "Properties View", change the "Type" property to "Automatic Navigation Flow".

Save and use the "Generate and Run" button to see the changes on the Web Page.

Master & Multiple Details

One way to improve the "Basic Master & Details" pattern is to add details for the same master instance.

In the case of "Companies Master & Details" basic pattern, you can add the "Company Primary Address" as one of the details of the "Company". Add the "Details" view component by selecting it from the "View Component" section of the toolbar, and place it inside the new page. Type the name for it, "Company Address". Configure the "Details" properties related to "Data Binding". From the Properties View of the Component, click on the "Select" button of the "Entity" property and choose as Entity "Address". Press the "OK" button to confirm. Set the "Display Attributes" of this Component by choosing all of them. To retrieve the "Primary Address" of a "Company" we need a "Relationship Role Condition", so let's delete the default "Key Condition".

Now let's add a "Relationship Role Condition" by right-clicking on the component and choosing the "Add Relationship Role Condition" command. Type a meaningful name for the condition, such as "company". Configure the condition by choosing the correct role. From the "Properties View" of the "Role Condition" choose the "Select" button of the "Role" property and choose the "Company to Address" Relationship.

Let's now add the "Parameter Binding" to pass the "key" of the company to the "Condition". Add a "Data Flow" by selecting the "Flow" icon from the toolbar. Then click first on the "Details" of the "Company" and then on the "Details" of the "Address". Since the two Components are based on two Entities connected by a relationship, WebRatio automatically infers this "Binding". This will automatically extract all the addresses of the selected company (which could be more than one).

Since we want to extract only one address, let’s add an "Attribute Condition" to retrieve only the "Primary Address" of the selected company. Right-click on the "Component" and choose the "Add Attributes Condition" command. Type a meaningful name for it, such as "primary address". Configure the condition by choosing the correct attribute, which is "primary". From the Properties View of the "Condition" choose the Predicate "Equal" and type "TRUE" in the "Value" property. This will filter the only address that has the flag set to true. In other words, this will spot only the primary address.

To test the "Master and Multi Details" pattern, save the project and use the "Generate and Run" command.

Master & Details with Extra Information

Let’s suppose that you want to show the name of the "Sales Manager" assigned to a company, assuming that the "Company" Entity does not include the "Simple Imported Attribute" for it and that you don’t want to change the Domain Model. Given the prerequisites above, the only way that you could do this would be by adding a "Details" Component that will show the sales manager’s information. WebRatio Platform gives you another way to show that attribute, which is importing it on the fly. This procedure will retrieve, at runtime, the value you're looking for without mapping anything to the database, and without changing the Domain Model. The only drawback of this procedure is that the attribute will be available only for the component on which you define it.

To import attributes on the fly, select the View Component on which you want to import the information and from the Properties View click on the "Select" button of the "Display attributes" property. On the right of the "Display Attribute Selection" dialog you will find the "Import…" button. Press this button to open the "Import Attribute" dialog. From here you can browse the Domain Model elements related to the entity of your View Component. For instance, to retrieve the name of a sales manager, you can browse the "CompanyToSalesManager" relationship role and pick the "Name" attribute of the "Sales Manager" entity. And press the "OK" button. Click on the "OK" button to confirm your choice.