Module: Knuckles::View

Extended by:
View
Included in:
View
Defined in:
lib/knuckles/view.rb

Overview

An absolutely bare bones serializer. It is meant as a replacement for ‘ActiveModelSerializers`, but is entirely focused on being simple and explicit. Views are templates that satisfy the interface of:

  • root #=> symbol

  • data #=> hash

  • relations #=> hash

Any object that satisfies that interface can be rendered correctly by the ‘Renderer` stage.

Examples:

Extending for a custom view


module TagView
  extend Knuckles::View

  def root
    :tags
  end

  def data(tag, _)
    {id: tag.id, name: tag.name}
  end

  def relations(tag, _)
    {posts: has_many(tag.posts, PostView)}
  end
end

Instance Method Summary collapse

Instance Method Details

#data(_object, _options = {}) ⇒ Hash

Serialize an object into a hash. This simply returns an empty hash by default, it must be overridden by submodules.

Examples:

Overriding data


module TagView
  extend Knuckles::View

  def data(tag, _)
    {id: tag.id, name: tag.name}
  end
end

Parameters:

  • _object (Object) —

    The object for serializing.

  • _options (Hash) (defaults to: {}) —

    The options to be used during serialization, i.e. ‘:scope`

Returns:

  • (Hash) —

    A hash representing the serialized object.



82
83
84
 
# File 'lib/knuckles/view.rb', line 82

def data(_object, _options = {})
  {}
end

#has_many(objects, view, options = {}) ⇒ Array<Hash>

Renders all associated objects using the specified view.

Examples:

Render a single association


PostView.has_one(post.authors, AuthorView) #=> [
  {id: 1, name: "Me"},
  {id: 2, name: "You"}
]

Parameters:

  • objects (Array) —

    Array of associated objects to serialize.

  • view (Module) —

    A module responding to ‘data`.

  • options (Hash) (defaults to: {}) —

    The options passed to the view for rendering.

Returns:

  • (Array<Hash>) —

    All rendered association data.



142
143
144
 
# File 'lib/knuckles/view.rb', line 142

def has_many(objects, view, options = {})
  objects.map { |object| view.data(object, options) }
end

#has_one(object, view, options = {}) ⇒ Array<Hash>

Renders an associated object using the specified view, wrapping the results in an array.

Examples:

Render a single association


PostView.has_one(post.author, AuthorView) #=> [{id: 1, name: "Author"}]

Parameters:

  • object (Object) —

    The associated object to serialize.

  • view (Module) —

    A module responding to ‘data`.

  • options (Hash) (defaults to: {}) —

    Passed to the view for rendering.

Returns:

  • (Array<Hash>) —

    A single rendered data object is always returned.



123
124
125
 
# File 'lib/knuckles/view.rb', line 123

def has_one(object, view, options = {})
  has_many([object], view, options)
end

#relations(_object, _options = {}) ⇒ Hash

Extracts associations for an object. Later these are merged with the output of ‘data`. View relations are shallow, meaning the relations of relations are not included.

Examples:

Override relations


module PostView
  extend Knuckles::View

  def relations(post, _)
    {author: has_one(post.author, AuthorView),
     comments: has_many(post.comments, CommentView)}
  end
end

Parameters:

  • _object (Object) —

    The object to extract relations from

  • _options (Hash) (defaults to: {}) —

    The options used during extraction, i.e. ‘:scope`

Returns:

  • (Hash) —

    The serialized associations



106
107
108
 
# File 'lib/knuckles/view.rb', line 106

def relations(_object, _options = {})
  {}
end

#render(object, options = {}) ⇒ Hash

Convenience for combining the results of data and relations into a single object.

Examples:

Rendering an object


TagView.render(tag) #=> {tags: [{id: 1, name: "Alpha"}]}

Parameters:

  • object (Object) —

    The object for serializing.

  • options (Hash) (defaults to: {}) —

    The options to be used during serialization, i.e. ‘:scope`

Returns:

  • (Hash) —

    A hash representing the serialized object and relations.



59
60
61
 
# File 'lib/knuckles/view.rb', line 59

def render(object, options = {})
  relations(object, options).merge!(root => [data(object, options)])
end

#root ⇒ Symbol?

Specifies the top level key that data will be stored under. The value will not be stringified or pluralized during rendering, so be aware of the format.

Returns:

  • (Symbol, nil) —

    By default root is ‘nil`, it should be overridden to return a plural symbol.



43
44
 
# File 'lib/knuckles/view.rb', line 43

def root
end