Module: Scrivito::AttributeContent::ClassMethods

Included in:
BasicObj, BasicWidget
Defined in:
lib/scrivito/attribute_content.rb

Instance Method Summary collapse

Instance Method Details

#attribute(name, type, options = {}) ⇒ Object

Defines an attribute.

For the purpose of persisting model data in the CMS, the attributes of the model need to be defined. When defining an attribute, you specify the name under which Scrivito should persist its value as well as the type of content it is meant to contain, and, for the enum and multienum types, the selectable values.

Attributes are inherited. If, for example, the Page model defines a title attribute of the string type, the SpecialPage model, which inherits from Page, is also equipped with title. Inherited attributes can be overridden, i.e. you may redefine title in SpecialPage if you want its type to be html, for example.

Examples:

Defining attributes:

class Page < ::Obj
  attribute :my_string, :string
  attribute 'my_html', 'my_html'
  attribute :my_enum, :enum, values: %w[a b c], default: 'a'
  attribute :my_multienum, :multienum
end

Page.attribute_definitions
#=> #<Scrivito::AttributeDefinitionCollection>

Page.attribute_definitions[:my_string]
#=> #<Scrivito::AttributeDefinition>

Page.attribute_definitions[:my_string].type
#=> "string"

Page.attribute_definitions[:my_html].type
#=> "html"

Page.attribute_definitions[:my_enum].type
#=> "enum"
Page.attribute_definitions[:my_enum].values
#=> ["a", "b", "c"]

Page.attribute_definitions[:my_multienum].type
#=> "multienum"
Page.attribute_definitions[:my_multienum].values
#=> []

Inheriting attributes:

class Page < ::Obj
  attribute :title, :string
end

class SpecialPage < Page
end

SpecialPage.attribute_definitions[:title].type
#=> "string"

Overriding inherited attributes:

class Page < ::Obj
  attribute :title, :string
end

class SpecialPage < Page
  attribute :title, :html
end

Page.attribute_definitions[:title].type
#=> "string"

SpecialPage.attribute_definitions[:title].type
#=> "html"

Parameters:

  • name (Symbol, String) —

    name of the attribute.

  • type (Symbol, String) —

    type of the attribute. Scrivito supports the following types: string, stringlist, html, enum, multienum, widgetlist, reference, referencelist, link, linklist, and binary.

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

    definition options.

Options Hash (options):

  • :values (Symbol, String) —

    selectable values for enum and multienum attributes. If no values are provided for attributes of these types, the resulting array of selectable values is empty.

  • :default (Symbol, String) —

    custom default value. See DEFAULT_ATTRIBUTE_VALUES for factory defaults. See #default_for for more advanced defaults.

Returns:

  • nil

Raises:

See Also:



409
410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/scrivito/attribute_content.rb', line 409

def attribute(name, type, options = {})
  name, type, options = name.to_s, type.to_s, options
  assert_valid_attribute_name(name)
  assert_valid_attribute_type(type)
  default = options.delete(:default) || options.delete('default')
  if default
    assert_valid_attribute_default(name, type, default)
    default_for(name) { default }
  end
  own_attribute_definitions[name] = AttributeDefinition.new(name, type, options)
  nil
end

#attribute_definitions ⇒ Scrivito::AttributeDefinitionCollection

Returns the attribute definitions.

Returns:

See Also:



547
548
549
 
# File 'lib/scrivito/attribute_content.rb', line 547

def attribute_definitions
  AttributeDefinitionCollection.new(all_attribute_definitions)
end

#default_for(attribute_name, &block) ⇒ Object

Sets the default value of an attribute.

If Obj.create or Widget.new are called without providing a value for a specific custom attribute, the block is called, and its return value is used as the initial value of this attribute.

The block is called with two parameters.

The first parameter is an ActiveSupport::HashWithIndifferentAccess containing the attributes that were passed to Obj.create or Widget.new.

The second parameter is a Hash containing the context that was handed over to Obj.create or Widget.new. If the current visitor is a User, this user can be accessed by means of the :scrivito_user key contained in the provided context.

Examples:

Setting a simple default:

class MyPage < Obj
  attribute :title, :string
  default_for(:title) { 'Spam' }
end

my_page = MyPage.create
my_page.title # => 'Spam'

A default depending on the given attributes:

class MyPage < Obj
  attribute :title, :string

  default_for :title do |attributes|
    if (path = attributes[:_path]) && path.starts_with('/de')
      'Hier den Titel eingeben'
    else
      'Your title here'
    end
  end
end

my_page = MyPage.create(_path: '/en/test')
my_page.title # => 'Your title here'

my_page = MyPage.create(_path: '/de/test')
my_page.title # => 'Hier den Titel eingeben'

A more complex default, depending on the given attributes and the current user:

class MyPage < Obj
  attribute :title, :string

  default_for :title do |attributes, context|
    if use_german_title?(context[:scrivito_user], attributes[:_path])
      'Hier den Titel eingeben'
    else
      'Your title here'
    end
  end

  private

  #
  # Assuming there is a +MyUser+ model equipped with a +preferences+ method which
  # returns the preferences of the current user.
  # The +email+ of a +MyUser+ is the +id+ of the corresponding +Scrivito::User+ as set in
  # +Scrivito::Configuration.editing_auth+.
  #
  def use_german_title?(scrivito_user, path)
    scrivito_user && MyUser.find_by(email: scrivito_user.id).preferences[:locale] == 'de' ||
      path && path.starts_with?('/de')
  end
end

alice = Scrivito::User.define('[email protected]')
alice.preferences[:locale] # => 'en'

my_page = MyPage.create({_path: '/de/test'}, alice)
my_page.title # => 'Your title here'

bob = Scrivito::User.define('[email protected]')
bob.preferences[:locale] # => 'de'

my_page = MyPage.create({_path: '/en/test'}, bob)
my_page.title # => 'Hier den Titel eingeben'

Parameters:

  • attribute_name (Symbol, String) —

    the name of the attribute.

  • block (Proc) —

    that returns the default value.

Returns:

  • nil

Raises:

See Also:



519
520
521
522
523
524
 
# File 'lib/scrivito/attribute_content.rb', line 519

def default_for(attribute_name, &block)
  attribute_name = attribute_name.to_s
  raise ScrivitoError, 'No block given' unless block_given?
  attribute_defaults[attribute_name] = block
  nil
end

#description_for_editor ⇒ String

Short description of a CMS object or widget type for the UI. The description is displayed when adding new pages or widgets, for example. As a general rule, it is used whenever no widget or object instance is available. If there is, the BasicObj#description_for_editor and, respectively, BasicWidget#description_for_editor instance methods are used instead.

This method can be overridden to customize the description displayed to editors.

Returns:

  • (String) —

    the Class name



536
537
538
 
# File 'lib/scrivito/attribute_content.rb', line 536

def description_for_editor
  name
end

#hide_from_editor ⇒ Object

This method prevents UI users from creating Objs or Widgets of the given type. It does not prevent adding such objects programatically.

By default, hide_from_editor is false.

Examples:

Hiding error pages:

class ErrorPage < Obj
  hide_from_editor
end

Hiding admin widgets:

class AdminWidget < Widget
  hide_from_editor
end



593
594
595
 
# File 'lib/scrivito/attribute_content.rb', line 593

def hide_from_editor
  @hide_from_editor = true
end