activesp 0.0.1 → 0.0.4

data/lib/activesp/folder.rb

@@ -1,38 +1,101 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the "Software"), to deal in the Software without
+# restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following
+# conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# 
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# 
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
 module ActiveSP
   
   class Folder < Item
     
+    # See {Base#key}
+    # @return [String]
     def key
-      encode_key("F", [parent.key, @id])
+      encode_key("F", [@list.key, @id])
     end
     
-    def items(options = {})
-      @list.items(options.merge(:folder => self))
+    def is_folder?
+      false
     end
     
+    # Returns the list of items in this folder
+    # @param [Hash] options See {List#each_item}, :folder option has no effect
+    # @return [Array<Item>]
+    def each_item(options = {}, &blk)
+      @list.each_item(options.merge(:folder => self), &blk)
+    end
+    association :items
+    
+    def each_folder(options = {}, &blk)
+      @list.each_folder(options.merge(:folder => self), &blk)
+    end
+    association :folders do
+      def create(parameters = {})
+        @object.create_folder(parameters)
+      end
+    end
+    
+    def create_folder(parameters = {})
+      @list.create_folder(parameters.merge(:folder => absolute_url))
+    end
+    
+    def each_document(options = {}, &blk)
+      @list.each_document(options.merge(:folder => self), &blk)
+    end
+    association :documents do
+      def create(parameters = {})
+        @object.create_document(parameters)
+      end
+    end
+    
+    def create_document(parameters = {})
+      @list.create_document(parameters.merge(:folder => absolute_url))
+    end
+    
+    # Returns the item with the given name
+    # @param [String] name
+    # @return [Item]
     def item(name)
       query = Builder::XmlMarkup.new.Query do |xml|
         xml.Where do |xml|
           xml.Eq do |xml|
             xml.FieldRef(:Name => "FileLeafRef")
-            xml.Value(name, :Type => "String")
+            xml.Value(name, :Type => "Text")
           end
         end
       end
       items(:query => query).first
     end
     
-    def /(name)
-      item(name)
-    end
+    alias / item
     
-    undef attachments
-    undef content_urls
+    undef content
     
+    # @private
     def to_s
       "#<ActiveSP::Folder url=#{url}>"
     end
     
+    # @private
     alias inspect to_s
     
   end

data/lib/activesp/ghost_field.rb

@@ -1,21 +1,90 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the "Software"), to deal in the Software without
+# restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following
+# conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# 
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# 
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
 module ActiveSP
   
+  # This class represents the field definitions for objects in SharePoint for which the
+  # fields cannot be changed and are thus not represented by an object in SharePoint.
+  # These include fields of sites, lists, users, grouos, roles, content types and fields.
+  # The interface of this class is not as complete as the interface if a Field, mainly
+  # because it does not make much sense to do so
   class GhostField
     
     include Util
     
+    # @private
     attr_reader :Name, :internal_type, :Mult, :ReadOnly
     
+    # @private
     def initialize(name, type, mult, read_only)
       @Name, @internal_type, @Mult, @ReadOnly = name, type, mult, read_only
     end
     
+    # @private
     def Type
       translate_internal_type(self)
     end
     
+    # Returns the attributes of this object as a Hash
+    # @return [Hash{String => Integer, Float, String, Time, Boolean, Base}]
     def attributes
-      @attributes ||= {
+      original_attributes.dup
+    end
+    
+    # Returns the value of the attribute of the given name, or nil if this object does not have an attribute by the given name
+    # @param [String] name The name of the attribute
+    # @return [Integer, Float, String, Time, Boolean, Base]
+    def attribute(name)
+      current_attributes[name]
+    end
+    
+    # Returns whether or not this object has an attribute with the given name
+    # @param [String] name The name of the attribute
+    # @return [Boolean]
+    def has_attribute?(name)
+      current_attributes.has_key?(name)
+    end
+    
+    # See {Base#method_missing}
+    def method_missing(m, *a, &b)
+      ms = m.to_s
+      if a.length == 0 && has_attribute?(ms)
+        attribute(ms)
+      else
+        super
+      end
+    end
+    
+  private
+    
+    def current_attributes
+      original_attributes
+    end
+    
+    def original_attributes
+      @original_attributes ||= {
         "ColName" => @Name,
         "DisplayName" => @Name,
         "Mult" => @Mult,

data/lib/activesp/group.rb

@@ -1,3 +1,28 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the "Software"), to deal in the Software without
+# restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following
+# conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# 
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# 
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
 module ActiveSP
   
   class Group < Base
@@ -7,35 +32,49 @@ module ActiveSP
     include Util
     include InSite
     
-    # attr_reader :name
-    
     persistent { |site, name, *a| [site.connection, [:group, name]] }
+    # @private
     def initialize(site, name)
       @site, @name = site, name
     end
     
+    # See {Base#key}
+    # @return [String]
     def key
       encode_key("G", [@name])
     end
     
+    # Returns the list of users in this group
+    # @return [User]
     def users
       call("UserGroup", "get_user_collection_from_group", "groupName" => @name).xpath("//spdir:User", NS).map do |row|
         attributes = clean_attributes(row.attributes)
         User.new(@site, attributes["LoginName"])
       end
     end
-    cache :users, :dup => true
+    cache :users, :dup => :always
+    
+    # Returns false. The same method is present on {Role} where it returns true. Roles and groups can generally be
+    # duck-typed, and this method is there for the rare case where you do need to make the distinction
+    # @return [Boolean]
+    def is_role?
+      false
+    end
     
+    # See {Base#save}
+    # @return [void]
+    def save
+      p untype_cast_attributes(@site, nil, internal_attribute_types, changed_attributes)
+    end
+    
+    # @private
     def to_s
       "#<ActiveSP::Group name=#{@name}>"
     end
     
+    # @private
     alias inspect to_s
     
-    def is_role?
-      false
-    end
-    
   private
     
     def data

data/lib/activesp/item.rb

@@ -1,3 +1,28 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the "Software"), to deal in the Software without
+# restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following
+# conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# 
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# 
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
 module ActiveSP
   
   class Item < Base
@@ -6,56 +31,151 @@ module ActiveSP
     extend Caching
     include Util
     
+    # Returns the list in which the item is located
+    # @return [List]
     attr_reader :list
     
-    def initialize(list, id, folder, uid = nil, url = nil, attributes_before_type_cast = nil)
-      @list, @id, @folder = list, id, folder
+    # @private
+    def initialize(list, id, folder = :unset, uid = nil, url = nil, attributes_before_type_cast = nil)
+      @list, @id = list, id
+      @folder = folder if folder != :unset # We have to allow for nil
       @uid = uid if uid
       @site = list.site
       @url = url if url
       @attributes_before_type_cast = attributes_before_type_cast if attributes_before_type_cast
     end
     
+    def ID
+      @id
+    end
+    
+    def is_folder?
+      false
+    end
+    
+    # Returns the folder, if any, that this item is located in.
+    # @return [Folder, nil]
+    def folder
+      query = Builder::XmlMarkup.new.Query do |xml|
+        xml.Where do |xml|
+          xml.Eq do |xml|
+            xml.FieldRef(:Name => "FileRef")
+            xml.Value(::File.dirname(url), :Type => "Text")
+          end
+          xml.Eq do |xml|
+            xml.FieldRef(:Name => "FSObjType")
+            xml.Value(1, :Type => "Text")
+          end
+        end
+      end
+      @list.items(:folder => :all, :query => query).first
+    end
+    cache :folder
+    
+    # Returns the parent of this item.
+    # @return [Folder, List]
     def parent
-      @folder || @list
+      folder || @list
     end
     
+    # @private
     def id
       uid
     end
     
+    # @private
     def uid
       attributes["UniqueID"]
     end
     cache :uid
     
+    # The URL of this item
+    # @return [String]
     def url
-      URL(@list.url).join(attributes["ServerUrl"]).to_s
+      # URL(@list.url).join(attributes["ServerUrl"]).to_s
+      attributes["ServerUrl"]
     end
     cache :url
     
+    def absolute_url
+      URL(@list.url).join(attributes["ServerUrl"]).to_s
+    end
+    cache :absolute_url
+    
+    # See {Base#key}
+    # @return [String]
     def key
-      encode_key("I", [parent.key, @id])
+      encode_key("I", [@list.key, @id])
     end
     
-    def attachments
-      result = call("Lists", "get_attachment_collection", "listName" => @list.id, "listItemID" => @id)
-      result.xpath("//sp:Attachment", NS).map { |att| att.text }
+    # Returns a list of the URLs of the attachments of this item. Note that for items in a document
+    # library, this returns an empty list
+    # @return [Array<String>]
+    def attachment_urls
+      @list.when_list do
+        result = call("Lists", "get_attachment_collection", "listName" => @list.id, "listItemID" => @id)
+        return result.xpath("//sp:Attachment", NS).map { |att| att.text }
+      end
+      @list.when_document_library { raise TypeError, "a document library does not support attachments" }
+      @list.raise_on_unknown_type
     end
-    cache :attachments, :dup => true
+    cache :attachment_urls, :dup => :always
     
-    def content_urls
-      case @list.attributes["BaseType"]
-      when "0", "5"
-        attachments
-      when "1"
-        [url]
-      else
-        raise "not yet BaseType = #{@list.attributes["BaseType"].inspect}"
+    # Yields each attachment as a ActiveSP::File object.
+    # 
+    def each_attachment
+      attachment_urls.each { |url| yield ActiveSP::File.new(self, url, true) }
+    end
+    
+    def add_attachment(parameters = {})
+      @list.when_list do
+        parameters = parameters.dup
+        content = parameters.delete(:content) or raise ArgumentError, "Specify the content in the :content parameter"
+        file_name = parameters.delete(:file_name) or raise ArgumentError, "Specify the file name in the :file_name parameter"
+        result = call("Lists", "add_attachment", "listName" => @list.ID, "listItemID" => self.ID, "fileName" => file_name, "attachment" => Base64.encode64(content.to_s))
+        add_result = result.xpath("//sp:AddAttachmentResult", NS).first
+        if add_result
+          clear_cache_for(:attachment_urls)
+          return ActiveSP::File.new(self, add_result.text, true)
+        else
+          raise "cannot add attachment"
+        end
+      end
+      @list.when_document_library { raise TypeError, "a document library does not support attachments" }
+      @list.raise_on_unknown_type
+    end
+    
+    association :attachments do
+      def create(parameters = {})
+        @object.add_attachment(parameters)
       end
     end
-    cache :content_urls, :dup => true
     
+    def content
+      @list.when_list { raise TypeError, "a list has attachments" }
+      @list.when_document_library { return ActiveSP::File.new(self, url, false) }
+      @list.raise_on_unknown_type
+    end
+    
+    def content=(data)
+      @list.when_list { raise TypeError, "a list has attachments" }
+      @list.when_document_library { @list.create_document(:overwrite => true, :content => data, "FileLeafRef" => original_attributes["FileLeafRef"]) }
+      @list.raise_on_unknown_type
+    end
+    
+    # Returns a list of the content URLs for this item. For items in document libraries, this
+    # returns the url, for other items this returns the attachments. These URLs can be used
+    # to download all contents. See {Connection#fetch}
+    # @return [Array<String>]
+    def content_urls
+      @list.when_list { return attachment_urls }
+      @list.when_document_library { return is_folder? ? [] : [url] }
+      @list.raise_on_unknown_type
+    end
+    cache :content_urls, :dup => :always
+    
+    # Returns the content type of this item
+    # @return [ContentType]
     def content_type
       ContentType.new(@site, @list, attributes["ContentTypeId"])
     end
@@ -65,15 +185,99 @@ module ActiveSP
     #   call("Versions", "get_versions", "fileName" => attributes["ServerUrl"])
     # end
     
+    # See {Base#save}
+    # @return [self]
+    def save
+      update_attributes_internal(untype_cast_attributes(@site, nil, internal_attribute_types, changed_attributes))
+      self
+    end
+    
+    def check_out
+      @list.when_list { raise TypeError, "cannot check out list items; they would disappear" }
+      @list.raise_on_unknown_type
+      result = call("Lists", "check_out_file", "pageUrl" => absolute_url, "checkoutToLocal" => false)
+      checkout_result = result.xpath("//sp:CheckOutFileResult", NS).first.text
+      if checkout_result == "true"
+        self
+      else
+        raise "cannot check out this item"
+      end
+    end
+    
+    def check_in(options = {})
+      options = options.dup
+      type = options.delete(:type) or raise ArgumentError, ":type parameter not specified"
+      comment = options.delete(:comment)
+      options.empty? or raise ArgumentError, "unsupported options #{options.keys.map { |k| k.inspect }.join(", ")}"
+      @list.when_list { raise TypeError, "cannot check in list items because you can't check them out" }
+      @list.raise_on_unknown_type
+      if checkin_type = { :minor => 0, :major => 1, :overwrite => 2 }[type]
+        if type == :minor && !@list.attribute("EnableMinorVersion")
+          raise TypeError, "this list does not support minor versions"
+        end
+        result = call("Lists", "check_in_file", "pageUrl" => absolute_url, "comment" => comment, "CheckinType" => checkin_type)
+        checkin_result = result.xpath("//sp:CheckInFileResult", NS).first.text
+        if checkin_result == "true"
+          self
+        else
+          raise "cannot check in this item"
+        end
+      else
+        raise ArgumentError, "invalid checkin type #{type.inspect}, valid values are :minor, :major and :overwrite"
+      end
+    end
+    
+    def cancel_checkout
+      @list.when_list { raise TypeError, "cannot undo check-out for list items because you can't check them out" }
+      @list.raise_on_unknown_type
+      result = call("Lists", "undo_check_out", "pageUrl" => absolute_url)
+      cancel_result = result.xpath("//sp:UndoCheckOutResult", NS).first.text
+      if cancel_result == "true"
+        self
+      else
+        raise "cannot cancel check-out for this item"
+      end
+    end
+    
+    def update_attributes(attributes)
+      attributes.each do |k, v|
+        set_attribute(k, v)
+      end
+      save
+    end
+    
+    def destroy
+      updates = Builder::XmlMarkup.new.Batch("OnError" => "Continue", "ListVersion" => 1) do |xml|
+        xml.Method("ID" => 1, "Cmd" => "Delete") do
+          xml.Field(self.ID, "Name" => "ID")
+        end
+      end
+      result = call("Lists", "update_list_items", "listName" => @list.id, "updates" => updates)
+      create_result = result.xpath("//sp:Result", NS).first
+      error_code = create_result.xpath("./sp:ErrorCode", NS).first.text.to_i(0)
+      if error_code == 0
+        @ID = nil
+      else
+        raise "cannot create item, error code = #{error_code}"
+      end
+      self
+    end
+    
+    # @private
     def to_s
       "#<ActiveSP::Item url=#{url}>"
     end
     
+    # @private
     alias inspect to_s
     
+    def ==(object)
+      ::ActiveSP::List === object && self.ID == object.ID
+    end
+    
   private
     
-    def data
+    def raw_attributes
       query_options = Builder::XmlMarkup.new.QueryOptions do |xml|
         xml.Folder
       end
@@ -85,13 +289,14 @@ module ActiveSP
           end
         end
       end
-      result = call("Lists", "get_list_items", "listName" => @list.id, "viewFields" => "<ViewFields></ViewFields>", "queryOptions" => query_options, "query" => query)
-      result.xpath("//z:row", NS).first
+      @list.__each_item(query_options, "query" => query) do |attributes|
+        return attributes
+      end
     end
-    cache :data
+    cache :raw_attributes
     
     def attributes_before_type_cast
-      clean_item_attributes(data.attributes)
+      clean_item_attributes(raw_attributes)
     end
     cache :attributes_before_type_cast
     
@@ -104,6 +309,30 @@ module ActiveSP
       list.fields_by_name
     end
     
+    def update_attributes_internal(attributes)
+      attributes = attributes.dup
+      if file_leaf_ref = attributes.delete("FileLeafRef")
+        base_name = ::File.basename(file_leaf_ref, ".*")
+      end
+      updates = Builder::XmlMarkup.new.Batch("OnError" => "Continue", "ListVersion" => 1) do |xml|
+        xml.Method("ID" => 1, "Cmd" => "Update") do
+          xml.Field(self.ID, "Name" => "ID")
+          construct_xml_for_update_list_items(xml, @list.fields_by_name, attributes)
+          xml.Field(base_name, "Name" => "BaseName") if base_name
+        end
+      end
+      result = call("Lists", "update_list_items", "listName" => @list.id, "updates" => updates)
+      create_result = result.xpath("//sp:Result", NS).first
+      error_code = create_result.xpath("./sp:ErrorCode", NS).first.text.to_i(0)
+      if error_code == 0
+        row = result.xpath("//z:row", NS).first
+        @attributes_before_type_cast = clean_item_attributes(row.attributes)
+        reload
+      else
+        raise "cannot create item, error code = #{error_code}"
+      end
+    end
+    
   end
   
 end