A.9. screens.xml

Files of this type are used in the generic user interface of the Web Client and the Desktop Client for registration of screen XML-descriptors.

XML schema is available at http://schemas.haulmont.com/cuba/6.8/screens.xsd.

The file location is specified in the cuba.windowConfig application property. When you create a new project in Studio, it creates the web-screens.xml file in the root package of the web module, for example modules/web/src/com/company/sample/web-screens.xml.

The file has the following structure:

screen-config – the root element. It contains the following elements:

  1. screen – screen descriptor.

    screen attributes:

    • id – screen identifier used to reference this screen from the application code (e.g. in the Frame.openWindow() and other methods) and in the menu.xml.

    • template – path to screen’s XML-descriptor. Resources interface rules apply to loading the descriptor.

    • class – if the template attribute is not set, this attribute should contain the name of the class implementing either Callable or Runnable.

      In case of Callable, the call() method should return an instance of Window, which will be returned to the invoking code as the result of calling WindowManager.openWindow(). The class may contain a constructor with string parameters, defined by the nested param element (see below).

    • agent - if multiple templates are registered with the same id, this attribute is used to choose a template to open. There are three standard agent types: DESKTOP, TABLET, PHONE. They enable selection of a screen template depending on the current device and display parameters. See Screen Agent for details.

    • multipleOpen – optional attribute, allowing a screen to be opened multiple times. If set to false or not defined and the screen with this identifier has already been opened in the main window, the system will show the existing screen instead of opening a new one. If set to true, any number of screen instances can be opened.

    screen elements:

    • param – defines a screen parameter submitted as a map to the controller's init() method. Parameters, passed to the openWindow() methods by the invoking code, override the matching parameters set in screens.xml.

      param attributes:

      • name – parameter name.

      • value – parameter value. Strings true and false are converted into the corresponding Boolean values.

  2. include – includes a different file, e.g. screens.xml.

    include attributes:

    • file – path to a file according to the rules of the Resources interface.

Example of a screens.xml file:

<screen-config xmlns="http://schemas.haulmont.com/cuba/screens.xsd">

  <screen id="sales$Customer.lookup" template="/com/sample/sales/gui/customer/customer-browse.xml"/>
  <screen id="sales$Customer.edit" template="/com/sample/sales/gui/customer/customer-edit.xml"/>

  <screen id="sales$Order.lookup" template="/com/sample/sales/gui/order/order-browse.xml"/>
  <screen id="sales$Order.edit" template="/com/sample/sales/gui/order/order-edit.xml"/>

</screen-config>