Skip to content

Latest commit

 

History

History
112 lines (83 loc) · 3.24 KB

README.md

File metadata and controls

112 lines (83 loc) · 3.24 KB
Raw

Graph Object Mapper (Grom)

Grom is a custom ORM that takes graph data and deserializes it into objects. It uses the RDF.rb library. It was created in the context of UK Parliament's new website.

Installation

gem install grom

Add this line to your application's Gemfile:

gem 'grom'

Then execute:

$ bundle

Usage

Set up

You will need to set three constants in order for the gem to work.

API_ENDPOINT = 'http://example.com'
API_ENDPOINT_HOST = 'example.com'
DATA_URI_PREFIX = 'http://id.example.com'

The API Endpoint will be the endpoint where you are making the calls to get graph data.
The Data URI prefix is the prefix that you use to define the entities in your triple store.

Models

Models inherit from Grom::Base and need a self.property_translator hash defined. The keys are predicates (without the prefix) and the values are the translated object properties.

An example of a Person class.

class Person < Grom::Base

  def self.property_translator
    {
        id: 'id',
        forename: 'forename',
        surname: 'surname',
        middleName: 'middle_name',
        dateOfBirth: 'date_of_birth'
    }
  end
end

Retrieving Objects

#all

To return a collection of objects use the class method all.

people = Person.all #=> returns an array of People objects

This method can take unlimited parameters. Including a parameter appends it to the endpoint url creating a new url. For example,

people = Person.all('current') #=> returns an array of current People

This generates the endpoint url http://#{API_ENDPOINT}/people/current.ttl and returns a list of current people from there.

#find

To return a single object use the class method find with an id.

person = Person.find('1') #=> returns a Person object

Associations

#has_many

For a simple has_many association, declare the association at the top of the model. For example, if Person has many contact_points, create a ContactPoint class and declare the association at the top of the Person class.

The name of the association must match the name of the class but it needs to be underscored and pluralized just like in ActiveRecord.

class Person < Grom::Base
  has_many :contact_points

It is then possible to retrieve the contact_points for a person in the following way:

person = Person.find('1')
person.contact_points #=> returns an array of contact_points related to person
#has_many_through

For a has_many_through association, declare the association at the top of the model. For example, if Person has many parties through party_memberships, create a Party class and a PartyMembership class, then declare the association at the top of the Person class.

class Person < Grom::Base
  has_many_through :parties, via: :party_memberships

It is then possible to retrieve the parties for a person in the following way:

person = Person.find('1')
person.parties #=> returns an array of parties with the party_memberships stored as a hash

License

The gem is available as open source under the terms of the MIT License.