Class: Scrivito::BasicWidget

Inherits:
Object
  • Object
show all
Extended by:
AttributeContent::ClassMethods
Includes:
AttributeContent
Defined in:
lib/scrivito/basic_widget.rb

Overview

The CMS widget class

Direct Known Subclasses

Widget

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes = {}) ⇒ BasicWidget

Create a new Widget. The new Widget must be stored inside a container (i.e. an Obj or another Widget) before it can be used.

See Obj.create for a detailed overview of how to set attributes.

Examples:

Create a widget using a subclass

# you can create widgets by explicitly providing the attribute `_obj_class`
new_widget = Widget.new(_obj_class: "MyWidget")
# but it is better to simply use the constructor of a subclass
new_widget = MyWidget.new

Create a widget and store it inside an Obj

# create the widget
new_widget = Widget.new(_obj_class: "MyWidget")
# store it inside an obj
my_obj(my_widget_field: [new_widget])

Parameters:

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


81
82
83
84
 
# File 'lib/scrivito/basic_widget.rb', line 81

def initialize(attributes = {})
  @attributes_to_be_saved = self.class.prepare_attributes_for_instantiation(attributes)
  @attribute_cache = {}
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Scrivito::AttributeContent

Instance Attribute Details

#container ⇒ Object

returns the entity (Scrivito::BasicObj or Scrivito::BasicWidget) that references this widget



254
255
256
 
# File 'lib/scrivito/basic_widget.rb', line 254

def container
  @container
end

#container_attribute_name ⇒ Object

returns the name of the widget attribute that references this widget



260
261
262
 
# File 'lib/scrivito/basic_widget.rb', line 260

def container_attribute_name
  @container_attribute_name
end

Class Method Details

.attribute(name, type, options = {}) ⇒ Object Originally defined in module AttributeContent::ClassMethods

Defines an attribute.

In order to be able to persist model data in CMS you have to define its attributes. By defining an attribute you tell Scrivito under which name its value should be persisted, which type of content it will contain etc, which values are allowed etc.

Attributes are inherited, e.g. if a model Page defines an attribute title of type string and a model SpecialPage inherits from Page, then the model SpecialPage will also have the attribute title. Inherited attributes can be overridden, e.g. SpecialPage can override the inherited attribute title by defining its own title with a different type 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]
  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 following types: string, html, enum, multienum, widgetlist, reference, referencelist and binary.

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

    definition options.

Options Hash (options):

  • :values (Symbol, String) —

    allowed values for types enum and multienum. If no values are given for that types, then an empty array will be assumed.

Returns:

  • nil

Raises:

.attribute_definitions ⇒ Scrivito::AttributeDefinitionCollection Originally defined in module AttributeContent::ClassMethods

Returns the attribute definitions.

Returns:

See Also:

  • Scrivito::AttributeContent.attribute

.description_for_editor ⇒ Object Originally defined in module AttributeContent::ClassMethods

This method determines the description that is shown in the UI and defaults to class name. It can be overriden by a custom value.

.hide_from_editor ⇒ Object Originally defined in module AttributeContent::ClassMethods

This method disables the creation of Objs or Widgets of the given type using the UI. It does not prevent adding these 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

.valid_container_classes ⇒ Array<String, Symbol, Class>?

This method can be overridden in subclasses to control to which pages or widgets the given widget class can be added. This method can be used to ensure that only a special type of widget can be added to a specific container. An example for this is a TabGroupWidget that should contain widgets of the TabWidget type only, and, vice versa, a TabWidget should only be contained in a TabGroupWidget. A value of nil means that no additional restrictions are applied.

This method only further restricts the list of valid classes defined by means of AttributeContent#valid_widget_classes_for.

Examples:

class TabGroupWidget < Widget
  def valid_widget_classes_for(field_name)
    [TabWidget]
  end
end

class TabWidget < Widget
  def self.valid_container_classes
    [TabGroupWidget]
  end
end

Returns:

  • (Array<String, Symbol, Class>, nil) 


45
46
 
# File 'lib/scrivito/basic_widget.rb', line 45

def self.valid_container_classes
end

Instance Method Details

#[](attribute_name) ⇒ Object Originally defined in module AttributeContent

Returns the value of an attribute specified by its name. Passing an invalid key will not raise an error, but return nil.

Parameters:

  • attribute_name (Symbol, String) —

    the name of the attribute.

Returns:

  • the value of the attribute if it defined or nil otherwise.

#container_field_name ⇒ Object

Deprecated.

returns the name of the widget field that references this widget



267
268
269
270
271
272
 
# File 'lib/scrivito/basic_widget.rb', line 267

def container_field_name
  Scrivito::Deprecation.warn('Scrivito::BasicWidget#container_field_name is deprecated'\
    ' and will be removed in a future version.'\
    ' Please use Scrivito::BasicWidget#container_attribute_name instead.')
  container_attribute_name
end

#copy ⇒ Object

Create a copy of a Widget.

The copy will have all attributes of the original widget including its widgets. Its attributes can be accessed only after it has been stored in a widget field of an Obj, since initially the copy is not stored in any widget field.

Examples:

Duplicate the first widget in field my_widget

obj.update(my_widgets: obj.my_widgets.push(obj.my_widgets.first.copy))


127
128
129
130
131
132
133
134
135
136
 
# File 'lib/scrivito/basic_widget.rb', line 127

def copy
  attributes = {}
  attribute_definitions.each do |attribute_definition|
    attribute_name = attribute_definition.name
    attribute_value = read_attribute(attribute_name)
    attribute_value = attribute_value.map(&:copy) if attribute_definition.widgetlist?
    attributes[attribute_name] = attribute_value
  end
  self.class.new(attributes)
end

#description_for_editor ⇒ Object

This method determines the description that is shown in the widget tooltips. It can be overriden by a custom value.



317
318
319
 
# File 'lib/scrivito/basic_widget.rb', line 317

def description_for_editor
  obj_class_name
end

#destroy ⇒ Object

Destroys the Widget in the current Workspace



110
111
112
113
 
# File 'lib/scrivito/basic_widget.rb', line 110

def destroy
  new_widget_list = container[container_attribute_name] - [self]
  container.update(container_attribute_name => new_widget_list)
end

#obj_class ⇒ Scrivito::ObjClass? Originally defined in module AttributeContent

Deprecated.

Returns the obj class of this object.

Returns:

See Also:

#obj_class_name ⇒ String Originally defined in module AttributeContent

Returns the obj class name of this object.

Returns:

  • (String)

#revert ⇒ Object

Note:

This method does not support Widgets, which are new. Please use Widget#destroy to destroy them.

Note:

This method does not support Widgets, which are deleted. Please use Obj#revert to restore them.

Reverts all changes made to the Widget in the current workspace.

Raises:



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/scrivito/basic_widget.rb', line 193

def revert
  workspace.assert_revertable

  case modification
  when Modification::UNMODIFIED
    # do nothing
  when Modification::EDITED
    previous_obj_content =
        CmsRestApi.get("revisions/#{workspace.base_revision_id}/objs/#{obj.id}")
    previous_widget_content = previous_obj_content["_widget_pool"]["#{id}"]
    previous_widget_content.delete_if do |attribute_name, _|
      type_of_attribute(attribute_name) == 'widgetlist'
    end
    CmsRestApi.put("workspaces/#{workspace.id}/objs/#{obj.id}",
        { obj: {_widget_pool: {id => previous_widget_content}} })
  else
    raise ScrivitoError, "cannot revert changes, since widget is #{modification}."
  end
end

#update(attributes) ⇒ Object

Update the attributes of this Widget

See Obj.create for a detailed overview of how to set attributes

Parameters:

  • attributes (Hash) 


103
104
105
106
 
# File 'lib/scrivito/basic_widget.rb', line 103

def update(attributes)
  obj.update(_widget_pool: { self => attributes })
  reload
end

#valid_widget_classes_for(field_name) ⇒ nil, Array<Symbol, String, Class> Originally defined in module AttributeContent

Hook method to control which widget classes should be available for this page or widget. Override it to allow only certain classes or none. Must return either NilClass, or Array.

If nil is returned (default), then all widget classes will be available for this page or widget.

If an Array is returned, then it should include the desired classes. Each class must be either a String, a Symbol or the Class itself. Only these classes will be available and their order will be preserved.

Parameters:

  • field_name (String) —

    Name of the widget field.

Returns:

  • (nil, Array<Symbol, String, Class>)