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
```apple js gem install grom
Add this line to your application's Gemfile:
```ruby
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
.
```apple js
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,
```apple js
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.
```apple js
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:
```apple js
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:
```apple js 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](http://opensource.org/licenses/MIT).