Reference guide:
Model
|
View |
Tabular data |
Object/relational
mapping |
Controllers
|
Application |
Customizing
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>
- name (required): Name of the application.
- label (optional): It's much better to use i18n
files.
- default-module (one, optional): New in v2.2.2.
For defining the controllers for the default (automatically generated
for each component) modules.
- 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>
- name (required): Unique identifier of the module
within this application.
- label (optional): Short name to be shown to the
user. It's much better to use i18n files.
- description (optional): Long description to be
shown to the user. It's much better to use i18n files.
- 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.
- 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.
- view (one, optional): The view used to display the
detail. If you leave it blank, then the default view will be used.
- web-view (one, optional): Allows you to define a
JSP page to be used as a view.
- tab (one, optional): The tab used in list mode. If
you do not specify it, then the default tab will be used.
- controller (several, optional): Controllers with
the available actions used initially.
- 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.
- 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:
- To define a controller in your controllers.xml with the
same name of the component.
- 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:
- If you define a module named Customer in application.xml
then this module will be the valid one, else...
- 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.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 ...
- 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
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
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.