Advanced Data Management: IFML Model

IFML Modeling with WebRatio Platform
888 views Published on Feb 24, 2015 | Time 30 min
Applies to: 7.2 or higher

In a Web application, you often need to manage the information shown to the user. Managing information means to create, update, or delete information. With WebRatio Platform you can easily model an Administration section in which the Web application user can manage the application data. In this lesson we discuss an enhanced version of the Data Management pattern, which allows you to manage more than one information at the same time. This is a common situation when you need to create the page allowing the user to create or update an invoice, an order or a purchase. In fact, usually these objects have an header and a detail section composed of several items.

Transcript

Table of contents

Multiple Form Component

The main View Component we are going to see in this lesson is the Multiple Form Component. In fact the Multiple Form is a View Component used to display a form. It has the same behavior of a Form Component, but allows management of multiple rows at once. This component is an enhanced version of the Form Component you learned in the "Form Inputs" online lesson.

Field Types

It's possible to add two types of fields to a Multiple Form: Field and Selection Field. You cannot add Multi Selection Field to a Multiple Form.

Multiple Form Example

Let's see how to use the Multiple Form in a working example. The best practice is to have a unique page that allows the Web Application user to manage the desired information. For the Advanced Data Management example, let’s continue working on our "CRM" Web application. We will model a page in which the user can create a new purchase, select a purchase from a list, and update the purchase's information, or select a purchase from a list and delete it.

Multiple Form - IFML Model

This is the IFML Model to design if you want to obtain a result similar to the Web application shown before. The model is composed of different elements. Let's review the purpose of each element in order to better understand the proposed IFML model. The List Component is configured to show all the existing purchases to the user. That’s why the purchase Domain Model object is used and no conditional expression is applied on the Component. This is a typical example, but if you need to, you can add your own conditional expression to the component. Before using a Multiple Form Component, to specify the main purchase information we need an object-based Form component, with the Purchase as main object. The form Component is associated with all the fields necessary to manage the purchase’s information (e.g., company, date and notes). Since the form component is object based, it also has an implicit conditional expression applied that helps to preload all the parts of the Form structure. Every time you place an object based Form Component you will be able to load data inside each field simply passing the Primary Key of the object you want to preload. In this example we will preload the Form with all the information of one purchase, which can be the one purchased selected by the user from the list. Notice a checkmark placed on the form component. This icon reminds you that there is a set of Validation Rules for the fields composing the form. A Validation Rule is a check that you can add on fields in order to be sure that the data inserted by the user complies with the requirements of the application domain. We do not cover this topic in this lesson, but you can find out about it by referring to the online documentation.
An additional component is used in order to preload the company field of the Purchase Form with all the available companies. This is the aim of the Selector Component named "Load Companies" and of the Data Flow outcoming from it. In order to be able to add several purchase items to the purchase, we need to use a Multiple Form Component. The multiple form component is associated with all the fields necessary to manage the purchase item information (e.g., product and quantity). As for the Form Component, even the Multiple Form Component has, if object based, an implicit conditional expression applied that helps to preload all the parts of the Multiple Form structure. Every time you place an object based Multiple Form Component you will be able to load data inside each field simply by passing the Primary Keys of the objects you want to preload. In this example the objects to be shown are the instances of the purchased items related to the purchase selected by the user from the list.
The "Min Length" property provides the minimum number of instances for the Multiple Form. By default this property is set to 1. In this case, the Multiple Form will be displayed with a single instance of the associated domain object. This is an example of multiple form with "Min Length" property set to 1. As you can see, there is a single occurrence for each field of the multiple form in the page. When "Min Length" property is set to a value greater than 1, the Multiple Form Component will be displayed with multiple instances of the associated domain object. This is an example of multiple form with "Min Length" property set to 3. As you can notice, each field of the Multiple Form occurs 3 times. You can also dynamically set the Multiple Form length using a proper Layout Template for the Multiple Form Component. Notice a checkmark placed on the Multiple Form Component. This icon reminds you that there is a set of Validation Rules for the fields composing the form.

An additional component is used in order to preload the product field of the Purchase item form with all the available products. This is the aim of the Selector Component named "Load Product" and of the Data Flow coming from it. This two Selector Components are used in order to retrieve all the information related to the Purchase and its Purchased Items and pass them to the related Form and Multiple Form Components using two Data Flows. The Navigation Flow connecting the List Component to the Selector Component "Selected Purchase" is named "Edit", and it allows the Web application user to select an element from the list. The flow also binds information between the two connected components. In this case, the purchase key is bound with the Selector Component Key Condition. In this way the Form Component is preloaded with the information of the selected element and the user can update it. The Navigation Flow connecting the Form Component to the page is named "Cancel" and it allows the user to reset the form without saving the changes. This Navigation Flow does not bind any information. Note that in order to reset the form it is not necessary to validate the user input, so you must remember to uncheck the "Validate" property. The "Save Purchase" action refers to an existing Action Definition containing all the business logic needed in order to create a new purchase or update the information of an existing one.

In this lesson we do not cover the Action Definition modeling for data management. You can refer to the online lesson about "Advanced Data Management: Action Definition" for further information.

The Navigation Flow connecting the form component and the "Save Purchase" action triggers the action execution. This Navigation Flow is named "Save", and it must bind all the information necessary to pass user input to the Action. The binding dialog in this case has on the right all the input parameters of the Action, which are inherited from the referenced Action Definition. You must bind each of these input parameter with an output parameter from the Form. The purchase key input parameter must be bound with the Purchase Primary Key of the Form Component, which contains the key of the company the user is currently updating. The purchase object input parameter must be bound with the "Purchase Object" form output parameter, which contains all the fields values provided by the user when filling out the form. An additional Data Flow is necessary in order to provide to the "Save Purchase" action all the information specified into the Multiple Form component. In the binding dialog you must bind the Purchased Item Objects input parameter with the Purchased Item Objects output parameter. The "Delete Purchase" action refers to an existing Action Definition containing all the business logic needed in order to delete an existing purchase. In this lesson, we do not cover the action definition modeling for data management. You can refer to the lesson about Advanced Data Management: Action Definition for further information.
The Navigation Flow connecting the Form Component and the "Delete Purchase" action trigger the action execution. This Navigation Flow is named "Delete" and it must bind all the information necessary to pass the user input to the action. The binding dialog in this case places on the right the key of the purchase to delete. You must bind this information to the purchase key attribute provided by the list component. The OK Flows connecting the "Save Purchase" Action to the page and the "Delete Purchase" Action to the page are for reloading the page after the corresponding action has been correctly executed. The KO Flows connecting the "Save Purchase" Action to the error page and the "Delete Purchase" Action to the error page, show an error page when something goes wrong in the corresponding action execution.

How to Model the Multiple Form

Now that you learn which elements compose the advanced data management IFML model, let’s see in practice how to create the model in WebRatio Platform. Let’s continue working on our "CRM" web project in which we already added the Domain Model composed of the "Purchase", "Purchased Item", "Product" and "Companies" objects, and the "Administration" site view containing the "Purchase" area and the "Purchase Management" page. An "Error page" is used to notice the user when an error occurs in the Web application execution. Finally the project contains a Modules Definitions View named "Action Definitions", which includes all the action definitions necessary to complete the model. Move to the "Administration" site view and select the "List" view component from the toolbar section related to "View Components". Click on the "Purchase Management" page to add it and type a name for the component, for example "Purchases". Then move to the Properties View and press the "Select" button next to the Entity property. In the opening dialog select the Purchase object and press the "OK" button to confirm. Add now the Display Attributes to your List, press the "Select" button next to the property and choose the "date", "amount" and "note" attributes; then press the "OK" button. Choose the desired Sort Attributes for the list by pressing the "Sort" button next to the Sort Attributes property. Choose for instance the "date" ordered descending.

To let the user fill in the main information about the "Purchase" let’s use a Form Component. Select the "Form" Component from the "View Components" section of the toolbar and click inside the page. Then write a meaningful name for it, for example "Purchase Info". Select the "Purchase Info" form component and move to the Properties View. Press the "Select" button next to the "Entity" property. In the opening dialog select the "Purchase" object and press the "OK" button. Right-click on the form component and select the "Entity Field Wizard..." option. In the opening dialog, choose "date" ,"note" attributes and "PurchaseToCompany" Relationship. The "Entity Field Wizard" feature creates a specific field in the form component for each attribute of the corresponding domain model object. In particular: for each attribute it creates a simple Field, for each [1:N] Relationship it create a Selection Field and for each [N:1] Relationship it creates a Multiselection Field. Then press the "Finish" button to confirm.

Select the Form Component and move to the Outline View. Expand the "Purchase Info" form item: it contain now two simple fields ("Date" and "Note") mapped on the corresponding attribute in the "Purchase" Domain Model Object and a selection field "PurchaseToCompany" mapped on the homonymous Relationship. Let’s rename the "PurchaseToCompany" selection field. Right-click on the " PurchaseToCompany " selection field, and select "Refactor" then "Rename" option. Write a meaningful name for the Selection Field, for example "Company". Now let's add a Validation Rule on the "date" field. In the Outline View right-click on "date" field, then select the "Add" and then the "Validation Rule" option. In the opening dialog, select the "Mandatory" item, then press the "OK" button to confirm. Write a name for the validation rule, for example "mandatory". Select the "Selector" component from the toolbar section related to "Utility Components". Click on the page to add it and type a name for it, for example "Load Companies". Move to the Properties View and press the "Select" button next to the Entity property. In the opening dialog choose the "Company" object and press the "OK" button. Choose the desired "Sort Attributes" for the "Selector" Component by pressing the "Sort" button next to the "Sort Attributes" property. Choose for instance the "Name" attribute ordered ascending.

To preload the "Company" selection field with all the available companies, let's use a Data Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the Selector Component and then on the Form Component. Then double-click on the flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "company key" with the "company [output]" parameter and the "company name" with the "company [label]" parameter provided by the Form Component. Press the "OK" button to confirm.

To let the user fill in information about the purchased items let's add a Multiple Form Component to the Page. Select the "Multiple Form" component from the "View Components" section of the toolbar and click inside the page. Write a meaningful name for it, for example "Purchased Items Info". Select the Multiple Form and move to the Properties View. Press the "Select" button next to the "Entity" property. In the opening dialog select the "Purchased Item" object and press the "OK" button to confirm. Right-click on the Multiple Form Component and select the "Entity Field Wizard..." option. In the opening dialog, choose "Quantity" attribute and "PurchasedItemToProduct" relationship. Press the "OK" button.

The "Entity Field Wizard" feature will create a simple Field in the first case and a Selection Field for the other. Then press the "Finish" button to confirm. Select the Form Component and move to the Outline View. Expand the "Purchased Item Info" form item: it contain now the "Quantity" field mapped on the corresponding attribute in the "Purchased Item" Domain Model Object and the "PurchasedItemToProduct" selection field mapped on the homonymous Relationship. Let’s rename the "PurchasedItemToProduct" selection field. Right-click on the " PurchasedItemToProduct " selection field, and select "Refactor" then "Rename" option. Write a meaningful name for the Selection Field, for example "Product".

Now select the "Purchased Items Info" multiple form and move to the Properties View. Write the number "10" in the field next to the "Min Length" property.
In this way the "Purchased Items Info" Multiple Form will be displayed with ten instances of "Purchased Item" object.

Now let's add a Validation Rule on the "quantity" field. In the Outline View, right-click on "quantity" field, then select "Add" and then "Validation Rule". In the opening dialog, select the "Mandatory" item, then press the "OK" button to confirm. Write a name for the Validation Rule, for example "mandatory".

Choose the "Selector" component from the toolbar section related to "Utility Components". Click on the page to add it and type a name for it, for example "Load Products". Move to the Properties View and press the "Select" button next to the "Entity" property. In the opening dialog, choose the "Product" object and press the "OK" button to confirm. Choose the desired Sort Attributes for the Selector by pressing the "Sort" button next to the "Sort Attributes" property. Choose for instance the "Name" ordered ascending.

To fill the "Product" selection field with all the available products, let's use a Data Flow. Select the "Flow" item from the toolbar section related to Flows and click on the "Load Product" Selector Component and then on the Multiple Form Component. Then double-click on the flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "product key" with the "product [output]" parameter and the "product name" with the "product [label]" parameter provided by the Form Component. Press the "OK" button to confirm.

To retrieve the purchased selected by the user, let’s use a Selector Component. Select the "Selector" component from the toolbar section related to "Utility Components". Click on the page to add it and type a name for it, for example "Selected Purchase". Move to the Properties View and press the "Select" button next to the "Entity" property. In the opening dialog choose the "Purchase" object and press the "OK" button. Right-click on the "Selected Purchase" Component and select the "Add" and then the "Key Condition" option. In the Properties View, write a name for the condition, for example "purchase primary key".

To let the user edit an existing purchase let’s use a Navigation Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the "List" component and then on the "Selected Purchase" selector component. Select the Flow and move to the Properties View. Write a name for the flow, for example "Edit". Then double-click on the flow to make the binding. WebRatio automatically proposes the binding between the "oid" provided by the "Purchases" List Component and the "purchase primary key" key condition provided by the "Selected Purchase" selector component. Press the "OK" button to confirm.

To preload the "Purchase Info" form with the selected purchase's data let's use a Data Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the "Selected Purchase" selector component and then on the "Purchase Info" form. Then double-click on the flow to make the binding.
Since the Form Component is object based, it also has an implicit conditional expression applied that helps to preload all the parts of the Form structure. You can load data inside each field of an object based Form, simply passing the Primary Key of the object you want to preload. In the opening dialog, in fact you can find a Key Condition among the parameters provided by the "Purchase Info" Form. In order to preload the Form with all the information of one purchase, bind the Key Condition provided by the "Purchase Info" Form with the ‘purchase primary key’ parameter provided by the "Selected Purchase" Selector. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Key Condition [oid]" parameter provided by the Form with the "purchase primary key" parameter provided by the Selector Component. Press the "OK" button to confirm.

To get all the purchased items related to the selected purchase, let's use another Selector Component. Select the "Selector" component from the toolbar section related to "Utility Components". Click on the page to add it and type a name for it, for example "Selected Purchased Items". Move to the Properties View and press the "Select" button next to the "Entity" property. In the opening dialog choose the "Purchased Item" object and press the "OK" button. Right-click on the "Selected Purchased Items" Component and select the "Add" and then the "Relationship Role Condition" option. In the Properties View, write a name for the condition, for example “purchase primary key". Then press the "Select" button next to the "Role" property and choose the "PurchaseToPurchased Item [Purchase -> Purchased Item]" relationship. Press the "OK" button to confirm.

To retrieve all the purchase items related to the selected purchase, let's use a Data Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the "Selected Purchase" selector component and then on the "Selected Purchased Items" selector component. Then double-click on the flow to make the binding. WebRatio Platform automatically proposes the binding between the "purchase primary key" provided by the "Selected Purchased Items" selector component and the "oid" attribute provided by the "Selected Purchase" Selector Component.

To preload the "Purchased Items Info" multiple form with the selected purchased items, let's use a Data Flow. Select the "Flow" item from the toolbar section related to Flows and click on the "Selected Purchased items" selector component and then on the "Purchased Items Info" multiple form. Then double-click on the flow to make the binding. Since the Multiple Form Component is object-based, it also has an implicit conditional expression applied that helps to preload all the parts of the Multiple Form structure. You can load data inside each field of an object-based Multiple Form, simply passing the Primary Key set of the objects you want to preload. In the opening dialog, in fact you can find a Key Condition among the parameters provided by the "Purchased Items Info" Form. In order to preload the Form with all the information of the purchased items, bind the Key Condition provided by the "Purchased Items Info" multiple form with the "purchased item primary key" parameter provided by the "Selected Purchased Items" selector. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Key Condition [oid]" parameter provided by the Multiple Form with the "purchase primary key" parameter provided by the Selector Component. Press the "OK" button to confirm.

To let the user to cancel the operation without saving the changes, let’s use a Navigation Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the Form Component and then on the "Purchase Management" Page. Select the flow and move to the Properties View. Write a name for the flow, for example "Cancel". This Navigation Flow does not bind any information. The important thing to remember is that in order to cancel the operation it is not necessary to validate the user input, so you must remember to uncheck the "Validate" property.

Now let’s add the "Save purchase" action. Select the "Action" item from the toolbar section related to "Containers" and click inside the "Purchase" area. Select the Action and move to the Properties View. Press the "Select" button next to the "Action Definition" property and select the "Save Purchase" action definition. Repeat the same steps for adding the "Delete Purchase" action.

To let the user save a purchase let’s use a Navigation Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the Form Component and then on the "Save Purchase" action. Select the flow and move to the Properties View. Write a name for the flow, for example "Save". Then double-click on the flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Purchase Key" parameter with the "Key [oid]" parameter provided by the Form Component and the "Purchase" parameter provided by the action input port with the "Purchase Object" provided by the Form. Press the "OK" button to confirm.

To save all the Purchased Items' data let's use a Data Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the "Purchased Items Info" Multiple Form and then on the "Save Purchase” Action. Move to the Properties View and set "Data Flow" value for the "Type" property. Then double-click on the flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Purchase Items Keys" parameter with the "Key [oid]" parameter provided by the Multiple Form Component and the "Purchase Items" parameter provided by the Action Input Port with the "Purchased Item Objects" provided by the Multiple Form. Press the "OK" button to confirm. To let the user delete a purchase let’s use a Navigation Flow. Select the "Flow" item from the toolbar section related to "Flows" and click on the List Component and then on the "Delete Purchase" Action. Select the flow and move to the Properties View. Write a name for the flow, for example "Delete". Then double-click on the flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Purchase Key" parameter with the "purchase primary key" parameter provided by the List Component. Press the "OK" button to confirm.

To reload the page after the action execution let’s use an OK Flow. Select the "OK Flow" item from the toolbar section related to "Flows" and click on the "Save Purchase" Action and then on the "Purchase Management" Page. Do the same for the "Delete Purchase" action.

To show the error page to the user when an action execution fails, let’s use an KO Flow. Select the "KO Flow” item from the toolbar section related to "Flows" and click on the "Save Purchase" Action and then on the "Error message" component in the "Error page". Then double-click on the KO Flow to make the binding. In the opening dialog bind the "Shown Messages" parameter provided by the Message Component with the "Error Message" parameter provided by the Action. Do the same for the ADelete Purchase" action. Now that you have the complete model, press the "Generate and Run" button to see the result on the Web Application.

Multiple Form layout options

If you already know, at design time, how many objects you have to manage at the same time with your Multiple Form Component, you can display it using a static Layout Template, with a fixed number of rows. Otherwise, if you don’t know yet at design time, how many instances your Multiple Form Component could have, you can define and change the number of rows at run time using a Dynamic Layout Template.

Normal Layout Template

Normal Component Layout Template: let’s consider the case where we have a Multiple Form Component and we choose "WRDefault/Normal" layout template as Component Layout Template. In this case the Multiple Form Component will be displayed with a fixed dimension and we can establish the number of the occurrences for each field using the "Min Length" property. This is an example of Multiple Form displayed using the Normal Layout Template. As you can see the multiple form is shown like this:

  • Each row contains all the fields belonging to the Multiple Form Component.
  • In this example you can see 3 rows, this is because the "Min Length" property is set to 3.
  • You cannot remove or add any row to the Multiple Form Component. Its dimension is fixed and depends on the "Min Length" property.

How to Apply the Normal Layout Template to Multiple Form Component

In the "Purchase Management" Page, select the "Purchased Items Info" Multiple Form and move to the Layout View. Select the "Purchased Items Info" Multiple Form in the grid and move to the Properties View. Click on the dropdown menu next to the "Component Layout" property and select the "WRDefault/Dynamic" option.

Now save the "CRM" project and press the "Generate Layout" button. As you can see, the "Purchased Items Info" Multiple Form is displayed showing a minus and a plus button at the end of the row. Click on the plus button to add another instance of "Purchased Item" object to the "Purchased Items Info" Multiple Form. In this way you can add as many instances as you want. Then click on the minus button at the end of the row. The corresponding instance will be deleted. In this way you can delete all the instances but the first from the "Purchased Items Info" multiple form in the Page.

Now let’s get back to the "CRM" web project. In the "Purchase Management" Page, select the "Purchased Items Info" Multiple Form and move to the Layout View. Select the "Purchased Items Info" Multiple Form in the grid and move to the Properties View. Click on the dropdown menu next to the "Component Layout" property and select the "WRDefault/Normal" option.

Now save the "CRM" project and press the "Generate Layout" button. In this case, notice that the "Purchased Items Info" multiple form is displayed with a single instance of "Purchased Item" object and there is no way to add or delete any other instances to it.

Dynamic Layout Template

Let’s consider now the case where we have a Multiple Form Component and we apply "WRDefault/Dynamic" layout template on it. In this case the Multiple Form Component is shown like this:

  • Each row contains all the fields belonging to the Multiple Form Component.
  • The number of rows depends on the "Min Length" property (in this case "Min Length" = 3).
  • At the end of each row there is a minus mark button. You can delete the corresponding row clicking on it.
  • At the end of all the rows there is a plus mark button. You can add an additional row to the Multiple Form clicking on it.
  • The "Min Length" Property set the initial number of instances, but you can add or remove one or more rows.

In this way you can establish the number of instances at runtime.

How to Apply the Dynamic Layout Template to Multiple Form Component

In the "Purchase Management" Page, select the "Purchased Items Info" Multiple Form and move to the Layout View. Select the "Purchased Items Info" Multiple Form in the grid and move to the Properties View. Click on the dropdown menu next to the "Component Layout" property and select the "WRDefault/Dynamic" option.

Now save the CRM Project and press the "Generate Layout" button. As you can see, the "Purchased Items Info" Multiple Form is displayed showing a minus and a plus button at the end of the row. Click on the plus button to add another instance of "Purchased Item" object to the "Purchased Items Info" Multiple Form. In this way you can add as many instances as you want. Then click on the minus button at the end of the row. The corresponding instance will be deleted. In this way you can delete all the instances but the first from the "Purchased Items Info" Multiple Form in the Page. Now let’s get back to the CRM Web Project. In the "Purchase Management" Page, select the "Purchased Items Info" Multiple Form and move to the Layout View. Select the "Purchased Items Info" Multiple Form in the grid and move to the Properties View. Click on the dropdown menu next to the "Component Layout" property and select the "WRDefault/Normal" option.

Now save the "CRM" project and press the "Generate Layout" button. In this case, notice that the "Purchased Items Info" multiple form is displayed with a single instance of "Purchased Item" object and there is no way to add or delete any other instances to it.