Wiki Integration

dunnleaddress edited this page Sep 30, 2014 · 38 revisions

To make it easier to customize the content and look-and-feel of your onebusaway-webapp installation, we provide a content configuration option that we call wiki integration. The idea is that you can point your onebusaway-webapp installation at a wiki or some other content management system, allowing you to control the various content pages that are included in the webapp.

OBA deployments have used XWiki so far. Once you have a new XWiki instance set up, you can then import the existing OBA XWiki contents via an XAR backup file of the Puget Sound instance, available here on Google Drive. Note that you can either use a stand-alone XWiki install, or deploy an XWiki WAR inside Tomcat. Some feedback has indicated that Tomcat may be a more stable option.

IMPORTANT - When importing this OBA content in the standalone XWiki server with XWiki v4.2 Enterprise, , its important that you DO NOT import the "XWiki" directory (i.e., Uncheck the "XWiki" directory during the import process). Otherwise, this will interfere with your current XWiki installation by altering some of the main administration pages. It is recommended that you only import the contents of the "Main" folder. Note that XWiki v5.1 deployed as a WAR in Tomcat appears to have a different requirement - you MUST install the entire backup package, including the "Main" folder. In xwiki 6.2.1 I imported package "OneBusAway Puget Sound XWiki Export - nbackup.xar" with all default settings then I imported the package xwiki-enterprise-ui-mainwiki-all-6.2.xar (from http://enterprise.xwiki.org/xwiki/bin/view/Main/Download) again with all default settings (option: When a document already exists in the wiki Add a new version to the existing document) The result was succeeded with usable content pages.

IMPORTANT - If you import the Puget Sound wiki content, please be sure to update the references to the Logo.png and Footer.png images for the homepage to local copies of those images, instead of relying on the copies hosted on wiki.onebusaway.org, since this server is being decommissioned (see this thread for more info).

To start the import, in your XWiki instance go to "Admin->Content->Import". Note that if you don't yet have an admin account (i.e., its a fresh XWiki install), you'll need to enable the superadmin user, as discussed here. This should give you an exact duplicate of the Puget Sound OBA wiki. Password for all wiki content in the OBA export file is OneBusAway (possible username: Admin). After importing this file, check for references to wiki.onebusaway.org in the imported pages (particularly Main/Stylesheet) and replace them with the hostname of your XWiki instance.

For more information about how OneBusAway fetches XWiki content, please see this OBA dev. list post.

XWiki configuration for onebusaway-webapp

If you have an XWiki installation available at the url http://wiki.mydomain.org, you can configure your onebusaway-webapp to use the wiki by adding the following elements to your data-sources.xml config file:

<bean id="wikiDocumentService" class="org.onebusaway.wiki.xwiki.impl.XWikiDocumentServiceImpl">
    <property name="xwikiUrl" value="http://wiki.mydomain.org/xwiki" />
</bean>

<bean id="wikiRenderingService" class="org.onebusaway.wiki.xwiki.impl.XWikiRenderingServiceImpl">
    <property name="wikiDocumentViewUrl" value="/p/%{documentName}.action" />
    <property name="wikiDocumentEditUrl" value="http://wiki.mydomain.org/xwiki/bin/edit/Main/%{documentName}" />
    <property name="wikiAttachmentUrl" value="http://wiki.mydomain.org/xwiki/bin/download/Main/%{documentName}/%{attachmentName}" />
</bean>

The two components are a wiki document service and a wiki rendering service that control the source of pages and how they are rendered. There is a fair amount of flexibility in how you configure wiki integration.

Note that if you have the OBA webapp deployed to "/onebusaway-webapp" instead of the root URL, the "wikiDocumentViewUrl" element should instead be <property name="wikiDocumentViewUrl" value="/onebusaway-webapp/p/%{documentName}.action" />.

Also, please be sure to change the configuration to take any ports into account for the XWiki server. For example, here's the configuration for an OBA server running in the context path "/onebusaway-webapp", and an XWiki server running locally on port 8081:

<bean id="wikiDocumentService" class="org.onebusaway.wiki.xwiki.impl.XWikiDocumentServiceImpl">
    <property name="xwikiUrl" value="http://localhost:8081/xwiki" />
  </bean>

<bean id="wikiRenderingService" class="org.onebusaway.wiki.xwiki.impl.XWikiRenderingServiceImpl">
    <property name="wikiDocumentViewUrl" value="/onebusaway-webapp/p/%{documentName}.action" />
    <property name="wikiDocumentEditUrl" value="http://localhost:8081/xwiki/bin/edit/Main/%{documentName}" />
    <property name="wikiAttachmentUrl" value="http://localhost:8081/xwiki/bin/download/Main/%{documentName}/%{attachmentName}" />
</bean>

Serving Wiki content without XWiki

If it is inconvenient to run a standalone XWiki server, and the added functionality of the XWiki frontend is not needed, it is possible to use onebusaway-webapp itself to serve pages from the local filesystem.

<bean id="wikiDocumentService" class="org.onebusaway.wiki.file.FileWikiDocumentServiceImpl">
    <property name="documentDirectory" value="/srv/www/oba/wiki/" />
</bean>

<bean id="wikiRenderingService" class="org.onebusaway.wiki.xwiki.impl.XWikiRenderingServiceImpl">
    <property name="wikiDocumentViewUrl" value="/p/%{documentName}.action" />
    <property name="wikiAttachmentUrl" value="/p/%{documentName}@%{attachmentName}!attachment.action" />
</bean>

Set the documentDirectory path to point to a local directory (which must be accessible to Tomcat). Files in this directory which are marked up with XWiki markup and named with a .wiki extension will be served automatically. There is no caching, so changes are reflected as soon as they are made on the filesystem.

OneBusAway Wiki Integration project

onebusaway-wiki-integration

Latest Version: 1.0.0

The OneBusAway Wiki Integration dependency is included in the onebusaway-webapp by default, but you can also use it with other projects. Details on all releases can be found in the Release Notes.

The library is broken up into a few key modules:

  • onebusaway-wiki-integration-api - Defines the wiki integration api interfaces
  • onebusaway-wiki-integration-file - A file-based wiki integration plugin
  • onebusaway-wiki-integration-simple - A dummy wiki integration plugin for testing
  • onebusaway-wiki-integration-xwiki - Parent module for the XWiki-based modules
    • onebusaway-wiki-integration-xwiki-impl - An XWiki-based wiki integration plugin
    • onebusaway-wiki-integration-xwiki-struts-macros - XWiki macros for simulating Struts tags with XWiki markup
    • onebusaway-wiki-integration-urlnotification-plugin - XWiki plugin that can make a request to a configurable URL every time a wiki page is edited

Documentation

You can access the latest Javadoc for the library. Also, see example source code below.

Using in Maven

The library is available as a Maven module. Simply add the module dependency:

<dependencies>
    <dependency>
        <groupId>org.onebusaway</groupId>
        <artifactId>onebusaway-wiki-integration-file</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>