Longwell is a web application designed to let you browse and search an RDF model, especially large models.
Learning to configure Longwell to suit your needs requires some basic knowledge of Semantic Web concepts as well as a familiarity with RDF/N3 syntax. Also, a reasonable idea of the shape of the data you plan on browsing before getting started is helpful, at least the classes or properties that you want to focus on. While knowledge of the data model dramatically increases your ability to configure Longwell to provide a much more useful browsing experience, it's not required since Longwell is capable of presenting you with something useful even without any configuration or previous knowledge about the data you are browsing.
Running Longwell on your RDF Data
The requirements for running Longwell on your machine are:
- a Java Virtual Machine (JVM) version 1.4 or later installed on your operating system .
- the Apache Maven 2.0 or later build tool (with the mvn command available in your path).
These are the steps to get Longwell up and running with your own RDF data:
- Open your favorite shell/terminal on Unix/MacOSX or DOS Prompt on Windows;
- cd to the base directory of the Longwell distribution;
- Type mvn package to download the dependencies and build the code (this assumes that Maven is installed and its command line tool mvn is available to your shell path, refer to the maven installation documentation on how to do this).
- Type ./longwell -r path/to/RDF/data/ on Unix/MacOSX or longwell /r path\to\rdf\data\ on Windows, where "path to RDF data" is the a location on your disk where the RDF data you want to load is currently stored.
- Note: Longwell is capable of loading files that end with rdf, rdfs, owl, n3 and rss (here Longwell assumes RSS 1.0 which is RDF; other versions will generate errors). If the path is a directory, Longwell will recursively scan it for all files that look like RDF. If the file is GZIP compressed (e.g., ends in .rdf.gz), Longwell will automatically decompress it before reading it.
- Once Longwell has stopped initializing, loading and processing the data (which might take from a few seconds to hours, depending on the size of your dataset), point your browser at http://127.0.0.1:8080/ and enjoy.
The Longwell user interface
The most important aspect of Longwell is the faceted browsing UI paradigm.
A facet is a particular metadata field that is considered important for the dataset you are browsing. Longwell can be configured to prioritize which facets are 'open' when the page loads and in what order, an/or it can analyze facets and choose heuristically which are most important and should be 'opened.'
Once the facets are selected for a specific dataset, Longwell starts processing the dataset and extracts a list of facets, their values, and the number of times each facet value occurs in the dataset. This is shown in the right hand side, where each facet is boxed independently. Clicking on the facet's title will toggle it open or closed.
Clicking on a facet value guides Longwell to add a facet restriction and display only the items that fulfill all restrictions. The facet pane on the right is also updated, showing the facets and values that are available in the resulting sub-dataset for further drill-down.
When no more facet restrictions are possible, the right pane will be empty.
Browsing by adding restrictions in the right pane has the effect of "zooming in" the dataset by locally removing from the view anything that's not of interest at that particular time. The user also has the ability to "zoom out" by removing a restriction that was previously selected (in the top left section).
The result of the restriction is a subset of the items available in the dataset (what is considered "an item" is also a configurable property of Longwell). Longwell can also be configured to display particular properties of the items in various ways, and, mixing with CSS stylesheets, it is possible to obtain pleasant presentations of them without having to modify Longwell's source code. See the section below for more info on this.
Longwell also gives the ability to perform a "free text" restriction that reduces the browsed dataset to all items that contain the searched string in their properties' values. This restriction is triggered by entering text in the input box above the facet list.
How do I run a different Longwell configuration?
Longwell is built around the concept of extensible configurations. This means that a configuration can redefine just the part of the Longwell UI that needs to be changed, and the rest of the UI will be defined by the underlying configuration, reducing duplication.
The directory ./src/main/webapp (which is also the webapp context root) is the default location where Longwell looks for its configurations. In order to run one of the default configurations, you must specify the name of the configuration folder to the Longwell invocation scripts:
./longwell -c <configuration>
longwell /c <configuration>
If no configuration is specified it will default to the longwell configuration. The following configurations are available:
- longwell - the default configuration, also used as a base for all other configurations
- example - a simple configuration that shows how to write your own configuration
- semantic-bank - the server side companion of Piggy Bank (the Simile Bank is a live instance of this configuration)
- conference-bank - a specialized semantic bank for conferences (the ISCW 2005 Bank is a live instance of this configuration)
What's in a Longwell configuration?
A longwell configuration has the following structure:
configuration.properties- the configuration metadata and properties
fresnel.n3- the definition for the Fresnel lenses and styles
./data/- RDF data that is loaded during the configuration initalization
./templates/- the Velocity templates used by the configuration
The configuration.properties file has three parts:
- longwell.configuration.extends indicates what configuration it extends. If this is not present it means that your configuration won't extend any, so unless you know what you're doing, things are unlikely to work as you expect. If unsure, make it extend the longwell configuration.
- For example:
- your configuration extends the semantic-bank.
- longwell.template.[name] registers a new template injection
- For example:
- and then the calls to
- will be routed to your own template instead of the one defined by the extended configuration. You can have as many injections defined as you wish, even if their names were never used by the extended configuration.
- longwell.command.[action].[name](.template) indicates what Java class to add to what HTTP action and name, with an optional Velocity template.
- This allows you to change the Java class that responds to a particular command request and the Velocity template that that class uses to output its response.
- For example:
- says that the command focus called with an HTTP GET request will be dispatched to the edu.mit.simile.longwell.command.FocusCommand class and
- says the resulting output will use the commands/focus.vt template.
- There is no way to add Java classes using only the configuration mechanism (for now), so if you plan to write your own Java code to augment Longwell, you must place the source in the src/main/java folder if you want the Longwell build system to include it.
Where can I find examples of Longwell configurations to start from?
Go to the list of Longwell Demos to find online Longwell demos and links to their configurations.
How do I change the style of an item?
The SIMILE Project is a participant in the Fresnel display vocabulary effort, an ontology aimed at providing reusable display configurations across different RDF-based end-user oriented systems. A separate SIMILE code base implements Fresnel as a Sesame-based library available for use in other Java applications. For the time being, please consult the Fresnel user manual for instructions on how to construct a display configuration using Fresnel Core vocabulary constructs. Note that Fresnel in Longwell is applied one resource at a time.
For optimal portability, provide a
dc:title description suitable for user consumption, particularly on
The SIMILE Fresnel implementation includes an extension to describe facet display not found in core which is described below.
The facet configuration vocabulary is composed of two main concepts, facets and types. A set of facets is associated with a set of types. For example:
@prefix facets: <http://simile.mit.edu/2006/01/ontologies/fresnel-facets> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax#> . @prefix dc: <http://purl.org/dc/elements/1.1/> . @prefix ow: <http://www.ontoweb.org/ontology/1#> . :publicationFacets rdf:type facets:FacetSet ; facets:types ( ow:Publication ) ; facets:facets ( dc:type dc:publisher dc:contributor dc:subject ) .
facets:types property expects a list of
rdfs:Class class values, valid objects to the
rdf:type property. If the list of facets should apply to all resources, use the
facets:allTypes resource as the only value in the list instead.
facets:facets property expects a list of
rdf:Property values to be used as facets.
Longwell will display facets used in this vocabulary in the order they are given; they will appear as 'opened' facet boxes while all other facet boxes will be closed when a page of results is first viewed.
Where can I learn more about Fresnel?
There's an example found in
src/main/webapp/example/ that shows how to apply custom Fresnel lenses. The
fresnel.n3 file found there contains a set of lenses you could use as a starting point for getting into Fresnel, the display ontology we use to control rendering for certain types of resources. The Fresnel subsystem goes unused by default, so you don't have to write a lens for everything, just the types of resources you feel require it for your uses.
More info about Fresnel.
I can't find what I'm looking for, what do I do?
You might want to read the list of frequently asked questions or add your own question there so that we can answer it.
Back to Longwell.