Basic collection structure

Intro

While the app was built with the possibility in mind to adapt it to different local needs and data structures, there is a default structure. While the app tries hard to figure out the correct structure by itself, this may fail. If you use a structure different from the default, you may need to adapt several scripts and keep that in mind when updating and upgrading.

Default Structure

The default setup install the app into the collection /db/apps/edoc of eXist. It contains the main HTML files and the everything else the app needs to run. It is also home to several subcollections:

edoc
 ├─admin
 ├─data
 ├─global
 ├─include
 ├─modules
 ├─resources
 ├─rest
 ├─schema
 ├─templates
 ├─(annotations)
 ├─(doc)

• admin, as the name suggests, contains a few scripts to help admins keep an overview of the projects within this installation (more are to be added in later versions).
• data is where the different projects go as subcollections. While it can be empty, it may contain start.xml and should contain wdbmeta.xml to give a global start page or set global metadata.
• global is where globally available or root level content is stored, e.g. index.html. This is the only place in the app root where users should (and need to) make changes
• include contains recent versions of related projects, namely the schema for wdbmeta.xml and a collection of XSL/XQuery functions to deal with strings (extending the normal XPath string functions).
• modules is where the main global scripts go.
• resources contains global resources such as default XSLTs, global CSS and JavaScript.
• rest contains scripts for the RESTful interface. While it is possible for users to change these scripts, it is recommended to instead add scripts instead of changing existing ones.
• schema contains schema files for global files other than wdbmeta.xml (currently, this is only config.xml).
• templates contains the rump HTML files used for the templating system. While it is possible to change these files, most changes can better be done by using project specific layout and functions. The standard files here may be overwritten by an update.
• annotation and doc are not in use yet but are to be considered 'reserved' as they will be used for internal functions in upcoming releases.

Except for global, there are no user servicable parts in these collections. All changes may be overwritten by an update or upgrade. Instead, use the configuration options and project specific layout and functions to adapt functions and layout to your needs. Should you really require a change in one of these subcollections, consider opening an issue instead so this can be changed to an option that can be set on a project or instance level.

Non-default structures

projects as subcollections of edoc

It is possible to deviate from the general structure. For instance, one might want to forego the data subcollection and store all projects as a subcollection within edoc itself. This is possible and should be recognized correctly by all scripts; however, as the main call to view a page is via view.html and an ID, this is not strictly necessary. Should you need it e.g. to maintain a stable URL for the source XML/XSLT/etc. files, consider using a reverse proxy instead, especially if you run into problems reading and displaying files.

different name than edoc

It is also possible to name the collection other than edoc. In fact, this feature will be put to use in a later release as part of the possibility to have both publication and workbench roles run on the same eXist server. All scripts should be able to figure out the correct name.

as a subcollection of db instead of /db/apps

This is possible, too, and should not require additional changes. If you run into problems with the URLs generated by the scripts, automatic resolution of the basic URL might have failed. Consider setting the appropriate option in config.xml

port 80 and/or no mention of 'exist' in URL

If you want to have a URL without port 8080 and the 'exist' part, so 'http://example.com/edoc/view.html' rather than 'http://example.com:8080/exist/apps/edoc', you need to adjust eXist's configuration. Depending on the way you deployed eXist, the port configuration can be found e.g. in the Jetty config files (e.g. tools/jetty/etc/jetty-http.xml). In eXist's main controller-config.xml change

<root pattern=".*" path="/"/>

to

<root pattern="/edoc" path="xmldb:exist:///db/edoc" />
<root pattern=".*" path="/"/>

and in exist-webapp-context.xml, change

<Set name="contextPath">/exist</Set>

to

<Set name="contextPath">/</Set>

If you cannot access the collection or any of the builtin apps, e.g. Dashboard or monex, the “portal” might be blocking Jetty’s /-context. Try editing tools/jetty/webapps/portal/WEB-INF/jetty-web.xml and change the context to something different than / or /exist, e.g. /portal. Most likely, Dashboard etc. will not be immediately accessible after the splash screen (which, on a production server, should not be a problem) but need to be accessed manually under $server/apps/dashboard/index.html. (see https://sourceforge.net/p/exist/mailman/message/35823429/)

Another way of doing this – and maybe a better one if this is available to you – is to use a reverse proxy to point to exist/apps/edoc. Depending on your setup, you may lose access to eXide or monex. To solve this, add the following to your controller.xql before any redirect that checks for html:

<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
    <forward url="/apps/eXide/" absolute="yes">
        <set-header name="Cache-Control" value="max-age=3600, must-revalidate"/>
    </forward>
</dispatch>

and alike for monex.

data collection other than data

No problems are expected here as the scripts should be able to figure out the correct paths. As with all the other cases, please report any issues you may find.