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, options| ... } ⇒ 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, opts|
    user.vehicles + opts[:additional_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, options) —

    The object and the options passed to render are also yielded to the block.

Returns:

  • (Field) —

    A Field object

Raises:



151
152
153
154
155
156
157
158
159
 
# File 'lib/blueprinter/base.rb', line 151

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

  field(
    method,
    options.merge(association: true, extractor: AssociationExtractor.new),
    &block
  )
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



304
305
306
 
# File 'lib/blueprinter/base.rb', line 304

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

.field(method, options = {}) {|object, options| ... } ⇒ 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 do |object, options|
    "options[:title_prefix] #{object.first_name} #{object.last_name}"
  end
  # 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, options) —

    The object and the options passed to render are also yielded to the block.

Returns:

  • (Field) —

    A Field object



112
113
114
115
116
117
118
119
120
 
# File 'lib/blueprinter/base.rb', line 112

def self.field(method, options = {}, &block)
  current_view << Field.new(
    method,
    options.fetch(:name) { method },
    options.fetch(:extractor) { AutoExtractor.new },
    self,
    options.merge(block: block),
  )
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



259
260
261
262
263
 
# File 'lib/blueprinter/base.rb', line 259

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

.identifier(method, name: method, extractor: AutoExtractor.new) {|object, options| ... } ⇒ 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

Passing a block to be evaluated as the value.

class UserBlueprint < Blueprinter::Base
  identifier :uuid do |user, options|
    options[:current_user].anonymize(user.uuid)
  end
end

Parameters:

Yields:

  • (object, options) —

    The object and the options passed to render are also yielded to the block.

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

Returns:

  • (Field) —

    A Field object



50
51
52
53
54
55
56
57
58
 
# File 'lib/blueprinter/base.rb', line 50

def self.identifier(method, name: method, extractor: AutoExtractor.new, &block)
  view_collection[:identifier] << Field.new(
    method,
    name,
    extractor,
    self,
    block: block,
  )
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.



283
284
285
 
# File 'lib/blueprinter/base.rb', line 283

def self.include_view(view_name)
  current_view.include_view(view_name)
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



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/blueprinter/base.rb', line 228

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



177
178
179
 
# File 'lib/blueprinter/base.rb', line 177

def self.render(object, options = {})
  jsonify(prepare_for_render(object, 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) 


197
198
199
 
# File 'lib/blueprinter/base.rb', line 197

def self.render_as_hash(object, options= {})
  prepare_for_render(object, options)
end

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

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

Examples:

Generating a hash with an extended view

post = Post.all
Blueprinter::Base.render_as_json 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) 


217
218
219
 
# File 'lib/blueprinter/base.rb', line 217

def self.render_as_json(object, options= {})
  prepare_for_render(object, options).as_json
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



323
324
325
326
327
 
# File 'lib/blueprinter/base.rb', line 323

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