Class: Mongoid::Field

Inherits:
Object show all
Defined in:
lib/mongoid/field.rb

Overview

Defines the behaviour for defined fields in the document.

Constant Summary collapse

NO_CAST_ON_READ =
[
  Array, Binary, Boolean, Float, Hash,
  Integer, BSON::ObjectId, Set, String, Symbol
]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options = {}) ⇒ Field

Create the new field with a name and optional additional options.

Examples:

Create the new field.

Field.new(:name, :type => String)

Parameters:

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

    The field options.

Options Hash (options):

  • :type (Class)

    The class of the field.

  • :default (Object)

    The default value for the field.

  • :label (String)

    The field’s label.

Since:

  • 1.0.0



84
85
86
87
88
89
90
# File 'lib/mongoid/field.rb', line 84

def initialize(name, options = {})
  @type = options[:type] || Object
  @name, @default, @label = name, options[:default], options[:label]
  @copyable = (@default.is_a?(Array) || @default.is_a?(Hash))
  @options = options
  check_default!
end

Instance Attribute Details

#copyableObject (readonly)

Returns the value of attribute copyable.



13
14
15
# File 'lib/mongoid/field.rb', line 13

def copyable
  @copyable
end

#klassObject (readonly)

Returns the value of attribute klass.



13
14
15
# File 'lib/mongoid/field.rb', line 13

def klass
  @klass
end

#labelObject (readonly)

Returns the value of attribute label.



13
14
15
# File 'lib/mongoid/field.rb', line 13

def label
  @label
end

#nameObject (readonly)

Returns the value of attribute name.



13
14
15
# File 'lib/mongoid/field.rb', line 13

def name
  @name
end

#optionsObject (readonly)

Returns the value of attribute options.



13
14
15
# File 'lib/mongoid/field.rb', line 13

def options
  @options
end

#typeObject

Returns the value of attribute type.



12
13
14
# File 'lib/mongoid/field.rb', line 12

def type
  @type
end

Class Method Details

.option(option_name, &block) ⇒ Object

Stores the provided block to be run when the option name specified is defined on a field.

No assumptions are made about what sort of work the handler might perform, so it will always be called if the ‘option_name` key is provided in the field definition – even if it is false or nil.

Examples:

Mongoid::Field.option :required do |model, field, value|
  model.validates_presence_of field if value
end

Parameters:

  • option_name (Symbol)

    the option name to match against

  • block (Proc)

    the handler to execute when the option is provided.



43
44
45
# File 'lib/mongoid/field.rb', line 43

def option(option_name, &block)
  options[option_name] = block
end

.optionsHash

Return a map of custom option names to their handlers.

Examples:

Mongoid::Field.options
# => { :required => #<Proc:0x00000100976b38> }

Returns:

  • (Hash)

    the option map



24
25
26
# File 'lib/mongoid/field.rb', line 24

def options
  @options ||= {}
end

Instance Method Details

#cast_on_read?true, false

When reading the field do we need to cast the value? This holds true when times are stored or for big decimals which are stored as strings.

Examples:

Typecast on a read?

field.cast_on_read?

Returns:

  • (true, false)

    If the field should be cast.



56
57
58
# File 'lib/mongoid/field.rb', line 56

def cast_on_read?
  !NO_CAST_ON_READ.include?(type)
end

#defaultObject

Get the default value for the field.

Examples:

Get the default.

field.default

Returns:

  • (Object)

    The typecast default value.

Since:

  • 1.0.0



68
69
70
# File 'lib/mongoid/field.rb', line 68

def default
  copy.respond_to?(:call) ? copy : set(copy)
end

#get(object) ⇒ Object

Used for retrieving the object out of the attributes hash.

Examples:

Get the value.

field.get("Value")

Parameters:

  • The (Object)

    object to cast from the database.

Returns:

  • (Object)

    The converted value.

Since:

  • 1.0.0



129
130
131
# File 'lib/mongoid/field.rb', line 129

def get(object)
  type.get(object)
end

#set(object) ⇒ Object

Used for setting an object in the attributes hash.

If nil is provided the default will get returned if it exists.

If the field is an identity field, ie an id, it performs the necessary cast.

Examples:

Get the setter value.

field.set("New Value")

Parameters:

  • object (Object)

    The value to cast to a database value.

Returns:

  • (Object)

    The typecast value.

Since:

  • 1.0.0



107
108
109
110
111
112
113
114
115
116
117
# File 'lib/mongoid/field.rb', line 107

def set(object)
  unless options[:identity]
    type.set(object)
  else
    if object.blank?
      type.set(object) if object.is_a?(Array)
    else
      options[:metadata].constraint.convert(object)
    end
  end
end