moskitt codgen ox tutorial2 uim2ox article eng

1

Tutorial 2: Including UserInterface design in OpenXava

applications with MOSKitt,

Table of ContentsIntroduction ................................................................................................................. 1Task 1: Create a new Sketcher model with MOSKitt. .......................................................... 1Task 2: Create a new OpenXava module for the management of invoices (Invoice) .................... 3

Task 2.1: Modeling of the OpenXava module for the Invoice management (Invoice) ........... 4Task 3: Launching the OpenXava application ................................................................... 14

IntroductionIn this tutorial we are going to see how to include User Interface layout design as a new parameter forthe OpenXava code generator. We start it in the point in which a project has the UML2 model startedto specify the business logic of the system.

To obtain this UML2 model you can choose between one of these two options:

• Using MOSKitt for building the UML2 model yourself. In this case you can follow the instructionsof Tutorial1: Developing an OpenXava application from UML2 MOSKitt models.

• Using the invoice_domain model from the project InvoicingModels provided byMOSKitt into the oxportal-4.2.X.zip file (available in MOSKitt web). Follow theinstalation instructions which you can also find in the MOSKitt website (in the MOSKitt Codegeneration/Java/JEE web applications with OpenXava section). Basically these instructions are:

1. Downlodas oxportal-4.2.X.zip file.

2. Unzip the file.

3. Open MOSKitt selecting as workspace: <MOSKitt_HOME>/oxportal/workspace.

4. InvoiceModeling project will be available in MOSKitt Resource Explorer View.

Once the UML2 model is ready we are going to explain how to specify the user interface model forOpenXava modules in which the analyst considers it necessary. It happens that in some cases the designof the User Interface made by default by OpenXava Framework doesn't satisfy users requirementes.

In order to demonstrate how to specify non-default layout designs for a certain module, we will giveyou a guide on designing the layout of the Invoice module, included into the Management InvoicingApplication.

Task 1: Create a new Sketcher model withMOSKitt.

1. Select the menu option File/New.../MOSKitt Sketcher Diagram.

2. In the first page of the wizard for creating Sketcher models give name to the sketcher model.


applications with MOSKitt

2

3. In next page check the option Initialize from template and in thelist below select the item called Patrones Genéricos para Sketcher(sketcher_generic_templates.sketcher_diagram) as you can see in the nextfigure:

Now you have available a set of sketcher models (templates) specifying basic web components.You can reuse this components as needed to specify your windows more quickly.

4. Press Finish and then a new Sketcher model will be opened in the Sketcher editor. Then the editorwill show you a new diagram with only one element of type Window which is named EditableWindow as you can see in the next figure:



3

Every element of type Window represents in our Sketcher model an OpenXava module.

5. Over the layout, go to Properties view and give value to the Id property to give a name to theapplication (not to the OpenXava module).

For more information about the templates provided by MOSkitt, please refer to the MOSKItt User'sManual.

Task 2: Create a new OpenXava module forthe management of invoices (Invoice)

Every element of type Window represents in our Sketcher model an OpenXava module. In order tomake easier the modeling process of OpenXava modules, MOSKitt provides two predefined models(templates):

• Editable Window.

• Not Editable Window.

For more information concerning the templates for modeling OpenXava modules, please see thesection named "Generic templates for modeling web applications" located in the final appendix of theCodgen-OpenXava manual.

For creating a new OpenXava module, open the MOSKitt Artifacts Library view and draga template to the Sketcher initial canvas. Now, you can see the element Window that symbolize themodule.

In the next image we can see the templates provided by MOSKitt for modeling Openxava modules:



4

Warning! in the Generic Windows group, the Sketcher Selection Window template is aWindow element in Sketcher but it does not represent an OpenXava module.

If we keep dragging windows from the Generic Windows folder of the MOSKitt ArtifactsLibrary view in order to specify each of the OpenXava modules, we will get the next diagram asa result:

The previous figure shows the view of the main diagram (named Application Diagram at thebeginning), in wich we have a representation of each module of the application.

Task 2.1: Modeling of the OpenXava module for theInvoice management (Invoice)

We are going to model with the MOSKitt Sketcher the first module (Invoice), related to the Invoicemanagement as a part of our Invoicing application. The module that we are going to model with theSketcher is based in this module located in the OpenXava website:

http://www.openxava.org/web/guest/invoice.

In this case, we will focus on having the basic management operations (insertion, edition and deletion),that way, we are going to use the Editable Window template (since this is the first module, wecan take advantage of the Sketcher Editable Window when we are creating a new module):

From this windows we are going to specify the following information:

http://www.openxava.org/web/guest/invoice



5

• Id property of the window: is located in the Properties tab of the Window (in the Basic subtab).This property contains the name of the module, in this case, Invoice.

You can edit the window by double clicking over the figure that represents the module in de maindiagram (as you can see in the previous figure). After double clicking you will see the following figure:

As we can see in the previous figure, we don't start from scratch, we start from an initial model thatprovides the Editable Window template. In this template we can see two main elements of paneltype:

• A panel that represents the List view of the module.

• A Panel that represents the Detail view of the module.

To support the code generation of OpenXava views, the elements of the panel are tagged as:

• Tabular: Tag used to define the List view.

• Registro: Tag used to define the Detail view.

The tags associated to every Sketcher element appear in the subtab Tags included into the PropertiesView.

The next figure shows which graphic elements of the Sketcher are labeled with Tabular orRegistro tag:

Warning! to avoid misreadings we are going to clarify the nomeclature used by MOSKitt to describedifferent concepts:

• The Tabular tag is used for representing the List view of an OpenXava module.

• The Registry tag is used for representing the Detail view of an OpenXava module.

• The Detail tag is used for representing a Detail block in a Master/Detail hirarchy contained in anOpenXava module (don't confuse with the Detail View corresponding to the Registry tag)

Task 2.1.1: Modeling the List view of the Invoice module.

The next step is to model the List view of the Invoice module. This view corresponds to one of thecomponents that are contained in the Editable Window: the panel tagged as Tabular.



6

Following the example in the OpenXava web, the window which we are going to model looks like this:

Using the elements of the palette provided by MOSKitt-Sketcher we can complete the previous panelin order to achieve the next look:

Basically we have made the following actions:

• Add new columns to the table provided by the Editable Window template (to add it you mustselect Table Column elements located in the Sketcher palette, into the submenu Table).

• Set the title in each one of the column header of the table using the Text property. This property islocated in the Properties Tab, Basic subtab of each Table Column element.

• Link every widget (Table Column elements in this case) with the corresponding UML2properties using both Data Model Element and Data Model Path properties.

• Link the columns titled as Number, Date and Paid with the properties Number, Date andPaid of the Invoice class.

• Link the columns titled as Number of Customer and Name of Customerwith the properties Number and Name of the Customer class navigating through theInvoice_Customer association. This association appears when we deploy the Invoice classin the Object Selection wizard (caution!, this is very important).

For more information about how to relate Sketcher and UML2 models you can see the last sectionin this point titled "How to relate Sketcher elements whith UML element".

In the next figure you can see how both properties (Data Model Element and Data Model Path) havebeen filled for the column Number of the Invoice class:



7

In the next figure you can see how both properties (Data Model Element and Data Model Path) havebeen filled for the column Number of the Invoice's customer (labeled as Number of Customer).See the difference with the previous example:

For more information about how to relate Sketcher and UML2 models you can see the last section inthis point titled "How to relate Sketcher elements whith UML element".

For more information about how to use the MOSKitt-Sketcher editor you can see the User Manualin MOSKitt.

Task 2.1.2: Modeling the Detail view of the Invoice module.

Now, we are going to model the Detail view of the Invoice module. This view corresponds to oneof the components that are contained in the Editable Window: the panel tagged as Registro.



8

Following the example in the OpenXava website, the window which we are going to model is morecomplex than the previous one because it contains nested panels. Let's proceed step by step. The firstpanel to model looks like this:

This panel contains in its header data belonging to the Invoice class. It also contains three tab panels:the first one named Customer shows information about the customer of the invoice.

Using the elements of the palette provided by MOSKitt-Sketcher we can complete the previous panelin order to achieve the next look:



9

To accomplish this task we have followed the next steps:

• Relocate the TextBox provided by the Sketcher template.

• Add new TextBox widgets for the properties Year, Number, Paid and Date.

• Set the title in each one of these TexBox using the Text property. This property is located in theProperties Tab, Basic subtab of each TextBox element (Year, Number, Paid andDate).

• Link every widget (TextBox elements in this case) with the corresponding UML2 properties ofthe Invoice class using both Data Model Element and Data Model Path properties. For moreinformation about how to relate Sketcher and UML2 models you can see the last section in thispoint titled "How to relate Sketcher elements whith UML element".

• Add a new TabPanel element (panel with tabs) with 3 TabItems (tabs). This elements can bedragged&dropped from the submenu Panel of the Sketcher Palette.

For each one of these TabItems we have been done next steps:

• Set the title using the Text property (this property is located in the Properties Tab, Basicsubtab of each TabItem element). The value for this property will be Customer, Data orDeliveries depending on the TabItem selected.

• Complete the panel with the needed widgets.

We are going to see step by step, how to model each one of these TabItems:

• Customer TabItem: This tab shows the data of the customer of an specific invoice (as you cansee in prevoius figure). To model this tab follow next steps:

• Include a Single Selection Group Panel component by dragging&dropping from theGeneric Components folder that you can find in the MOSKitt Artifacts Libraryview (for more information about the Sketcher templates provided by MOSKitt to make easiermodeling web applications you can see the guide section titled "Plantillas genéricas para elmodelado de aplicaciones web" in the User Manual of the Codgen-openxava MOSKitt module.



10

• Include an Image element to show the property photo of the Customer class (include also itscorresponding Labelelement).

• Set the title in each one of these elements using the Text property. This property is located inthe Properties Tab, Basic subtab of each sketcher element (Litle Code, Type, Nameand Photo).

• Fill the Data Model Element property to link every widget (TextBox and Label elementsin this case) with the corresponding UML2 properties of the Customer class navigatingthrough the Invoice_Customer association. This association appears when we deploy theInvoice class in the Object Selection wizard (caution!, this is very important). For moreinformation about how to relate Sketcher and UML2 models you can see the last section in thispoint titled "How to relate Sketcher elements whith UML element".

• TabItem Data: This tab shows the lines of an specific invoice (each invoice line will be locatedin a row of a table). Follow next stepx for modeling this TabItem:

• Include a Detail-Tabular Panel component by dragging&dropping from the GenericComponents folder that you can find in the MOSKitt Artifacts Library view (formore information about the Sketcher templates provided by MOSKitt to make easier to modelweb applications you can see section titled "Plantillas genéricas para el modelado de aplicacionesweb" in the User Manual of the Codgen-openxava MOSKitt module.

• Add new columns to the table (these are Table Column elements located in the submenuTable of the Sketcher Palette)

• Set the title in each one of these Table Column using the Text property. This property islocated in the Properties Tab, Basic subtab of each Table Column element.

• Fill the Data Model Element property to link every widget (Table Column in this case)with the corresponding UML2 properties of the InvoiceDetail class navigating throughthe Invoice_InvoiceDetail association. This association appears when we deploy theInvoice class in the Object Selection wizard (caution!, this is very important). For moreinformation about how to relate Sketcher and UML2 models you can see the last section in thispoint titled "How to relate Sketcher elements whith UML element".

The next figure shows how to model this tab with MOSKitt-Sketcher:



11

• TabItem Deliveries: This tab shows the list of deliveries of an specific invoice. It does notallow to insert new deliveries, only to relate existent deliveries to the active invoice. Follow nextsteps for modeling this tab:

• Include a Multiple Selection Panel component by dragging&dropping from theGeneric Components folder that you can find in the MOSKitt Artifacts Libraryview (for more information about the Sketcher templates provided by MOSKitt to make easierto model web applications you can see section titled "Plantillas genéricas para el modelado deaplicaciones web" in the User Manual of the Codgen-openxava MOSKitt module.

• Complete this component with the needed widgets in the same way as it has been made to modelthe previous panels.

• Fill the Data Model Element property to link every widget with the correspondingUML2 properties of the Delivery class navigating through the Invoicing_Deliveryassociation. This association appears when we deploy the Invoice class in the ObjectSelection wizard (caution!, this is very important). For more information about how to relateSketcher and UML2 models you can see the last section in this point titled "How to relate Sketcherelements whith UML element".

The next figure shows how to model this tab with MOSKitt-Sketcher:



12

For more information about how to use the MOSKitt-Sketcher editor you can see the User Manualin MOSKitt.

Task 2.1.3: Modeling the Both views of the Invoice module.

This view shows both List view and Detail view at the same time. You do not have to model this view,because it has been modeled at the same time you have modeled the other two views (List and Detail.

Following the example in the OpenXava web, the window we are going to model looks like this:

Next figure shows the Both view, which is composed by List view and Detail view:



13

How to relate Sketcher elements with UML element

A Sketcher model will be complete when the widgets contained on it are linked with the UMLelements. In this way, analysts will be able to identify:

• Which class property must be shown in each widget.

• If these properties can be edited by means of the related widget.

• Which class operations can be invoked from the interface (usually pushing a button widget).

• Which enumeration litterals can be offered into a list of valuesQué enumerados deben ser ofrecidosen una lista de valores

• and so on...

The first step we must do for having access to the UML2 elements from the Sketcher model is to loadthe UML model as a new resource of the Sketcher using the Load Resource options available throughthe contextual menu.

At this moment the Load Resource wizard appears. Pushing the Browse Workspace... buttonwe must search the UML2 model named invoice_domain.uml (in this tutorial) and finally wewill push OK.



14

After doing that, all the elements included into the UML2 model will be accesible to the Sketchermodel.

The previous figure shows the properties of a TextBox.

For each sketcher element we must fill the following properties:

• Id: widget identificator.

• Elemento Modelo: UML2 element related with the widget.

• Ruta Elemento Modelo: shows the path to reach the property into the UML2 diagram class. See anexample to ilustrate the importance of this property:

• If you select the property Quantity of the Invoice_Detail class, the interface generatedwill show all the invoice lines corresponding to all the invoices in your system, and for each one,only the Quantity property will appear.

• However, if you select the same propety but navigating from the Invoice class through theassociation Invoice_InvoiceDetail, you are saying thay you are going to show only theQuantity property of all the lines for the active invoice.

In the next figure you can see how MOSKitt marks the elements already linked with UML element bymeans of a D simbol in the left up side of some widgets. To know with which specific UML elementa widget is linked you must go to the Properties tab to see which is the value for the Elemento Modeloand Ruta Elemento Modelo properties.

For more information about all the available elements in the Sketcher palette and its properties youcan see the User Manual of the MOSKitt-Sketcher module.

Task 3: Launching the OpenXava applicationTo execute this task you must follow the tutorial titled Tutorial 3: How to launch an OpenXavaapplication with OXPortal.

moskitt codgen ox tutorial2 uim2ox article eng

Documents