Template

A template is the frame of a screen. It decides where the screen title, the breadcrumbs, the buttons and the content are drawn. A template has one or more source points, and the screen XML fills each one with a tag that names it in its source attribute.

You choose the template of a screen with the required template attribute of the screen element, and you fill its source points with tag elements:

<screen template="window" label="SCREEN_TITLE_QUE"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/screen.xsd">
  <tag source="hidden"></tag>
  <tag source="buttons">
    <button label="BUTTON_SEND" icon="exchange" id="ButSndSyn">
      <button-action type="server" server-action="maintain" target-action="TstQueSndSyn" />
    </button>
  </tag>
  <tag source="center">
    <window label="SCREEN_TEXT_CRITERIA">
      ...
    </window>
  </tag>
</screen>

The example is a trimmed copy of the screen QueTst of the React test application (awe-tests/awe-boot-react). The center source holds the screen itself and the buttons source the buttons of the top right corner of the window.

Note: Templates are not JSP files any more. Both clients draw the screen from the XML: the AngularJS client uses templates generated by the server (StringTemplate), and the React client uses React components.

Source points of the standard templates

AWE has three standard templates. Their source points are the same in both engines:

Template	For	center	buttons	modal	hidden	Title and breadcrumbs
full	No frame, only the sources: main page, navigation bars, screens made to be included	Yes	No	Yes	Yes	No
window	Screens that open from the menu, inside the application	Yes	Yes	Yes	Yes	Yes
document	Screens that show a document, like the application manual	Yes	Yes	Yes	Yes	AngularJS engine only

The source points are:

• center: the center container of the template. This is where you define the structure of the screen.
• buttons: the buttons of the upper right zone of the screen. Only in window and document.
• modal: the place for the modal windows. Put here the dialog elements and the include elements that bring dialogs from other screens.
• hidden: a hidden container for hidden criteria and messages.

The title of the screen (label attribute) and the breadcrumbs are filled in by the template, you do not define them with a source.

Every source can appear once per screen (the schema checks it), and the tag of a source must be a direct child of the screen. A tag with a source that the template does not have (for example buttons in full) is not drawn, and in the AngularJS engine a source name that the template does not declare makes the screen fail. In the React engine the style of the center, buttons and modal tags is added to the class of their container.

Note: AWE's own generic screens use other values (base, home, login, message) that are not defined by the standard templates of the clients. Do not use them in application screens: the React client shows the message The template <name> has not been created yet. for a template it does not know.

Window header

The window template has two header modes:

Mode	What the header shows
breadcrumb	The menu breadcrumb, ending with the title of the screen, and the buttons source at its right. This is the default
none	No breadcrumb and no title: only the buttons source, on a row of its own at the right. The row wraps on narrow viewports

Choose the mode for the whole application with the property awe.application.window-header (see properties), and for one screen with the window-header attribute of the screen. The attribute overrides the property in both directions: a screen can hide the breadcrumb in an application that shows it, and the other way round.

<screen template="window" label="SCREEN_TITLE_USERS" window-header="none" ...>

The full and document templates are not affected. In the test hooks, the breadcrumb test id is only present in breadcrumb mode.

Note: In the AngularJS engine the server passes the header parameter only to the templates that declare it, so your own templates keep working unchanged. Add it to a copy of window to support the mode.

Navigable breadcrumb

In breadcrumb mode the levels are links, in both engines:

• The home icon opens the start screen.
• A menu option level opens its screen, as the menu does.
• A menu group level opens the side menu expanded at that group (an open drawer on narrow viewports). With the horizontal menu, or when the menu does not know the group, a group is plain text.
• The last level is the current page: plain text marked aria-current="page". The breadcrumb is a nav labelled with the locale key SCREEN_TEXT_BREADCRUMB.
• With more than 4 levels the breadcrumb shows the first level, an ellipsis button and the last two levels. The button (named by SCREEN_TEXT_BREADCRUMB_EXPAND, with aria-expanded) shows the hidden levels in place.
• A screen opened from another screen (not from the menu) shows the trail of the screens it came from, and the origin screen is a level that goes back to it. The trail resets when a screen is launched from the menu, the home icon or a menu level.

Test hooks: breadcrumb, breadcrumb-home, breadcrumb-level (a menu level carries name, an origin screen path; the current page carries data-active="true") and breadcrumb-ellipsis. In the AngularJS engine the current page shows its title only when the server knows it, so the trail may end one level earlier than in React.

Own templates

If you need a different frame (for example a screen with a side panel), you can add your own template. How you do it depends on the engine:

• React engine. Write a React component that receives the screen structure (elementList) and draws the sources it needs, and register it by name with registerTemplate(name, component), exported by the awe-react-client package. Then use template="[name]" in your screens. The registration fails if the name already exists, so you cannot replace full, window or document.
• AngularJS engine. Add a StringTemplate group file at templates/[module]/templates.stg in your application, where [module] is one of the modules of awe.application.module-list (see properties). A template is a definition whose parameters are the source points (breadcrumbs, title, buttons, center, modal and hidden in the standard ones) and whose body uses them with $center$, $modal$...

A screen that uses your own template must have the template in both engines if the application runs in both.

Related pages

• Screen: the template attribute.
• Tags: the source attribute that fills a source point.
• Include: reuse the content of a source of another screen.
• Layout: how the content of a source is expanded.
• Screens: the list of screen elements.

Reviewed for AWE 5.