scrivito_sdk 0.66.0 → 0.70.0.rc1

data/lib/scrivito/basic_widget.rb

@@ -1,6 +1,10 @@
 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
@@ -67,13 +71,13 @@ class BasicWidget
   # @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
@@ -85,12 +89,15 @@ class BasicWidget
   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
@@ -112,9 +119,14 @@ class BasicWidget
     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)
@@ -122,7 +134,7 @@ class BasicWidget
     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]
@@ -134,11 +146,11 @@ class BasicWidget
   #
   # @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
@@ -197,9 +209,9 @@ class BasicWidget
   #
   # @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+.
@@ -265,19 +277,19 @@ class BasicWidget
     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
@@ -328,7 +340,7 @@ class BasicWidget
   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.

data/lib/scrivito/binary.rb

@@ -1,8 +1,8 @@
 module Scrivito
 
 # @api public
-# The Binary class represents the data stored in a binary attribute of an Obj
-# or Widget
+# The Binary class represents the data stored in a binary attribute of an {Scrivito::BasicObj Obj}
+# or a {Scrivito::BasicWidget Widget}.
 class Binary
   attr_reader :id, :transformation_definition
 
@@ -29,6 +29,12 @@ class Binary
   # @api public
   # The URL for accessing the binary data and downloading it using an HTTP GET request.
   #
+  # @note The URL is calculated on demand, i.e. if the URL has not been cached yet,
+  #   this method calls the Scrivito API to retrieve the URL.
+  #   If you want to link to a Binary, consider using {Scrivito::RoutingHelper#scrivito_url}
+  #   instead. This is generally much faster,
+  #   as it performs the Scrivito API call asynchronously.
+  #
   # @note URLs for private content have an expiration time in order to protect them.
   #   Therefore, the URL should be accessed immediately after it has been returned
   #   (i.e. within a couple of minutes). Accessing it after expiration causes an error.
@@ -49,39 +55,40 @@ class Binary
   end
 
   # @api public
-  # the filename of this binary data, for example "my_image.jpg"
-  # @return [String] the filename of binary
+  # The filename of this binary data, for example "my_image.jpg".
+  # @return [String] the filename of the binary
   def filename
     File.basename(URI(url).path)
   end
 
   # @api public
-  # the content type of this binary data, for example "image/jpeg"
+  # The content type of this binary data, for example "image/jpeg".
   # @return [String] content type
   def content_type
     headers[:content_type]
   end
 
   # @api public
-  # the length of this binary data, in bytes.
+  # The length of this binary data, in bytes.
   # @return [Integer] number of bytes
   def content_length
     headers[:content_length].to_i
   end
 
   #
-  # Returns a transformed {Scrivito::Binary}.
+  # Use this method to transform images, i.e. to scale down large images or to generate thumbnails of images.
+  # Only applicable if this {Scrivito::Binary} is an image.
   #
-  # @api beta
+  # @api public
   #
-  # Calling this method will not change the binary, but instead return a copy of it,
+  # This method does not change the binary. Instead, it returns a copy of it,
   # transformed using the +definition+.
   #
-  # If the original binary has already been transformed, then the returned binary will be a
-  # combination of the transformations. Thus the transformations can be chained (see examples).
+  # If the original binary has already been transformed, the returned binary will be a
+  # combination of the transformations. Thus, the transformations can be chained (see examples).
   #
-  # The transformed data is calculated "lazily", so calling {Scrivito::Binary#transform} will not
-  # trigger any calculation. The calculation will be triggered only if data is accessed, for example
+  # The transformed data is calculated "lazily", so calling {Scrivito::Binary#transform} does not
+  # trigger any calculation. The calculation is triggered only when data is accessed, for example
   # via {Scrivito::Binary#url}.
   #
   # @param [Hash] definition transformation definition
@@ -89,87 +96,90 @@ class Binary
   # @option definition [Fixnum,String] :width The width in pixels of the output image. Must be a
   #   positive integer.
   #
-  #   If only this dimension is specified, the other dimension will be calculated automatically to
+  #   If only this dimension has been specified, the other dimension is calculated automatically to
   #   preserve the aspect ratio of the input image.
   #
-  #   If the +fit+ parameter is set to +:clip+, then the actual output one of width and height may
-  #   be equal to or less than the dimensions you specify to prevent distortion.
+  #   If the +fit+ parameter is set to +:clip+, then either the actual output width or the output
+  #   height may be less than the amount you specified to prevent distortion.
   #
   #   If neither +width+ nor +height+ is given, the width and height of the input image
-  #   will be used.
+  #   is used.
   #
-  #   The maximum output image size width + height = 4096 pixels. The given width and height may be
-  #   adjusted to accomodate this limit. The output image will never be larger than the source
-  #   image, i.e. the given width and height may be adjusted to keep the output image from exceeding
-  #   the dimensions of the input image.
+  #   The maximum size of the output image is defined as width + height = 4096 pixels. The given
+  #   width and height may be adjusted to accommodate this limit. The output image will never be
+  #   larger than the source image, i.e. the given width and height may be adjusted to prevent the
+  #   dimensions of the output image from exceeding those of the input image.
   #
-  #   When the given width and height are adjusted, the aspect ratio is preserved.
+  #   If the given width and height are adjusted, the aspect ratio is preserved.
   #
   # @option definition [Fixnum,String] :height The height in pixels of the output image. Must be a
   #   positive integer.
   #
-  #   If only this dimension is specified, the other dimension will be calculated automatically to
+  #   If only this dimension has been specified, the other dimension is calculated automatically to
   #   preserve the aspect ratio of the input image.
   #
-  #   If the +fit+ parameter is set to +:clip+, then the actual output one of width and height may
-  #   be equal to or less than the dimensions you specify to prevent distortion.
+  #   If the +fit+ parameter is set to +:clip+, then either the actual output width or the output
+  #   height may be less than the amount you specified to prevent distortion.
   #
   #   If neither +width+ nor +height+ is given, the width and height of the input image
-  #   will be used.
+  #   is used.
   #
-  #   The maximum output image size width + height = 4096 pixels. The given width and height may be
-  #   adjusted to accomodate this limit. The output image will never be larger than the source
-  #   image, i.e. the given width and height may be adjusted to keep the output image from exceeding
-  #   the dimensions of the input image.
+  #   The maximum size of the output image is defined as width + height = 4096 pixels. The given
+  #   width and height may be adjusted to accommodate this limit. The output image will never be
+  #   larger than the source image, i.e. the given width and height may be adjusted to prevent the
+  #   dimensions of the output image from exceeding those of the input image.
   #
-  #   When the given width and height are adjusted, the aspect ratio is preserved.
+  #   If the given width and height are adjusted, the aspect ratio is preserved.
   #
   # @option definition [Symbol,String] :fit Controls how the tranformed image is fitted to the
   #   given width and heigth. Valid values are +:clip+ and +:crop+. The default value is +:clip+.
   #
-  #   If set to +:clip+ it resizes the image to fit within the width and height boundaries without
-  #   cropping or distorting the image. The resulting image is assured to match one of the
+  #   If set to +:clip+, the image is resized so as to fit within the width and height boundaries
+  #   without cropping or distorting the image. The resulting image is assured to match one of the
   #   constraining dimensions, while the other dimension is altered to maintain the same aspect
   #   ratio of the input image.
   #
-  #   If set to +:crop+ it resizes the image to fill the given width and height and preserves the
-  #   aspect ration by cropping any excess image data. The resulting image will match both the given
-  #   width and height without distorting the image. The crop is done centered, i.e. the center of
+  #   If set to +:crop+, the image is resized so as to fill the given width and height, preserving
+  #   the aspect ratio by cropping any excess image data. The resulting image will match both the given
+  #   width and height without distorting the image. Cropping is done centered, i.e. the center of
   #   the image is preserved.
   #
   # @option definition [Fixnum,String] :quality Controls the output quality of lossy file formats.
-  #   Applies when the format is +"jpg"+. Valid values are in the range from +0+ to +100+.
+  #   Applies if the format is +"jpg"+. Valid values are in the range from +0+ to +100+.
   #   The default value is +75+.
   #
   # @return [Scrivito::Binary] transformed binary
   #
-  # @example Crop image to fit into 50 x 50 pixel square
+  # @example Crop image to fit into 50 x 50 pixel square.
   #   @obj.blob.transform(width: 50, height: 50, fit: :crop)
   #
-  # @example Convert image to a low quality JPEG
+  # @example Convert image to a low quality JPEG.
   #   @obj.blob.transform(quality: 25)
   #
-  # @example Combine the both transformations
+  # @example Combine two transformations.
   #   @obj.blob.transform(width: 50, height: 50, fit: :crop).transform(quality: 25)
   #
+  # @see Scrivito::Configuration
+  # @see ScrivitoHelper#scrivito_image_tag
+  #
   def transform(definition)
     self.class.new(id, public?, (transformation_definition || {}).merge(definition), original)
   end
 
   #
-  # Returns whether a binary is transformed.
-  # @api beta
+  # Returns whether a binary has been transformed.
+  # @api public
   #
   def transformed?
     !!transformation_definition
   end
 
   #
-  # Returns the transformation original of a binary.
+  # Returns the original version of a transformed binary.
   #
-  # @api beta
+  # @api public
   #
-  # If a binary is a result of a transformation, then its original binary is returned.
+  # If a binary is the result of a transformation, the original version of the binary is returned.
   # Otherwise +self+.
   #
   # @return [Scrivito::Binary] original binary
@@ -184,6 +194,13 @@ class Binary
     @original || self
   end
 
+  def meta_data
+    @meta_data ||= begin
+      deserialized_meta_data = deserialize_meta_data(CmsBackend.instance.find_binary_meta_data(id))
+      MetaDataCollection.new(deserialized_meta_data)
+    end
+  end
+
   private
 
   def public_content?
@@ -211,6 +228,18 @@ class Binary
   def access_type
     public? ? 'public_access' : 'private_access'
   end
+
+  def deserialize_meta_data(raw_meta_data)
+    deserialized_meta_data = {}
+    raw_meta_data.each_pair do |key, (type, value)|
+      deserialized_meta_data[key] = case type
+                                    when 'date' then DateAttribute.parse(value)
+                                    when 'number' then value.to_i
+                                    else value
+                                    end
+    end
+    deserialized_meta_data
+  end
 end
 
 end

data/lib/scrivito/binary_routing.rb

@@ -0,0 +1,52 @@
+module Scrivito
+
+class BinaryRouting < Struct.new(:request, :scrivito_engine)
+  def binary_url(binary)
+    binary_url_from_cache(binary) || binary_redirect_url(binary)
+  end
+
+  def binary_obj_url(obj, binary, image_options = {})
+    binary = if image_options.has_key?(:transform)
+      apply_custom_transformation(binary, image_options[:transform])
+    else
+      apply_default_transformation(binary, obj)
+    end
+    binary_url(binary)
+  end
+
+  def resolved_binary_obj_url(obj, binary)
+    apply_default_transformation(binary, obj).url
+  end
+
+  private
+
+  def binary_url_from_cache(binary)
+    if url_from_cache = binary.url_from_cache
+      BinaryRewrite.call(request, url_from_cache)
+    end
+  end
+
+  def binary_redirect_url(binary)
+    encrypted_params = BinaryParamVerifier.generate(binary)
+    scrivito_engine.binary_path(encrypted_params: encrypted_params)
+  end
+
+  def apply_custom_transformation(binary, transformation_definition)
+    if transformation_definition
+      binary.transform(transformation_definition)
+    else
+      binary
+    end
+  end
+
+  def apply_default_transformation(binary, obj)
+    if (transformation_definition = Scrivito::Configuration.default_image_transformation) &&
+        obj.apply_image_transformation?
+      binary.transform(transformation_definition)
+    else
+      binary
+    end
+  end
+end
+
+end

data/lib/scrivito/cache_middleware.rb

@@ -7,7 +7,6 @@ class CacheMiddleware
 
   def call(env)
     clear_caches
-    clear_runtime
 
     @app.call(env)
   end
@@ -15,10 +14,6 @@ class CacheMiddleware
 
   private
 
-  def clear_runtime
-    Scrivito::LogSubscriber.reset_runtime
-  end
-
   def clear_caches
     Workspace.cache.clear
     CmsBackend.instance.clear_cache

data/lib/scrivito/client_attribute_serializer.rb

@@ -0,0 +1,134 @@
+module Scrivito
+
+module ClientAttributeSerializer
+  def self.serialize_obj(obj)
+    serialized_output = {}
+
+    # system attributes
+    serialized_output.merge!(serialize_system_attrs(obj))
+
+    # custom attributes
+    serialized_output.merge!(serialize_custom_attrs(obj))
+
+    # _widget_pool
+    serialized_output.merge!(serialize_widget_pool(obj.widgets))
+
+    serialized_output
+  end
+
+  def self.serialize_system_attrs(obj)
+    {
+      '_id'        => obj.id,
+      '_obj_class' => obj.obj_class_name,
+      '_path'      => obj.path,
+      '_permalink' => obj.permalink,
+    }
+  end
+
+  def self.serialize_custom_attrs(obj_or_widget)
+    Hash[
+      obj_or_widget.attribute_definitions.map do |definition|
+        name = definition.name
+        type = definition.type
+        value = obj_or_widget[name]
+
+        [name, serialize_custom_attr_value(type, value)]
+      end
+    ]
+  end
+
+  def self.serialize_widget_pool(widgets)
+    {
+      '_widget_pool' => Hash[
+        widgets.map do |widget|
+          [widget.id, serialize_widget(widget)]
+        end
+      ]
+    }
+  end
+
+  def self.serialize_custom_attr_value(type, value)
+    return unless value
+
+    case type
+    when 'binary'        then serialize_binary_value(value)
+    when 'date'          then serialize_date_value(value)
+    when 'enum'          then serialize_enum_value(value)
+    when 'html'          then serialize_html_value(value)
+    when 'link'          then serialize_link_value(value)
+    when 'linklist'      then serialize_linklist_value(value)
+    when 'multienum'     then serialize_multienum_value(value)
+    when 'reference'     then serialize_reference_value(value)
+    when 'referencelist' then serialize_referencelist_value(value)
+    when 'string'        then serialize_string_value(value)
+    when 'stringlist'    then serialize_stringlist_value(value)
+    when 'widgetlist'    then serialize_widgetlist_value(value)
+    end
+  end
+
+  def self.serialize_binary_value(value)
+    {'url' => value.url, 'filename' => value.filename}
+  end
+
+  def self.serialize_date_value(value)
+    value.utc.iso8601
+  end
+
+  def self.serialize_enum_value(value)
+    value
+  end
+
+  def self.serialize_html_value(value)
+    value
+  end
+
+  def self.serialize_link_value(value)
+    value.to_cms_api_linklist_params.stringify_keys
+  end
+
+  def self.serialize_linklist_value(value)
+    value.map do |link|
+      serialize_link_value(link)
+    end
+  end
+
+  def self.serialize_multienum_value(value)
+    value.map do |enum|
+      serialize_enum_value(enum)
+    end
+  end
+
+  def self.serialize_reference_value(value)
+    value.id
+  end
+
+  def self.serialize_referencelist_value(value)
+    value.map do |reference|
+      serialize_reference_value(reference)
+    end
+  end
+
+  def self.serialize_string_value(value)
+    value
+  end
+
+  def self.serialize_stringlist_value(value)
+    value.map do |string|
+      serialize_string_value(string)
+    end
+  end
+
+  def self.serialize_widgetlist_value(value)
+    value.map do |widget|
+      widget.id
+    end
+  end
+
+  def self.serialize_widget(widget)
+    {
+      '_obj_class' => widget.obj_class_name
+    }.merge(serialize_custom_attrs(widget))
+  end
+end
+
+end