Chapter 8: Application

An application is the software that the final user can use. For now you have seen how to define the pieces that make up an application (mainly the components and the actions), now you will learn how to assemble these pieces in order to create applications.
The definition of an OpenXava application is given in the file application.xml that can be found in the xava directory of your project.
The file syntax is:

<application
    name="name"                   <!-- 1 -->
    label="label"                 <!-- 2 -->
>
    <default-module ... /> ...    <!-- 3  New in v2.2.2 -->
    <module ... /> ...            <!-- 4 -->
</application>

1. name (required): Name of the application.
2. label (optional): It's much better to use i18n files.
3. default-module (one, optional): New in v2.2.2. For defining the controllers for the default (automatically generated for each component) modules.
4. module (several, optional): Each module executable by final user.

In short, an application is a set of modules. Let's see how define a module:

<module
    name="name"                    <!--  1 -->
    folder="folder"                <!--  2 -->
    label="label"                  <!--  3 -->
    description="description"      <!--  4 -->
>
    <env-var ... /> ...            <!--  5 -->
    <model ... />                  <!--  6 -->
    <view ... />                   <!--  7 -->
    <web-view ... />               <!--  8 -->
    <tab ... />                    <!--  9 -->
    <controller ... /> ...         <!-- 10 -->
    <mode-controller ... />        <!-- 11 -->
    <doc ... />                    <!-- 12 -->
</module>

1. name (required): Unique identifier of the module within this application.
2. folder (optional): Folder in which the module will reside. It's a tip to classify the modules. For the moment it's used to generate a folder structure for JetSpeed2 but its use can be amplified in future. You can use / or . to indicate subfolders (for example, "invoicing/reports" or "invoicing.reports").
3. label (optional): Short name to be shown to the user. It's much better to use i18n files.
4. description (optional): Long description to be shown to the user. It's much better to use i18n files.
5. env-var (several, optional): Allows you to define variables with a value that can be accessed by actions. Thus you can have actions configurable by module.
6. model (one, optional): Name of the component used in this module. If you leave it blank, then it is required to set the value to web-view.
7. view (one, optional): The view used to display the detail. If you leave it blank, then the default view will be used.
8. web-view (one, optional): Allows you to define a JSP page to be used as a view.
9. tab (one, optional): The tab used in list mode. If you do not specify it, then the default tab will be used.
10. controller (several, optional): Controllers with the available actions used initially.
11. mode-controller (one, optional): Allows to define the behavior to switch from detail to list mode and vice versa, as well as to define a module without detail and view (with no modes).
12. doc (one, optional): It's mutually exclusive with all other elements. It allows you to define a module that contains documentation only and no logic. Useful for generating informational portlets for your application.

Typical module example

Defining a simple module can be like this:

<application name="Management">
    <module name="Warehouse" folder="warehousing">
        <model name="Warehouse"/>
        <controller name="Typical"/>
        <controller name="Warehouse"/>
    </module>
    ...
</application>

In this case you have a module that allows the user to create, to delete, to update, to search, to generate PDF reports and to export to Excel the warehouses data (thanks to Typical controller) and also to execute actions only for warehouses (thank to Warehouse controller). In the case the system generates a module structure (as in JetSpeed2 case) this module will be in folder "warehousing".
In order to execute this module you need to open your browser and go to:
http://localhost:8080/Management/xava/module.jsp?application=Management&module=Warehouse
Also a portlet is generated to allow you to deploy the module as a JSR-168 portlet in a Java portal.

Default modules (new in v2.2.2)

OpenXava assumes a default module for each component in the application, although the module is not explicitly defined in applicaction.xml.
That is, if you define a component Invoice.xml, you can open your browser and go to:
http://localhost:8080/Management/xava/module.jsp?application=Management&module=Invoice
Also a portlet is generated to allow you to deploy the module as a JSR-168 portlet in a Java portal.
And all this without defining it in application.xml.
The controller for these default modules will be Typical, but you can change this default value using the default-module element in application.xml, in this way:

<application name="Management">
 
    <default-module>
        <controller name="ManagementCRUD"/>
    </default-module>
 
</application>

In this case all the default modules of the Management application will have the controller ManagementCRUD assigned to them.
If you want that certain module does not use these default controllers, you have two options:

1. To define a controller in your controllers.xml with the same name of the component.
2. To define explicitly the module in application.xml, as it's explained above.

To sum up, if you define a component, named Customer, for example, then you have a module named Customer, and also a portlet. This module will be defined in one of this ways:

1. If you define a module named Customer in application.xml then this module will be the valid one, else...
2. If you define a controller named Customer in controllers.xml a module will generated using the controller Customer as controller and the component Customer as model, else..
3. 3.If you define a default-module element in your application.xml then a module will generated using the controllers in default-module and the component Customer as model, else ...
4. as fallback a module with Typical as controller and Customer as model will be assumed.

Only detail module

A module with only detail mode, without list, is defined this way:

<module name="InvoiceNoList">
    <model name="Invoice"/>
    <controller name="Typical"/>
    <mode-controller name="Void"/>        <!-- 1 -->
</module>

Void (1) mode controller is for removing the "detail – list" links; in this case by default the module uses detail mode only.

Only list module

A module with only list mode, without detail, is defined this way:

<module name="FamilyListOnly">
    <env-var name="XAVA_LIST_ACTION" value=""/>     <!-- 1  New in v2.0.4 -->
    <model name="Family"/>
    <controller name="Typical"/>
    <controller name="ListOnly"/>                   <!-- 2 -->
    <mode-controller name="Void"/>                  <!-- 3 -->
</module>

Void (3) mode controller is for removing the "detail – list" links. Furthermore on defining ListOnly (2) as controller the module changes to list mode on init, so this is an only list module. Finally, setting XAVA_LIST_ACTION to empty string (1) the detail link in each row is missing (new in v2.0.4).

Documentation module

A documentation module can only display a HTML document. It's easy to define:

<module name="Description">
    <doc url="doc/description" languages="en,es"/>
</module>

This module shows the document web/doc/description_en.html or web/doc/description_es.html depending on the browser language. If the browser language is not English nor Spanish then it assumes English (the first specified language). If you do not specify the language, then the document web/doc/description.html is shown.
This is useful for informational portlets. This type of module has no effect outside a portal environment.

Read only module

A read only module, that is only for consulting data, not for modifying, can be defined as following:

<module name="CustomerReadOnly">
    <env-var name="XAVA_SEARCH_ACTION" value="CRUD.searchReadOnly"/>  <!-- 1 -->
    <model name="Customer"/>
    <controller name="Print"/>                                        <!-- 2 -->
</module>

Using CRUD.searchReadOnly (1) the user cannot edit the data, and using only Print controller (2) (without CRUD or Typical) the actions for saving, deleting, etc are not available. This is a simply consulting module.

The syntax for application.xml is not difficult. You can see more examples in OpenXavaTest/xava/application.xml.