Technical Summary

From a technical perspective, the Ossian Online project had two objectives:

  1. to create an easy-to-use, visually appealing web interface to explore a set of TEI encoded XML files and associated page images;
  2. to provide a way for users to interact with the texts, and with each other, through annotation of the texts.

What follows is an overview of the technologies and processes employed to reach these objectives.

User Interface Design

The design process for the website started on paper, before moving quickly to the Balsamiq wireframing tool. The interface design was established quite quickly, with only minor alterations between the first version wireframe design and the currently live version, as shown below.

Homepage Wireframe
Homepage wireframe and Live version
Edition Wireframe
Individual Edition wireframe and Live version

From these Balsamiq wireframes, the process moved to the creation of a static HTML prototype of the site, where the visual design work was completed. Taking this approach, rather than creating the design in an image editor, allowed more detailed consideration of how the various design decisions would be affected by varying page or device screen sizes. This approach also has the advantage of minimising development time, as much of the code from the prototype can be reused in the development of the full system.

Back-end Development

The texts for the project are delivered as individual TEI-encoded XML files. A range of XSLT (1.0) stylesheets are used to transform the texts into their requested output formats (currently HTML or plain-text). Parts of the XSL build on the work in the Omeka TEIDisplay Plugin, created by the Scholars' Lab at the University of Virginia.

In addition to displaying visible HTML content, XSLT was written to extract metadata matching current Dublin Core elements, the output of which is included as meta tags in the HTML document's <head> section.

Between the user and the raw TEI-XML is a PHP web application, built on the Laravel Framework. The use of this framework allowed for rapid experimentation and feature development, as well as the easy construction of a REST-ful API which is used for the annotation system. It also allowed the project to take advantage of certain lower-level features, such as caching and user authentication, without having spend development time recreating them internally.

Also behind the application is an SQLite database, which holds information about the various texts and editions, along with annotation data. The choice of framework upon which the application is built makes swapping the database platform for a more robust alternative, should it be required, a trivial task. The schema for the database table design is stored as PHP, which can be migrated to a number of different platforms without any alteration; likewise, queries to the database are via ORM (Object-relational Mapping) - using Laravel's Eloquent - which abstracts database-specific language away from the code containing the Ossian Online-related logic. Again, this makes the replacement of the underlying data storage system a relatively trivial matter.

The primary drawback to the development of a PHP-based system is the lack of support for XSLT 2.0 in PHP. This lack of support means that many of the TEI-oriented XSLT stylesheets published were not supported, and could not be used without alteration. While not a major inhibitor to progress, support for XSLT2.0 in PHP would have likely reduced the XSLT-related development time.

Front-end development

Output from the web application is handled via Laravel's Blade templating language. Most commonly, the output is as HTML. The front-end of the website is built on HTML5.

The design of the website is implemented in part with the Bootstrap Framework, aspects of which are customised to reach the desired style for the website. CSS code is generated via the LESS CSS pre-processor.

On the individual texts, interaction is enabled through the use of jQuery - this handles behaviours such as displaying the text's linked images, notes, etc. On the front-end of the site, text annotation is via the Annotator.js library.

Development Environment

Development related

Development of the project used a Virtual Machine, running on Vagrant - this allowed the development environment to mirror the production server upon which the project would be deployed. Such an approach helps to avoid unexpected (and often difficult to track down) problems that can arise when different versions of software are run in the development and production environments.

For front-end coding, a two notable tools were used to streamline the development process:

  • Bower - a package manager to find, install, and keep the front-end external libraries up-to-date;
  • Grunt - a JavaScript task runner was used to manage the build process, for example, processing the LESS files into CSS and merging & minifying JavaScript files to improve performance.

On the back-end, Composer, a PHP package manager, was used to install external code dependencies, and to keep this external code up-to-date.

Code Management

Code for the project is stored under version control in an externally-hosted Git repository. In addition to functioning as a remote backup of the code, this allowed multiple users to work on the application at the same time, and for multiple "branches", or versions, of the application to be worked upon at the same time.

In addition to hosting the code, the repository service provides an Issue Tracker which was used internally to report and manage bugs and feature requests within the project.

Image management

Page images for the texts were supplied as .jp2 files. To convert them for use on the web, Adobe Fireworks was used to batch convert the files to .jpg, and to re-size them to an appropriate size for use on the website.

Analytics and Marketing

To track usage of the site, Google Analytics was installed. This provides a variety of reports on how the site is being used, such as visitors' geographical location, how they are finding the website, and how they interact with the website once there.

A decision was made early on to launch a "Demo" version of the website, and to add to it incrementally, rather than to have a "big-bang" launch where only the finished project is revealed publicly. An important consideration in this approach is how to reach users who visit the work-in-progress version, to tell them when the full project is available. To partially address this, a newsletter sign-up form was added to the site - this form is linked to our newsletter service, run by Mailchimp.

Finally, an external blog was created using Tumblr to serve as a platform for news and information about the project. While hosted externally, the Tumblr service allows for a certain amount of customisation of the design template; this ensured that a common look-and-feel could be maintained between the main project site and the related blog.

Last updated: 10 December 2015.