openxava / documentation / Application

Reference guide: Model | View | Tabular data | Object/relational mapping | Controllers | Application | Customizing

Table of contents

Application
Typical module example
Default modules (new in v2.2.2)
Only detail module
Only list module
Documentation module
Read only module
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 src/main/resources/xava directory of your project (in xava directory in v6 or older).
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 -->
    label="label"                  <!--  2 -->
    description="description"      <!--  3 -->
>
    <env-var ... /> ...            <!--  4 -->
    <model ... />                  <!--  5 -->
    <view ... />                   <!--  6 -->
    <web-view ... />               <!--  7 -->
    <tab ... />                    <!--  8 -->
    <controller ... /> ...         <!--  9 -->
    <mode-controller ... />        <!-- 10 -->
    <doc ... />                    <!-- 11  Until v6.6.3 -->
</module>
  1. name (required): Unique identifier of the module within this application.
  2. label (optional): Short name to be shown to the user. It's much better to use i18n files.
  3. description (optional): Long description to be shown to the user. It's much better to use i18n files.
  4. 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.
  5. 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.
  6. view (one, optional): The view used to display the detail. If you leave it blank, then the default view will be used.
  7. web-view (one, optional): Allows you to define a JSP page to be used as a view.
  8. tab (one, optional): The tab used in list mode. If you do not specify it, then the default tab will be used.
  9. controller (several, optional): Controllers with the available actions used initially.
  10. mode-controller (one, optional): Allows to define the behavior to switch from detail to list mode, as well as to define a module without list mode. The available values are Mode (the default one) and DetailOnly. Between v4m5 and v5.9.1 there was a mode split, removed in v6.0. Between v4m5 and v5.9.1 the available mode controllers were Mode (detail - list - split), DetailList, DetailOnly, ListOnly and SplitOnly. Since v6.0 DetailList, ListOnly and SplitOnly no longer exist, but are assumed as Mode to not produce backward incompatibilities.
  11. doc (one, optional): Until v6.6.3. 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 (not supported in the current OpenXava version) 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/modules/Warehouse
Until v6.6.3 a portlet was generated to allow you to deploy the module as a JSR-168/286 portlet in a Java portal. Portal support was removed in v7.0.
You can see the definition of Typical controller in openxava/src/main/resources/xava/default-controllers.xml (in OpenXava/xava/default-controllers.xml for v6 or older), where you also can find other useful controllers such as TypicalNotResetOnSave, TypicalNewOnInit or TypicalRealExcel with a slight differente behavior.

Default modules (new in v2.2.2)

OpenXava assumes a default module for each entity in the application, although the module is not explicitly defined in applicaction.xml.
That is, if you define an entity Invoice.java, you can open your browser and go to:
http://localhost:8080/management/modules/Invoice
Until v6.6.3 a portlet was generated to allow you to deploy the module as a JSR-168/286 portlet in a Java portal. Portal support was removed in v7.0.
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. 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 (new in v4m5):
<module name="InvoiceNoList">
    <model name="Invoice"/>
    <controller name="Typical"/>
    <mode-controller name="DetailOnly"/>        <!-- 1 -->
</module>
Just use DetailOnly (1) as mode-controller.
If you are using a version prior to v4m5 you have to define a detail only module in 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. This way though deprecated is still supported.

Only list module

A module with only list mode, without detail, is defined this way (new in v6.0):
<module name="FamilyListOnly">
    <env-var name="XAVA_LIST_ACTION" value=""/>  <!-- 1  New in v2.0.4 -->
    <model name="Family"/>
    <controller name="Typical"/>
</module>
Setting XAVA_LIST_ACTION to empty string (1) the detail link in each row is missing (new in v2.0.4).
If you are using a version between v4m5 and v5.9.1 define the list only mode thus:
<module name="FamilyListOnly">
    <env-var name="XAVA_LIST_ACTION" value=""/>  
    <model name="Family"/>
    <controller name="Typical"/>
    <mode-controller name="ListOnly"/>           <!-- 1 -->
</module>
ListOnly (1) mode controller is for removing the "detail – list – both" links and inititializing the module in list mode. Since v6.0 these links no longer exist for any module. This way though deprecated is still supported.
If you are using a version prior to v4m5 you have to define a list only module in this way:
<module name="FamilyListOnly">
    <env-var name="XAVA_LIST_ACTION" value=""/>
    <model name="Family"/>
    <controller name="Typical"/>
    <controller name="ListOnly"/>                   <!-- 1 -->
    <mode-controller name="Void"/>                  <!-- 2 -->
</module>
Void (2) mode controller is for removing the "detail – list" links. Furthermore on defining ListOnly (1) as controller the module changes to list mode on init, so this is an only list module. This way though deprecated is still supported.

Documentation module (until 6.6.3)

Warning: Documentation modules only work with Liferay or WebSphere Portal
Portal support was dropped in v7.0, so documentation modules are ignored since v7.0
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 (or ExtendedPrint since v4.6) 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/src/main/resources/xava/application.xml.