supplejack_client 1.0.1

data/lib/supplejack/url_formats/item_hash.rb

@@ -0,0 +1,208 @@
+# The Supplejack Client code is Crown copyright (C) 2014, New Zealand Government,
+# and is licensed under the GNU General Public License, version 3.
+# See https://github.com/DigitalNZ/supplejack_client for details.
+#
+# Supplejack was created by DigitalNZ at the National Library of NZ
+# and the Department of Internal Affairs. http://digitalnz.org/supplejack
+
+module Supplejack
+  module UrlFormats
+    class ItemHash
+      
+      attr_accessor :params, :search, :i_unlocked, :i_locked, :h_unlocked, :h_locked
+      
+      def initialize(params={}, search=nil)
+        @params     = params || {}
+        @search     = search
+        @i_unlocked = filters_of_type(:i)
+        @i_locked   = filters_of_type(:il)
+        @h_unlocked = filters_of_type(:h)
+        @h_locked   = filters_of_type(:hl)
+      end
+      
+      def to_api_hash
+        hash = {}
+        text_value = text(params[:text])
+        hash[:text]             = text_value if text_value
+        hash[:geo_bbox]         = params[:geo_bbox] if params[:geo_bbox]
+        hash[:record_type]      = params[:record_type] || 0
+        hash[:record_type]      = hash[:record_type].to_i unless hash[:record_type]=="all"
+        hash[:page]             = (params[:page] || 1).to_i
+        hash[:per_page]         = (params[:per_page] || Supplejack.per_page).to_i
+        hash[:and]              = and_filters if and_filters.try(:any?)
+        hash[:without]          = without_filters if without_filters.try(:any?)
+        hash[:facets]           = params[:facets] if params[:facets].present?
+        hash[:facets_per_page]  = params[:facets_per_page].to_i if params[:facets_per_page].present?
+        hash[:fields]           = params[:fields] || Supplejack.fields.join(',')
+        hash[:query_fields]     = query_fields if query_fields
+        hash[:solr_query]       = params[:solr_query] if params[:solr_query].present?
+        
+        if params[:sort].present?
+          hash[:sort] = params[:sort]
+          hash[:direction] = params[:direction] || "asc"
+        end
+        
+        hash
+      end
+      
+      # Returns all the active filters for the current search
+      # These filters are used to scope the search results
+      #
+      def filters(filter_type=nil)
+        filters = {}
+        
+        symbol = filter_symbol(filter_type)
+        
+        memoized_filters = self.instance_variable_get("@#{symbol}_filters")
+        return memoized_filters if memoized_filters
+                
+        unlocked = filters_of_type(symbol.to_sym)
+        locked = filters_of_type("#{symbol}l".to_sym)
+        
+        filters = Supplejack::Util.deep_merge!(unlocked, locked)
+                
+        @all_filters = filters.dup.symbolize_keys.to_hash rescue {}
+        self.instance_variable_set("@#{symbol}_filters", @all_filters)
+        @all_filters
+      end
+      
+      def and_filters(filter_type=nil)
+        @and_filters ||= {}
+        @and_filters[filter_symbol(filter_type)] ||= filters(filter_type).reject {|filter, value| filter.to_s.match(/-(.+)/) or is_text_field?(filter)}
+      end
+
+      def is_text_field?(filter)
+        return false if filter.nil?
+        filter.to_s.split(//).last(5).join('').to_s == '_text'
+      end
+      
+      def without_filters(filter_type=nil)
+        symbol = filter_symbol(filter_type)
+        @without_filters ||= {} 
+        return @without_filters[symbol] if @without_filters[symbol]
+        
+        @without_filters[symbol] = {}
+        filters(filter_type).each_pair do |filter, value|
+          if filter.to_s.match(/-(.+)/)
+            @without_filters[symbol][$1.to_sym] = value
+          end
+        end
+        @without_filters[symbol]
+      end
+      
+      def all_filters
+        return @all_filters if @all_filters
+        self.filters
+        @all_filters
+      end
+      
+      def filter_symbol(filter_type=nil)
+        if filter_type
+          filter_type == :items ? 'i' : 'h'
+        else
+          params[:record_type].to_i == 0 ? 'i' : 'h'
+        end
+      end
+       
+      # Returns the value from the text param and joins any values from
+      # fields which end in _text (ie. creator_text)
+      #
+      # @param [ String ] default_text A string with the user query
+      #
+      def text(default_text=nil)
+        text_values = []
+        text_values << default_text if default_text.present?
+        
+        all_filters.each do |filter, value|
+          text_values << value if is_text_field?(filter)
+        end
+        
+        return nil if text_values.empty?
+        text_values.join(' ')
+      end
+      
+      # Returns the query_fields from the current search filters so that
+      # specific fields can be searched.
+      # The '_text' is removed from the end of the field name
+      #
+      def query_fields
+        query_fields = []
+                
+        all_filters.each do |filter, value|
+          if is_text_field?(filter)
+            query_fields << filter.to_s.chomp!('_text').to_sym
+          end
+        end
+        
+        return nil if query_fields.empty?
+        query_fields
+      end
+      
+      # Returns one type of filters
+      #
+      # @param [ :i, :il, :h, :hl ] filter_type The symbol of the filter type
+      #
+      def filters_of_type(filter_type)
+        params[filter_type].dup.symbolize_keys.to_hash rescue {}
+      end
+      
+      # Returns a hash options to be used for generating URL's with all the search state.
+      #
+      # @param [ Hash ] filter_options A hash of options to be able to remove or add filters
+      #
+      # @filter_option option [ Array ] :except A array of filter names to be removed
+      # @filter_options option [ Hash ] :plus A hash with filters and their values to be added
+      #
+      def options(filter_options={})
+        filter_options.reverse_merge!({:except => [], :plus => {}})
+        filter_options[:except] ||= []
+      
+        hash = {}
+        {:i => :i_unlocked, :il => :i_locked, :h => :h_unlocked, :hl => :h_locked}.each_pair do |symbol, instance_name|
+          filters = self.send(instance_name).clone || {}
+          
+          filters.each_pair do |name, value|
+            filters.delete(name) if value.blank?
+          end
+          
+          filter_options[:except].each do |exception|
+            if exception.is_a?(Hash)
+              facet, values_to_delete = exception.first
+              values_to_delete = Util.array(values_to_delete)
+              existing_values = Util.array(filters[facet])
+              new_values = existing_values - values_to_delete
+              
+              if new_values.any?
+                new_values = new_values.first if new_values.size == 1
+                filters[facet] = new_values
+              else
+                filters.delete(facet)
+              end
+            else
+              filters.delete(exception)
+            end
+          end
+      
+          if filter_options[:plus].try(:any?) && filter_options[:plus][symbol].try(:any?)
+            filters = Util.deep_merge(filters, filter_options[:plus][symbol])
+          end
+      
+          hash[symbol] = filters.symbolize_keys if filters.any?
+        end
+      
+        [:text, :direction, :sort].each do |attribute|
+          attribute_value = search.send(attribute)
+          hash.merge!(attribute => attribute_value) if attribute_value.present?
+        end
+                
+        unless filter_options[:except].include?(:page)
+          hash.merge!(:page => search.page) if search.page.present? && search.page != 1
+        end
+        
+        hash.merge!(:record_type => 1) if search.record_type > 0
+        return hash
+      end
+      
+    end
+  end
+end

data/lib/supplejack/user.rb

@@ -0,0 +1,132 @@
+# The Supplejack Client code is Crown copyright (C) 2014, New Zealand Government,
+# and is licensed under the GNU General Public License, version 3.
+# See https://github.com/DigitalNZ/supplejack_client for details.
+#
+# Supplejack was created by DigitalNZ at the National Library of NZ
+# and the Department of Internal Affairs. http://digitalnz.org/supplejack
+
+module Supplejack
+
+  # The +User+ class represents a User on the Supplejack API
+  #
+  # A User instance can have a relationship to many UserSet objects, this
+  # relationship is managed through the UserSetRelation class which adds 
+  # ActiveRecord like behaviour to the relationship.
+  #
+  # A User object can have the following values:
+  # - id
+  # - name
+  # - username
+  # - email
+  # - api_key
+  # - encrypted_password
+  #
+  class User
+    extend Supplejack::Request
+
+    attr_reader :id, :attributes, :api_key, :name, :username, :email, :encrypted_password, :sets_attributes
+    attr_accessor :use_own_api_key, :regenerate_api_key
+
+    def initialize(attributes={})
+      @attributes = attributes.try(:symbolize_keys) || {}
+      @api_key = @attributes[:api_key] || @attributes[:authentication_token]
+      @id = @attributes[:id]
+      @sets_attributes = @attributes[:sets]
+      @use_own_api_key = @attributes[:use_own_api_key] || false
+      @regenerate_api_key = @attributes[:regenerate_api_key] || false
+
+      [:name, :username, :email, :encrypted_password].each do |attr|
+        self.instance_variable_set("@#{attr}", @attributes[attr])
+      end
+    end
+
+    # Initializes a UserSetRelation class which adds behaviour to build, create
+    # find and order sets related to this particular User instance
+    #
+    # @return [ UserSetRelation ] A UserSetRelation object
+    #
+    # def sets
+    #   @sets ||= UserSetRelation.new(self)
+    # end
+
+    # Executes a PUT request to the API with the user attributes
+    #
+    # @return [ true, false ] True if the API returned a success response, false if not.
+    #
+    def save
+      begin
+        updated_user = self.class.put("/users/#{self.api_key}", {}, self.api_attributes)
+        @api_key = updated_user['user']['api_key'] if regenerate_api_key?
+        return true
+      rescue StandardError => e
+        return false
+      end
+    end
+
+    # Execures a DELETE request to the API to remove the User object.
+    #
+    # @return [ true, false ] True if the API returned a success response, false if not.
+    #
+    def destroy
+      begin
+        id_or_api_key = self.id || self.api_key
+        self.class.delete("/users/#{id_or_api_key}")
+        return true
+      rescue StandardError => e
+        return false
+      end
+    end
+
+    # Returns a Hash of attributes which will be sent with the POST request.
+    #
+    # @return [ Hash ] A hash of field names and their values
+    #
+    def api_attributes
+      attrs = {}
+    
+      [:name, :username, :email, :encrypted_password].each do |attr|
+        value = self.public_send(attr)
+        attrs[attr] = value if value.present?
+      end
+      
+      attrs[:sets] = @sets_attributes if @sets_attributes.present?
+      attrs[:authentication_token] = nil if regenerate_api_key?
+      attrs
+    end
+
+    # Returns true/false depending whether it will use it's own API Key
+    # for managing sets
+    #
+    # @return [ true/false ] False by default, true when intentionally set at user initialization.
+    #
+    def use_own_api_key?
+      !!@use_own_api_key
+    end
+
+    # Returns true/false depending whether it will regenerate it's API Key
+    #
+    # @return [ true/false ] False by default, true when intentionally set.
+    #
+    def regenerate_api_key?
+      !!@regenerate_api_key
+    end
+
+    # Executes a GET request to the API to find the user with the provided ID.
+    #
+    # @return [ Supplejack::User ] A Supplejack::User object
+    #
+    def self.find(id)
+      response = get("/users/#{id}")
+      new(response["user"])
+    end
+
+    # Executes a POST request to the API with the user attributes to create a User object.
+    #
+    # @return [ Supplejack::User ] A Supplejack::User object with recently created id and api_key.
+    #
+    def self.create(attributes={})
+      response = post("/users", {}, {user: attributes})
+      new(response["user"])
+    end
+  end
+end

data/lib/supplejack/user_set.rb

@@ -0,0 +1,349 @@
+# The Supplejack Client code is Crown copyright (C) 2014, New Zealand Government,
+# and is licensed under the GNU General Public License, version 3.
+# See https://github.com/DigitalNZ/supplejack_client for details.
+#
+# Supplejack was created by DigitalNZ at the National Library of NZ
+# and the Department of Internal Affairs. http://digitalnz.org/supplejack
+
+module Supplejack
+
+  # The +UserSet+ class represents a UserSet on the Supplejack API
+  #
+  # A UserSet instance can have many Item objects, the relationship
+  # with the Item objects is managed through the ItemRelation class which adds
+  # ActiveRecord like behaviour to the relationship.
+  #
+  # A Item object can have the following values:
+  # - id
+  # - name
+  # - description
+  # - privacy
+  # - priority
+  # - count
+  # - tags
+  # 
+  class UserSet
+    extend Supplejack::Request
+    include ActiveModel::Conversion
+    extend ActiveModel::Naming
+
+    ATTRIBUTES = [:id, :name, :description, :privacy, :url, :priority, :count, :tags, :tag_list, :homepage, :records, :created_at, :updated_at, :approved, :record]
+    attr_accessor *ATTRIBUTES
+    attr_accessor :api_key, :errors, :user
+
+    PRIVACY_STATES = ['public', 'hidden', 'private']
+    
+    def initialize(attributes={})
+      @attributes = attributes.try(:symbolize_keys) || {}
+      @user = Supplejack::User.new(@attributes[:user])
+      self.attributes = @attributes
+    end
+
+    def attributes
+      attributes = {}
+      ATTRIBUTES.each do |attribute|
+        value = self.send(attribute)
+        attributes[attribute] = value if value.present?
+      end
+      attributes
+    end
+
+    # Return a Hash of attributes which is used to extract the relevant
+    # UserSet attributes when creating or updating a UserSet
+    #
+    # @return [ Hash ] A hash with field names and their values
+    #
+    def api_attributes
+      api_attributes = {}
+      [:name, :description, :privacy, :priority, :tag_list, :homepage, :approved].each do |attr|
+        api_attributes[attr] = self.send(attr)
+      end
+      api_attributes[:records] = self.api_records
+      api_attributes
+    end
+
+    # Return a array of hashes with the format: {record_id: 123, position: 1}
+    # Each hash represents a Supplejack::Item within the UserSet
+    #
+    # This array is used to send the UserSet items information to the API.
+    #
+    # @return [ Array ] An array of Hashes.
+    #
+    def api_records
+      records = self.records.is_a?(Array) ? self.records : []
+      records.map do |record_hash| 
+        record_hash = record_hash.try(:symbolize_keys) || {}
+        if record_hash[:record_id]
+          {record_id: record_hash[:record_id], position: record_hash[:position] }
+        else
+          nil
+        end
+      end.compact
+    end
+
+    # Initializes a ItemRelation class which adds behaviour to build, create and
+    # find items related to this particular UserSet instance
+    #
+    # @return [ ItemRelation ] A ItemRelation object
+    #
+    def items
+      @items ||= ItemRelation.new(self)
+    end
+
+    # Returns the UserSet priority which defaults to 1
+    #
+    def priority
+      @priority || 1
+    end
+
+    # Returns the api_key from the UserSet or from the User which this set belongs to.
+    # 
+    def api_key
+      @api_key || @user.try(:api_key)
+    end
+
+    # Returns a comma separated list of tags for this UserSet
+    #
+    def tag_list
+      return @tag_list if @tag_list
+      self.tags.join(', ') if self.tags
+    end
+
+    def favourite?
+      self.name == "Favourites"
+    end
+
+    def private?
+      self.privacy == "private"
+    end
+
+    def public?
+      self.privacy == "public"
+    end
+
+    def hidden?
+      self.privacy == "hidden"
+    end
+
+    # Convinience method to find out if a particular record_id is part of the UserSet
+    #
+    # @param [ Integer ] A record_id
+    #
+    # @return [ true, false ] True if the provided record_id is part of the UserSet, false otherwise.
+    #
+    def has_record?(record_id)
+      !!self.items.detect {|i| i.record_id == record_id.to_i }
+    end
+
+    # Returns the record id of the associated record in a safe manner
+    #
+    # @return [Intger, nil ] the record id if it exists, false otherwise
+    def set_record_id
+      self.record['record_id'] if self.record
+    end
+
+    # Executes a POST request when the UserSet hasn't been persisted to the API, otherwise it executes
+    # a PUT request.
+    #
+    # When the API returns a error response, the errors are available through the UserSet#errors 
+    # virtual attribute.
+    #
+    # @return [ true, false ] True if the API response was successful, false if not.
+    # 
+    def save
+      begin
+        if self.new_record?
+          response = self.class.post("/sets", {api_key: self.api_key}, {set: self.api_attributes})
+          self.id = response["set"]["id"]
+        else
+          self.class.put("/sets/#{self.id}", {api_key: self.api_key}, {set: self.api_attributes})
+        end
+        Rails.cache.delete("/users/#{self.api_key}/sets") if Supplejack.enable_caching
+        return true
+      rescue StandardError => e
+        self.errors = e.inspect
+        return false
+      end
+    end
+
+    # Updates the UserSet attributes and persists it to the API
+    #
+    # @return [ true, false ] True if the API response was successful, false if not.
+    #
+    def update_attributes(attributes={})
+      self.attributes = attributes
+      self.save
+    end
+
+    # Assigns the provided attributes to the UserSet object
+    # 
+    def attributes=(attributes)
+      attributes = attributes.try(:symbolize_keys) || {}
+      attributes.each do |attr, value|
+        self.send("#{attr}=", value) if ATTRIBUTES.include?(attr)
+      end
+      self.records = ordered_records_from_array(attributes[:ordered_records]) if attributes[:ordered_records]
+    end
+
+    # Define setter methods for both created_at and updated_at so that
+    # they always return a Time object.
+    # 
+    [:created_at, :updated_at].each do |attribute|
+      define_method("#{attribute}=") do |time|
+        self.instance_variable_set("@#{attribute}", Util.time(time))
+      end
+    end
+
+    # Takes an ordered Array of record_ids and converts it into a Array
+    # of Hashes which the API expects, inferring the position value from
+    # the position of the record_id in the Array.
+    #
+    # @param [ Array ] A array of record_ids
+    #
+    # @return [ Array ] A array of hashes in the format {record_id: 1, position: 1}
+    #
+    # @example
+    #   user_set.ordered_records_from_array([89,66])      => [{record_id: 89, position: 1}, {record_id: 66, position: 2}]
+    #
+    def ordered_records_from_array(record_ids)
+      records = []
+      record_ids.each_with_index do |id, index|
+        records << {record_id: id, position: index+1}
+      end
+      records
+    end
+
+    # Returns if the UserSet is persisted to the API or not.
+    #
+    # @return [ true, false ] True if the UserSet is persisted to the API, false if not.
+    #
+    def new_record?
+      self.id.blank?
+    end
+
+    # Executes a DELETE request to the API with the UserSet ID and the user's api_key
+    # 
+    # @return [ true, false ] True if the API response was successful, false if not.
+    # 
+    def destroy
+      if self.new_record?
+        return false
+      else
+        begin
+          self.class.delete("/sets/#{self.id}", {api_key: self.api_key})
+          Rails.cache.delete("/users/#{self.api_key}/sets") if Supplejack.enable_caching
+          return true
+        rescue StandardError => e
+          self.errors = e.inspect
+          return false
+        end
+      end
+    end
+
+    def persisted?
+      !new_record?
+    end
+
+    # Fetches the UserSet information from the API again, in case it had changed.
+    # This can be useful if they items for a UserSet changed and you want the relation
+    # to have the most up to date items.
+    # 
+    def reload
+      begin
+        self.instance_variable_set("@items", nil)
+        self.attributes = self.class.get("/sets/#{self.id}")["set"]
+      rescue RestClient::ResourceNotFound => e
+        raise Supplejack::SetNotFound, "UserSet with ID #{id} was not found"
+      end
+    end
+
+    # A UserSet is viewable by anyone if it's public or hidden
+    # When the UserSet is private it's only viewable by the owner.
+    #
+    # @param [ Supplejack::User ] A Supplejack::User object
+    #
+    # @return [ true, false ] True if the user can view the current UserSet, false if not.
+    # 
+    def viewable_by?(user)
+      return true if self.public? || self.hidden?
+      self.owned_by?(user)
+    end
+
+    # Compares the api_key of the user and the api_key assigned to the UserSet
+    # to find out if the user passed is the owner of the set.
+    #
+    # @param [ Supplejack::User ] A Supplejack::User object
+    #
+    # @return [ true, false ] True if the user owns the current UserSet, false if not.
+    #
+    def owned_by?(user)
+      return false if user.try(:api_key).blank? || self.api_key.blank?
+      user.try(:api_key) == self.api_key
+    end
+
+    # Executes a GET request with the provided UserSet ID and initializes
+    # a UserSet object with the response from the API.
+    #
+    # @return [ UserSet ] A UserSet object
+    # 
+    def self.find(id, api_key=nil)
+      begin
+        response = get("/sets/#{id}")
+        attributes = response["set"] || {}
+        user_set = new(attributes)
+        user_set.api_key = api_key if api_key.present?
+        user_set
+      rescue RestClient::ResourceNotFound => e
+        raise Supplejack::SetNotFound, "UserSet with ID #{id} was not found"
+      end
+    end
+
+    # Executes a GET request to the API /sets/public endpoint to retrieve
+    # all public UserSet objects.
+    #
+    # @param [ Hash ] options Supported options: :page, :per_page
+    #
+    # @option options [ Integer ] :page The page number used to paginate through the UserSet objects
+    # @option options [ Integer ] :per_page The per_page number to select the number of UserSet objects per page.
+    #
+    # @return [ Array ] A array of Supplejack::UserSet objects
+    # 
+    def self.public_sets(options={})
+      options.reverse_merge!(page: 1, per_page: 100)
+      response = get("/sets/public", options)
+      sets_array = response["sets"] || []
+      user_sets = sets_array.map {|attrs| new(attrs) }
+      Supplejack::PaginatedCollection.new(user_sets, options[:page].to_i, options[:per_page].to_i, response["total"].to_i)
+    end
+
+    # Execute a GET request to the API /sets/home endpoint to retrieve
+    # all UserSet objects which have the :homepage flag set to true
+    #
+    # @return [ Array ] A array of Supplejack::UserSet objects
+    #
+    def self.homepage_sets
+      path = "/sets/home"
+      if Supplejack.enable_caching
+        response = Rails.cache.fetch(path, expires_in: 1.day) do
+          get(path)
+        end
+      else
+        response = get(path)
+      end
+      sets_array = response["sets"] || []
+      user_sets = sets_array.map {|attrs| new(attrs) }
+    end
+
+    # This method is normally provided by ActiveModel::Naming module, but here we have to override it
+    # so that in the Supplejack Website application it behaves as if the Supplejack::UserSet class was not under the
+    # Supplejack namespace.
+    #
+    # This is useful when using a Supplejack::UserSet object in the Rails provided routes helpers. Example:
+    #
+    #   user_set_path(@user_set)
+    # 
+    def self.model_name
+      ActiveModel::Name.new(self, nil, "UserSet")
+    end
+  end
+end