basic_widget.rb in scrivito_sdk-0.70.0.rc1

- old
+ new

@@ -1,8 +1,12 @@
 module Scrivito
 
-# The CMS widget class
+# The CMS widget class. Widget classes let you create widget types for the individual kinds
+# of content editors want to place on pages or into widgets. All widget classes are based on
+# subclasses of {Scrivito::BasicWidget Widget}. As with CMS objects, the content of a widget
+# is stored in its attributes.
+# @see http://scrivito.com/page-with-widgets Creating a page type with widgets
 # @api public
 class BasicWidget
   extend AttributeContent::ClassMethods
   include AttributeContent
 
@@ -65,17 +69,17 @@
   #
   # See {Scrivito::BasicObj.create Obj.create} for a detailed overview of how to set attributes.
   # @api public
   # @param [Hash] attributes
   #
-  # @example Create a widget using a subclass
-  #   # you can create widgets by explicitly providing the attribute `_obj_class`
+  # @example Create a widget using a subclass:
+  #   # you can create widgets by explicitly providing the '_obj_class' attribute
   #   new_widget = Widget.new(_obj_class: "MyWidget")
   #   # but it is better to simply use the constructor of a subclass
   #   new_widget = MyWidget.new
   #
-  # @example Create a widget and store it inside an Obj
+  # @example 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])
   #
@@ -83,16 +87,19 @@
     @attributes_to_be_saved = self.class.prepare_attributes_for_instantiation(attributes)
     @attribute_cache = {}
   end
 
   #
-  # Creates a new {Scrivito::BasicWidget Widget}.
+  # Creates a new {Scrivito::BasicWidget Widget}. The defaults set via
+  # {Scrivito::AttributeContent::ClassMethods#default_for Widget.default_for}
+  # are taken into account.
   #
   # @api public
   #
-  # It also considers the defaults set via
-  # {Scrivito::AttributeContent::ClassMethods#default_for Widget.default_for}.
+  # @note Note that creating a widget does not implicitly persist it. The widget is only persisted
+  #   if its creation is part of the creation of the object containing it, or as the object or
+  #   widget containing it is updated.
   #
   # @param [Hash] attributes for the new widget
   # @param [Hash] context in which the object creating should happen
   # @option context [Scrivito::User] :scrivito_user current visitor
   # @return [Widget] the newly created {Scrivito::BasicWidget Widget}
@@ -110,21 +117,26 @@
 
   def revision
     obj.revision
   end
 
-  # Update the attributes of this Widget
+  # Updates the attributes of this {Scrivito::BasicWidget Widget}.
+  # See {Scrivito::BasicObj.create Obj.create} for a detailed overview of how to set attributes.
+  # @example Set the title of a specific widget contained in the 'main_content' attribute of an Obj:
+  #   obj.main_content[4].update(title: "New Title")
   #
-  # See {Scrivito::BasicObj.create Obj.create} for a detailed overview of how to set attributes
+  # @example Add a widget to the 'main_content' widgetlist attribute:
+  #   widgets = obj.main_content << MyWidget.new(title: "Fresh")
+  #   obj.update(main_content: widgets)
   # @api public
   # @param [Hash] attributes
   def update(attributes)
     obj.update(_widget_pool: { self => attributes })
     reload
   end
 
-  # Destroys the {Scrivito::BasicWidget Widget} in the current {Workspace}
+  # Destroys the {Scrivito::BasicWidget Widget} in the current {Workspace}.
   # @api public
   def destroy
     new_widget_list = container[container_attribute_name] - [self]
     container.update(container_attribute_name => new_widget_list)
   end
@@ -132,15 +144,15 @@
   #
   # Create a copy of a {Scrivito::BasicWidget Widget}.
   #
   # @api public
   #
-  # 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
-  # {Scrivito::BasicObj Obj}, since initially the copy is not stored in any widget field.
+  # The copy will have all the attributes of the original widget including its widgets.
+  # Its attributes can be accessed only after it has been stored in a +widgetlist+ field of an
+  # {Scrivito::BasicObj Obj}, since initially the copy is not stored in such a field.
   #
-  # @example Duplicate the first widget in field +my_widget+
+  # @example Duplicate the first widget contained in the +my_widget+ field.
   #   obj.update(my_widgets: obj.my_widgets.push(obj.my_widgets.first.copy))
   #
   def copy
     attributes = {}
     attribute_definitions.each do |attribute_definition|
@@ -195,13 +207,13 @@
   #
   # Reverts all changes made to the +Widget+ in the current workspace.
   #
   # @api public
   #
-  # @note This method does not support +Widget+s, which are +new+.
+  # @note This method does not support +new+ +Widget+s.
   #   Please use {Scrivito::BasicWidget#destroy Widget#destroy} to destroy them.
-  # @note This method does not support +Widget+s, which are +deleted+.
+  # @note This method does not support +deleted+ +Widget+s.
   #   Please use {Scrivito::BasicObj#revert Obj#revert} to restore them.
   #
   # @raise [ScrivitoError] If the current workspace is +published+.
   # @raise [ScrivitoError] If the +Widget+ is +new+.
   # @raise [ScrivitoError] If the +Widget+ is +deleted+.
@@ -263,23 +275,23 @@
     else
       super
     end
   end
 
-  # returns the entity ({Scrivito::BasicObj} or {Scrivito::BasicWidget}) that references this widget
+  # Returns the entity ({Scrivito::BasicObj} or {Scrivito::BasicWidget}) that references this widget.
   # @api public
   def container
     @container || container_and_attribute_name.first
   end
 
-  # returns the name of the widget attribute that references this widget
+  # Returns the name of the +widgetlist+ attribute that references this widget.
   # @api public
   def container_attribute_name
     @container_attribute_name || container_and_attribute_name.second
   end
 
-  # returns the name of the widget field that references this widget
+  # Returns the name of the 'widgetlist' field that references this widget.
   # @api public
   # @deprecated
   def container_field_name
     Scrivito::Deprecation.warn('Scrivito::BasicWidget#container_field_name is deprecated'\
       ' and will be removed in a future version.'\
@@ -326,10 +338,10 @@
     update_proc = -> { obj.widget_data_from_pool(id) }
     update_data(update_proc)
   end
 
   # @api public
-  # This method determines the description to be shown in the widget tooltips. By default,
+  # This method determines the description to be shown as widget tooltips. By default,
   # it uses the value of the +Widget.description_for_editor+ class method.
   #
   # This method can be overridden to customize the description displayed to the editor.
   #
   # @return [String] description for the editor