Personalizar comportamentos de campo

Visão geral

Neste guia, você verá como personalizar o comportamento dos campos nos modelos Mongoid.

Especificar valores padrão

Você pode configurar campos para ter valores padrão usando a opção default. Os valores de campo padrão podem ser valores fixos ou Proc.

O exemplo seguinte especifica um valor padrão fixo para o campo state :

class Order
  include Mongoid::Document
  
  field :state, type: String, default: 'created'
end

O exemplo seguinte especifica um valor padrão Proc para o campo fulfill_by :

class Order
  include Mongoid::Document
  
  field :fulfill_by, type: Time, default: ->{ Time.now + 3.days }
end

# Time.now is set to the time the class is loaded
field :submitted_at, type: Time, default: Time.now
# Time.now is set to the time the document is instantiated
field :submitted_at, type: Time, default: ->{ Time.now }

Você pode definir um valor padrão que depende do estado do documento usando a palavra-chave self em uma instância Proc. O exemplo seguinte define o valor padrão fulfill_by para depender do estado do campo submitted_at :

field :fulfill_by, type: Time, default: ->{
  self.submitted_at + 4.hours
}

Por padrão, o Mongoid aplica Proc valores padrão após configurar e inicializar todos os outros atributos. Para aplicar o padrão antes de definir os outros atributos, defina a opção pre_processed como true, conforme mostrado no exemplo a seguir:

field :fulfill_by, type: Time, default: ->{ Time.now + 3.days },
  pre_processed: true

Especificar nomes de armazenamento

Você pode especificar um nome de campo separado para armazenar no banco de dados, enquanto ainda se refere ao campo por seu nome original em seu aplicação. Isso pode economizar espaço de armazenamento, porque o MongoDB armazena todas as informações de campo junto com cada documento.

Você pode definir um nome de armazenamento alternativo usando a palavra-chave as:. O exemplo a seguir cria um campo chamado name que o Mongoid armazena no banco de dados como n:

class Band
  include Mongoid::Document
  field :n, as: :name, type: String
end

O Mongoid armazena o campo name como "n", mas você ainda pode acessar o campo como name em seu aplicação.

Aliases de campo

Você pode criar um alias para seu campo usando a opção alias_attribute. A especificação de um alias não altera como o Mongoid armazena o campo no banco de dados, mas permite que você acesse o campo com um nome diferente em seu aplicação.

O exemplo seguinte especifica um alias para o campo name :

class Band
  include Mongoid::Document
  field :name, type: String
  alias_attribute :n, :name
end

Para remover um alias de campo , você pode usar a opção unalias_attribute. O exemplo seguinte remove o alias para o campo name :

class Band
  unalias_attribute :n
end

Você também pode usar unalias_attribute para remover o nome alternativo id predefinido do campo _id. Isso pode ser usado para armazenar valores diferentes no campo _id e em um campo id .

Redefinição de campo

Por padrão, o Mongoide permite redefinir campos em um modelo. Para gerar um erro quando um campo é redefinido, defina a opção de configuração duplicate_fields_exception no seu arquivo mongoid.yml como true.

Se a opção duplicate_fields_exception estiver definida como true, você ainda poderá redefinir um campo específico definindo a opção overwrite como true ao definir o campo. O exemplo a seguir define o campo name e, em seguida, redefine o campo usando a opção overwrite:

class Person
  include Mongoid::Document
  field :name
  field :name, type: String, overwrite: true
end

Campo de ID personalizado

Por padrão, o Mongoid define o campo _id em documentos para conter um valor BSON::ObjectId que o Mongoid gera automaticamente. Você pode personalizar o tipo ou especificar o valor padrão do campo _id especificando-o em seu modelo.

O exemplo seguinte cria uma classe Band com um campo _id personalizado:

class Band
  include Mongoid::Document
  field :name, type: String
  field :_id, type: String, default: ->{ name }
end

Você pode omitir o valor padrão para o campo _id. Se você não especificar um valor padrão para o campo, o Mongoid persistirá o documento sem um valor _id. Para documentos de nível superior, o servidor MongoDB atribui automaticamente um valor _id. No entanto, para documentos incorporados, o servidor não atribui um valor _id.

Quando você não especifica um valor para o campo _id, o Mongoid não recupera o valor atribuído automaticamente do servidor. Por esse motivo, você não pode recuperar o documento do banco de dados usando o valor _id.

Valores não convertíveis

Um valor é considerado não atribuível se não puder ser convertido para o tipo de campo especificado. Por exemplo, uma array é considerada não atribuível quando atribuída a um campo Integer .

Na v8.0 e posterior, Mongoid atribui nil a valores que são não atribuíveis. O valor original não atribuível é armazenado no hash attributes_before_type_cast com seus nomes de campo .

Getters e setters personalizados

Você pode substituir os métodos getter e setter padrão para um campo especificando um método com o mesmo nome do campo e chamando o método read_attribute ou write_attribute para operar no valor bruto do atributo.

O exemplo a seguir cria um getter e setter personalizados para o campo name de uma classe Person :

class Person
  include Mongoid::Document
  field :name, type: String
  # Custom getter for 'name' to return the name in uppercase
  def name
    read_attribute(:name).upcase if read_attribute(:name)
  end
  
  # Custom setter for 'name' to store the name in lowercase
  def name=(value)
    write_attribute(:name, value.downcase)
  end
end

Atributos somente leitura

Você pode especificar um campo para ser somente leitura especificando a opção attr_readonly. Isso permite que você crie documentos com os atributos, mas não os atualize.

O exemplo seguinte cria uma classe Band e especifica o campo name como somente leitura:

class Band
  include Mongoid::Document
  field :name, type: String
  field :origin, type: String
  attr_readonly :name
end

Se você chamar um método de atualização em massa, como update_attributes, e passar um campo somente para leitura, o Mongoid ignorará o campo somente para leitura e atualizará todos os outros. Se você tentar atualizar explicitamente um campo somente leitura, o Mongoid emitirá uma exceção de ReadonlyAttribute.

Para saber mais sobre como especificar modelos inteiros como somente leitura, consulte a seção Documentos somente para leitura do guia Executar operaçõesde dados.

Localizar campos

Mongoid suporta campos localizados usando o i18n gem. Quando você localiza um campo, o Mongoid armazena o campo como um hash de chaves e valores de locale . O acesso aos campos se comporta da mesma forma que um valor de string. Você pode localizar campos de qualquer tipo de campo .

O exemplo seguinte cria uma classe Product com um campo review localizado :

class Product
  include Mongoid::Document
  field :review, type: String, localize: true
end
I18n.default_locale = :en
product = Product.new
product.review = "Marvelous!"
I18n.locale = :de
product.review = "Fantastisch!"
product.attributes
# Outputs: { "review" => { "en" => "Marvelous!", "de" => "Fantastisch!" }

Você pode obter e definir todas as traduções de uma só vez ligando para o método _translations:

product.review_translations
# Outputs: { "en" => "Marvelous!", "de" => "Fantastisch!" }
product.review_translations =
  { "en" => "Marvelous!", "de" => "Wunderbar!" }

Você pode especificar contingências para campos localizados habilitando o recurso de contingências i18n.

Habilite as contingências em um aplicação Rails definindo a configuração config.i18n.fallbacks em seu ambiente e definindo os idiomas da contingência:

config.i18n.fallbacks = true
config.after_initialize do
  I18n.fallbacks[:de] = [ :en, :es ]
end

Habilite contingências em aplicativos não Rails incluindo o módulo no backend i18n e definindo as linguagens de contingência:

require "i18n/backend/fallbacks"
I18n::Backend::Simple.send(:include, I18n::Backend::Fallbacks)
I18n.fallbacks[:de] = [ :en, :es ]

Depois de ativar as contingências, se um idioma ativo não tiver uma tradução, ele será pesquisado no idioma alternativo especificado.

Você pode desabilitar idiomas de contingência para um campo especificado configurando a opção fallbacks para falso ao definir o campo:

class Product
  include Mongoid::Document
  field :review, type: String, localize: true, fallbacks: false
end

Ao executar query de campos localizados, o Mongoid altera automaticamente os critérios de query para que correspondam à locale atual. O exemplo a seguir consulta a classe Product para uma revisão no locale en :

# Match all products with Marvelous as the review. The current locale is :en.
Product.where(review: "Marvelous!")
# The resulting MongoDB query filter: { "review.en" : "Marvelous!" }