README in rtriplify-0.0.2 vs README in rtriplify-0.0.3

@@ -1,55 +1,221 @@
-rTriplify
-========
+=rtriplify
 
-rTriplify is a ruby clone of the triplify-php version. It is used to create
-a rdf-mapping of your existing database and serves it out to the (semantic)-web.
+==What is rtriplify
 
-rTriplify uses the rails database models to generate your rdf-data.
-It comes with most of the origin features of triplify.
-I will go on detail on this later.
+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:
 
-In addition you have the possibility to generate RDFa -Data and place it inside of
-your webpage as a hidden div. Please be aware that this is not the clean way to
-serve your content as RDFa. But I think, if you have generated the mapping file
-for your database it's just the consequence to place RDFa on your page instead.
-RTriplify gives you the right tools to place RDFa tags on your Webpage without having
-to do a full code review of your templates. And of course, search engines like google
-and yahoo already watch for these tags. Google already rewards RDFa tags with some specials.
-For further informations please see here [1] or [2] here
+* RDF/N3
+* RDFa (eperimental feature - please see details)
 
+You can serve these formats in the following output-formats:
 
-Links:
-[1]http://www.google.com/support/webmasters/bin/answer.py?hl=en&answer=99170
-[2]http://developer.yahoo.com/searchmonkey/    (sadly this project has been rejected)
+* JSON (N3)
+* RDF/N3 file (N3)
+* As hidden div in the view of your application (RDFa)
 
-Example
-=======
+==How to serve data
 
-gem install rtriplify
+You have to do several steps to configure and run a rtriplify instance with your Application.
+For experienced users just do the following steps:
 
-then place a triplify.yml file in the config folder of your RoR-application.
-Probably it's the best idea to use the sample config file included in the gem or
-you can download a clean sample file here [3] too.
 
-Usaly the sample config has all configuration possibilitys inside of it and
-it's well documented. I think you can start now and change the config so that it
-will fit to your Application.
+1. install rtriplify
 
-Now, you want to see your nice RDF-Data?
+2. add "triplify.yml" file to your app/config folder
 
-just add following route in the route.config:
+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"
 
-that's it. Now just go to http://your-app.com/triplify/ and you will get the full
-RDF dump of your database. (If you haven't changed the data-depth part in the config)
+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.
 
-That's all the magic.
-For detailed documentation I'll go on detail on some of the config sections.
+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.
 
-Links:
-[3] sample config
-Copyright (c) 2010 Nico Patitz, released under the MIT license
+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