Mappers
The job of a mapper is to take an incoming request (e.g. the body of a PUT or POST) and transform the data therein to changes in the application (usually records in the database.)
Generally, you'll have (at least) one mapper per REST resource. Those mappers will be descendants of Xing::Mappers::Base.
Subclasses must define:
| Method | Purpose |
|---|---|
| aliases | for self.record |
| record_class | if the mapper maps to an AR object |
Subclasses should usually define:
| Method | Purpose |
|---|---|
| assign_values | move values from JSON into the mapped AR record |
Subclasses may also want to define:
| Method | Purpose |
|---|---|
| locator_attribute_name | if the locator something other than :id, like :url_slug |
| find_existing_record | for locating the underlying AR record |
| build_new_record | for for instantiating a new underlying AR record |
| map_nested_models | |
| build_errors | if simply copying AR errors is insufficient |
| save | if they need to save more than 1 AR record |
When updating records, pass the locator (e.g. DB id, url_slug, or other unique resource extracted from the resource path) as the second argument.
Example
class ProjectMapper < Xing::Mappers::Base
# These aliases aren't strictly necessary. By default
# any Xing mapper has a class variable with getter and setter
# called 'record', which is assumed to be the ActiveRecord object
# that the mapper is mapping to. But since this one maps Projects,
# we alias so that we can use the more readable #project and #project=
# methods.
alias project record
alias project record=
def record_class
# this should be the actual ActiveRecord class we are mapping to
Project
end
def assign_values(data_hash)
# the assign_values method in the superclass assumes that
# attribute names in the data hash match attribute names
# in the activerecord class, so often you don't need to do anything
super
end
def map_nested_models
# if the project JSON resource embedded other nested resources,
# logic for extracting their data (to get put into related AR records,
# or wherever) would go here.
end
end