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
- Java 1.5 or higher
- Ant 1.8.2 must be installed on your system
Setting up a project
- Download ProjectAssistant.
- 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.
- ROOT-DIR - src - main - lib (Java libraries specific to your project) - webapp (standard web application directory) - XRX (root directory for XRX application that will be deployed to the db) - target - bf-src (directory containing all betterFORM sources) - YOUR-APP-NAME (directory containing your applications sources)
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.
You have to use a tagged version of betterFORM that is available from Github. You can see the existing versions by browsing http://github.com/betterFORM/betterFORM/downloads. If you’d like to use a version that is not already available as tag please feel free to contact us via the betterFORM users mailing list.