Module: Mongoid::Serializable

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In: `Composable`, `Document`, `GlobalDiscriminatorKeyAssignment::InvalidFieldHost`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, ActiveSupport::Concern
Defined in:	lib/mongoid/serializable.rb

Overview

This module provides the extra behavior for including associations in JSON and XML serialization.

Instance Method Summary

#serializable_hash(options = nil) ⇒ Hash

Gets the document as a serializable hash, used by ActiveModel’s JSON serializer.
#field_names(options) ⇒ Array<String> private Internal use only Internal use only

Get the names of all fields that will be serialized.
#relation_names(inclusions) ⇒ Array<Symbol> private

Since the inclusions can be a hash, symbol, or array of symbols, this is provided as a convenience to parse out the names.
#relation_options(inclusions, options, name) ⇒ Hash private

Since the inclusions can be a hash, symbol, or array of symbols, this is provided as a convenience to parse out the options.
#serialize_attribute(attrs, name, names, options) ⇒ Object private Internal use only Internal use only

Serialize a single attribute.
#serialize_relations(attributes = {}, options = {}) private

For each of the provided include options, get the association needed and provide it in the hash.

DSL Calls

included

We need to redefine where the JSON configuration is getting defined, similar to ActiveRecord.

[ GitHub ]

# File 'lib/mongoid/serializable.rb', line 11


included do
  class << self
    # These methods are previously defined by ActiveModel which we override to include default behavior.
    remove_method :include_root_in_json if method_defined?(:include_root_in_json)
    remove_method :include_root_in_json= if method_defined?(:include_root_in_json=)
    def include_root_in_json
      @include_root_in_json.nil? ? ::Mongoid.include_root_in_json : @include_root_in_json
    end

    attr_writer :include_root_in_json
  end
end

Instance Method Details

#field_names(options) ⇒ Array<String> (private)

This method is for internal use only.

Get the names of all fields that will be serialized.

Examples:

Get all the field names.

document.send(:field_names)

Returns:

(Array<String>) —

The names of the fields.

[ GitHub ]

# File 'lib/mongoid/serializable.rb', line 74


def field_names(options)
  names = (as_attributes.keys + attribute_names).uniq.sort

  only = Array.wrap(options[:only]).map(&:to_s)
  except = Array.wrap(options[:except]).map(&:to_s)
  except |= [ self.class.discriminator_key ] unless Mongoid.include_type_for_serialization

  if !options[:only].nil? && (!Mongoid.serializable_hash_with_legacy_only || !only.empty?)
    names &= only
  elsif !except.empty?
    names -= except
  end
  names
end

#relation_names(inclusions) ⇒ Array<Symbol> (private)

Since the inclusions can be a hash, symbol, or array of symbols, this is provided as a convenience to parse out the names.

Examples:

Get the association names.

document.relation_names(:include => [ :addresses ])

Parameters:

inclusions (Hash | Symbol | Array<Symbol>) —

The inclusions.

Returns:

(Array<Symbol>) —

The names of the included associations.

[ GitHub ]

# File 'lib/mongoid/serializable.rb', line 146


def relation_names(inclusions)
  inclusions.is_a?(Hash) ? inclusions.keys : Array.wrap(inclusions)
end

#relation_options(inclusions, options, name) ⇒ Hash (private)

Since the inclusions can be a hash, symbol, or array of symbols, this is provided as a convenience to parse out the options.

Examples:

Get the association options.

document.relation_names(:include => [ :addresses ])

Parameters:

inclusions (Hash | Symbol | Array<Symbol>) —

The inclusions.
options (Hash) —

The options.
name (Symbol) —

The name of the association.

Returns:

(Hash) —

The options for the association.

[ GitHub ]

# File 'lib/mongoid/serializable.rb', line 161


def relation_options(inclusions, options, name)
  if inclusions.is_a?(Hash)
    inclusions[name]
  else
    { except: options[:except], only: options[:only] }
  end
end

#serializable_hash(options = nil) ⇒ Hash

Gets the document as a serializable hash, used by ActiveModel’s JSON serializer.

Examples:

Get the serializable hash.

document.serializable_hash

Get the serializable hash with options.

document.serializable_hash(:include => :addresses)

Parameters:

options (Hash) (defaults to: nil) —

The options to pass.

Options Hash (options):

:except (Symbol | String | Array<Symbol | String>) —

Do not include these field(s).
:include (Symbol | String | Array<Symbol | String>) —

Which association(s) to include.
:only (Symbol | String | Array<Symbol | String>) —

Limit the field(s) to only these.
:methods (Symbol | String | Array<Symbol | String>) —

What methods to include.

Returns:

(Hash) —

The document, ready to be serialized.

[ GitHub ]

# File 'lib/mongoid/serializable.rb', line 45


def serializable_hash(options = nil)
  options ||= {}
  attrs = {}

  names = field_names(options)

  method_names = Array.wrap(options[:methods]).map do |name|
    name.to_s if respond_to?(name)
  end.compact

  (names + method_names).each do |name|
    without_autobuild do
      serialize_attribute(attrs, name, names, options)
    end
  end
  serialize_relations(attrs, options) if options[:include]
  attrs
end

#serialize_attribute(attrs, name, names, options) ⇒ Object (private)

This method is for internal use only.

Serialize a single attribute. Handles associations, fields, and dynamic attributes.

Examples:

Serialize the attribute.

document.serialize_attribute({}, "id" , [ "id" ])

Parameters:

attrs (Hash) —

The attributes.
name (String) —

The attribute name.
names (Array<String>) —

The names of all attributes.
options (Hash) —

The options.

Returns:

(Object) —

The attribute.

[ GitHub ]

# File 'lib/mongoid/serializable.rb', line 103


def serialize_attribute(attrs, name, names, options)
  if relations.key?(name)
    value = send(name)
    attrs[name] = value ? value.serializable_hash(options) : nil
  elsif names.include?(name) && !fields.key?(name)
    attrs[name] = read_raw_attribute(name)
  elsif !attribute_missing?(name)
    attrs[name] = send(name)
  end
end

#serialize_relations(attributes = {}, options = {}) (private)

For each of the provided include options, get the association needed and provide it in the hash.

Examples:

Serialize the included associations.

document.serialize_relations({}, :include => :addresses)

Parameters:

attributes (Hash) (defaults to: {}) —

The attributes to serialize.
options (Hash) (defaults to: {}) —

The serialization options.

Options Hash (options):

:include (Symbol) —

What associations to include
:only (Symbol) —

Limit the fields to only these.
:except (Symbol) —

Dont include these fields.

[ GitHub ]

# File 'lib/mongoid/serializable.rb', line 126


def serialize_relations(attributes = {}, options = {})
  inclusions = options[:include]
  relation_names(inclusions).each do |name|
    association = relations[name.to_s]
    if association && relation = send(association.name)
      attributes[association.name.to_s] =
        relation.serializable_hash(relation_options(inclusions, options, name))
    end
  end
end