omeka_client 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ad08751ec7991ecc76863bf3f80e24e82e5a34f9
-  data.tar.gz: 65f8d081ee86f044ba6a8da39606a18395da6488
+  metadata.gz: 2c418f1c4a8a156799af715c94334dbe596f48b5
+  data.tar.gz: 5f3983cbd7613018f0322870882302c7861dd69f
 SHA512:
-  metadata.gz: 836c522e5ffe3984195df0b833ca1a8df3a6f18f7f2f04e184759839e846fffac0c6915b378ce56812bdaa044b6efb242fbec99cbb4b77d94c2d85b66fb724c2
-  data.tar.gz: 877faf52eb48ef0d1cec2765c6c254597c7634c2f13d806602357b8e27abceb0db117e76f524a87288007d79838a488fb1ee5b98019cae93c421fd6fb00b3604
+  metadata.gz: 182384179f38915a0159801aceb7245649e48fd3c10bb964f19c8b1c00d267c7278bdc89104b178c868d5aac6434a342374d22a331e954a4bb0d5c00090c4485
+  data.tar.gz: 6d1169b72dc03c26d3e683be72403b3ae05d401d2a4d325f4605cb1500cd93a10e912b4dd3ee396523613f615ac3d7f0d534b23212ac3fa1245b2baee46bd4a1

data/README.md

@@ -34,21 +34,26 @@ Next, create a client to interact with your Omeka site. You'll need your endpoin
 You can use the convenience methods for easy access to data. The most useful methods return classes that represent OmekaItems.
 
     item = client.omeka_items(1)
-    item.id
+
+Now you can access every piece of information returned by the Omeka API through the `data` variable.
+
+    item.data.id
     # => 1
-    item.public
+    item.data.public
     # => true
-    item.dublin_core.title
+    item.data.added
+    # => "2013-07-13T04:47:08+00:00"
+
+But since the data you probably want most are the element texts for either the Dublin Core Metadata or the Item Type Metadata, they can be accessed through methods of this type:
+
+    item.dc_title
     # => "Questions of the Soul"
-    item.dublin_core.author
+    item.dc_author
     # => "Hecker, Isaac Thomas, 1819-1888."
-    item.item_type
-    # => "book"
-    item.item_type_metadata.binding
+    item.itm_binding
     # => "cloth"
-
-    item = client.omeka_items
-    # returns array of OmekaItem instances
+    item.itm_signature
+    # => "signed by author"
 
 There are some helper methods to get other results in other forms:
 
@@ -62,12 +67,26 @@ There are some helper methods to get other results in other forms:
     puts items[0]['url']
     # => http://localhost/omeka/api/items/1
 
+Once you have an Omeka item, you can update it on the site, create a new item on the site, or delete it from the site.
+
+    # Create a new item (your local Ruby item will not point to this new item)
+    client.post_item(item)
+
+    # Update an item
+    item.dc_title = "Updated via API"
+    client.put_item(item)
+
+    # Delete an item
+    client.delete_item(item)
+
 If you want more flexibility about what you're requesting, you can use the lower-level methods.
 
     client.get('collections', 1)
 
     client.get_hash('collections', 1)
 
+You can send information to the Omeka site using the low-level methods `client.push`, `client.put`, and `client.delete`. These methods each takes a JSON object.
+
 If you just want a raw REST connection to Omeka, then you can access the underlying instance from the [Rest gem][].
 
     client.connection
@@ -78,10 +97,6 @@ You can run the tests by running `rake test`. You'll need to have an Omeka site
 
 You can generate the documentation by running `rake yard`.
 
-## Future plans
-
-For now the gem only handles GET requests. I'm going to work on making methods that pull information out of Omeka as robust as possible before I deal with POST, PUT, and DELETE. In particular, the class representations of Omeka items are important. Contributions are more than welcome.
-
 ## License
 
 This gem is licensed under the [GPLv3][], the same as Omeka.

data/lib/omeka_client/client.rb

@@ -1,10 +1,10 @@
 module OmekaClient
 
-  # 
+  #
   # A class to create clients that interact with the Omeka API
-  # 
+  #
   # @author Lincoln Mullen
-  # 
+  #
   class Client
 
     attr_accessor :endpoint, :api_key, :connection
@@ -33,7 +33,7 @@ module OmekaClient
     # @param  id [Integer] The id of the specific resource to request. Include
     #   an id to get just one item; do not include it to get all the items.
     # @param  query [Hash] Additional query parameters
-    # 
+    #
     # @return [NetHttpPersistentResponseWrapper] A wrapper around the object
     # @since 0.0.1
     def get(resource, id = nil, query = {} )
@@ -65,7 +65,7 @@ module OmekaClient
     #   "items", "collections"
     # @param  body [String] A string containing a JSON representation of the body of the item
     # @param  query = {} [Hash] Additional query parameters (optional)
-    # 
+    #
     # @return [NetHttpPersistentResponseWrapper] A wrapper around the object
     # @since 0.0.3
     def post(resource, body = nil, query = {} )
@@ -79,7 +79,7 @@ module OmekaClient
     #   "items", "collections"
     # @param  id [Integer] The id number of the Omeka resource to delete
     # @param  query = {} [Hash] Additional query parameters
-    # 
+    #
     # @return [NetHttpPersistentResponseWrapper] A wrapper around the object
     # @since 0.0.3
     def delete(resource, id, query = {} )
@@ -105,7 +105,7 @@ module OmekaClient
     #   "items", "collections"
     # @param  id [Integer] The id number of the Omeka resource to update
     # @param  query = {} [Hash] Additional query parameters
-    # 
+    #
     # @return [NetHttpPersistentResponseWrapper] A wrapper around the object
     # @since 0.0.3
     def put(resource, id, body, query = {} )
@@ -115,18 +115,18 @@ module OmekaClient
       self.connection.put(url, :body => body, :params => query)
     end
 
-    # Methods that return classes
+    # Methods that use classes
     # -------------------------------------------------------------------
 
-    # 
+    #
     # Get an array or a single Omeka item represented as an OmekaItem class
     # @param  id  [Integer] The ID of the item to return. No value gets an
     # array of all the items.
-    # @param  query = {} [Hash] Additional query parameters 
+    # @param  query = {} [Hash] Additional query parameters
     # @since  0.0.2
-    # 
+    #
     # @return [OmekaItem] An OmekaItem representation of the desired item,
-    # or an array of OmekaItems 
+    # or an array of OmekaItems
     def omeka_items(id = nil, query = {} )
       response = self.get_hash('items', id = id, query = query)
       if id.nil?
@@ -140,11 +140,32 @@ module OmekaClient
       end
     end
 
+    # Create a new item from an OmekaItem instance
+    # @param omeka_item [OmekaItem] An instance of OmekaItem
+    # @since 0.0.4
+    def post_item(omeka_item)
+      self.post("items", omeka_item.data.to_h.to_json)
+    end
+
+    # Update an item using an OmekaItem instance
+    # @param omeka_item [OmekaItem] An instance of OmekaItem
+    # @since 0.0.4
+    def put_item(omeka_item)
+      self.put("items", omeka_item.data.id, omeka_item.data.to_h.to_json)
+    end
+
+    # Delete the item represented by an OmekaItem instance
+    # @param omeka_item [OmekaItem] An instance of OmekaItem
+    # @since 0.0.4
+    def delete_item(omeka_item)
+      self.delete("items", omeka_item.data.id)
+    end
+
     # Convenience methods
     # -------------------------------------------------------------------
 
     # Get the description of the Omeka site
-    # 
+    #
     # @return [Hash] A hash of the description of the Omeka site
     def site
       self.get_hash('site')
@@ -159,9 +180,9 @@ module OmekaClient
     end
 
     # Get a list of the Omeka items
-    # 
+    #
     # TODO: Check that items are available in the resources
-    # 
+    #
     # @return [Array] Returns an array of item hashes
     # @since 0.0.1
     def items
@@ -169,9 +190,9 @@ module OmekaClient
     end
 
     # Get a list of the Omeka collections
-    # 
+    #
     # TODO: Check that items are available in the resources
-    # 
+    #
     # @return [Array] Returns an array of collection hashes
     # @since 0.0.1
     def collections

data/lib/omeka_client/omeka-item.rb

@@ -1,61 +1,64 @@
-require "ostruct"
+require "recursive-open-struct"
 
 module OmekaClient
 
-  # 
+  #
   # A class to represent an item in an Omeka site
-  # 
+  #
   # @author Lincoln Mullen
   # @since  0.0.2
-  # 
+  #
   class OmekaItem
 
-    # Instance variables for each of the main parts of the metadata
-    attr_accessor :id, :url, :public, :featured, :added, :modified, \
-    :item_type, :collection, :owner, :files, :tags, :dublin_core, \
-    :item_type_metadata, :extended_resources
+    attr_accessor :data
 
-    # 
-    # Parse the data we got from the API into handy methods
+    # Parse the data we got from the API into handy methods. All of the data
+    # from the JSON returned by the API is available as RecursiveOpenStructs
+    # through @data. The Dublin Core and Item Type Metadata fields are also
+    # available though special methods of the form dc_title and itm_field.
+    #
     # @param  hash [Hash] Uses the hash from OmekaClient::Client::get_hash
-    # 
+    #
     def initialize(hash)
+      @data = RecursiveOpenStruct.new(hash, :recurse_over_arrays => true)
 
-      # Some of these values have strings. Others return arrays or hashes.
-      @id = hash['id']
-      @url = hash['url']
-      @public = hash['public']
-      @featured = hash['featured']
-      @added = hash['added']
-      @modified = hash['modified']
-      @item_type = hash['item_type']
-      @collection = hash['collection']
-      @owner = hash['owner']
-      @files = hash['files']
-      @tags = hash['tags']
-      @extended_resources = ['extended_resources']
-
-      # OpenStruct.new requires a hash of method names and methods values,
-      # which we construct here for Dublin Core and for the Item Type
-      # Metadata. The downside is that we are discarding some data.
-      # Element names become method names: "Lesson Plan" to "lesson_plan"
-      dc_metadata = Hash.new
-      item_metadata = Hash.new
-      hash['element_texts'].each do |e|
-        if e['element_set']['name'] == "Dublin Core"
-          method_name = e['element']['name'].downcase.gsub(/\s/, '_')
-          dc_metadata[method_name] = e['text']
-        elsif e['element_set']['name'] == "Item Type Metadata"
-          method_name = e['element']['name'].downcase.gsub(/\s/, '_')
-          item_metadata[method_name] = e['text']
+      # Step through the element texts separating them into Dublin Core and
+      # Item Type Metadata elements. e is the element text hash; i is the
+      # index of the element_text in the array of element texts.
+      @data.element_texts.each_with_index do |e, i|
+        if e.element_set.name == "Dublin Core"
+          # Define a reader method that retrieves the data from this element
+          # text in @data
+          self.class.send(:define_method,
+            # The name of the method will have the form "dc_title"
+            e.element.name.downcase.gsub(/^/, 'dc_').gsub(/\s/, '_'),
+            proc{ @data.element_texts[i].text }
+            )
+          # Define a setter method that sets the data for this element text in
+          # @ data
+          self.class.send(:define_method,
+            # The name of the method will have the form "dc_title="
+            e.element.name.downcase.gsub(/^/, 'dc_').gsub(/\s/, '_').gsub(/$/, '='),
+            proc{ |value| @data.element_texts[i].text = value }
+            )
+        elsif e.element_set.name == "Item Type Metadata"
+          # Define a reader method that retrieves the data from this element
+          # text in @data
+          self.class.send(:define_method,
+            # The name of the method will have the form "itm_field"
+            e.element.name.downcase.gsub(/^/, 'itm_').gsub(/\s/, '_'),
+            proc{ @data.element_texts[i].text }
+            )
+          # Define a setter method that sets the data for this element text in
+          # @ data
+          self.class.send(:define_method,
+            # The name of the method will have the form "itm_title="
+            e.element.name.downcase.gsub(/^/, 'itm_').gsub(/\s/, '_').gsub(/$/, '='),
+            proc{ |value| @data.element_texts[i].text = value }
+            )
         end
       end
 
-      # The OpenStruct will provide methods of the style
-      # item.dublin_core.title
-      @dublin_core = OpenStruct.new(dc_metadata)
-      @item_type_metadata = OpenStruct.new(item_metadata)
-
     end
 
   end

data/lib/omeka_client/version.rb

@@ -1,4 +1,4 @@
 module OmekaClient
   # The version number
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/omeka_client.gemspec

@@ -22,6 +22,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 10.1.0"
   spec.add_development_dependency "minitest"
   spec.add_development_dependency "yard", "~> 0.8.6.2"
+  spec.add_development_dependency "pry", "~> 0.9.12.2"
 
   spec.add_dependency "rest", "~> 2.6.3"
+  spec.add_dependency "recursive-open-struct", "~> 0.4.3"
 end

data/test/client_test.rb

@@ -82,7 +82,7 @@ describe OmekaClient::Client do
   it "must be able to POST an item and then DELETE it" do
     body = '{"public":true,"featured":false,"element_texts":[{"html":false,"text":"Item Added via API","element_set":{"id":1,"url":"http:\/\/localhost\/omeka-2.1-rc1\/api\/element_sets\/1","name":"Dublin Core","resource":"element_sets"},"element":{"id":50,"url":"http:\/\/localhost\/omeka-2.1-rc1\/api\/elements\/50","name":"Title","resource":"elements"}}]}'
     client.post("items", body).code.must_equal 201
-    id = client.omeka_items.last.id
+    id = client.omeka_items.last.data.id
 
     # We can't make an assertion yet, because of a bug in the rest gem.
     client.delete("items", id)
@@ -93,12 +93,23 @@ describe OmekaClient::Client do
     body_updated = '{"featured":true,"element_texts":[{"html":false,"text":"Item Updated via API","element_set":{"id":1,"url":"http:\/\/localhost\/omeka-2.1-rc1\/api\/element_sets\/1","name":"Dublin Core","resource":"element_sets"},"element":{"id":50,"url":"http:\/\/localhost\/omeka-2.1-rc1\/api\/elements\/50","name":"Title","resource":"elements"}}]}'
     client.post("items", body_original)
     item_original = client.omeka_items.last
-    item_original.dublin_core.title.must_equal "Item Added via API"
-    item_original.featured.must_equal false
-    client.put("items", item_original.id, body_updated).code.must_equal 200
-    item_updated = client.omeka_items(item_original.id)
-    item_updated.dublin_core.title.must_equal "Item Updated via API"
-    item_updated.featured.must_equal true
+    item_original.dc_title.must_equal "Item Added via API"
+    item_original.data.featured.must_equal false
+    client.put("items", item_original.data.id, body_updated).code.must_equal 200
+    item_updated = client.omeka_items(item_original.data.id)
+    item_updated.dc_title.must_equal "Item Updated via API"
+    item_updated.data.featured.must_equal true
+  end
+
+  it "must be able to post, put, and delete an OmekaItem" do
+    item = client.omeka_items(1)
+    item.dc_title = "This item has been added via the API"
+    client.post_item(item).code.must_equal 201
+    new_item = client.omeka_items.last
+    new_item.dc_title.must_equal item.dc_title
+    new_item.dc_title = "This item has been updated via the API"
+    client.put_item(new_item).code.must_equal 200
+    client.delete_item(new_item) # can't test response code because of the bug
   end
 
 end

data/test/omeka-item_test.rb

@@ -3,75 +3,82 @@ require "omeka_client"
 
 # Set up an test client
 test_endpoint = "http://localhost/omeka-2.1-rc1/api"
-test_api_key = "c56c8f542bc98483b71896523d4faa6321de193b"
+test_api_key  = "3b036221e180af46bafa4b5e4a1db30e84e78e89"    # contributor
 client = OmekaClient::Client.new(test_endpoint, test_api_key)
-# item_array = client.omeka_items
-item_single = client.omeka_items(1)
-
+item = client.omeka_items(1)
 
 describe OmekaClient::OmekaItem do
 
-  it "should have an ID" do
-    item_single.id.must_equal 1
+  it "should represent the JSON data as a RecursiveOpenStruct" do
+    item.data.must_be_instance_of RecursiveOpenStruct
   end
 
-  it "should have a URL" do
-    item_single.url.must_be_instance_of String
+  it "should have an ID" do
+    item.data.id.must_equal 1
   end
 
   it "should have a URL" do
-    item_single.url.must_be_instance_of String
+    item.data.url.must_be_instance_of String
   end
 
   it "should know whether it's public" do
-    item_single.public.wont_be_nil
+    item.data.public.wont_be_nil
   end
 
   it "should know whether it's featured" do
-    item_single.featured.wont_be_nil
+    item.data.featured.wont_be_nil
   end
 
   it "should have a date added" do
-    item_single.added.must_be_instance_of String
+    item.data.added.must_be_instance_of String
   end
 
   it "should have a date modified" do
-    item_single.modified.must_be_instance_of String
+    item.data.modified.must_be_instance_of String
   end
 
   it "should have an item type" do
-    item_single.item_type.must_be_instance_of Hash
+    item.data.item_type.must_be_instance_of RecursiveOpenStruct
   end
 
   it "should have a collection" do
-    item_single.collection.must_be_instance_of Hash
+    item.data.collection.must_be_instance_of RecursiveOpenStruct
   end
 
   it "should have files" do
-    item_single.files.must_be_instance_of Hash
+    item.data.files.must_be_instance_of RecursiveOpenStruct
   end
 
   it "should have tags" do
-    item_single.tags.must_be_instance_of Array
+    item.data.tags.must_be_instance_of Array
   end
 
   it "should have extended resources" do
-    item_single.extended_resources.must_be_instance_of Array
+    item.data.extended_resources.must_be_instance_of Array
   end
 
-  it "should have the Dublin Core metadata" do
-    item_single.dublin_core.must_be_instance_of OpenStruct
+  it "should have methods for each of the Dublin Core metadata" do
     dc_fields = [:title, :subject, :contributor, :description, :creator, \
     :source, :publisher,  :date,  :rights, :relation, :format, :language, \
     :type, :identifier, :coverage]
     dc_fields.each do |field|
-      item_single.dublin_core.send(field).must_be_instance_of String
+      item.send("dc_#{field}").must_be_instance_of String
     end
   end
 
   it "should have the Item Type metadata" do
-    item_single.item_type_metadata.must_be_instance_of OpenStruct
-    # The item type is unpredictable, so it's hard to be more specific
+    # We're assuming we know the item type, in this case Lesson Plan
+    itm_fields = [:duration, :standards, :objectives, :materials, \
+      :lesson_plan_text]
+    itm_fields.each do |field|
+      item.send("itm_#{field}").must_be_instance_of String
+    end
+  end
+
+  it "should be able to set the Dublin Core values and access them" do
+    new_title = "My New DC Title"
+    item.dc_title = new_title
+    item.data.element_texts[0].text.must_equal new_title
   end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omeka_client
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Lincoln Mullen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-30 00:00:00.000000000 Z
+date: 2013-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.8.6.2
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.12.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.12.2
 - !ruby/object:Gem::Dependency
   name: rest
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 2.6.3
+- !ruby/object:Gem::Dependency
+  name: recursive-open-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.3
 description: A REST client to access the Omeka API
 email:
 - lincoln@lincolnmullen.com