proof-sharepoint-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02de9841d5e27fa6c194f2c556e2ada51f4fd3488174d81d3dea471f39aab4f5
+  data.tar.gz: b3e32950b55aa4408ec9fa2a9bec3d585aaf8f01ea9645f46f7b6085cc973f1a
+SHA512:
+  metadata.gz: 142b225cdfbc1f844aff2670eb09f6b5ca740b0625571ca0c2461697d2f4ff86ceb142be4cf0f22ee13e1e089d4107509a7945c4a1c69fc8f4a8baf2d87ee56d
+  data.tar.gz: 46a37d9d7aadab3338668659e6f57f7c26655a7a281fab6210fc053d00fb1a4bbac5a5a53c582026fb63e8c53570f238706f330c9a892719884b3d7192761c31

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [1.0.0]
+* Initial Release
+
+### Changes
+- Better error logging.
+- Support for 2013 authentication.
+- Extract make object to facilitate external testing.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,19 @@
+PATH
+  remote: .
+  specs:
+    proof-sharepoint-ruby (1.0.0)
+      curb (~> 0.8, <= 0.9.10)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    curb (0.9.10)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  proof-sharepoint-ruby!
+
+BUNDLED WITH
+   2.1.4

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2014, Plaristote
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the {organization} nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,167 @@
+sharepoint-ruby
+===============
+A ruby gem that maps Sharepoint's REST API in a simple and accessible fashion.
+
+How to use
+===============
+First, you'll have to initialize a sharepoint site and open a session in order to start making requests to the REST API:
+
+```Ruby
+require 'sharepoint-ruby'
+
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'server-relative-site-url'
+site.session.authenticate 'mylogin', 'mypassword'
+
+blog = Sharepoint::Site.new 'mytenant.sharepoint.com', 'sites/blog'
+blog.session.authenticate 'user', 'pwd'
+lists = blog.lists
+for l in lists
+  puts l.title
+end
+```
+
+Note that site.session.authenticate might throw an exception if the authentication doesn't go well (wrong urls, STS unavailable, or wrong login/password).
+The exceptions might be of type ConnectionToStsFailed, AuthenticationFailed, ConnexionToSharepointFailed, UnknownAuthenticationError.
+
+### Connecting to your own STS
+By default, sharepoint-ruby uses Microsoft's STS (https://login.microsoftonline.com/extSTS.srf), which works for Sharepoint Online. You may use your own STS by using the optional third parameter of Sharepoint::Site.new:
+
+```Ruby
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
+site.session.authenticate  'username', 'password', 'https://sts_url.com/extSTS.srf'
+```
+
+### Connecting using NTLM
+You may also connect using the NTLM method. For that purpose, you'll have to overwrite the default session handler with `Sharepoint::HttpAuth::Session`.
+
+```Ruby
+require 'sharepoint-http-auth'
+
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
+site.session = Sharepoint::HttpAuth::Session.new site
+site.session.authenticate 'login', 'password'
+site.protocole = 'http' # default protocole is https: don't forget to set this if you use http.
+```
+
+### Connecting using Kerberos
+You may also connect using Kerberos if you're using *MIT Kerberos*. 
+For that purpose, you'll have to overwrite the default session handler with `Sharepoint::KerberosAuth::Session`.
+
+```Ruby
+require 'sharepoint-kerberos-auth'
+
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
+site.session = Sharepoint::KerberosAuth::Session.new site
+site.session.authenticate 'login', 'password'
+site.protocole = 'http' # default protocole is https: don't forget to set this if you use http.
+```
+
+### General features
+
+Once you're logged in, you may access the site's ressource through the site object:
+```Ruby
+fields  = site.fields # Get all the site's fields
+groups  = site.groups # Get all the site's groups
+users   = site.users  # Get all the site's users
+
+lists = site.lists # Get all the site's list
+list  = site.list 'Documents' # Get a list by title
+list  = site.list '51925dd7-2108-481a-b1ef-4bfa4e69d48b' # Get a list by guid
+views = list.views # Get all the lists views
+
+folders = site.folders # Get all the site's folder
+folder  = site.folder '/SiteAssets/documents' # Get a folder by server relative path
+files   = folder.files # Get all the folder's files
+```
+
+### OData mapping
+When Sharepoint answers with an OData object, the `site.query` method will automatically map it to the corresponding Sharepoint::Object class.
+For instance, if Sharepoint answered with an OData object of type 'SP.List', `site.query` will return an instance of the Sharepoint::List class. These classes implement a getter and a setter for all the properties declared for the corresponding object in Sharepoint's 2013 Documentation.
+
+N.B: Note that the setter only exists if the property is declared as write-accessible in the documentation.
+N.B#2: Note that despite the camel casing used by Sharepoint, the getter and setter are snake cased (i.e: the CustomMasterUrl property becomes accessible through the custom_master_url getter and custom_mater_url= getter).
+
+#### Sharepoint::Object specifics
+Sharepoint::Object contains a few methods to help you handle your objects:
+
+The `guid` method can be used to retrieve the guid of any object.
+
+The `reload` method returns an instance of the same object from the remote sharepoint site. It may be useful if you want to be sure that your object contains the latest changes.
+
+The `save` method will automatically compile your changes and perform the MERGE request with the Sharepoint site.
+
+The `destroy` method will destroy the remote ressource on the Sharepoint site.
+
+The `copy` method can duplicate an existing object. If you send it a Sharepoint::Object as a parameter, it will duplicate into the parameter. If you don't send any parameter, it will create a new object. Note that no changes happen on the sharepoint site until you've called the `save` method on the returned object.
+
+### Deferred objects
+Some of the properties of the OData object are 'deferred', which means that the property only provides a link to a ressource that you would have to get for yourself.
+Not with the sharepoint-ruby gem however: the first time you try to access a deferred property, the object will on it's own go look for the corresponding remote ressource: the result will be stored for later uses, and then be returned to you.
+
+### Modifying Sharepoint's ressources
+The Sharepoint REST API provides us with methods to create, update or delete resources. In the Sharepoint::Object, these behaviours are implemented through the save and delete methods.
+
+##### Updating objects
+This piece of code will change the custom master page used by the Sharepoint site to 'oslo.master':
+```Ruby
+  web = site.context_info # Sharepoint::Site.context_info returns the Web object for the current site (see: http://msdn.microsoft.com/en-us/library/office/dn499819(v=office.15).aspx )
+  web.custom_master_url = '/_catalogs/masterpage/oslo.master'
+  web.save
+```
+
+##### Creating objects
+You may also create your own objects. This will be slightly different: we will create our own instance of a Sharepoint::List object.
+Some Sharepoint objects have values that can only be set during their initialization: `sharepoint-ruby` doesn't allow you to set these values through a setter.
+In the case of list, Sharepoint will require you to specify the value for the `BaseTemplate` property. This is how you would specify the default value for an attribute that isn't write-accessible:
+```Ruby
+  list             = Sharepoint::List.new site, { 'BaseTemplate' => Sharepoint::LIST_TEMPLATE_TYPE[:GenericList] }
+  list.title       = 'My new list'
+  list.description = 'A list created by sharepoint-ruby'
+  list             = list.save # At creation, the remote object created will be returned by the save method.
+```
+Note that the attribute's name in the constructor remains camel cased (`BaseTemplate`), though the getter for this attribute is still snake cased (`base_template`).
+
+##### Destroying objects
+Now, say you want to destroy the list you just created, this will do nicely:
+```Ruby
+  list.destroy
+```
+
+### Parenting
+In the previous paragraph, we saw how to create a Sharepoint::List object. Sharepoint lists aren't parented to any other objects: Sharepoint views however are parented to a list. If you wanted to create a view for the list we just created, you would have to specify a parent for the view:
+
+```Ruby
+  view               = Sharepoint::View.new site
+  view.title         = 'My new view'
+  view.personal_view = false
+  view.parent        = list # Setting the view's parent to the Sharepoint::List
+  view.save
+```
+
+### Collections
+In sharepoint-ruby, collections are merely arrays of Sharepoint::Objects. If you wish to add an object to a colleciton, set the parent to the object providing the collection.
+
+### List Items
+Sharepoint doesn't allow the user to fetch more than 100 items per query. When your list contains more than a 100 items, you may fetch them using the `find_items` method:
+
+```Ruby
+  list = site.list 'My List'
+  # Use the skip option to paginate
+  list.find_items skip: 50 # returns items from 50-150
+  # You may use other operators in your query, such as orderby, select, filter and top:
+  list.find_items skip: 100, orderby: 'Title asc'
+```
+
+### Exceptions
+Inevitably, some of your requests will fail. The object sharepoint returns when an error happens is also mapped by sharepoint-ruby in the Sharepoint::SPException class.
+The SPException class contains methods to inspect the query that was made to the server:
+
+```Ruby
+  begin
+    list = site.list 'title that does not exists'
+  rescue Sharepoint::SPException => e
+    puts "Sharepoint complained about something: #{e.message}"
+    puts "The action that was being executed was: #{e.uri}"
+    puts "The request had a body: #{e.request_body}" unless e.request_body.nil?
+  end
+```

data/lib/sharepoint-error.rb

@@ -0,0 +1,3 @@
+module Sharepoint
+  class SharepointError < StandardError; end
+end

data/lib/sharepoint-fields.rb

@@ -0,0 +1,126 @@
+module Sharepoint
+  class Field < Sharepoint::Object
+    include Sharepoint::Type
+    sharepoint_resource
+    belongs_to :list
+
+    field 'DefaultValue'
+    field 'Description'
+    field 'Direction'
+    field 'EnforceUniqueValues'
+    field 'FieldTypeKind'
+    field 'Group'
+    field 'Hidden'
+    field 'Indexed'
+    field 'JSLink'
+    field 'ReadOnlyField'
+    field 'Required'
+    field 'SchemaXml'
+    field 'Scope'
+    field 'Sealed'
+    field 'Sortable'
+    field 'StaticName'
+    field 'Title'
+    field 'TypeAsString'
+    #field 'ValidationFormula'
+    #field 'ValidationMessage'
+  end
+
+  module Taxonomy
+    class TaxonomyField < Field
+    end
+  end
+
+  class FieldCalculated < Field
+    field 'DateFormat'
+    field 'Formula'
+    field 'OutputType'
+  end
+
+  class FieldComputed < Field
+    field 'EnableLookup'
+  end
+
+  class FieldDateTime < Field
+    field 'DateTimeCalendarType'
+    field 'DisplayFormat'
+    field 'FriendlyDisplayFormat'
+  end
+
+  class FieldGeolocation < Field
+  end
+
+  class FieldGuid < Field
+  end
+
+  class FieldLookup < Field
+    field 'AllowMultipleValues'
+    field 'IsRelationship'
+    field 'LookUpField'
+    field 'LookUpList'
+    field 'LookUpWebId'
+    field 'PrimaryFieldId'
+    field 'RelationshipDeleteBehavior'
+
+    def create_uri
+      unless parent.nil?
+        parent.__metadata['uri'] + '/fields/addfield'
+      else
+        'fields/addfield'
+      end
+    end
+
+    def create
+      @site.query :post, create_uri, { parameters: @data }.to_json
+    end
+  end
+
+  class FieldUser < FieldLookup
+    field 'AllowDisplay'
+    field 'Presence'
+    field 'SelectionGroup'
+    field 'SelectionMode'
+  end
+
+  class FieldMultiChoice < Field
+    field 'Choices'
+    field 'FillInChoice'
+  end
+
+  class FieldChoice < Field
+    field 'EditFormat'
+  end
+
+  class FieldRatingScale < Field
+    field 'GridEndNumber'
+    field 'GridNAOptionText'
+    field 'GridStartNumber'
+    field 'GridTextRangeAverage'
+    field 'GridTextRangeHigh'
+    field 'GridTextRangeLow'
+  end
+
+  class FieldMultiLineText < Field
+    field 'AllowHyperlink'
+    field 'AppendOnly'
+    field 'NumberOfLines'
+    field 'RestrictedMode'
+    field 'RichText'
+  end
+
+  class FieldNumber < Field
+    field 'MaximumValue'
+    field 'MinimumValue'
+  end
+
+  class FieldCurrency < FieldNumber
+    field 'CurrencyLocaleId'
+  end
+
+  class FieldText < Field
+    field 'MaxLength'
+  end
+
+  class FieldUrl < Field
+  end
+end

data/lib/sharepoint-files.rb

@@ -0,0 +1,80 @@
+require 'open-uri'
+
+module Sharepoint
+  class Folder < Sharepoint::Object
+    include Sharepoint::Type
+    sharepoint_resource get_from_name: 'GetFolderByServerRelativeUrl'
+
+    field 'WelcomePage'
+    field 'UniqueContentTypeOrder'
+
+    method :recycle
+
+    def file_from_name name
+      @site.query :get, "#{__metadata['uri']}/files/getbyurl('#{URI::encode(name.to_s)}')"
+    end
+
+    def add_file name, content
+      uri = "#{__metadata['uri']}/files/add(overwrite=true,url='#{URI::encode(name.to_s)}')"
+      @site.query :post, uri, content
+    end
+
+    def add_folder name
+      uri  = "#{__metadata['uri']}/folders"
+      body = { '__metadata' => { 'type' => 'SP.Folder' }, 'ServerRelativeUrl' => name.to_s }
+      @site.query :post, uri, body.to_json
+    end
+  end
+
+  class File < Sharepoint::Object
+    include Sharepoint::Type
+    belongs_to :folder
+    sharepoint_resource getter: 'GetFileByServerRelativeUrl', no_root_collection: true
+
+    method :approve,                     default_params: ({ comment: '' })
+    method :deny,                        default_params: ({ comment: '' })
+    method :checkin,                     default_params: ({ comment: '', checkintype: 0 })
+    method :checkout
+    method :undo_checkout
+    method :copy_to,                     default_params: ({ overwrite: true })
+    method :move_to,                     default_params: ({ flags: 9 })
+    method :get_limited_webpart_manager, default_params: ({ scope: 0 }), http_method: :get
+    method :download,                    endpoint: '$value',             http_method: :get, skip_json: true
+    method :upload,                      endpoint: '$value',             http_method: :put
+    method :publish,                     default_params: ({ comment: '' })
+    method :unpublish,                   default_params: ({ comment: '' })
+    method :recycle
+
+    def upload_from_file filename
+      content = String.new
+      ::File.open filename, 'rb' do |file|
+        line = nil
+        content += line while line = file.gets
+      end
+      upload content
+    end
+
+    def download_to_file filename
+      content = download
+      ::File.open filename, "w:#{content.encoding.name}" do |file|
+        file.write content
+      end
+    end
+  end
+
+  class FileVersion < Sharepoint::Object
+    include Sharepoint::Type
+    belongs_to :file
+
+    ##
+    # created_by is taken an I can't seem to override it.
+    def creator
+      _, number, library_path = url.split('/', 3)
+      server_path = URI::encode("/#{site.name}/#{library_path}").gsub(/'/, '%27%27')
+      @site.query(
+        :get,
+        "GetFileByServerRelativeUrl('#{server_path}')/Versions(#{number})/CreatedBy"
+      )
+    end
+  end
+end