Deploying a dev version to eXist

This document describes how to deploy an arbitrary version of betterFORM into eXist.

For developers that like to work with the latest and greatest features of betterFORM and eXist it is not enough to use the installer. Instead you’ll like to deploy some source code version of betterFORM and deploy it to some version of eXist.

Step by step instructions

Before you start please make sure that you have Ant 1.8.2 or higher installed! Older versions won’t work.

Step 1

Check out the eXist version you’d like to work with. E.g. if you’d like to use the trunk version of eXist use a SVN client to check it out to a local workspace or if you’re using the command-line please execute:

svn co https://exist.svn.sourceforge.net/svnroot/exist/trunk/eXist exist-trunk

Step 2

To build eXist you have to change into the root directory of your workspace and execute:

./build.sh (for Unix systems)

or

build.bat (for Windows systems)

This should create a working eXist binary for you. If you have trouble here you should contact the eXist-open mailinglist for help. Please see the eXist homepage on how to get help.

Step 3

Checkout betterFORM and build it. Do so by fetching the wanted version from Github by executing:

git clone https://github.com/betterFORM/betterFORM.git betterFORM

This requires that you have a Git client available and installed. If that’s a problem for you you can use the ‘downloads’ section on Github to download an archive of the sources. In that case you have to unarchive this archive into a directory of your choice.

If you want to work with a certain branch of betterFORM you have to execute:

git checkout [branch_name]

where [branch_name] is the branch you want to use. Please note that the main development activities of betterFORM are taking place on a branch called ‘development’. You can see all available branches on the ‘Switch Branches’ menu on Github.

Step 4

To let betterFORM know about your eXist workspace you have to change to directory ‘[betterform_rootdir]’ where [betterform_roodir] is the directory you have choosen for your betterFORM workspace.

Open ‘build.properties.xml’ in a text-editor and adapt the property ‘eXist.home’ to point to your exist workspace (e.q. <eXist><home>/Users/dev/projects/exist-trunk</home></eXist>) You must use an absolute path here. Save your changes. You only have to change this single property. All other eXist related entries are not needed for updating the extension inside of eXist.

Step 5

Build the betterFORM eXist extension. First change to directory ‘[betterform_rootdir]/XRX’. You have two Options to build the extension:

a.) build betterFORM as a jar that contains all classes and resources in a single jar-file. This will contain an optimized version of the JavaScript layer. To get the optimized version execute:

ant -f build-XRX.xml update-betterFORM

b.) build an exploded version of betterFORM that allows to debug JavaScript. This version will be build with:

ant -f build-XRX.xml update-betterFORM-exploded

To avoid conflicts switching from one mode to another will automatically de-install the other one. So if you started working with optimized mode and used option b. to install the exploded version this will automatically delete the jar-file from eXist.

Step 6

As last step you will have to update the betterFORM provided XForms.

To do so change to directory ‘[betterform_rootdir]” and once again edit the ‘build.properties.xml’ file.

Search for the properties ‘eXist.db.user’ and ‘eXist.db.passwd’.

Set eXist.’db.user’ to the user which should own the betterFORM content. If you have installed the within eXist provided examples the ‘admin’ user will already own them, so set this to ‘admin’. The ‘eXist.db.passwd’ property has to contain the password of the ‘eXist.db.user’.

For example:

<eXist>
   ...
   <!-- user name and password for the file storing tasks -->
   <db>
      <user>admin</user>
      <passwd>secret</passwd>
      ...
   </db>
   ...
</eXist>

If your eXist installation runs inside another context then ‘/exist’ you will also have to change the ‘eXist.context’.

For example if you run eXist in a root context  :

<eXist>
   ...
   <context></context>
   ...
</eXist>

Then run :

ant -f build-XRX.xml update-betterFORM-content

Now you are ready to start eXist and work with betterFORM XForms. Happy hacking.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Subscribe to the comments via RSS Feed


%d bloggers like this: