contentful-management 0.8.0 → 0.9.0

data/lib/contentful/management/content_type_entry_methods_factory.rb

@@ -1,20 +1,41 @@
 module Contentful
   module Management
+    # Wrapper for Entry manipulation for a specific Content Type
+    # @private
     class ContentTypeEntryMethodsFactory
       attr_reader :content_type
 
+      # @private
       def initialize(content_type)
         @content_type = content_type
       end
 
+      # Gets all entries for a specific ContentType
+      #
+      # @param [Hash] params
+      # @see _ For complete option list: http://docs.contentfulcda.apiary.io/#reference/search-parameters
+      # @option params [String] 'sys.id'
+      # @option params [String] :limit
+      # @option params [String] :skip
+      # @option params [String] :order
+      #
+      # @return [Contentful::Management::Array<Contentful::Management::Entry>]
       def all(params = {})
         Entry.all(content_type.space.id, params.merge(content_type: content_type.id))
       end
 
+      # Creates an entry for a content type.
+      #
+      # @param [Hash] attributes
+      #
+      # @return [Contentful::Management::Entry]
       def create(attributes)
         Entry.create(content_type, attributes)
       end
 
+      # Instantiates an empty entry for a content type.
+      #
+      # @return [Contentful::Management::Entry]
       def new
         dynamic_entry_class = content_type.client.register_dynamic_entry(content_type.id, DynamicEntry.create(content_type))
         dynamic_entry = dynamic_entry_class.new

data/lib/contentful/management/dynamic_entry.rb

@@ -4,27 +4,30 @@ require_relative 'location'
 
 module Contentful
   module Management
+    # Wrapper for Entries with Cached Content Types
     class DynamicEntry < Contentful::Management::Entry
+      # Coercions from Contentful Types to Ruby native types
       KNOWN_TYPES = {
-          'String' => :string,
-          'Text' => :string,
-          'Symbol' => :string,
-          'Integer' => :integer,
-          'Float' => :float,
-          'Boolean' => :boolean,
-          'Date' => :date,
-          'Location' => Location
+        'String' => :string,
+        'Text' => :string,
+        'Symbol' => :string,
+        'Integer' => :integer,
+        'Float' => :float,
+        'Boolean' => :boolean,
+        'Date' => :date,
+        'Location' => Location
       }
 
+      # @private
       def self.create(content_type)
         unless content_type.is_a? ContentType
           content_type = ContentType.new(content_type)
         end
 
         fields_coercions = Hash[
-            content_type.fields.map do |field|
-              [field.id.to_sym, KNOWN_TYPES[field.type]]
-            end
+          content_type.fields.map do |field|
+            [field.id.to_sym, KNOWN_TYPES[field.type]]
+          end
         ]
 
         Class.new DynamicEntry do
@@ -33,16 +36,16 @@ module Contentful
             define_method accessor_name do
               fields[field.id.to_sym]
             end
-            define_method "#{ accessor_name }_with_locales" do
+            define_method "#{accessor_name}_with_locales" do
               fields_for_query[field.id.to_sym]
             end
-            define_method "#{ accessor_name }=" do |value|
+            define_method "#{accessor_name}=" do |value|
               if localized_or_default_locale(field, locale)
-                  @fields[locale] ||= {}
-                  @fields[locale][field.id.to_sym] = value
+                @fields[locale] ||= {}
+                @fields[locale][field.id.to_sym] = value
               end
             end
-            define_method "#{ accessor_name }_with_locales=" do |values|
+            define_method "#{accessor_name}_with_locales=" do |values|
               values.each do |locale, value|
                 if localized_or_default_locale(field, locale)
                   @fields[locale] ||= {}
@@ -61,15 +64,16 @@ module Contentful
           end
 
           define_singleton_method :to_s do
-            "Contentful::Management::DynamicEntry[#{ content_type.id }]"
+            "Contentful::Management::DynamicEntry[#{content_type.id}]"
           end
 
           define_singleton_method :inspect do
-            "Contentful::Management::DynamicEntry[#{ content_type.id }]"
+            "Contentful::Management::DynamicEntry[#{content_type.id}]"
           end
         end
       end
 
+      # @private
       def localized_or_default_locale(field, locale)
         field.localized || default_locale == locale
       end

data/lib/contentful/management/entry.rb

@@ -6,7 +6,7 @@ require_relative 'resource/field_aware'
 module Contentful
   module Management
     # Resource class for Entry.
-    # https://www.contentful.com/developers/documentation/content-management-api/#resources-entries
+    # @see _ https://www.contentful.com/developers/documentation/content-management-api/#resources-entries
     class Entry
       include Contentful::Management::Resource
       include Contentful::Management::Resource::SystemProperties
@@ -17,12 +17,41 @@ module Contentful
       attr_accessor :content_type
 
       # Gets a collection of entries.
-      # Takes an id of space and hash of parameters with optional content_type_id.
-      # Returns a Contentful::Management::Array of Contentful::Management::Entry.
+      #
+      # @param [String] space_id
+      # @param [Hash] parameters
+      # @see _ For complete option list: http://docs.contentfulcda.apiary.io/#reference/search-parameters
+      # @option parameters [String] 'sys.id' Entry ID
+      # @option parameters [String] :content_type
+      # @option parameters [Integer] :limit
+      # @option parameters [Integer] :skip
+      #
+      # @return [Contentful::Management::Array<Contentful::Management::Entry>]
       def self.all(space_id, parameters = {})
         request = Request.new(
-            "/#{ space_id }/entries",
-            parameters
+          "/#{space_id}/entries",
+          parameters
+        )
+        response = request.get
+        result = ResourceBuilder.new(response, {}, {})
+        result.run
+      end
+
+      # Gets a collection of published entries.
+      #
+      # @param [String] space_id
+      # @param [Hash] parameters
+      # @see _ For complete option list: http://docs.contentfulcda.apiary.io/#reference/search-parameters
+      # @option parameters [String] 'sys.id' Entry ID
+      # @option parameters [String] :content_type
+      # @option parameters [Integer] :limit
+      # @option parameters [Integer] :skip
+      #
+      # @return [Contentful::Management::Array<Contentful::Management::Entry>]
+      def self.all_published(space_id, parameters = {})
+        request = Request.new(
+          "/#{space_id}/public/entries",
+          parameters
         )
         response = request.get
         result = ResourceBuilder.new(response, {}, {})
@@ -30,34 +59,43 @@ module Contentful
       end
 
       # Gets a specific entry.
-      # Takes an id of space and entry.
-      # Returns a Contentful::Management::Entry.
+      #
+      # @param [String] space_id
+      # @param [String] entry_id
+      #
+      # @return [Contentful::Management::Entry]
       def self.find(space_id, entry_id)
-        request = Request.new("/#{ space_id }/entries/#{ entry_id }")
+        request = Request.new("/#{space_id}/entries/#{entry_id}")
         response = request.get
         result = ResourceBuilder.new(response, {}, {})
         result.run
       end
 
       # Creates an entry.
-      # Takes a content type object and hash with attributes of content type.
-      # Returns a Contentful::Management::Entry.
+      #
+      # @param [Contentful::Management::ContentType] content_type
+      # @param [Hash] attributes extracted from Content Type fields
+      #
+      # @return [Contentful::Management::Entry]
       def self.create(content_type, attributes)
         custom_id = attributes[:id]
         locale = attributes[:locale]
         fields_for_create = if attributes[:fields] # create from initialized dynamic entry via save
                               tmp_entry = new
                               tmp_entry.instance_variable_set(:@fields, attributes.delete(:fields) || {})
-                              Contentful::Management::Support.deep_hash_merge(tmp_entry.fields_for_query, tmp_entry.fields_from_attributes(attributes))
+                              Contentful::Management::Support.deep_hash_merge(
+                                tmp_entry.fields_for_query,
+                                tmp_entry.fields_from_attributes(attributes)
+                              )
                             else
                               fields_with_locale content_type, attributes
                             end
 
         request = Request.new(
-            "/#{ content_type.sys[:space].id  }/entries/#{ custom_id }",
-            {fields: fields_for_create},
-            nil,
-            content_type_id: content_type.id
+          "/#{content_type.sys[:space].id}/entries/#{custom_id}",
+          { fields: fields_for_create },
+          nil,
+          content_type_id: content_type.id
         )
         response = custom_id.nil? ? request.post : request.put
         result = ResourceBuilder.new(response, {}, {})
@@ -67,6 +105,11 @@ module Contentful
         entry
       end
 
+      # Gets Hash of fields for the current locale
+      #
+      # @param [String] wanted_locale
+      #
+      # @return [Hash] localized fields
       def fields(wanted_locale = default_locale)
         requested_locale = locale || wanted_locale
         @fields[requested_locale] = {} unless @fields[requested_locale]
@@ -76,16 +119,18 @@ module Contentful
       end
 
       # Updates an entry.
-      # Takes an optional hash with attributes of content type.
-      # Returns a Contentful::Management::Entry.
+      #
+      # @param [Hash] attributes extracted from Content Type fields
+      #
+      # @return [Contentful::Management::Entry]
       def update(attributes)
         fields_for_update = Contentful::Management::Support.deep_hash_merge(fields_for_query, fields_from_attributes(attributes))
 
         request = Request.new(
-            "/#{ space.id }/entries/#{ id }",
-            {fields: fields_for_update},
-            id = nil,
-            version: sys[:version]
+          "/#{space.id}/entries/#{id}",
+          { fields: fields_for_update },
+          nil,
+          version: sys[:version]
         )
         response = request.put
         result = ResourceBuilder.new(response, {}, {}).run
@@ -93,7 +138,9 @@ module Contentful
       end
 
       # If an entry is a new object gets created in the Contentful, otherwise the existing entry gets updated.
-      # See README for details.
+      # @see _ README for details.
+      #
+      # @return [Contentful::Management::Entry]
       def save
         if id
           update({})
@@ -104,13 +151,14 @@ module Contentful
       end
 
       # Publishes an entry.
-      # Returns a Contentful::Management::Entry.
+      #
+      # @return [Contentful::Management::Entry]
       def publish
         request = Request.new(
-            "/#{ space.id }/entries/#{ id }/published",
-            {},
-            id = nil,
-            version: sys[:version]
+          "/#{space.id}/entries/#{id}/published",
+          {},
+          nil,
+          version: sys[:version]
         )
         response = request.put
         result = ResourceBuilder.new(response, {}, {}).run
@@ -118,13 +166,14 @@ module Contentful
       end
 
       # Unpublishes an entry.
-      # Returns a Contentful::Management::Entry.
+      #
+      # @return [Contentful::Management::Entry]
       def unpublish
         request = Request.new(
-            "/#{ space.id }/entries/#{ id }/published",
-            {},
-            id = nil,
-            version: sys[:version]
+          "/#{space.id}/entries/#{id}/published",
+          {},
+          nil,
+          version: sys[:version]
         )
         response = request.delete
         result = ResourceBuilder.new(response, {}, {}).run
@@ -132,13 +181,14 @@ module Contentful
       end
 
       # Archives an entry.
-      # Returns a Contentful::Management::Entry.
+      #
+      # @return [Contentful::Management::Entry]
       def archive
         request = Request.new(
-            "/#{ space.id }/entries/#{ id }/archived",
-            {},
-            id = nil,
-            version: sys[:version]
+          "/#{space.id}/entries/#{id}/archived",
+          {},
+          nil,
+          version: sys[:version]
         )
         response = request.put
         result = ResourceBuilder.new(response, {}, {}).run
@@ -146,13 +196,14 @@ module Contentful
       end
 
       # Unarchives an entry.
-      # Returns a Contentful::Management::Entry.
+      #
+      # @return [Contentful::Management::Entry]
       def unarchive
         request = Request.new(
-            "/#{ space.id }/entries/#{ id }/archived",
-            {},
-            id = nil,
-            version: sys[:version]
+          "/#{space.id}/entries/#{id}/archived",
+          {},
+          nil,
+          version: sys[:version]
         )
         response = request.delete
         result = ResourceBuilder.new(response, {}, {}).run
@@ -160,9 +211,10 @@ module Contentful
       end
 
       # Destroys an entry.
-      # Returns true if succeed.
+      #
+      # @return [true, Contentful::Management::Error] success
       def destroy
-        request = Request.new("/#{ space.id }/entries/#{ id }")
+        request = Request.new("/#{space.id}/entries/#{id}")
         response = request.delete
         if response.status == :no_content
           return true
@@ -173,24 +225,30 @@ module Contentful
       end
 
       # Checks if an entry is published.
-      # Returns true if published.
+      #
+      # @return [Boolean]
       def published?
         sys[:publishedAt] ? true : false
       end
 
       # Checks if an entry is archived.
-      # Returns true if published.
+      #
+      # @return [Boolean]
       def archived?
         sys[:archivedAt] ? true : false
       end
 
       # Returns the currently supported local.
+      #
+      # @return [String] current_locale
       def locale
         sys[:locale] || default_locale
       end
 
-      # Parser for assets attributes from query.
+      # Parser for entry attributes from query.
       # Returns a hash of existing fields.
+      #
+      # @private
       def fields_for_query
         raw_fields = instance_variable_get(:@fields)
         fields_names = flatten_field_names(raw_fields)
@@ -201,14 +259,16 @@ module Contentful
         end
       end
 
+      # @private
       def flatten_field_names(fields)
-        without_locales = fields.map { |k,v| v }
+        without_locales = fields.map { |_, v| v }
         without_locales.map(&:keys).flatten.uniq
       end
 
+      # @private
       def fields_from_attributes(attributes)
         attributes.each do |id, value|
-          attributes[id] = {locale => parse_update_attribute(value)}
+          attributes[id] = { locale => parse_update_attribute(value) }
         end
       end
 
@@ -216,29 +276,29 @@ module Contentful
 
       def self.parse_attribute_with_field(attribute, field)
         case field.type
-          when ContentType::LINK then
-            {sys: {type: field.type, linkType: field.link_type, id: attribute.id}} if attribute
-          when ContentType::ARRAY then
-            parse_fields_array(attribute)
-          when ContentType::LOCATION then
-            {lat: attribute.properties[:lat], lon: attribute.properties[:lon]} if attribute
-          else
-            attribute
+        when ContentType::LINK then
+          { sys: { type: field.type, linkType: field.link_type, id: attribute.id } } if attribute
+        when ContentType::ARRAY then
+          parse_fields_array(attribute)
+        when ContentType::LOCATION then
+          { lat: attribute.properties[:lat], lon: attribute.properties[:lon] } if attribute
+        else
+          attribute
         end
       end
 
       def parse_update_attribute(attribute)
         case attribute
-          when Asset
-            self.class.hash_with_link_object('Asset', attribute)
-          when Entry
-            self.class.hash_with_link_object('Entry', attribute)
-          when Location
-            {lat: attribute.properties[:lat], lon: attribute.properties[:lon]}
-          when ::Array
-            self.class.parse_fields_array(attribute)
-          else
-            attribute
+        when Asset
+          self.class.hash_with_link_object('Asset', attribute)
+        when Entry
+          self.class.hash_with_link_object('Entry', attribute)
+        when Location
+          { lat: attribute.properties[:lat], lon: attribute.properties[:lon] }
+        when ::Array
+          self.class.parse_fields_array(attribute)
+        else
+          attribute
         end
       end
 
@@ -248,12 +308,10 @@ module Contentful
 
           Contentful::Management::Resource::FieldAware.create_fields_for_content_type(self)
 
-          if self.respond_to? name
-            return self.send(name, *args, &block)
-          end
+          return send(name, *args, &block) if respond_to? name
         end
 
-        raise NameError.new("undefined local variable or method `#{name}' for #{self.class}:#{self.sys[:id]}", name)
+        fail NameError.new("undefined local variable or method `#{name}' for #{self.class}:#{sys[:id]}", name)
       end
 
       def fetch_content_type
@@ -261,7 +319,7 @@ module Contentful
       end
 
       def self.hash_with_link_object(type, attribute)
-        {sys: {type: 'Link', linkType: type, id: attribute.id}}
+        { sys: { type: 'Link', linkType: type, id: attribute.id } }
       end
 
       def self.parse_fields_array(attributes)
@@ -272,12 +330,12 @@ module Contentful
       def self.parse_objects_array(attributes)
         attributes.each_with_object([]) do |attr, arr|
           arr << case attr
-                   when Entry then
-                     hash_with_link_object('Entry', attr)
-                   when Asset then
-                     hash_with_link_object('Asset', attr)
-                   when Hash then
-                     attr
+                 when Entry then
+                   hash_with_link_object('Entry', attr)
+                 when Asset then
+                   hash_with_link_object('Asset', attr)
+                 when Hash then
+                   attr
                  end
         end
       end
@@ -289,8 +347,8 @@ module Contentful
         attributes.keep_if { |key| field_names.include?(key) }
 
         attributes.each do |id, value|
-          field = fields.select { |field| field.id.to_sym == id.to_sym }.first
-          attributes[id] = {locale => parse_attribute_with_field(value, field)}
+          field = fields.detect { |f| f.id.to_sym == id.to_sym }
+          attributes[id] = { locale => parse_attribute_with_field(value, field) }
         end
       end
     end