Arkenstone Basics

Arkenstone Basics

Class structure

Arkenstone needs a URL in order to create RESTful Urls for CRUD operations. You can set the url to the root of resource with the url directive:

class Widget
  include Arkenstone::Document
  
  url 'http://example.com/widgets'
end

Arkenstone also needs to know what properties to pay attention to. These are called attributes:

class Widget
  include Arkenstone::Document
  
  url 'http://example.com/widgets'
  
  attributes :name, :size, :sku
end

When HTTP responses are received, the JSON properties of the response are mapped to these attributes.

{
  "name":"Widget 1",
  "size":"10",
  "sku":"12345"
}

This response will create a Widget object with a name of "Widget 1" and so on.

Requests also function the same way. A POST or PUT request will map the attributes to a JSON request.

Under the hood

Arkenstone uses a bunch of Ruby meta-programming to add functionality. The first place to look is in document.rb. When Arkenstone::Document is included in a class, the included method is called. This includes extra modules that are used by Arkenstone, which may in turn add their own set of modules to the class.

Most of the declarative functionality for a class is stored in Arkenstone::Document::ClassMethods.

Class Attrs

• :arkenstone_url — This is where the root url for the entity is stored when you call url http://example.com/widgets.
• :arkenstone_attributes — This is where the attributes you declare in attributes :x, :y, :z are stored.
• :arkenstone_hooks — More on this later.
• :arkenstone_inherit_hooks — More on this later.

Notable Class Methods

url(new_url) — When you declare

  url 'http://example.com/widgets'

This is the method that is called. It takes the new_url parameter and stores it in the arkenstone_url accessor.

---

attributes(*options) — When you declare

  attributes :name, :size, :sku

This is the method that is called. It stores the options splat passed in within the arkenstone_attributes accessor.

---

build(options) — Constructs an instance of the class and sets its attributes to the values provided by the options hash. It loops through the options and matches each key in itself to a property on the object.

---

parse_all(to_parse) — Constructs an array of objects from a string or hash.

---

create(options) — Creates and saves a single instance with the attribute values provided.

---

find(id) — Performs a GET request to the instance url with the supplied id. Builds an instance with the response.

---

all — Performs a GET request on the arkenstone_url. It expects to receive a json array of properties to deserialize into a list of objects.

Notable Instance Methods

attributes — Returns a hash with the values of properties defined in the class method attributes.

---

attributes=(options) — Sets the values of multiple properties for an instance. Discards properties in the options that don't exist on the object.

---

new_record? — Returns a boolean if the instance has been saved or not.

---

to_json — Serialized the object's attributes to JSON.

---

save — Updates the timestamps (if they exist), then saves the instance either through a POST or a PUT depending on if the instance is new or not. Returns a boolean if the save was successful.

---

reload — Refetches the attributes of the instance. Is the equivalent of doing a find all over again.

---

update_attributes(new_attributes) — Takes a new_attributes hash, updates the instances properties, and save's it.

---

update_attribute(key, value) — Same as update_attributes but with a single property.

---

destroy — Sends a DELETE request via the instance_url to destroy the instance.