Defining the XML Layout

This document covers the following topics:


Previewing the Layout

If you want to find out how the current layout definitions are rendered on the page, you can preview the layout. The preview of the layout is shown in the preview area. For example:

Preview

The preview area is a sensitive area. When you select a control in the preview area (for example, the title bar), this control is automatically selected in the layout tree.

Note:
If you want to design your page layouts with a right-to-left (RTL) layout direction, you can set this in the Ajax Developer preferences (as a default for new user interface components), when creating a new user interface component, or when changing the properties of an existing user interface component.

Start of instruction setTo preview the layout

  • From the Ajax Developer menu, choose Refresh Preview.

    Or:
    Choose the following button from the Ajax Developer toolbar:

    Toolbar button

    The preview area is updated according to the defined preview mode (see below).

    If the system finds wrong definitions, a message is displayed in the Problems view. To select the wrong control definition, double click the message line in the Problems view.

Changing the Preview Mode

There are two different preview modes:

Run Application

This is the default setting.

For page layouts other than NATPAGE layouts, the latest changes to the adapter class are used when you preview your layout.

For NATPAGE layouts, only generic Java-side classes, which are part of the Application Designer framework, are used for the preview. The Natural adapter itself is not run. To run a NATPAGE layout with the Natural adapter, you use the Run As > Natural Application command with the corresponding Natural program.

Screen Test Only

For page layouts other than NATPAGE layouts: When the name of an adapter class has not been defined in the model property of the page, or when an adapter class has been defined which does not yet exist, an error screen is shown when you try to preview your layout. In this case, you have the possibility to activate Screen Test Only. Your layout will then be loaded with an empty adapter. This means that you will not have any functionality. Any changes that you make in your Java development environment will not be reflected in the preview.

For NATPAGE layouts: Instead of the generic Java-side classes of the Application Designer framework, which are executed when you choose Run Application, the layout is loaded with the same empty adapter as described above for non-NATPAGE layouts. For NATPAGE layouts, Screen Test Only is only used for troubleshooting. If Run Application fails, you can use Screen Test Only, for example, to verify whether Java Scripting and the basic Application Designer framework are able to load the page layout properly.

Start of instruction setTo change the preview mode

  • From the Ajax Developer menu, choose Preview Mode > mode, where mode is one of the preview modes described above.

Changing the Display Mode

When you change the display mode, this is immediately considered in the preview area.

By default, the layout display mode as defined in the project properties is used. However, by choosing a different display mode (HTML or SWT) from the Ajax Developer menu, you can temporarily change the preview without having to change the settings in the project properties.

The menu provides for selection the following display modes:

HTML

When this display mode is active, the preview is shown as in the browser. The layout is rendered in the preview area with the actual CSS style sheet.

SWT

When this display mode is active, the preview is rendered as SWT controls. The actual CSS style sheets are ignored. Only a subset of the supported controls can be rendered as SWT controls. Responsive controls cannot be rendered as SWT controls.

Project Settings

This is the default setting. When this display mode is active, the corresponding settings from the project properties are used.

Start of instruction setTo change the display mode

  • From the Ajax Developer menu, choose Display Mode > mode, where mode is one of the display modes described above.

Previewing the Layout in a New Browser Window

You can display and test the current layout, which is normally shown in the preview area, in a separate browser window. The browser shows the URL that is used to invoke this page.

Start of instruction setTo preview the layout in a new browser window

  • From the Ajax Developer menu, choose Preview in New Browser Window.

    Or:
    Choose the following button from the Ajax Developer toolbar:

    Toolbar button

Setting the Properties for a Control

When you select a control in the layout area or in the preview area, its properties are shown in the Properties view and you can edit them immediately. Example:

Properties

The All tab is always provided for all controls. The availability of other tabs depends on the control which is currently selected.

The Props tab is only shown when the control has *prop properties (such as visibleprop), and the Events tab is only shown when the control has *method properties (such as contextmenumethod). These tabs are provided for your convenience. They show the properties which bear a reference to the program code. However, the properties that are shown on these tabs are also shown on the All tab.

When it is possible to change, for example, the font for text on a control, the Text tab is available. For further information, see Changing the Appearance of Text.

The Data tab is only shown for field controls. It shows any validation rules or formulae that have been defined for the field. Using the corresponding Edit button, you can invoke either the validation rules editor or the formula editor. For further information, see Using the Validation Rules Editor or Using the Formula Editor.

Start of instruction setTo set a property using the Properties view

  1. Select the control in the layout area or in the preview area.

    The properties for the selected control are now shown in the Properties view. For some properties, default values are provided.

  2. Specify the value for the required property.

    Note:
    The values of some important properties (for example, the name or textid of the Title Bar control) are shown in the layout area, in round brackets after the XML tag. If you modify the value of such a property, the changed value will be shown in the layout area.

Changing the Appearance of Text

Instead of setting the corresponding property for a control, you can change the appearance of text (for example, on a button) using the Text tab of the Properties view. This tab is available for all controls for which the appearance of text can be changed.

The Text tab provides for selection only those options which make sense with the selected control. Example for a button:

Properties for text

Start of instruction setTo change the appearance of text

  1. Select the control in the layout area or in the preview area.

  2. Select the Text tab of the Properties view.

  3. Choose the Browse button.

    A dialog appears in which you can specify all required settings (such font family, font color or italics). These settings are then automatically entered on the Text tab.

  4. If you want to change the alignment, select the corresponding option button.

    Your changes are immediately shown in the preview area.

Adding Controls to the Layout

The controls that you can add to the layout can be found in the various sections of the controls palette. You simply drag them from the controls palette onto the corresponding node in the layout area or to the preview area. The preview area is immediately refreshed.

Controls palette

Start of instruction setTo add a control to the layout

  1. Open the required section of the controls palette by choosing the corresponding button (for example, the Controls button).

    When you move the mouse over a control, a tool tip appears which also displays the control name which will be used in the XML layout. For example:

    Tooltip

  2. Drag the control from the controls palette onto the required node in the layout area.

    Or:
    Drag the control from the controls palette and drop it in the preview area.

    Note:
    A control can only be inserted at a valid position. Thus, it may happen that the control is not inserted in the node which was highlighted when you dropped the control, but at a different position.

    When you drop information, the system will sometimes respond by offering a context menu with certain options about where to place the control. Depending on the current context, different commands are available. For example:

    Context menu

    The new node is automatically selected in the layout area so that you can maintain its properties directly in the Properties view

Creating a Folder for Images

All resources that your user interface component needs (such as images) must be contained in your project directory in the Eclipse workspace. It is good practice to create a specific folder for these resources.

Start of instruction setTo create a folder for images

  1. In the ProjectExplorer view or in the Natural Navigator view, select the user interface component for which you want to create a folder.

  2. Invoke the context menu and choose New > Other.

  3. In the resulting dialog box, expand the General node, select Folder and choose the Next button.

  4. Specify a folder name (for example, "images") and then choose the Finish button.

  5. Place all images that you want to use in the images folder that you have just created.

Defining a Background Image

You can define a background image for your page. The image must be a file with the extension gif, jpeg or jpg.

Start of instruction setTo define a background image

  1. Select a control for which a background image can be set.

    Note:
    When a background image cannot be set for a control, the Insert Background Image command is disabled.

  2. From the Ajax Developer menu, choose Insert Background Image.

    Or:
    Choose the following button from the Ajax Developer toolbar:

    Toolbar button

    A dialog appears.

  3. Select the image file from your images folder (see also Creating a Folder for Images).

    The path to the image will automatically be converted to a relative path.

  4. Choose the Open button.

    The correct relative URL is automatically set in the corresponding property. In different controls, different properties are used to support background images. Background images are supported, for example, by the pagebodystyle property of the PAGEBODY control and the titlestyle property of the TITLEBAR control.

    The correct style definition including the relative URL for the background image file is automatically set in the corresponding property. For example:

    background-image:url(images/absbackground_small.gif)

Defining a Style Sheet

You can assign a style sheet to your page. This can either be a predefined style sheet or one of your own style sheets that you have created using the Style Sheet Editor. The style sheet must be a file with the extension css.

Instead of setting the corresponding property for the page (see Static Selection of the Style Sheet File), you can define a style sheet as described below.

Start of instruction setTo define a style sheet

  1. From the Ajax Developer menu, choose Insert Style Sheet.

    Or:
    Choose the following button from the Ajax Developer toolbar:

    Toolbar button

    A dialog appears.

  2. Specify the path to your style sheet.

    You have to specify a style sheet from your local file system. The file must be located in the same directory as your web application (or any subdirectory). When you specify an absolute path, this will automatically be converted to a relative path.

Defining Hot Keys

You can assign hot keys to pages and to the controls FIELD and ROWTABLEAREA2. For example, you can define the hot key CTRL+S for calling the method onSave.

See also Extended Hot Key Management in the Natural for Ajax.

Start of instruction setTo define hot keys

  1. Select the control in the layout area or in the preview area.

    Note:
    When a control is selected for which hot keys cannot be defined, your hot key definition will apply to the page.

  2. From the Ajax Developer menu, choose Insert Hotkeys.

    Or:
    Choose the following button from the Ajax Developer toolbar:

    Toolbar button

    A dialog appears. When hot keys have already been defined, they are shown. Example:

    Hot keys

  3. When hot keys have already been defined, choose the Add New Line button to add an additional hot key.

    Note:
    To remove a hot key, select the corresponding row and choose the Remove Selected Lines button.

  4. From the drop-down list box in the first column, select the key that you want to use as a hot key. For example, "83" represents the S key and "120" represents the F9 key.

    Or:
    In the text box of the drop-down list box in the first column, enter a text ID that is to be translated by the multi language management.

  5. Define each key (CTRL, SHIFT and/or ALT) which is to be used for the hot key by selecting "true" from the corresponding drop-down list box.

    Note:
    If neither "true" nor "false" is selected for a key, the default setting "false" is used.

  6. In the Method column, specify the name of the method that is to be invoked when the user presses the hot key.

  7. When all hot keys have been defined, choose the Take Over button.

Managing the Nodes in the Layout Area

The following topics are covered below:

Moving Nodes

You can manage the nodes in the layout area using the following buttons which are shown below the layout tree:

Button Description
Move to top Moves the selected node up to first position in the tree.
Move up Moves the selected node up to the previous position in the tree.
Move down Moves the selected node down to the next position in the tree.
Move to bottom Moves the selected node down to last position in the tree.

When an operation is not allowed, clicking on the corresponding button has no effect.

Using the Clipboard

You can manage the nodes in the layout tree using the following commands from the Edit menu of Eclipse:

Command Description
Cut Cuts the selected node.
Copy Copies the selected node.
Delete Deletes the selected node.
Undo Undoes the previous action. The previous action can be, for example, a move operation or a changed property value.
Redo Redoes the previous undo action.

Note:
To copy and paste information in the Properties view, use the key combinations CTRL+C and CTRL+V.

Drag-and-Drop

In the layout area, you copy or move the nodes using drag-and-drop.

Start of instruction setTo copy or move a node using drag-and-drop

  1. In the layout area, select the node you want to move so that it is highlighted.

    Press SHIFT or CTRL, if you want to select more than one node.

  2. Press the left mouse button and keep it pressed.

  3. Drag the mouse to the target node.

    While you drag the mouse, a tool tip in light colors is shown for the node(s) you are currently dragging.

  4. Release the mouse button.

    A context menu appears and you can choose the location where you want to place the copy or the moved item (for example, in front of the target node).

    Note:
    When the copy or move operation is not allowed, the context menu does not appear.

  5. Choose the required command from the context menu.

    Note:
    To cancel the drag process, move the mouse outside the context menu or press ESC. The context menu will disappear and any selected nodes will keep their current position.

Context Menus

You can manage the nodes in the layout tree using context menus. The following commands may appear in a context menu:

Command Description
Add as first Subnode Adds a control as the first subnode of the selected node. A cascading menu is available for this command, containing all controls that can be added as a subnode of the selected node.
Add as last Subnode Adds a control as the last subnode of the selected node. A cascading menu is available for this command, containing all controls that can be added as a subnode of the selected node.
Add as preceding Sidenode Adds a control before the selected node, on the same level as the selected node. A cascading menu is available for this command, containing all controls that can be added as a sidenode of the selected node.
Add as subsequent Sidenode Adds a control after the selected node, on the same level as the selected node. A cascading menu is available for this command, containing all controls that can be added as a sidenode of the selected node.
Cut Cuts the selected node.
Copy Copies the selected node.
Paste as first Subnode Pastes the cut or copied node as the first subnode of the selected node.
Paste as last Subnode Pastes the cut or copied node as the last subnode of the selected node.
Paste as preceding Sidenode Pastes the cut or copied node before the selected node, on the same level as the selected node.
Paste as subsequent Sidenode Pastes the cut or copied node after the selected node, on the same level as the selected node.
Remove Deletes the selected node.
Open all Subnodes Opens all subnodes of the selected node.
Close all Subnodes Closes all subnodes of the selected node.

Managing the Controls in the Preview Area

You can manage controls directly in the preview area.

When you select a control in the preview area, it is highlighted with a different color in the layout area and vice versa. Pressing CTRL+SHIFT while selecting a control will select its parent control. You can copy or move the control. In SWT mode you can also resize the control.

The following topics are covered below:

Moving and Copying Controls in the Preview Area

You can move or copy a control or groups of controls directly in the preview area.

Note:
To select more than one control, press CTRL or SHIFT while selecting the controls.

Start of instruction setTo move controls in the preview area

  1. Select the controls that you want to move.

  2. Drag the controls to a new valid position.

Start of instruction setTo copy controls in the preview area

  1. Select the controls that you want to copy.

  2. Press CTRL and drag the controls to a valid position at which it is possible to insert the copies.

The drop position will be highlighted. A control can only be inserted at a valid position. Thus, it may happen that the control is not inserted in the node which was highlighted when you dropped the control. When you drop controls, the system will sometimes respond by offering a context menu with certain options about where to place the control.

Start of instruction setTo copy/move controls in the preview area via context menu

  1. Right-click with the mouse on the control you want to copy. If you want to copy several controls, select them first before right-clicking with the mouse.

  2. Select Copy or Cut.

Start of instruction setTo paste controls in the preview area via context menu

  1. Right-click with the mouse at a valid position.

  2. Select your preferred Paste operation from the context menu.

Controls with visibleprop

When defining a visibleprop for controls, this means that the control is only visible when at runtime the value is set to TRUE. Responsive controls are shown in the HTML preview even if they have a visibleprop.

Customizing the Selection Highlighting

When a control is selected, it is highlighted with a specific style in the preview area. For the HTML Preview you can customize the highlighting style.

Start of instruction setTo customize the highlighting style

  1. Open the style sheet that you use for your page layouts in the Style Sheet Editor. The default style sheet is the CIS_DEFAULT.css.

  2. Select the Style Details tab as shown below.

    graphics/ad-layoutpainter-previewstyles.png

  3. Customize the preview* styles according to your needs.

    Preview Variable Description
    previewSelect Style for selected controls.

    Note:
    The selected active control has the style previewActive.

    previewActive The active control, for which the properties are shown in the property view.
    previewDragOver During drag and drop, controls are highlighted when the mouse is dragged over the control.

Resizing Controls in the Preview Area

In SWT Preview mode you can set the width and/or height of a control directly in the preview area.

Start of instruction setTo resize a control in the preview area

  1. Select the control that you want to resize.

  2. Move the mouse pointer over the dashed border of the selected control.

    The mouse pointer changes, indicating that you can start the resizing.

  3. Press the mouse button and drag the border until the control has the desired width or height.

  4. Release the mouse button.

Viewing the XML Code

When creating the layout, you can view the currently defined XML code at any point of time.

Start of instruction setTo view the XML code

  • Choose the XML tab which is shown at the bottom of the Layout Painter.

    Information such as the following is shown:

    XML layout definition

    Note:
    The properties which you leave blank in the Properties view are not shown in the XML code.

Saving the Layout

When you save the layout, all of your changes in the Layout Painter are saved.

When you save the page layout or build your project, errors and warnings are shown in the Problems view, which is a standard Eclipse view. An error occurs, for example, when a value has not been set for a mandatory property. When you click an error or warning, the control containing the error is selected in Layout Painter.

When you save a layout for the first time, an HTML file is generated (in addition to the XML file) which is placed into the root directory of your application project. This HTML file is updated each time you save the layout.

For NATPAGE layouts, the corresponding Natural adapter is also generated.

Note:
When you save the page, the preview area is automatically updated.

Start of instruction setTo save the page

  • Use the standard Eclipse functionality for saving (for example, CTRL+S).

Viewing the XML to HTML Generation Log

You can display information on the controls that have been written to the generated HTML page.

Start of instruction setTo view the log

  • From the Ajax Developer menu, choose Show Log.

    A dialog appears. For example:

    Log

Layout Tester

The layout tester can be used to test the currently defined layout according to the display mode which is defined in the properties of the project: it is either shown as in the browser or as in the SWT client.

Start of instruction setTo invoke the layout tester

  1. Select the layout in the ProjectExplorer view or in the Natural Navigator view.

  2. Invoke the context menu and choose Open With > Layout Tester.