You are hereAria User Guide / Section II: Introduction / Getting Started
Getting Started
In this chapter we will see how to build some simple Aria applications using both Java and XML. We will see all the features needed to build a fully functional application within Aria in action. The chapter provides an introduction to the setup mechanisms used within a Aria application. Most of the features described can be configured interactively but to aid understanding they are explained at a lower level.
The chapter assumes that you have already encountered the features described in the previous chapter and that you have a basic understanding of how Java based applications function.
Don't worry if you do not understand all the nuances of the technology described as the various pieces of the application are but together. Later chapters are devoted to the individual features employed.
If you are new to Java we recommend that you study some of the numerous educational resources available on the Internet, some of which are listed in the appendix on Java.
Hello world
Traditionally the first example used in many user guides is the infamous 'Hello World' example where the task is to emit or display the simple text 'Hello World'. In Aria this is very simple, all you need do is create an XML file called 'home.xml', preferably in a new folder. The XML file contains the declaration of the user interface needed for this task. It looks like the following:
Page user-interface declaration
And that's just about it. The only other thing that is needed is a convenient way of starting the application. To do this we create a startup command file. This command file doesn't have to do very much other than invoking the Java environment and telling it what class to start. The start class in this case is the entry point to the Aria framework or library. It contains the following command:
Command-line startup
The AriaRuntimeCommon jar is the minimum level of library support that can be used with Aria. It is a version of the Aria core compiled for early JDKs (including the Java environment embedded in Microsoft's Internet Explorer).
To use a fuller more functional JDK, for example to access the Swing toolkit instead of the AWT simply change the startup file to use this command:
Command-line startup for Swing
Running this command will create a Swing user interface (UI) for the application. The two versions of the application should look pretty much the same.
This little example immediately shows a number of the benefits of Aria and XML. Most obviously the UI declaration is very small and compact. Consider all the code needed to get such an example up and running in many languages. Secondly the approach of separating the UI declaration from the implementation makes it easy to switch that implementation, as shown above in switching from the AWT to Swing toolkits.
Hello world redux
Another much touted benefit of Aria is its close integration with Java and the ability to declare the UI in XML or in Java. To emphasize this let's see how we can build the same thing in Java.
This time instead of creating ' home.xml ' we need to create a Java class. Using the normal naming conventions and capitalization we will call this class ' Home.java '. The Java code needed is as follows:
Java UI class
Now while this isn't as compact as the XML declaration it is nonetheless a little more compact than the traditional Java code used for such an example.
To run this example there is of course another step required, that is, to compile the Java code. This can be done from the command-line, in the root directory of the project. Just type the following command:
Command-line startup for compilation of the Java class
This should create a file called ' Home.class ' in the same directory. The application can then be run in the very same way as the XML version. The underlying Aria will try loading an an XML file in preference to a Java class, so if it finds your XML file first then that will be used instead of the Java class even if the two files are in the same folder.
Beyond HelloWorld
While the HelloWorld examples offer a minimal way of getting started with Aria it is not normal. Aria can use many different resources and settings to configure and run an application. The HelloWorld examples relied on default settings for most of the Aria configuration.
Normally Aria applications are configured via a startup properties file. This file can be specified as a command-line argument:
Command-line startup using a startup properties file
Or, if no command-line argument is provided Aria will look for ' startup.properties '. (And remember that the startup file is regenerated by Aria whenever an application is saved. Aria itself uses a file project.aria to store the properties that are written to the startup.properties file).
It is also useful to separate the various components of an Aria project into separate sub-directories. Thus the XML declarations for pages are put into the ' pages ' sub-directory, while the Java source files are places in the ' src ' sub-directory. Other resources such as images are placed in the ' resources ' sub-directory and finally localization files are placed in the ' lang ' subdirectory.
When using Aria (as we will see in the next chapter), a special class/resource loader is built-in and can locate files in these subdirectories without the need for them to appear on the classpath.
The startup file contains settings that control much of how Aria is configured. Some of the more commonly used configuration settings are shown below and could be used for the HelloWorld example.
Startup properties
The purpose of these settings is as follows:
|
Startup parameter |
Usage |
|---|---|
|
CentreWin |
(true|false) Centers the application window on the screen when set to true. |
|
ClientHeight |
Set the height of the application window in pixels. |
|
ClientWidth |
Set the width of the application window in pixels. |
|
StartClass |
Sets the name of name of the initial class or XML file to display. |
|
StartPackage |
Sets the name of the package used for this application's Java classes. In the case of the HelloWorld examples no package was used so this setting could be omitted. The above example indicates that Aria should look for a class called 'aria.projects.helloworld.Home.class'. |
|
UseWindow |
( true|false ) Tells Aria to use a Window without a border or use a normal application frame to hold the application. |
|
StyleFile |
Points to the name of a style file used to configure the colours and fonts in the application. |
Building a simple address form
Most applications require user interaction and some data capture. Typical of this is entry of user details including name, telephone numbers and addresses.
This example goes beyond what was used in HelloWorld and shows some of the major steps in creating an attractive UI. We will start by creating a very simple form and then we will apply some style information to improve the look. In later sections this example will be expanded to produce a fully working, full featured form.
To start with we need a declaration of the input fields needed to capture the user input. We will use XML for this, and at its simplest this looks like the following:
An address form/page declared in XML
In the above declaration the Label fields are all right aligned and the edit fields are all named. We name the edit fields as later we will want to interact with them programmatically.
This form is basic and does not include any formatting specific to any region. The address is comprised of three lines whereas most applications would further customize addresses for things like post or zip codes. We leave such customization as a user exercise as it will not affect the overall behavior of the form.
Note also that the form is laid out using absolute positioning and that in general it is better to use layout managers for the positioning of components (again, this will be covered in later chapters).
Generally the order in which the components are declared is of little importance, but it is in this order that the components are added to the container and therefore this dictates the z-order of the components. The z-order may be of interest if components overlap.
Applying style
To improve the appearance of the form we apply some styling information. This style information simply consists of the name of a style to use when rendering the component.
Aria includes a style editor for interactively setting up the colours and fonts that comprise styles. These styles can then be interactively applied to a component or alternatively the styles can be applied via the Java code as the application executes.
The style details are stored in an XML file pointed to by the startup parameter ' StyleFile '. In the absence of a file name the files ' styles.xml ' is used. A typical style file includes colour and font information as below:
A typical style file
Styles are determined from this hierarchy so that in the above example the style ' CaptionSmall ' is of the same font and colour except with a smaller point size and italicized.
To apply a style to a component you just need to reference the style in the page's XML declaration. Thus applying style to the labels the above address form becomes:
An XML page using styles
Validating user inputs
When a form's data is eventually processed it helps if the data is appropriate for the intended process as much error checking can be eliminated. It also helps if the user is informed about input errors as early as possible.
Aria provides several levels of input validation. Firstly some of the input fields, like edit controls can be configured to accept a limited range of inputs (numbers, dates, passwords) and secondly the input can be validated using declarative validations.
Validations are rules that are applied to input fields. Aria takes the approach that these rules are reusable and therefore the validation rules are declared separate to the UI. The startup file is used to point at the validations declaration or by default a filename of validations.xml is assumed. Some examples of the validation rules are:
A validation rules file
The exact content and attributes of the rule depend on the type of validation being configured. The first example shows a min-max rule and specifies the limits for the range. The second and third examples are simple checks for the presence of an input value, a mandatory or obligatory value. Each of the examples includes a message that is shown in case an error is detected.
Validation rule checking is triggered whenever an input field loses input focus or when the user attempts to change the page or navigate to another page.
Of course the rules have to be assigned or attached to the appropriate input field and this is done in the page's XML file. For simplicity we will just assign the name checking but the complete example contains a fuller set of input validations. Thus the page becomes:
An XML page using validation rules
Using data
A form like the address page can not only be used to capture data but it can also be used to edit data. Aria includes an extensive data model that allows the UI to be separated from the data so that the applications logic need not know how to get, set or maintain values in the UI. The Aria data model is also an abstract hierarchy and can be referred to with expressions. Furthermore the application does not need to know how the data is actually stored as the model will assign storage as needed. Thus the application need only specify where to store the data in the model, for example the address form can be modified to store its edit values in the model.
The figure above shows a typical situation where data is transferred from page to page without one page needing to reference the other directly. Instead the pages refer to the data in model and they are thus less dependant on one another. In the same way the application code can refer to data in the model and the code can even update the data used by the two pages. Again the code is not dependant directly upon the user interface pages.
Normally the links between the components on user interface pages are declared as data bindings.
An XML page binding data to the user-interface components
Aria will automatically update the form so that it displays the data from the model whenever the page is displayed. Aria will also save the data automatically whenever the page goes out of context.
An application has also programmable control over the model and its interaction with the UI. Bindings can be changed and can be made to dynamically point to other locations, but that will be covered in more detail in later chapters.
The data model can be primed with data by configuring a data source via the startup file. The startup file can name a datasets file (datasets.xml by default). The datasets file in turn points to individual data sources. For example datasets.xml is often configured as follows:
A sample dataset reference
The data source name doesn't have any great significance, but the filename attribute points to the actual data. For this address form example the data might appear as follows:
A sample dataset
This sample data will populate the address form when the form is first shown.
Responding to events
So far we have covered the UI declaration, the validations and the data model but all of that is of little benefit unless we can apply some application logic.
Aria relies on Java for its programming and at the core of this is the Page class. Each page in Aria must be derived from this class. Fortunately this is a fairly simple task.
To demonstrate how application logic can be invoked we will add a button to the form so that a new or next page can be displayed. First though we will create the stub of the page's logic code:
A simple Java class with an event handler
This class contains the stub of the next method that we will later fill out to implement the required logic, but for now we still need to connect it to the UI.
The first step in connecting the page to the new class is to change the XML page definition so that it refers to the class, thus the Page element becomes:
Referencing the Java class in the page's XML declaration
Finally we need to trigger the method in response to the button click event, or in AWT/Swing the action event. To this we add an event handler declaration:
Adding an event handler to the page's XML
The complete form now appears like this:
The complete form
Changing pages
One of the most common tasks in building an application is providing a means of navigating around the application and since the *Page is the basis of all pages in an Aria application the Page class provides methods for changing pages.
To show the second page we modify the 'next' method.
Implementing the event handler
This new code will cause the application to display a page called "pageTwo" whenever the next button is pressed. If the application was coded as above, then it would not be strictly necessarry as Aria 3.0 allows the shortcut of specifying the showPage(pageName) expressions directly within the event handler for the component in question - in this case a button. (Of course some implementation of this new page is required, but that is left as a user exercise).
- Printer-friendly version
- Login or register to post comments