How to use ProjectAssistant

What is ProjectAssistant?

A warning before you read further:ProjectAssistant was made for developers that know what a commandline is, how to use Ant and are not afraid to edit an Ant build file. It is not a wizard-style tool nor a GUI for end users but helps experienced developers to improve the organisation of their project sources.

To help development of projects using betterFORM XRX we developed a set of Ant targets that make it easy to setup and maintain your project sources and keep them separate from the betterFORM sources. Main goals were:

quick and easy setup of a project using betterFORM XRX

separation of project sources and betterFORM sources

easy upgrading to a newer version of betterFORM

easy deployment of your XForms and resources

allowing to use your own versioning system to track your project changes

Requirements:

Java 1.5 or higher

Ant 1.8.2 must be installed on your system

Setting up a project

Create a new directory for your project and place the build file inside that.

Open the build.xml and edit the property ‘betterform.version’. You can choose any tagged version that is available from Github. The value of this property will default to the latest stable tag. So if you want to use the latest version you can skip this step.

Choose a name for your project and set it by editing the property ‘xApp.name’. Save your changes to the build.xml.

Execute ‘ant prepare’. This will download the correct versions of eXist and betterFORM and create a directory structure as shown below.
Please note that you’ll need to execute this only once at the beginning of a project.

Now you are ready to develop your XForms, XQueries and other resources that make up your XRX application and put them below the src/main/XRX directory. If you browse the directory structure you’ll find some sub-directories below ‘XRX’ that provide a template structure you can use to organize your project. The template structure is a mere convention which has evolved over time and was proposed by Dan McCreary the father of the XRX architecture pattern. You can change and adapt this structure freely to fit your needs.

Deploying your XRX application

To deploy your XRX application simply call ‘ant deploy’ from the command line. This will copy the complete structure below ‘src/main/XRX’ to the collection ‘/db/YOUR-APP-NAME’. Please note that the database must be running. There are two Ant targets that allow to start and stop the database server which are named ‘start’ and ‘stop’.

Creating your own installer

You can create a customized graphical installer for your application like the one betterFORM is using for its own installation. This will allow to install the complete XRX application in a comfortable way.

To create the installer do the following:

Change to the ‘installer’ directory in your projects’ root directoy,

Execute ‘ant -f build-installer.xml’.

The resulting installer will be in ‘PROJECT_ROOT/installer/target’ with the name ‘APP_NAME-install.jar’. This is an executable jar file that can be run on any system that has a Java 1.5 runtime available.

Upgrading the betterFORM version

To upgrade your project to a newer betterFORM version:

edit the build.xml and change the property ‘betterform.version’ to the new tag you’d like to use

save your changes and optionally change your applications name to reflect the version change

execute ‘ant clean-all prepare’ to download the new betterFORM version.

Please note that this will delete the local copies of eXist and betterFORM and start with a fresh download of those resources.