=rtriplify

==What is rtriplify

rtriplify is a ruby clone of the triplify-php version. It is used to create
an rdf-mapping of your existing database and serves it's content out to the (semantic)-web.
It offers several opportunities to improve your application with semantic-data in several
RDF- and output formats. The following RDF-formats are supported:

* RDF/N3
* RDFa (eperimental feature - please see details)

You can serve these formats in the following output-formats:

* JSON (N3)
* RDF/N3 file (N3)
* As hidden div in the view of your application (RDFa)

==How to serve data

You have to do several steps to configure and run a rtriplify instance with your Application.
For experienced users just do the following steps:


1. install rtriplify

2. add "triplify.yml" file to your app/config folder

3. configure the mapping to your datamodel

4. add route for rtriplify controller (optional)


For further information, these steps now in detail:

=== Install rtriplify

The easiest way to install rtriplify is by using ruby gem (of course you need a running ruby/rails environment).
Just open your command-prompt and input:

 gem install rtriplify

Another possibility is to install triplify as rails-plugin. In this case,
go to the root folder of you application and install it by executing the following command on your commandline:

 ruby script/plugin install http://github.com/rtriplify/rtriplify.git

Of course you can download the source from github and install it manually too.

=== Add configuration

rtriplify just starts up with your application, if you have placed a "triplify.yml" configuration file in the "app/config" folder.
Please add such a file. You can download a sample configuration file from https://github.com/rtriplify/rtriplify/blob/master/lib/config/triplify_demo.yml.
This configuration file located at lib/config/triplify_demo.yml folder of your triplify installation directory too.
(if installed as plugin you can find it at your-app-folder/vendor/plugin/rtriplify/lib/config/triplify_demo.yml)
Please don't forget to rename it to "triplify.yml".

=== Edit configuration

Usaly the sample configuration has all configuration possibilitys inside of it and
is well documentated. I think you can start now and change the configuration in a way that it
will fit to your Application. Please note that this configuration file is using the yaml syntax.
If your application doesn't start after installing the rtriplify,
please make sure, you have a well formed yaml configuration file.

Please see configuration attributes section for further information


=== Serve content

Rtriplify allows you to serve content in different ways:

1. As N3-File download with or without subclasses (all referencing objects)
2. N3-JSON with oder without subclasses
3. As embedded RDFa

Just add following route in the route.config:

 map.connect 'triplify/*specs', :controller => 'triplify', :action => "tripleize"

Now you can get triples without subclasses under the link:
 /triplify to get all triples
Depending on your configuration you can call
 /triplify/RDF-Class
or
 /triplify/RDF-Class/id
too, to get more specified set of triples.
Just do a JSON request on this URI to get it as JSON Object.
That' the same way, php-triplify works.

Now, if you want to serve specific triples in your application, e.g. under a product page,
rtriplify gives you the possibility to use respond_to functionality of Ruby on Rails.
Just modify your controller function to something similar to the following example:

  def show
    #load object
    @product = product.find(@params[:id])

    #new instance of Tripleizer
    t = Tripleizer.new
    respond_to do |format|
      format.html
      # render n3 triples
      format.n3 { render :text => t.rdf("Product",[@product]) }
    end
  end

It's important that you give the t.rdf function the correct parameters.
First parameter is the RDF-Class, second parameter is an array with some instances
of your models that should be used for rdf generation. Please note, that all
triples are generated iterative including all triples of RDF-subclasses.

If you want to use the RDFa feature of triplify you can generate the triples in a similar way.
Just store them as a variable and you can display them on your view at the wished position.

  def show
    #load_object
    @product = product.find(@params[:id])

    #new instance of Tripleizer
    t = Tripleizer.new
    #get RDFa - text
    @rdfa = t.rdfa("Offer",[@variants,@product_properties])

    respond_to do |format|
      format.html     
    end
  end

Please note that this feature is experimental. It's a possibility to embedd RDFa tags as hidden tags on your page without a complete review of your views.
And of course, search engines like google and yahoo look for these tags. Google already rewards RDFa tags with some special functions.

For further informations please see here:

http://www.google.com/support/webmasters/bin/answer.py?hl=en&answer=99170 or
http://developer.yahoo.com/searchmonkey/    (sadly this project is discontinued)


=== Config attributes

Here you will find some description configurating your rtriplify file.

namespaces:
  xmlns: http://www.w3.org/1999/xhtml/
All namespaces for your application. Please use them in your application to
get the data better linked .

 queries:
In general there are two possibilites to configure your rdf Data. First is by
using sql queries like in the php version of triplify. Please have a look at
http://triplify.svn.sourceforge.net/viewvc/triplify/triplify-php/config.dist.php?view=markup
to find out how to configure.

Secound possibility and may be the more "rails-way" is to use active record.
you have two hierarchy levels for configuration. First, the group and secound,
the Active record model.
A configuration line in the model has always the Schema
nameOfField: ar_field

ID field has a special meaning. The ID field is always the Subject of the RDF triples.
If your model has a relation to another Model you can reference the field by using
the "->" symbol. For example if your Country has States just reference it by
"state->State: states" before the "->" Symbol.  Behind this Symbol, the predicate is written.

Additional you can define a filter e.g.
 filter:
   ID: ">213 and id <224"

 query:
   Type:
     Model:
       attribute_name: field_name

In different scenarios, the  "attribute_name: field_name" is to simple, you can extend these commands in the following ways:

*attribute_name:  submodel.field_name
*attribute_name-> Ref_class: ref_model.reference_id
*attrubute_name->Ref_class: ref_model*reference_id
*attrubute_name->Ref_class:  MODEL( 'model-class','rdf-resource class')*field_name or, if multiple values
*attr_name:   CONST(gr:Sell,gr:datatype)
*attr_name:   CONST(gr:Sell,LINK)
*sql_query: sql_query like in triplify ..See here for further information

If your RDF/N3 and RDFa model have different schemas, you can add a rdfa_query node. Subnodes follow the same syntax as "query"-nodes.

 rdfa_query:

Objects are classified according to their type. However, you can specify
a mapping here, if objects of a certain type should be associated with a
different class (e.g. classify all users as 'foaf:person'). If you are
unsure it is safe to leave this configuration array empty.

objectProperties:
  field_name: type

Mapping a class to a specified type

 classMap:
   class: gr:Offering
 
The licence under which you publish your data
 license: http://creativecommons.org/licenses/by/3.0/us/

Additional metadata
You can add arbitrary metadata. The keys of the following array are
properties, the values will be represented as respective property values.

metadata:
  dc:title: test
  dc:publisher: test

 
Specify on which URI level to expose the data - possible values are:

* Use 0 or ommit to expose all available content on the highest level all content will be exposed when /triplify/ is accessed on your server. This configuration is recommended for small to medium websites.

* Use 1 to publish only links to the classes on the highest level and all content will be exposed when for example /triplify/user/ is accessed.

* Use 2 to publish only links on highest and classes level and all content will be exposed on the instance level, e.g. when /triplify/user/1/ is accessed.

 LinkedDataDepth: 2