Talia Basics

This tutorial is meant to get you started in creating your own digital library with Talia. It will show you the main building blocks of the application, and how to modify them.

The first parts of this manual introduce some of the basic concepts of the software, while the later parts are a hands-on tutorial.

Getting Started

• Before getting started with this tutorial, you should install Talia as explained in the TaliaInstallation guide. Be sure to also install the administration backend.
• Then import the demo data set as explained in the ImportingData instructions.

Now you should be almost ready to go. Install the mongrel gem (if you haven't already) and fire up your local development server:

gem install mongrel
...
jruby script/server

If the server is running on your local machine, you can now point your browser at http://localhost:3000/sources/ and you should be greeted with a screen like this:

Not quite bad, but there's much room for improvement.

Layout of the application

Talia is built on top of the Ruby on Rails framework. Each Talia application is a Rails application, and has the same basic layout. You may also use a lot of the existing Rails plugins to add to your Talia application.

This guide assumes that you have a working knowledge of Rails - if not, it may be time to check out the Getting Started Guide for Rails.

At this point, we will just have a quick look at the directory structure of our new application.

- talia_application
  +- app              <- Main application files
    +- controllers
    +- helpers
    +- models
    +- views
  +- config
  +- ontologies
  +- public
  +- script
  +- vendor
    +- plugins

Talia Concepts

Before we get to the hands-on part, let us first have a look at some of the basic concepts of Talia.

Talia Sources

The default page shows you all the "Source" in the system. In Talia, a "Source" is the basic item of information.

It can be anything you've put into the digital library. It may a record that refers to an existing physical object, like a book, a movie or a statue. It may be a digital representation of some object in the real world, like a photography or transcription. Or it may be a digital item that was created by you or your users.

Template system

Installing plugins is nice, but chances are that you will have to adapt the interface of your library quite a bit. To change the appearance of your application, you will have to modify the page templates that come with Talia. These template files are mostly HTML, with some Ruby code sprinkled in.

If are a web designer or otherwise familiar with HTML, you shouldn't have big problems editing the template files.

Hint: If you've installed the Hobo-based backend interface, you may also use the DRYML markup language, which is even more like HTML. But that is outside the scope of this tutorial. Here will will use the default system called ERB (embedded ruby).

Rails Template files

The templates for the HTML pages are kept in the "views" directory of any Rails application, including your Talia application. If you open the views/sources folder, you will see a number of template files that are used for the pages that you see on the !http://yoursite.com/sources/* URLs. All files are called *.html.erb which means that they are ERB templates that create HTML pages.

You'll also see a "semantic_templates" folder which is a speciality of Talia and at which we'll look in a moment.

But for now, have a look at the index.html.erb file - which is the one that creates the main list of sources that we saw above:

<div class="sources_list">
        <h1>Sources found: <%= @pagination ? @sources.total_entries : @sources.size  %></h1>
        <ul>
        <% for source in @sources %>
        <% next if(source.is_a?(TaliaCore::SourceTypes::DummySource)) %>
        <li>
                <p>
                        <span class="source_type"><%= type_images(source.types) %></span>
                        <span class="source_title"><%= title_for(source) %></span>
                        <span class="source-data"><%= data_icons(source.data_records) %></span>
                        <span class="more"> <%= link_to 'more...', :action => 'dispatch', :dispatch_uri => N::URI.new(source.uri).local_name %></span>
                </p>
        </li>
        <% end  %>
</ul>
</div>

<%= if(@pagination) ; will_paginate @sources ; end %>

As you can see this template only creates the "inner" portion of the page - the rest comes from the "layout" template that is shared between multiple pages. Again, check those Ruby on Rails tutorials to find out how this works.

Most of the template is basic HTML, and the code parts aren't too bad, either. But what do they mean?

<%= link_to 'something', ... %>

This kind of tag (with <%= ) means that something should be inserted into the HTML at this point. For example, the fragment above calls the "link_to" helper function; it will take the parameters written after it and create a link in the web page at this point. Rails and Talia have hundreds of those little helper functions for all kinds of uses - check the Rails tutorials and documentation.

<% for source in @sources %>
  <h1>Some code - Source <%= source.title %></h1>
<% end %>

This code fragment is a bit different. The <% for %> tag doesn't create HTML directly. Instead it repeats the block inside, each time for each element of the collection "@sources". So the fragment above would output an h1 tag with the title of each of the sources.

If you like, try modifying some parts of this template, and see the effects that it has.

The semantic data store

"Talia uses a semantic datastore that stores all the data in the RDF Format." Sounds cool - but what does it mean?

Actually, it's a kind of database, but more flexible. In traditional database (a "relational database"), all the data is stored in large tables. Each table has a fix number of columns "fields" and any number of rows "records". For example, you may have a table called "books", that has columns for the title, author and the sales figure for that book.

This is easy to understand, but has some limitations. Most importantly, if you have another "property" of a book, let's say the publisher, then you'll have to modify the table and add another column to it. And if you work with less-organized data, it may be a really pain finding a "schema" that fits all your data elements.

In the world of semantic data stores, things work a bit differently. Instead of a fixed table, you have a collection of "triples", as they are called in RDF language. Each triple is a little "sentence" with three elements:

<my book> <has author> <me>

The three parts of the triple are called

<subject> <predicate> <object>

and you can express any number of things with it. For example, if you want to add a publisher to a book you just add a triple that says <book> <has publisher> <really big publishing house>.

To make this more digestible for a computer, the parts of our sentence are URLs:

<http://somebooks.org/mycoolbook> <http://fake_vocabulary.org/has_publisher> <http://list_of_publishers.foo/reall_big>

Each URL is treated as an identifier for the thing that it is about (e.g. http://somebooks.org/mycoolbook would be the identifier of my book). If the computer sees the same URL in different "sentences", it knows that they talk about the same thing.

We also call the "predicate" of the sentence the "field" or "property" - since its function is essentially the same as the column (or field) name in a traditional database table.

Namespaces

URLs that are used for naming things often have a common "prefix". For example, the popular DublinCore elements have a number of that can be used as properties in Talia. For example, <http://purl.org/dc/elements/1.1/title> means that the object of this triple is the title of the element.

All DublinCore? elements start with <http://purl.org/dc/elements/1.1/>, and its annoying to type that out every time. Therefore, in RDF (and in Talia) you may use "namespace" to abbreviate these URLs. If you'd declare the namespace "dcns" to mean <http://purl.org/dc/elements/1.1/>, then you can write your triples like this:

<books:mycoolbook> <dcns:title> "Coolest Book"

ActiveRecord and ActiveSource

Rails applications usually use ActiveRecord to connect to the database. Simply put, ActiveRecord? allows for expressions in your code and/or templates that go like this:

title = book.title

In this case "book" would be an ActiveRecord that represents one record in the database. The code above means "look in the 'books' table of the database, and give me the title of this one book here". You can also use this notation in your templates:

<%= book.author %>

Which would mean "take the value of the 'author' field for this one book, and put it into my HTML page".

Talia, instead of using ActiveRecord has its own class called "ActiveSource". ActiveSource works very much like ActiveRecord, but with the added flexibility of the RDF data store. The "model" classes in Talia are usually based on ActiveSource.

With active source, the code from above may look like this:

<%= book.dcns::author %>

This means "take the DublinCore property 'author' (the 'dcns' namespace is automatically available in Talia) and give me the results". (Or, in RDF terms: Find the object values for all triples that start with <book> <dcns:author>).

The code above is not 100% correct - it is quite possible that a book has multiple authors (something that isn't very easy in relational databases). So the real code could look something like this:

<%= book.dcns::author.join(', ') %>

Equivalent notations would be:

<%= book[N::DCNS.author].join(', ') %>

or

<%= book['http://purl.org/dc/elements/1.1/author'].join(', ') %>

Finding Sources

Finding sources works also quite like (but not exactly like) in ActiveRecord. In ActiveRecord, a command to find all books by Nietzsche would look like this:

Book.find(:all, :conditions => { :author => 'nietzsche' } }

An ActiveSource query that does the same could look like this:

SourceBook.find(:all, :find_through => [ N::DCNS.author, N::LOCAL.nietzsche ])

This will select all books where the dcns:author field is local:nietzsche - "local" is a special namespace in Talia that is equal to the base URL of your site. Meaning that if your site were "http://ultracool.site.org/", then "N::LOCAL.nietzsche" expands to "http://ultracool.site.org/nietzsche".

Note: The "find_through" mechanism works only for one condition per query. For more complex queries, see the next section.

RDF Queries

If you have more complex conditions, you have to use the "semantic query interface". It works quite similiar to the SPARQL query language, but with a Ruby interface.

Example:

ActiveRDF::Query.new(TaliaCore::ActiveSource).select(:book).distinct.where(:book, N::DCNS.creator, :author).where(:author, N::XXX.lives_in, N::XXX.Berlin)

This performs a pattern matching on the data store, and selects all book entries where the creator lives in Berlin.

Assigning semantic properties

Obviously the ActiveSource interface also allows you to assign properties to your sources:

book.dcns::author << "Yours Truly"
book.dcns::author << "Some other Guy"

Tutorial

Now that we know the basics, it's time for some hands-on experience.

Adding pagination for the front page

Just to warm up, let's install a pagination for the front page. That means that we don't see all the results at once, but rather only ever 20 or so sources at a time. (Note: If you installed the administration backend, the pagination has already been installed and you will see a paginated list automatically.)

Talia is already prepared for pagination. If you want to use it, you just have to install the will_paginate plugin. This plugin is available as a gem, so all you need to do is

gem install will_paginate

and everything should work.

Adding image overlays

When you are on your applications main page (that is http://mysite/sources), you see little icons for all sources that have some data attached. When you click on one of them, Talia will open the data element in the same window.

To add a bit of eye candy to your application, we will try to open those files in an "overlay" on the same page. For this we install another plugin called muruca_widgets which contains a number of cool interface elements for Talia or other Rails applications.

Install the plugin with

gem install muruca_widgets

The first thing we will do is to modify the main page so that image files open in a nifty "overlay" when you click the image icons. This is one of the functionalities of the muruca_widgets; to install it in your application call

jruby script/generate colorbox

Once the files are installed, you need to include the functionality in your HTML pages. In the layouts/sources.html.erb file, we find the html <head> section. We add a tag to include the "jquery" javascript library and a <%= render :partial => 'shared/colorbox' %>. A partial is a piece of template code that you can use in multiple pages, and this will conveniently contain all the things we need to include to use the "colorbox" overlays. It also contains some default settings to get you jump-started. If you want to have a look at the template, you will find it in app/views/shared/_colorbox.html.erb. If you restart your application, this will already work, but let's have a look why. Open the file app/helpers/sources_helper.rb - this is the file that defines the "commands" that can be used in the templates. If you look at the bottom of this file, you will find this:

def data_record_options(record)
  if(record.mime.include?('image/'))
    ['image', {:class => 'cbox_image'}]
  elsif(record.mime.include?('text/'))
    ['text', {:class =>'cbox_inline' }]
  elsif(record.mime == 'application/xml')
    ['text', {:class => 'cbox_inline'}]
  else
    ['gear', {}]
  end
end

This helper (which is in turn used by the app/views/sources/_data_list.html.erb template) defines how the links to the data elements are rendered. As you can see, there is a "class" attribute, which depends on the MIME type of the record. By default it uses "cbox_image" and "cbox_inline" as the css classes - and these are the predefined classes that will activate the "colorbox" overlay. If you modify the class, you will see how the colorbox stops working.

Adding a time line

Our sample database contains a lot of events in history, so it would be cool if we had some graphical way to browse them. To do so, we'll need the "simile timeline" plugin which is included in the muruca-widgets gem. Since we already installed that in the previous step, we just need to do a

jruby script/generate simile_timeline

Now we can add the timeline_includes to the <head> section of the layouts/sources.html.erb

Using IIP images

Make Talia go multi-language (I18N)