Numishare Themes

In order that a single deployment of the Numishare Github repository into Orbeon accommodate multiple projects, each with a distinct aesthetic style, The Numishare public user interface scripts (XSLT, Javascript, and CSS) must be symlinked into a Numishare Themes folder within the Orbeon apps folder, typically located at $TOMCAT_HOME/webapps/orbeon/WEB-INF/resources/apps. The resources folder may be abbreviated at 'oxf:/', a shorthand protocol within Orbeon. As a result, there is one installation of Numishare at oxf:/apps/numishare, which contains all of the stable XForms applications that power the Numishare backend, but also contains the majority of XSLT stylesheets in the public user interface. In the American Numismatic Society's production deployment of Numishare, there are additional branches in Github for each individual project, like OCRE and the Egyptian National Library. There are stylistic alterations in the CSS files for each of these projects, but potentially also changes to the default layout on the project home page or record pages.

Creating themes

The default theme is a symlink of the 'ui' folder at /usr/local/projects/numishare/ui.

1. Create /var/lib/tomcat10/webapps/orbeon/WEB-INF/resources/apps/themes, substituting /var/lib/tomcat10 with the appropriate $TOMCAT_HOME, if necessary.
2. Create a symlink called default sudo ln -s /usr/local/projects/numishare/ui default
3. If necessary, check out additional other branches of Numishare onto the server, creating symlinks to the 'ui' folder accordingly, e. g., sudo ln -s /usr/local/projects/ocre/ui ocre

Projects may be linked to themes linked in this folder in the Modify Settings page.

Optional: Create proxy for themes (necessary for different ports and/or HTTPS)

Because the theme URL had been hardcoded by presuming 'http' connections and Tomcat under port 8080, this has presented problems when attempting to run Numishare on other ports or secure HTTP. As of June 2017, it is now possible to edit a <themes_url> in the Numishare config file. This <themes_url> is the URL of the themes folder, and should end in a forward slash, as it is concatenated with the theme symlink discussed in the above section. In the event the theme URL should be set in the config, you may want to configure the theme folder to be available through ProxyPass without relying on the Tomcat port. First, ensure you have already enabled the mod_proxy in Apache.

Edit your relevant Apache configuration under sites-enabled:

    #Forward Numishare themes
    ProxyPass        /themes/ http://localhost:8080/orbeon/themes/
    ProxyPassReverse  /themes/ http://localhost:8080/orbeon/themes/

    <Location /themes>
        Order allow,deny
        Allow from all
    </Location>

Substitute ports and protocols as necessary.

The example elements in config.xml below will result in Numishare reading http://localhost/themes/ocre/* for images, CSS, and JS files.

<orbeon_theme>ocre</orbeon_theme>
<themes_url>http://localhost/themes/</themes_url>

Altering Numishare Public UI pages on a per-project basis

Numishare pages for the administrative and public user interfaces are controlled by the Orbeon Page Flow Controller (PFC). Default pipelines that apply to all projects are controlled by regular expressions in the PFC. Like the Apache server configuration, the PFC pipelines are processed in order, so project-specific pipeline modifications must be placed before the generic regex-based catchall pipelines. For example, the home page of PELLA may be modified with a pipeline for "/numishare/pella/" rather than "/numishare/[^/]+/". Most pages will link to a model defined by the XML Pipeline Language (XPL), but all will link to a view defined by XPL. The regex views contain relative paths to XPL files in the base Numishare installation (/usr/local/projects/numishare). These relative paths may be replaced with absolute paths (with the file:// protocol) for additional project files. It is important to note that paths within XPL files themselves are relative, so additional modifications may need to be made to XPL files within individual projects that are referenced by the view XPL in the PFC.

<page path="/numishare/pella/" model="xpl/models/config.xpl" view="file:///usr/local/projects/pella/xpl/views/pages/index.xpl"/>

See the ANS production PFC for more examples.