Class: Blueprinter::Base

Inherits:
Object
  • Object
show all
Includes:
ActiveRecordHelpers
Defined in:
lib/blueprinter/base.rb

Class Method Summary collapse

Methods included from ActiveRecordHelpers

#active_record_relation?, included

Class Method Details

.association(method, options = {}) {|Object| ... } ⇒ Field

Specify an associated object to be included for serialization. Takes a required method and an option.

Examples:

Specifying an association

class UserBlueprint < Blueprinter::Base
  # code
  association :vehicles, view: :extended, blueprint: VehiclesBlueprint
  # code
end

Passing a block to be evaluated as the value.

class UserBlueprint < Blueprinter::Base
  association :vehicles, blueprint: VehiclesBlueprint do |user|
    user.vehicles + user.company.vehicles
  end
end

Parameters:

  • method (Symbol) —

    the association name

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

    options to overide defaults.

Options Hash (options):

  • :blueprint (Symbol) —

    Required. Use this to specify the blueprint to use for the associated object.

  • :name (Symbol) —

    Use this to rename the association in the JSON output.

  • :view (Symbol) —

    Specify the view to use or fall back to to the :default view.

Yields:

  • (Object) —

    The object passed to ‘render` is also passed to the block.

Returns:

  • (Field) —

    A Field object

Raises:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/blueprinter/base.rb', line 140

def self.association(method, options = {}, &block)
  raise BlueprinterError, 'blueprint required' unless options[:blueprint]
  name = options.delete(:name) || method

  options = if block_given?
    options.merge(extractor: BlockExtractor.new, block: block)
  else
    options.merge(extractor: AutoExtractor.new)
  end

  current_view << Field.new(method,
                            name,
                            AssociationExtractor.new,
                            self,
                            options.merge(association: true))
end

.associations(view_name = :default) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



244
245
246
 
# File 'lib/blueprinter/base.rb', line 244

def self.associations(view_name = :default)
  view_collection.fields_for(view_name).select { |f| f.options[:association] }
end

.exclude(field_name) ⇒ Array<Symbol>

Exclude a field that was mixed into the current view.

Examples:

Excluding a field from being included into the current view.

view :normal do
  fields :position, :company
end
view :special do
  include_view :normal
  field :birthday
  exclude :position
end
#=> [:company, :birthday]

Parameters:

  • field_name (Symbol) —

    the field to exclude from the current view.

Returns:

  • (Array<Symbol>) —

    an array of field names



287
288
289
 
# File 'lib/blueprinter/base.rb', line 287

def self.exclude(field_name)
  current_view.exclude_field(field_name)
end

.field(method, options = {}) {|Object| ... } ⇒ Field

Specify a field or method name to be included for serialization. Takes a required method and an option.

Examples:

Specifying a user’s first_name to be serialized.

class UserBlueprint < Blueprinter::Base
  field :first_name
  # other code
end

Passing a block to be evaluated as the value.

class UserBlueprint < Blueprinter::Base
  field :full_name {|obj| "#{obj.first_name} #{obj.last_name}"}
  # other code
end

Passing an if proc and unless method..

class UserBlueprint < Blueprinter::Base
  def skip_first_name?(user, options)
    user.first_name == options[:first_name]
  end

  field :first_name, unless: :skip_first_name?
  field :last_name, if: ->(user, options) { user.first_name != options[:first_name] }
  # other code
end

Parameters:

  • method (Symbol) —

    the field or method name you want to include for serialization.

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

    options to overide defaults.

Options Hash (options):

  • :extractor (AssociationExtractor, BlockExtractor, HashExtractor, PublicSendExtractor) —

    Kind of extractor to use. Either define your own or use Blueprinter’s premade extractors. The Default extractor is AutoExtractor

  • :name (Symbol) —

    Use this to rename the method. Useful if if you want your JSON key named differently in the output than your object’s field or method name.

  • :datetime_format (String) —

    Format Date or DateTime object with given strftime formatting

  • :if (Symbol, Proc) —

    Specifies a method, proc or string to call to determine if the field should be included (e.g. ‘if: :include_first_name?, or if: Proc.new { |user, options| options == user }). The method, proc or string should return or evaluate to a true or false value.

  • :unless (Symbol, Proc) —

    Specifies a method, proc or string to call to determine if the field should be included (e.g. ‘unless: :include_first_name?, or unless: Proc.new { |user, options| options != user }). The method, proc or string should return or evaluate to a true or false value.

Yields:

  • (Object) —

    The object passed to ‘render` is also passed to the block.

Returns:

  • (Field) —

    A Field object



98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/blueprinter/base.rb', line 98

def self.field(method, options = {}, &block)
  options = if block_given?
    {name: method, extractor: BlockExtractor.new, block: block}
  else
    {name: method, extractor: AutoExtractor.new}
  end.merge(options)
  current_view << Field.new(method,
                            options[:name],
                            options[:extractor],
                            self,
                            options)
end

.fields(*field_names) ⇒ Array<Symbol>

Specify one or more field/method names to be included for serialization. Takes at least one field or method names.

Examples:

Specifying a user’s first_name and last_name to be serialized.

class UserBlueprint < Blueprinter::Base
  fields :first_name, :last_name
  # other code
end

Parameters:

  • method (Symbol) —

    the field or method name you want to include for serialization.

Returns:

  • (Array<Symbol>) —

    an array of field names



237
238
239
240
241
 
# File 'lib/blueprinter/base.rb', line 237

def self.fields(*field_names)
  field_names.each do |field_name|
    field(field_name)
  end
end

.identifier(method, name: method, extractor: AutoExtractor.new) ⇒ Field

Specify a field or method name used as an identifier. Usually, this is something like :id

Note: identifiers are always rendered and considerered their own view, similar to the :default view.

Examples:

Specifying a uuid as an identifier.

class UserBlueprint < Blueprinter::Base
  identifier :uuid
  # other code
end

Parameters:

  • method (Symbol) —

    the method or field used as an identifier that you want to set for serialization.

  • name (Symbol) (defaults to: method) —

    to rename the identifier key in the JSON output. Defaults to method given.

  • extractor (AssociationExtractor, AutoExtractor, BlockExtractor, HashExtractor, PublicSendExtractor) (defaults to: AutoExtractor.new) —

    Kind of extractor to use. Either define your own or use Blueprinter’s premade extractors. Defaults to AutoExtractor

Returns:

  • (Field) —

    A Field object



40
41
42
 
# File 'lib/blueprinter/base.rb', line 40

def self.identifier(method, name: method, extractor: AutoExtractor.new)
  view_collection[:identifier] << Field.new(method, name, extractor, self)
end

.include_view(view_name) ⇒ Array<Symbol>

Specify another view that should be mixed into the current view.

Examples:

Including a normal view into an extended view.

class UserBlueprint < Blueprinter::Base
  # other code...
  view :normal do
    fields :first_name, :last_name
  end
  view :extended do
    include_view :normal # include fields specified from above.
    field :description
  end
  #=> [:first_name, :last_name, :description]
end

Parameters:

  • view_name (Symbol) —

    the view to mix into the current view.

Returns:

  • (Array<Symbol>) —

    an array of view names.



266
267
268
 
# File 'lib/blueprinter/base.rb', line 266

def self.include_view(view_name)
  current_view.include_view(view_name)
end

.inherited(subclass) ⇒ Object 



44
45
46
 
# File 'lib/blueprinter/base.rb', line 44

def self.inherited(subclass)
  subclass.send(:view_collection).inherit(view_collection)
end

.prepare(object, view_name:, local_options:) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This is the magic method that converts complex objects into a simple hash ready for JSON conversion.

Note: we accept view (public interface) that is in reality a view_name, so we rename it for clarity



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/blueprinter/base.rb', line 206

def self.prepare(object, view_name:, local_options:)
  unless view_collection.has_view? view_name
    raise BlueprinterError, "View '#{view_name}' is not defined"
  end
  prepared_object = include_associations(object, view_name: view_name)
  if array_like?(object)
    prepared_object.map do |obj|
      object_to_hash(obj,
                     view_name: view_name,
                     local_options: local_options)
    end
  else
    object_to_hash(prepared_object,
                   view_name: view_name,
                   local_options: local_options)
  end
end

.render(object, options = {}) ⇒ String

Generates a JSON formatted String. Takes a required object and an optional view.

Examples:

Generating JSON with an extended view

post = Post.all
Blueprinter::Base.render post, view: :extended
# => "[{\"id\":1,\"title\":\"Hello\"},{\"id\":2,\"title\":\"My Day\"}]"

Parameters:

  • object (Object) —

    the Object to serialize upon.

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

    the options hash which requires a :view. Any additional key value pairs will be exposed during serialization.

Options Hash (options):

  • :view (Symbol) —

    Defaults to :default. The view name that corresponds to the group of fields to be serialized.

Returns:

  • (String) —

    JSON formatted String



173
174
175
176
 
# File 'lib/blueprinter/base.rb', line 173

def self.render(object, options = {})
  view_name = options.delete(:view) || :default
  jsonify(prepare(object, view_name: view_name, local_options: options))
end

.render_as_hash(object, options = {}) ⇒ Hash

Generates a hash. Takes a required object and an optional view.

Examples:

Generating a hash with an extended view

post = Post.all
Blueprinter::Base.render_as_hash post, view: :extended
# => [{id:1, title: Hello},{id:2, title: My Day}]

Parameters:

  • object (Object) —

    the Object to serialize upon.

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

    the options hash which requires a :view. Any additional key value pairs will be exposed during serialization.

Options Hash (options):

  • :view (Symbol) —

    Defaults to :default. The view name that corresponds to the group of fields to be serialized.

Returns:

  • (Hash) 


194
195
196
197
 
# File 'lib/blueprinter/base.rb', line 194

def self.render_as_hash(object, options= {})
  view_name = options.delete(:view) || :default
  prepare(object, view_name: view_name, local_options: options)
end

.view(view_name) ⇒ View

Specify a view and the fields it should have. It accepts a view name and a block. The block should specify the fields.

Examples:

Using views

view :extended do
  fields :position, :company
  include_view :normal
  exclude :first_name
end

Parameters:

  • view_name (Symbol) —

    the view name

Yield Returns:

Returns:

  • (View) —

    a Blueprinter::View object



306
307
308
309
310
 
# File 'lib/blueprinter/base.rb', line 306

def self.view(view_name)
  @current_view = view_collection[view_name]
  yield
  @current_view = view_collection[:default]
end