module Knuckles::View
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.
@example 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
Public Instance Methods
Serialize an object into a hash. This simply returns an empty hash by default, it must be overridden by submodules.
@param [Object] _object The object for serializing. @param [Hash] _options The options to be used during serialization, i.e.
`:scope`
@return [Hash] A hash representing the serialized object.
@example Overriding data
module TagView extend Knuckles::View def data(tag, _) {id: tag.id, name: tag.name} end end
# File lib/knuckles/view.rb, line 82 def data(_object, _options = {}) {} end
Renders all associated objects using the specified view.
@param [Array] objects Array of associated objects to serialize. @param [Module] view A module responding to `data`. @param [Hash] options The options passed to the view for rendering.
@return [Array<Hash>] All rendered association data.
@example Render a single association
PostView.has_one(post.authors, AuthorView) #=> [ {id: 1, name: "Me"}, {id: 2, name: "You"} ]
# File lib/knuckles/view.rb, line 142 def has_many(objects, view, options = {}) objects.map { |object| view.data(object, options) } end
Renders an associated object using the specified view, wrapping the results in an array.
@param [Object] object The associated object to serialize. @param [Module] view A module responding to `data`. @param [Hash] options Passed to the view for rendering.
@return [Array<Hash>] A single rendered data object is always returned.
@example Render a single association
PostView.has_one(post.author, AuthorView) #=> [{id: 1, name: "Author"}]
# File lib/knuckles/view.rb, line 123 def has_one(object, view, options = {}) has_many([object], view, options) end
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.
@param [Object] _object The object to extract relations from @param [Hash] _options The options used during extraction, i.e. `:scope`
@return [Hash] The serialized associations
@example Override relations
module PostView extend Knuckles::View def relations(post, _) {author: has_one(post.author, AuthorView), comments: has_many(post.comments, CommentView)} end end
# File lib/knuckles/view.rb, line 106 def relations(_object, _options = {}) {} end
Convenience for combining the results of data and relations into a single object.
@param [Object] object The object for serializing. @param [Hash] options The options to be used during serialization, i.e.
`:scope`
@return [Hash] A hash representing the serialized object and relations.
@example Rendering an object
TagView.render(tag) #=> {tags: [{id: 1, name: "Alpha"}]}
# File lib/knuckles/view.rb, line 59 def render(object, options = {}) relations(object, options).merge!(root => [data(object, options)]) end
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.
@return [Symbol, nil] By default root is `nil`, it should be overridden to
return a plural symbol.
# File lib/knuckles/view.rb, line 43 def root end