Build Pages with the Page Designer

Once you have setup a project the next task is to create some content, and this means adding pages to you application. Aria includes many advanced features for editing pages, forms and other content for you rapplication, but this chapter gives a flying overview of the main features of the editor.

The role of pages

Pages are one of the main the building blocks of a Aria application and in most cases they tie in closely with the lifecycle and navigation of your applications main elements. Pages are designed to help you lead through the story (or more prosaically, the workflow) of your application, but pages are still quite flexible and not so strictly tied to the navigation that they restrict how you present your information, and later we will see how the role of pages is affected by the application style.

Creating a new page

Once a project has been created you can use the New Page Wizard to create a new page. The wizard is very simple, just taking the name of the new page as an input. If you are using the Files view within NetBeans then you can right click on the `pages' folder and choose the New Aria Page... option.

Once the new page has been created it is opened in the page designer.

Opening the page

The pages created by Aria are inserted into the pages folder, and this folder is automatically added to the project classspath. New pages are automatically opened, but existing ones can be opened by double-clicking on the page file or by choosing the Open option from the node's context menu. By default the page opens as a standalone page, but it can also be opened in the context of the pages named by the frameset, by choosing the Open in frameset command.

On Eclipse the behavior varies slightly and initially the default action when double clicking a page may be to open the page's XML in the default text editor, however once the page has first been opened subsequent double clicks will open the Aria page designer. Eclipse users may also have to open the AriaEditor perspective before all features of the page designer are available (see the Window|Show View|Other option).

Pages must belong to a project and normally a page can only exist or operate within the context of its project as the project provides access to the resources used by the page. Therefore to successfully use a page the owning project must first be opened, and to ensure this relationship is maintained Aria will open the project whenever you first attempt to open a page within a project.

For an overview of the main elements of the page designer please see .

Opening the page in a frameset

A page can also be opened as an element of the frameset (the content/center element) by choosing the Open in frameset command from the page node's context menu. When the page is opened in this way the page will be viewed as though the frameset devides the main window into named target areas that can be controller by the page manager. This editing mode assumes that the frameset is being used as part of an SDI (Single Document Interface) application even though the frameset can be used for other application styles.

Can should be taken with this editing mode it the pages referenced and opened by the framset are already open in other page designer windows. There will be a single instance of any page edited within the page designer and if the same page is opened in multple instances of the page designer then the changes made in one instance will affect the others (in fact the page being edited is just shown in the other instance of the designer once it becomes active).

The image below shows the Welcome page being as part of the frameset, in this case in the center of the frameset.

Preferred page size

If a page is bein used within a frameset it is not tied to any particular target area within the frameset and the application can instead chose to show it in any area. However, in practice the page will usually be shown in specific area and at a specific size. Some layouts can accomodate radical resizing depending on the content but for many it is useful to know the size that will be used for the default layout. By right clicking on a page's node you can choose the Preferred page size... option and set the default size for the component.

The dialog allows you to choose the area to use for the page based on the areas assigned by the frameset. Note that the application area is normally larger than the sum of the sizes of the pages held within the frameset as the application also includes decorations like borders and headers. Also not that even including the size consumed by headers and borders there may be some deviation if the application's end user has setup their computer with larger or smaller than normal fonts as default (this affects the header size) or tweak the operating system's user interface in a variety of ways. Using layout managers rather than absolute layout will help overcome the poblems caused by such differences between systems.

Adding components

Once the page has been opened for editing, adding components is straightforward. The component palette at the top right contains icons for most of the components that can be added to your application. If Aria is installed you will see two pages of components (two tabs) and you can also register new components or third party components for use in Aria (see See Working with components.).

To add a component, just click on the icon corresponding to the component you want to add, move the mouse to the point on the page where you want to insert the new component and click the mouse. The new component should be inserted at this point. If you do not recognise the icon for a component just let the mouse hover over the icon for a moment and you should see a tooltip telling you what type of component is represented by the icon.

If you have already added components to the page you may also be able to add component as children of existing components. Some components like panels and scrollpanes act as containers for other components, so to add a child to such a component just click on the container into which you want to insert your new component instead of the page.

Selecting and sizing a component

A component can be selected by clicking on the component, and multiple components can be selected by holding down the CTRL key while clicking on the components. (Only the common properties will be displayed in the property sheet)

A selected component (or components) can be moved by dragging it to another part of the page. The selected component can be sized by grabbing and dragging one of the selection handles.

The movement and positioning of the components will be affected by the grid and snapping properties of the page designer. You can access these propeties by right clicking on the page and selecting the appropriate options from the context menu.

If any of the snapping options are selected the components will snap to the appropriate positions so as to match the snap options. The arrow keys can also be used to move the components and moving the components with the arrow keys also honours the snapping properties of the page designer.

If the arrow keys are being used to manipulate the components holding down the CTRL key while using the keys cause the component size to vary instead of the position.

Sometimes the snapping options will make the components seem to stick to a particular position. A short sharp movement usually frees the component, but as an alternative you can type the coordinates or sizes directly into the component's property sheet to manipulate its position and size.

Equally, when dragging a component the size of the component may vary so that its edges honour the page designer's alignment properties, but when the component goes out of range of the snapping zone its size should be restored.

Nudging a component

A selected component can be nudged or moved using the arrow keys. Movements with the arrow keys are still influenced by the snap settings, the grid options and the layout managers and therefore using the arrow keys to nudge a component will lead to its size and positions being updated which can be desireable when properties have been changed via the property sheets.

Aligning components

The page designer properties also include the option to have components Snap to siblings so that components align with one another. When using this option and dragging components about the form alignment hints are briefly shown to indicate how one edge aligns, or snaps to another. When aligning edges the page designer attempts to allow for the operating system's recommendations for component spacing.

Setting up guides

Supplementing the snapping options are guides, which can either enforce layout considerations or merely act as a layout aide. Guides can be setup interactively once the designer has been placed into the edit mode, by clicking the button at the junction of the horizontal and vertical rulers. When in the mode the rulers change color.

In the (guide) edit mode, clicking on a ruler and dragging the mouse onto the page will add a new guide to the page. Equally a guide can be deleted by dragging it back to the ruler.

Further setup options for the guides can be configured by right clicking an individual guide and choosing Guide options... There options are covered in more detail in later sections (see See Guides.). You can also add columns and rows for regular form layouts by choosing the Setup columns... option.

Once the guides have been added you can select the Snap to guides option so that moving the components will snap them to the nearest guide within the snap zone. Setting this mode is not necessary if you wish to use the guides as a visual indication only. To exit the guide edit mode, again click on the button ath the junction of the rulers.

Layout managers and constraints

The final factor influencing the layout of components is the use of layout managers. Layout managers automatically adjust the size and position of a component when its parent has been resized. Each container (page or panel etc...) can have a layout manager, set via the property sheet for that container, and in turn each component can have layout constraints should the parent use constraints (some don't). For more information on how layout managers are used see See Layout..

In the context of the above overview of moving and sizing a component it should be noted that a layout manager will trump any of the above features and layout the component as it sees fit. Of course Aria's own layout managers may respect the positioning defined with the page designer, but this behavior varies from layout manager to layout manager.

Setting properties

When a component is selected the properties of that component are shown in a property sheet to the bottom right of the page designer.

Once the component properties are listed in the property sheet they can be set by clicking on the property value. The property can then be edited. Some properties will display a list of appropriate values from which you can select, whereas others will allow you freely enter a value of your choice. Editing of a property is normally completed by pressing the enter key, or by selecting another property or component. Once the new property has been entered the component is updated.

In-situ editing

For conveniece, a property sheet can be shown next to the component under the cursor. This mode of editing properties is known as in-situ editing. The in-situ editing mode can be changed by toggling the mode using the toolbar toggle button. The mode can be turned on and off, or a full property sheet, a cut-down mode can be shown.

Just as with the property sheet you click on a property value to edit that value. The in-situ editor follows the cursor after a short delay, so some care may be needed when moving the cursor from the component to the in-situ property sheet, but after some experimentation it should save you some mouse clicks and cursor movement.

Normally the page properties do not show in the in situ editor as they would constantly get in the way of normal editing, but the page properties can be displayed in the in situ editor by moving the cursor to the top left corner of the page while holding down the CTRL key.

Similarly, the in situ editor normally masks components beneath the editor to avoid unintentionally selecting other components while trying to edit a components properties. However sometimes it is desireable to select a component that is obscured by the in situ editor, and to do so hold the CTRL key down while moving the cursor.

Quickly setting the content

Another useful labour saving shortcut is to double click a component so that the editor for the default property is displayed. Typically the default property controls the content or text displayed in the component, or else the component name.

Styling a component

Components can be styled in a number of ways and depending upon the individual component there may be one or more styles. Like any other property the styles can be set using the property sheet or with the in-situ property sheet. AriaEditor also includes a style palette, located in the same area as the property sheet (but on the tab marked `Styles' ).

To set the style using the style palette select a component or components and double click a style within the style palette. The styles (mostly the colours and fonts) associated with the style are applied to the component. If the style is changed at some later stage then the component will be updated to reflected the modified style.

New styls can be configured by right clicking on a style in the style palette.

Delete, Cut, Copy and Paste

You can delete, cut, copy and paste components using the normal keyboad shortcuts, and by right clicking and choosing from the context menu. When components are cut and pasted they can be inserted multiple times. The insertion point is at the cursor position.

As the components are added they are renamed to avoid a name collision. Components can also be cut and pasted between panels and pages.

Locking components

Components can be locked so that they are not moved or modified accidentally. To lock a component right click on the component and choose lock from the context menu. The component can also be locked by choosing the component within the Component Inspector and using the inspector's context menu.

When a component is locked using the Component Inspector its children are also locked, and therefore a combination of the two context menus can help you quicked toggle the locking status of a hierarchy of components.

Hidden components

Components can be shown or hidden usisng the Visible property via the property sheets. Of course an invisible component cannot be selected in the normal way within the page designer, however the component will still be listed in the component inspector and selected via the component inspector, and once selected the component properties can be changed via the proeprty sheet.

Hooking up code

A page layout without code and functionality is little use and therefore the property sheet lists the events that can be associated with the selected component.

Adding an event handler is simply a matter of inserting the name of the event's response handler method in the property sheet. Once the value has been entered, the Java source code for the handler is inserted. Under the hood, the Aria framework takes care of the event handling plumbing.

In some cases you may not want to add a new event handler, so instead you can select the existing methods as the event handler from a list of methods shown in the property sheet.

Inserting predefined code

Within the source code editor you have access to all the normal code templates available within the IDE (be that NetBeans or Eclipse). In addition to the templates the source code editor's context menu include the Run Aria helper... option. Choosing this option pops up a dialog that lists some common Aria code fragments (this list can be extended).

Working with data

Aria supports many data formats and data source (including customized datasources) and the Aria plug-in allows for easy setup of the data sources and the data bindings that will be used to channel data into the on screen components.

Setting up a database table

Within NetBeans the Runtime window allows access to servers and other runtime resources. To setup a database within the Runtime view, first open the view from the Window menu and right click the Databases node. Add a database, following the instructions provided by the IDE. Even if you intend to use a standalone database like HSQLDB it is worth setting the database in server mode so that you can make best use of the tools provided by the IDE.

Once the database server has been setup choose the Aria | Visualization | Show the data visualizer view to open the Data Visualizer . Once open you can drag and drop tables from the Runtime | Database to the Data Visualizer to register the table and configure it for use in standalone application. A project must be open before the visualizer can be opened.

Setting up POJOs

TODO insert screen shots of setting a data binding

Setting up static data

For some nodes you can configure the data model as you go within the visualizer (you can also do this at runtime). The data visualizer includes toolbar buttons to allow you select the paths and to add or delete nodes. See Data binding. for more detailed information on using and managing data bindings.

Binding

Once data is available in the visualizer you can use it in multiple ways. The simplest way of setting up a binding is to drag and drop a node to the component to which it will be bound. Using drag and drop in this way fully configures the bindings.

For some types of nodes and some types of data a popup dialog may appear requesting further specification of the data binding attributes, for instance specifying the field to display in a drop down list or combo box.

Alternatively you can copy and paste the data path so as to later insert it in a data binding specification or path.

TODO insert screen shots of setting a data source

TODO insert screen shots of setting a data binding

Working with validations

TODO insert screen shots of setting a data source

And now for the XML

At times you may wish to work with XML directly, or use features that cannot be coded directly with the page designer and therefore the XML is just a click away. The page designer's toolbar has a button marked XML , which when clicked shows the XML editor.

You can switch back and forth between the XML and the Design view of the page designer at any time and the views are updated in the process.

Working with included pages

An advanced feature of Aria, that we will see more of in later chapters, is that one page can be included in another. The page designer offers some support for this, allowing you view and edit pages that have been composed in this way, however the editor does not yet allow you to choose which page a new component will be belong to. Instead the page designer uses the component hierarchy to decide what components belong to what page. Therefore the children of a component such as a panel belong to an included panel will themselves belong to the included panel.

Saving

Finally, your edits need to be saved and this can be done on a page by page basis using the normal File | Save menu action, or all edits can be saved at once using the File | Save All menu action.

Modified pages or resources are shown in the Files or Project view with a red dot or with an asterisk. When saved the dot/asterisk should disappear.