[[PageOutline]]

== 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:

{{{
#!sh
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:

[[Image(vanilla_front.png, nolink)]]

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

=== Layout of the application ===

Talia is built on top of the [http://rubyonrails.org/ 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 [http://guides.rails.info/getting_started.html Getting Started Guide] for Rails. 

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

{{{
#!text
- 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 be 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 you 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:

{{{
#!xml
<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?

{{{
#!xml
<%= 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.

{{{
#!xml
<% 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 [http://en.wikipedia.org/wiki/Resource_Description_Framework 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 fixed 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 URLs 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 "namespaces" to abbreviate these URLs. If you 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:

{{{
#!ruby
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:

{{{
#!xml
<%= 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:

{{{
#!xml
<%= 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:

{{{
#!xml
<%= book.dcns::author.join(', ') %>
}}}

Equivalent notations would be:

{{{
#!xml
<%= book[N::DCNS.author].join(', ') %>
}}}

or

{{{
#!xml
<%= 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:

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

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

{{{
#!ruby
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 [http://www.w3.org/TR/rdf-sparql-query/ SPARQL] query language, but with a Ruby interface.

Example:

{{{
#!ruby
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:

{{{
#!ruby
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 [http://wiki.github.com/mislav/will_paginate/ will_paginate] plugin. This plugin is available as a gem, so all you need to do is

{{{
#!sh
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 [http://github.com/net7/muruca_widgets muruca_widgets] which contains a number of cool interface elements for Talia or other Rails applications.

Install the plugin with

{{{
#!sh
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

{{{
#!sh
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:

{{{
#!ruby
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.

[[Image(overlay_colorbox.png, nolink)]]

=== 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 "[http://www.simile-widgets.org/timeline/ 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

{{{
#!sh
jruby script/generate simile_timeline
}}}

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

We want to show the timeline on the "index" page, the one that lists all the sources. For the simplest possible time line, we add a `timeline` to the `app/views/sources.index.html.erb` file. The `:data => { :sources => @sources }` part tells the timeline to take the data from the controller's `@sources` variable. When you click through the pages, you'll find that the time line will only show the sources on the current page. This is because `@sources` is filled by the controller, which only loads the data for the current page in order to save time and memory.

We could modify the controller to load all existing sources into `@sources` or into another variable. But there's an easier way: We can tell the time line to fetch the data by itself.

The `:source_finder => {}` tells the time line to fetch all `ActiveSource` elements from the data store, using no additional restraints. Instead of passing an empty hash, you could also use all the options that you can pass to `ActiveSource#find(:all, ...)`. There are a lot of other options to the time line, you can modify the layout, pass the data in directly (without using ActiveSource) and more. Check the documentation to find out how.

[[Image(timeline.png, nolink)]]

=== Using IIP images and overriding the semantic templates ===

Now we get to the heart of the Talia system. While having some nifty graphics is cool, all of our sources are using the same boring template so far. What we want to do is to have custom pages for each ''type'' of Source.

When you browse the list of sources, you'll notice a few symbols on the left-hand side. These represent the types of the sources (each can have more than one). We can make a template for any type, which will automatically be used for the sources of that type.



=== Make Talia go multi-language (I18N) ===