supplejack_client 1.0.1

data/README.md

@@ -0,0 +1,153 @@
+# Supplejack Client
+
+The Supplejack Client is a library to abstract the interaction with the Supplejack API. It connects to the Supplejack API, and allows you to treat models as if they were in a local database.
+
+For more information on how to configure and use this application refer to the [documentation](http://digitalnz.github.io/supplejack).
+
+## Installation
+
+Add it to your Gemfile:
+
+```ruby
+gem 'supplejack_client', github: 'git@github.com:DigitalNZ/supplejack_client.git'
+```
+
+Run bundle install:
+
+```ruby
+bundle install
+```
+
+Run the installation generator:
+
+```ruby
+rails g supplejack:install
+```
+
+An initializer was created at `config/initializers/supplejack_client.rb`
+
+You should set the variables needed by the Supplejack API:
+- Api Key
+- Api URL
+
+To start using Supplejack gem you have add the following line to any plain ruby class
+
+```ruby
+class Item
+  include Supplejack::Record
+end
+```
+
+Then do `Search.new(params)` or `Item.find(id)`
+
+## Configuration
+
+Modify the initializer at `config/initializers/supplejack_client.rb`.
+
+```ruby
+Supplejack.configure do |config|
+
+  # ===> Credentials
+  # Use the api_key for your Supplejack user
+  # Please replace XXXX with your own api key
+  config.api_key = "XXXX"
+  #
+  # ===> End point
+  # For production use default url which is http://api.youapihost.org
+  config.api_url = "http://youapihost.org"
+  #
+  # ===> URL Format
+  # This is the format use for the url's in the application
+  # The default is the item hash which looks like: "text='dog'&i[content_partner]=NLNZ&i[category]=Images"
+  config.url_format = :item_hash
+  #
+  # ===> Facets
+  # The is the list of facets that are going to be requested to the api
+  # When you ask for the facets, they are going to be ordered in the
+  # order presented here
+  config.facets = [
+    :name,
+    :description,
+    :age
+  ]
+  #
+  # ===> Facet values sorting
+  # By default facet values are sorted by whatever solr returns.
+  # The sorting options are :index and :count
+  # :index means lexical sorting (Alphabetical)
+  # :count means is ordered by the number of results for each facet value
+  config.facets_sort = nil
+  #
+  # ===> Fields
+  # This is a list of fields/groups that will be requested to the API for every
+  # record. :default will return the default set of fields.
+  #
+  config.fields = [
+    :default
+  ]
+
+  # ===> Number of facet values
+  # This will limit the number of facet values returned for each facet
+  # Be carefull not to make it too high for performance reasons
+  config.facets_per_page = 10
+  #
+  # ===> Per Page
+  # Number of results returned per page
+  config.per_page = 20
+  #
+  # ===> Timeout
+  # By default the request to the API will timeout after 30 seconds
+  config.timeout = 30
+  #
+  # ===> Single value methods
+  # Some of the values returned by the API are actually multiple values
+  # so they are returned as a array. But most of the time we are only intereseted
+  # in one of those values. Here you can define which values would you like to
+  # be converted to a string.
+  config.single_value_methods = [
+    :email
+  ]
+  #
+  # ===> Search attributes
+  # The search object can store any number of attributes which are actually
+  # the filters passed to the search
+  # Here you can define which attributes you want the search to accept.
+  # This is going to allow you to do:
+  #   search = Search.new(text: 'dog', i: {category: 'Images'})
+  #   search.category
+  #
+  config.search_attributes = [
+    :category
+  ]
+  #
+  # ===> Record klass
+  # Name of the main model throught which you interact with the Supplejack API
+  # This is used to initialize objects of this class when the list of
+  # favourites is fetched.
+  #
+  config.record_klass = "Record"
+  #
+  # ===> Enable Debugging
+  # Set this flag to true in order to get display errors and the actual SOLR requests 
+  # in the logs generated by the API.
+  #
+  config.enable_debugging = true
+  #
+  # ===> Enable Caching
+  # Set this flag to true in order to cache the facet_value response and the search counts
+  #
+  config.enable_caching = true  
+end
+```
+
+## COPYRIGHT AND LICENSING


+
+### SUPPLEJACK CODE - GNU GENERAL PUBLIC LICENCE, VERSION 3


+
+Supplejack is a tool for aggregating, searching and sharing metadata records. Supplejack Client is a component of Supplejack. The Supplejack Client code is Crown copyright (C) 2014, New Zealand Government. Supplejack was created by DigitalNZ at the National Library of NZ and the Department of Internal Affairs. http://digitalnz.org/supplejack
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses / http://www.gnu.org/licenses/gpl-3.0.txt


data/Rakefile

@@ -0,0 +1,9 @@
+# The Supplejack Client code is Crown copyright (C) 2014, New Zealand Government, 
+# and is licensed under the GNU General Public License, version 3.
+# One component is a third party component. See https://github.com/DigitalNZ/supplejack_api for details. 
+# 
+# Supplejack was created by DigitalNZ at the National Library of NZ and 
+# the Department of Internal Affairs. http://digitalnz.org/supplejack
+
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'

data/lib/generators/locales/en.yml

@@ -0,0 +1,11 @@
+# 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
+
+en:
+  supplejack_client:
+    next: Next
+    previous: Previous

data/lib/generators/supplejack/install_generator.rb

@@ -0,0 +1,28 @@
+# 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 Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+
+      desc "Creates a Supplejack Client initializer."
+
+      def copy_initializer
+        template "supplejack_client.rb", "config/initializers/supplejack_client.rb"
+      end
+
+      def copy_locale
+        copy_file "../locales/en.yml", "config/locales/supplejack_client.en.yml"
+      end
+
+      def show_readme
+        readme "README"
+      end
+    end
+  end
+end

data/lib/generators/templates/README

@@ -0,0 +1,19 @@
+======================================
+
+You are almost finished:
+
+An initializer was created at config/initializers/supplejack_client.rb
+
+You should set the variables needed by the Supplejack API:
+- Api Key
+- Api URL
+
+To start using Supplejack gem you have add the following line to any plain ruby class
+
+class Item
+  include Supplejack::Record
+end
+
+Then do Search.new(params) or Item.find(id)
+
+======================================

data/lib/generators/templates/supplejack_client.rb

@@ -0,0 +1,120 @@
+# 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
+
+Supplejack.configure do |config|
+
+  # ===> Credentials
+  # Use the api_key for your Supplejack user
+  # Please replace XXXX with your own api key
+  config.api_key = "XXXX"
+  #
+  # ===> End point
+  # For production use default url which is http://api.youapihost.org
+  # config.api_url = "http://youapihost.org"
+  #
+  # ===> URL Format
+  # This is the format use for the url's in the application
+  # The default is the item hash which looks like: "text='dog'&i[content_partner]=NLNZ&i[category]=Images"
+  # config.url_format = :item_hash
+  #
+  # ===> Custom Search
+  # In case you want to filter the results through a custom search
+  # specify the slug
+  # config.custom_search = nil
+  #
+  # ===> Facets
+  # The is the list of facets that are going to be requested to the api
+  # When you ask for the facets, they are going to be ordered in the
+  # order presented here
+  config.facets = [
+    :name,
+    :description,
+    :age
+  ]
+  #
+  # ===> Facet values sorting
+  # By default facet values are sorted by whatever solr returns.
+  # The sorting options are :index and :count
+  # :index means lexical sorting (Alphabetical)
+  # :count means is ordered by the number of results for each facet value
+  # config.facets_sort = nil
+  #
+  # ===> Fields
+  # This is a list of fields/groups that will be requested to the API for every
+  # record. :default will return the default set of fields.
+  #
+  config.fields = [
+    :default
+  ]
+
+  # ===> Number of facet values
+  # This will limit the number of facet values returned for each facet
+  # Be carefull not to make it too high for performance reasons
+  # config.facets_per_page = 10
+  #
+  # ===> Per Page
+  # Number of results returned per page
+  # config.per_page = 20
+  #
+  # ===> Timeout
+  # By default the request to the API will timeout after 30 seconds
+  # config.timeout = 30
+  #
+  # ===> Single value methods
+  # Some of the values returned by the API are actually multiple values
+  # so they are returned as a array. But most of the time we are only intereseted
+  # in one of those values. Here you can define which values would you like to
+  # be converted to a string.
+  # config.single_value_methods = [
+  #   :email
+  # ]
+  #
+  # ===> Search attributes
+  # The search object can store any number of attributes which are actually
+  # the filters passed to the search
+  # Here you can define which attributes you want the search to accept.
+  # This is going to allow you to do:
+  #   search = Search.new(text: 'dog', i: {category: 'Images'})
+  #   search.category
+  #
+  # config.search_attributes = [
+  #   :category
+  # ]
+  #
+  # ===> Record klass
+  # Name of the main model throught which you interact with the Supplejack API
+  # This is used to initialize objects of this class when the list of
+  # favourites is fetched.
+  #
+  # config.record_klass = "Record"
+  #
+  # ===> Enable Debugging
+  # Set this flag to true in order to get display errors and the actual SOLR requests 
+  # in the logs generated by the API.
+  #
+  # config.enable_debugging = true
+  #
+  # ===> Enable Caching
+  # Set this flag to true in order to cache the facet_value response and the search counts
+  #
+  # config.enable_caching = true  
+  # 
+  # ===> Attribute Tag
+  # HTML tag used by default to display the record attributes
+  #
+  # config.attribute_tag = :p
+  #
+  # ===> Label Tag
+  # HTML tag used by default to display the record attributes label
+  #
+  # config.label_tag = :span
+  #
+  # ===> Label class
+  # The CSS class used by the attribute label
+  #
+  # config.label_class = "label"
+end

data/lib/supplejack/config.rb

@@ -0,0 +1,116 @@
+# 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 Config
+
+    # Default values for the supplejack configuration.
+    #
+    # These values can be overwritten in a rails initializer for example:
+    #
+    # /config/initializers/supplejack.rb
+    #
+    # Supplejack.configure do |config|
+    #   config.api_key = "xxxx"
+    #   config.api_url = "api.supplejack.org"
+    #   etc....
+    # end
+
+    API_KEY                   = nil
+    API_URL                   = 'http://api.digitalnz.org'
+    URL_FORMAT                = :item_hash
+    FACETS                    = []
+    FACETS_PER_PAGE           = 10
+    FACETS_SORT               = nil
+    PER_PAGE                  = 20
+    PAGINATION_LIMIT          = nil
+    TIMEOUT                   = 30
+    RECORD_KLASS              = 'Record'
+    SEARCH_KLASS              = nil
+    FIELDS                    = [:default]
+    SUPPLEJACK_FIELDS                = []
+    ADMIN_FIELDS              = []
+    ENABLE_DEBUGGING          = false
+    ENABLE_CACHING            = false
+    ATTRIBUTE_TAG             = :p
+    LABEL_TAG                 = :strong
+    LABEL_CLASS               = nil
+
+    VALID_OPTIONS_KEYS = [
+      :api_key,
+      :api_url,
+      :facets,
+      :facets_per_page,
+      :facets_sort,
+      :single_value_methods,
+      :search_attributes,
+      :url_format,
+      :per_page,
+      :pagination_limit,
+      :timeout,
+      :record_klass,
+      :search_klass,
+      :fields,
+      :supplejack_fields,
+      :admin_fields,
+      :enable_debugging,
+      :enable_caching,
+      :attribute_tag,
+      :label_tag,
+      :label_class
+    ]
+
+    SINGLE_VALUE_METHODS = [
+      :description
+    ]
+
+    SEARCH_ATTRIBUTES = [
+      :location
+    ]
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+
+    def configure
+      yield self
+    end
+
+    def url_format_klass
+      "Supplejack::UrlFormats::#{Supplejack.url_format.to_s.classify}".constantize
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.api_key                  = API_KEY
+      self.api_url                  = API_URL
+      self.facets                   = FACETS
+      self.facets_per_page          = FACETS_PER_PAGE
+      self.facets_sort              = FACETS_SORT
+      self.single_value_methods     = SINGLE_VALUE_METHODS
+      self.search_attributes        = SEARCH_ATTRIBUTES
+      self.url_format               = URL_FORMAT
+      self.per_page                 = PER_PAGE
+      self.pagination_limit         = PAGINATION_LIMIT
+      self.timeout                  = TIMEOUT
+      self.record_klass             = RECORD_KLASS
+      self.search_klass             = SEARCH_KLASS
+      self.fields                   = FIELDS
+      self.supplejack_fields        = SUPPLEJACK_FIELDS
+      self.admin_fields             = ADMIN_FIELDS
+      self.enable_debugging         = ENABLE_DEBUGGING
+      self.enable_caching           = ENABLE_CACHING
+      self.attribute_tag            = ATTRIBUTE_TAG
+      self.label_tag                = LABEL_TAG
+      self.label_class              = LABEL_CLASS
+      self
+    end
+  end
+end