Prerequisites
In order to understand the content of this lesson, make sure you watched the following lesson:
Introduction
In a mobile application, you often need to manage information that is shown to the user. Managing the information means to create, update, or delete information. With WebRatio Platform you can easily model a section so that user can manage the application data.
In this lesson you learn how to model a screen that allows to the user to update an object in WebRatio Mobile Platform.
How to Model the User Interaction
Let's suppose you want to add to the "CRM" mobile project the chance for the user to update an existing company.
Let's open the "App View" of the Mobile Project and start to model.
First of all, let's add a "Screen" view container where you show the Companies List. Click the "View Container" section of the toolbar, choose the "Screen" item and place it in the work area to add it. Type a meaningful name for the screen, such as "Companies" and in its Properties View check the "Home" property.
To allow the user to select a company to change from a list, let's use the "List" component. Click the "View Components" section of the toolbar, choose the "List" item and click inside the "Companies" screen to add it. Type a name for the "List" component, such as "Companies List".
The list of elements to be shown can be defined by using a "Data Binding". Press the "Select" button next to the "Data Binding" property, choose the "Company" class and press the "OK" button to confirm. Now let's select which information of the company will be shown to the user in the list. We can use the "Display Attributes" property for this purpose. Press the "Select" button next to the "Display Attributes" property to choose the desired attributes, in this example we are going to select the name, then press the "OK" button. Let's suppose that we want the list to be sorted alphabetically by company name. We can use the "Sort Attributes" property for this purpose, press the "Sort" button next to the "Sort Attributes" property and choose the "Name" attribute with ascending sort. Press the "OK" button to confirm.
To allow the preloading of the fields, let's open the "Edit Form" wizard. Right-click on the "Form" view component and choose the "Edit Form..." option. Check the "Preloaded" property to all fields.
To retrieve the information of the selected company, let's add the "oid" field to save the key. Press the "Add Field" button and type the name to it, such as "oid". Set "integer" to the "Type" property. Check the "Preloaded" and the "Hidden" property, instead uncheck the "Modifiable" property. In this way, the information of the company key is saved but it is not shown in the screen. Press the "OK" button to confirm.
In order to let the user select a company from the list, let's use the On Select Event with a "Navigation Flow". Click on the "Flows" section of the toolbar and choose "Navigation Flow". Click first on the "Companies List" and then on the "Form" component. Type a name for the event, such as "Edit".
Double-click on the navigation flow to provide the company information to the "Form" component. Uncheck the "Enable Default Binding" property. In order to load the information of the selected company by the user, bind each attribute with each corresponding field by using the "Guess Binding" button. Press the "OK" button to confirm the choice.
How to Model "Update" Behavior
Let's change the action definition to handle the save of an existing company. Double-click on the action to open it.
We need to check if the company information refer to a new company or to an existing one. Let's use a "Switch" component. Click on the "Operations" section of the toolbar, choose the "Switch" item and click inside the work area. Type a meaningful name for the "Switch", such as "Company Exists?".
The "Switch" operation checks whether a parameter value is equal to one of the provided cases, and redirects the flow in the direction associated with that case.
Let's change the model in order to have the switch as the first operation of the chain. Right-click on the "Success Flow" to convert it to a "Data Flow", choose the "Refactor" and then "Convert to Data Flow" option. Click on the "Flows" section of the toolbar and choose the "Success Flow" item. Click first on the "Input Port" and then on the "Switch".
To check if the company exists we need to add a parameter to the "Input Port", which represents the company key. Right-click on the "Input Port", choose the "Add" and then "Port Definition Parameter" option. Type a name for the "Port Definition Parameter", such as "oid".
To send the key and check if the company exists or not, bind the company key with the Switch. Double-click on the "Success Flow" to see the "Parameters Binding" dialog. Uncheck the "Enable Default Binding" property and bind the "oid" input port parameter with the Switch. Then press the "OK" button.
To state that the "Create" operation must be executed after the "Switch" operation when the company does not exist, let's use a "Success Flow". Click the "Flows" section of the toolbar and choose the "Success Flow". Click first on the "Switch" operation and then on the "Create" operation.
The Switch Operation has an implicit code: "EMPTY". The Success Flow with the this code is followed when the input value is NULL or EMPTY. In our example, use it for the creation. Set the "EMPTY" code in its Properties View.
To update an existing company, let's use the "Update" operation. Click the "Operations" section of the toolbar, choose the "Update" item and then click inside the work area to add it.
The "Update" operation changes the value of one or more properties of a Domain Model object. By default, the operation uses the "oid" parameter in order to receive all the information about the company to be updated and stores it.
To state that the "Update" operation must change a company information let's define the "Data Binding" property. Press the "Select" button next to the "Data Binding" property to associate a class, in this case choose the "Company" class. Then press the "OK" button.
To state that the "Update" operation must be executed after the "Switch" operation when the company exists, let's use a "Success Flow" without define the "Code" property. Click on the "Flows" section of the toolbar and choose "Success Flow" item. Click first on the "Switch" operation and then on the "Update" operation.
When the execution of the operations is successful, the "Action Definition" must exit through the "Success Port". Let's use the success flow for this purpose. Click on the "Flows" section of the toolbar and choose "Success Flow" item. Click first on the "Update" Operation and then on the "Success Port".
After the execution of the "Update" operation, if an error occurs then the "Action Definition" must exit through the "Error Port". Let's use the "Error Flow" for this purpose. Click on the "Flows" section of the toolbar and choose the "Error Flow" item. Click first on the "Update" operation and then on the "Error Port".
Let's bind the company key from the update operation to the parameter of the success port. Double-click on the "Success Flow" to open the "Parameters Binding" dialog. Uncheck the "Enable Default Binding" property. To send the company key provided by the update operation, bind the "oid" attribute with the parameter by pressing the "Guess Binding" button. Then press the "OK" button.
Finally let's pass the company information to the "Update" operation. We use a "Data Flow" for this purpose. Click on the "Flows" section of the toolbar and choose "Data Flow" item. Click first on the "Input Port" and then on the "Update" operation. Double-click on the "Data Flow" to provide the company information from the "Input Port" to the "Update" operation. Uncheck the "Enable Default Binding" property. To send the values provided by the user and save the company information, bind each parameter with each attribute of the "Company" class by using the "Guess Binding" button. To change the information of an existing company, bind also the "oid" parameter with the "Key Condition". Finally, press the "OK" button to confirm.
Now that the definition is complete, let's use it in our model. Let's open the "App View".
In order to allow the user to save the information of an existing company, double-click on the "Navigation Flow" to bind the "oid" field. Uncheck the "Enable Default Binding" property and press the "Guess Binding" button. Then press the "OK" button.
In order to let the user to add a new company to the list, let's add the "Toolbar" in the Home Screen. Click on the "View Container" section of the toolbar, choose the "Toolbar" item and place it in the Screen to add it.
The "Toolbar" is a Container that allows you to model the application menu and to share content among screens.
Now let's add the "New" button in the "Toolbar" in order to trigger the action. Let's use a Navigation Flow for this purpose. Click on the "Flows" section of the toolbar and choose "Navigation Flow". Click first on the "Toolbar" and then on the "Company Management" screen. Type a name for the "Event", such as "New".
Let's define the layout settings in order to make the "New" button available in the "Main Grid". Let's open the "Layout" tab. In the Layout View, you can define all the properties concerning the way every visible element in which is rendered in the mobile application. Drag the "New" event in the Main Grid.
How to Emulate the Model
Generate the project to emulate the mobile application, by pressing the "Generate and Run" button.
From this section you can run the application on the browser or on your device. Press on the "Open Emulator" button to run the application on your PC.
Change the information of an existing company
Let's select a company to change its information. Then change the company information and press the "Save" button to store the data.
Save a new company
You can also add a new company. Press the "New" button to create a new company. Insert the company information and press the "Save" button to store the data.
How to Model "Cancel" Behavior
Let's suppose you want to add to the "CRM" mobile project the chance for the user to reset the form content without saving the changes. For this purpose, let's add an action to allow to reset the form component. Click on the "Action" in the toolbar and place it inside the work area.
In order to let the user reset the form content, let's use a Select Event with a "Navigation Flow". Click on "Flows" section of the toolbar and then choose the "Navigation Flow" item. Click first on the "Form" Component and then on the "Action". Type a name for the Event, such as "Cancel". Uncheck the "Validate" property since we do not want to validate fields, in its Properties View.
An "Action" is a container of operations and these operations should be defined in a dedicated section of the model. Let's open the "Action Definitions View".
First of all, let's add an "Action Definition" where you model the reset procedure. Press on the "Add Action Definition" button. Give a meaningful name to the "Action Definition", such as "Reset".
Double-click on the "Action Definition" to open it. In this case, we need only to model a Success Flow that associate the Input Port and the Success Port. Click on "Flows" section of the toolbar and then choose the "Success Flow". Click first on the "Input Port" and then on the "Success Port".
Now that the definition is complete, let's use it in our model. Let's open the "App View".
Let's associate the "Reset" action definition to the "Action". Press on the "Select" button next to the "Action Definition" property, choose the "Reset" Action Definition and press the "OK" button.
In order to reset the fields of the Form, let's use a Success Event with a "Navigation Flow". Click on the "Flows" section of the toolbar and choose the "Navigation Flow" item. Click first on the "Success Port" and then on the "Company Info" component.
Double-click on the "Navigation Flow" to see the "Parameters Binding" dialog. Uncheck the "Enable Default Binding" property. To reset the values in the form, bind the "NULL" value to the fields. Then press the "OK" button to confirm.
How to Emulate the Model
Generate the project to emulate the mobile application. Press the "Generate and Run" button.
From this section you can run the application on the browser or on your device. Press on the "Open Emulator" button to run the application on your PC.
Let's select a company to change its information. Press the "Cancel" button to clear the form and insert information of a new company. Insert the company information. Press the "Save" button to store the data.