11 Projects
Carousel applications are organized into projects with a well defined structure. The project acts to organize and coordinate the project and its resources. At both design and run time the project plays a crucial role in the behavior of the application. To help you better understand this behavior we have included an overview of a project and what it does for a Carousel application.
A project's role
A project is a collection of the resources used in an application. The project object within a Carousel application manages these resources and provides many facilities for loading and storing resources.
As many of the components in a Carousel application are loosely bound to one another some coordination of these otherwise disparate resources is required. The project therefore acts as a central coordinating resource and in programming an application the project is often the first place to look when trying to reference a component of the application.
Carousel projects also act as a way of ring-fencing the resources used by an application and the application context. The idea behind this is that you could have multiple projects running with a single JVM and you would therefore need to manage the resources of each project separately.
Originally XUI had used singletons (classes containing a static self reference) to provide easy access to key resource classes such as the XStyleManager that one might want to access in a great variety of places. While the singleton pattern made it easy to access these resources it greatly complicated initialization and the project lifecycle, never mind making it difficult to handle more than one project at a time. XUI 2.0 did away with the singletons and now all major objects are owned by the individual projects and ultimately by the project manager. The stricter hierarchy that this imposes makes managing an application somewhat easier and makes initialization clearer
|
.
Project setup
A project file is the key to a project. Carousel's project files are contained in the root of the project and have a .xui extension. The file is an XML file, but fortunately Carousel provides an editor for all the project's settings:
The editor is displayed automatically whenever a project folder is opened. The project also manages access to a number of folders. Each folder contains a distinct type of resource. Here is a summary of those folders:
Table 11-1 - Project folders
|
|
|
|
|
Stores the XML page descriptions
|
|
|
Stores the language files used for translation of the application.
|
|
|
Holds various resources used in the project including graphics, configuration files and so on.
|
|
|
The source code for the Java classes is held in this folder. Another folder (classes) may also be created depending on the configuration. The classes folder is a temporary folder and may be deleted at any time.
|
General setup
When the project initially opens the setup page of the project settings is displayed.
The settings on this page are general initialization and project description settings.
These settings can be configured at any time in the life of the project, but of course they may affect the runtime behavior. For example it is possible to switch widget sets but doing so may affect your business logic code if you have done something that specifically references an individual widget set. Similarly resizing a page to a smaller size may result in components not being visible to the end user.
If there is a problem you can always revert your settings to the previous values and your setup should be restored.
The properties on this page are:
Table 11-2 - General properties
|
|
|
|
|
This is the name by which the project is identified within Carousel.
|
|
|
The title of the application. The title is displayed on the application title bar at run-time for a normal application. Some applications do not display a title bar.
|
|
|
The width and height of the page. The application frame is adjusted so that the pages are the size specified here. The drop down provides a short-cut to some common sizes and the edit fields allow more precise adjustment of the size.
|
|
|
Check this option for the application to start-up in the centre of the primary display. Otherwise the application will start in the top left of the display.
|
|
|
Check this option to use a popup window. The option can be useful for creation of full screen like applications as no border or title bar is displayed. The option may also be of use for applets where it is not intended that the applet is to appear 'embedded' within the html page.
|
|
|
Carousel applications can run with a number of widget sets and the framework provides a certain level of isolation from the specifics of the widget set. You can use this option to choose or switch widget sets. Support for other widget sets is available outside of the editor.
|
|
|
You can select the page to display when the application starts using this option.
|
|
|
Specify the default package name for your application code here. The package name should follow the normal Java package naming conventions.
|
|
|
Carousel provides a logging facility for you applications when they are run with debug libraries. Various levels of verbosity can be chosen. The log is often the first place to look if you encounter problems when running the application.
|
Frames setup
Carousel supports the notion of framesets much the same way as HTML does. Frames are subdivisions of the screen or more precisely the applications client area. The frameset divides this space into several target areas with each target area containing a page. The target areas can be updated by displaying new pages within one or another.
It is entirely up to the individual application how these frames are updated. If no target area is specified when displaying a page the default content target is updated.
The content of some targets can be long running to provide application wide facilities such as navigation panels, headers and footers. An application need not employ a frameset.
The frameset is based on a border area and the editor page visually reflects this setup. Each of the areas can be named and a size can be suggested for the area. At least one target area must be included and normally this is the content target.
Files Setup
Rather than try to shoehorn everything into one configuration file Carousel uses a main configuration file, the project file to direct the framework to individual configuration files for particular elements of the project. These configuration files are identified on the file page.
Each configuration file can be located by clicking on the button next to the edit field to popup the file chooser.
The list of files is not exhaustive and as we will see later there may be more configuration files needed for some projects. Most of the configuration files are optional so it is not fatal if you are missing one or another. The system will attempt to load a default if one file is missing and any difficulty is logged.
The individual files are:
Table 11-3 - File settings
|
|
|
|
|
The style file contains information about the colours and fonts used within an application much like cascading stylesheets are used for HTML. By default the style file is located in the resources folder and is called styles.xml .
|
|
|
As mentioned above an application can optionally use a frameset. The frameset configuration is saved to the file specified here. If no frames file is found then it is assumed that the application has a single content area called content . The default frameset file is frames.xml and it should be found in the pages folder.
|
|
|
Carousel applications include a rich data model. The data model can be configured in a wide variety of ways with various data sources contributing to the overall model. Loading of the data model is initiated by reading of the model data configuration specified by the file name here. The default file is datasets.xml and it is normally placed in the resources folder.
|
|
|
Validation rules are rules that specify what is valid data, they constrain the user input to particular ranges of data that is at first glance acceptable to the application. The validation rules are configured via the validations file specified here.
|
|
|
The look and feel of the application only requires a choice of files if the Synth look and feel is employed.
|
Extensions setup
Carousel offers numerous extension possibilities an some of these extensions can be configured here.
The most common extensions, adding a component factory, adding and data binding factory and adding a validation factory can all be configured here.
The add option allows you to select the class that implements the appropriate extension.
It is worth noting that Carousel now includes a facility to register components via XML so you do not need to build a custom component factory to use additional components. The component factories are covered in detail in later chapters.
Extra setup
As an extensible framework it is difficult if not impossible for Carousel to know all the configuration parameters in advance. Therefore we have provided a generic facility to specify project configuration parameters.
The Extra page provides a table where you can add, remove and edit project settings. These settings are persisted to the project file.
Extensions can install additional parameters and third party configuration parameters are likely to appear in this list. Carousel itself uses this facility for some of its optional parameters and you will see this project editing facility referenced in later chapters.
Services provided
From a programming perspective the project provides the following services:
File access
Image loading
Startup parameter management
Resource management
Pages
Styles
Images
Data model
Classpaths
Carousel tries to simplify access to resources and therefore the project sometime needs to search several possible locations to find an individual resource. At it simplest a Carousel project normally refers to:
The project root,
The pages folder,
The lang folder,
The resources folder,
The Jar classpaths
The project can be accessed through the XProjectManager class which provides a static accessor:
Table 11-4 - Locating a project
XProject currentProject = XProjectManger.getCurrentProject();
|
This manual refers to the project on many occasions and this serves to highlight the pivotal role that a project has in managing a project. As mentioned above, when developing code within a Carousel application the project is also often the first place to look when trying to find a particular resource.
As of XUI 2.0 the XPage class includes a reference ' project ' to the current project so the above code may no longer be necessary in most situations.
If you were logged in you could rate this article or add a comment.
;)
;)
;)
;)
;)
;)
;)