davetron5000-gliffy 0.1.1

data/lib/gliffy/config.rb

@@ -0,0 +1,55 @@
+require 'logger'
+
+module Gliffy
+
+  # Global Configuration for Gliffy.  This is a singleton currently and can be accessed
+  # via the config class method
+  # 
+  # * You mostly need to set api_key, secret_key and account_name
+  # * You may wish to set protocol if you have a premium account and wish to use https
+  class Config
+
+    # A Logger level to control logging
+    attr_accessor :log_level
+    # The log device (as passed to Logger) for where log messages should go
+    attr_accessor :log_device
+    # The protocol, either 'http' or 'https' (though feel free to try 'gopher:' :)
+    attr_accessor :protocol
+    # The gliffy app root, which is pretty much www.gliffy.com/gliffy unless you know a secret
+    attr_accessor :gliffy_app_root
+    # The url relative to gliffy_app_root of where the API is accessed
+    attr_accessor :gliffy_rest_context
+    # Your API Key
+    attr_accessor :api_key
+    # Your Secret Key
+    attr_accessor :secret_key
+    # The name of your account
+    attr_accessor :account_name
+
+    @@instance=nil
+
+    def initialize
+      @log_level = Logger::DEBUG
+      @log_device = STDERR
+      @protocol = 'http'
+      @gliffy_app_root = 'www.gliffy.com/gliffy';
+      @gliffy_rest_context = 'rest'
+      @api_key = 'no api key specified'
+      @secret_key = 'no secret key specified'
+      @account_name = 'no account name specified'
+    end
+
+    # Returns the entire URL to the gliffy api root.  This uses protocol, gliffy_app_root
+    # and gliffy_rest_context, so you should not really override this
+    def gliffy_root
+      "#{protocol}://#{gliffy_app_root}/#{gliffy_rest_context}"
+    end
+
+    def self.config=(config); @@instance = config; end
+    def self.config
+      @@instance = Config.new if !@@instance
+      @@instance
+    end
+  end
+end
+

data/lib/gliffy/diagram.rb

@@ -0,0 +1,100 @@
+require 'rexml/document'
+require 'array_has_response'
+require 'gliffy/rest'
+
+include REXML
+
+module Gliffy
+
+  # A gliffy diagram (or, rather, the meta data about that diagram)
+  class Diagram < Response
+
+    attr_reader :id
+    attr_reader :num_versions
+    attr_reader :name
+    # The username of the proper owner of this diagram
+    attr_reader :owner_username
+    # A Time representing the date on which this diagram was created
+    attr_reader :create_date
+    # A Time representing the date on which this diagram was last modified
+    attr_reader :mod_date
+    # A Time representing the date on which this diagram was published,
+    # or nil if it was not published
+    attr_reader :published_date
+
+    def self.from_xml(element)
+      id = element.attributes['id'].to_i
+      num_versions = element.attributes['num-versions'].to_i
+      is_private = element.attributes['is-private'] == "true"
+      is_public = element.attributes['is-public'] == "true"
+
+      create_date = Time.at(element.elements['create-date'].text.to_i / 1000)
+      mod_date = Time.at(element.elements['mod-date'].text.to_i / 1000)
+      published_date = element.elements['published-date'] ? Time.at(element.elements['published-date'].text.to_i / 1000) : nil
+      name = element.elements['name'].text
+      owner_username = element.elements['owner'] ? element.elements['owner'].text : nil
+
+      Diagram.new(id,name,owner_username,is_public,is_private,num_versions,create_date,mod_date,published_date)
+    end
+
+    # True if this diagram is public
+    def is_public?
+      @is_public
+    end
+
+    # True if this diagram is private (and available only
+    # to the owner and account administrators)
+    def is_private?
+      @is_private
+    end
+
+    # sorts by diagram name
+    def <=>(other_diagram)
+      name <=> other_diagram.name
+    end
+
+    protected 
+    def initialize(id,name,owner_username,is_public,is_private,num_versions,create_date,mod_date,published_date)
+      super()
+      @id = id
+      @name = name
+      @owner_username = owner_username
+      @is_public = is_public
+      @is_private = is_private
+      @num_versions = num_versions
+      @create_date = create_date
+      @mod_date = mod_date
+      @published_date = published_date
+    end
+
+  end
+
+  # A link to edit a specific gliffy diagram
+  class LaunchLink < Response
+
+    # The name of the diagram, which can helpful
+    # in creating HTML hyperlinks to url
+    attr_reader :diagram_name
+    attr_reader :url
+
+    def self.from_xml(element)
+      diagram_name = element.attributes['diagram-name']
+      url = element.text
+      LaunchLink.new(diagram_name,url)
+    end
+
+    def full_url
+      Gliffy::Config.config.protocol + "://" + Gliffy::Config.config.gliffy_app_root + url
+    end
+
+    protected
+
+    def initialize(name,url)
+      super()
+      @diagram_name = name
+      @url = url
+    end
+  end
+
+  class Diagrams < ArrayResponseParser; end
+end

data/lib/gliffy/folder.rb

@@ -0,0 +1,63 @@
+require 'rexml/document'
+require 'array_has_response'
+require 'gliffy/rest'
+
+include REXML
+
+module Gliffy
+
+  class Folders < ArrayResponseParser; end
+
+  class Folder < Response
+
+    # An array of Folder objects that are contained within this folder
+    # If this is empty, it means this Folder is a leaf
+    attr_reader :child_folders
+    attr_reader :id
+    attr_reader :name
+    # The full path to this folder within the account's 
+    # folder hierarchy
+    attr_reader :path
+
+    def self.from_xml(element)
+      id = element.attributes['id'].to_i
+      default = element.attributes['is-default'] == "true"
+      name = element.elements['name'].text
+      path = element.elements['path'].text
+      child_folders = Array.new
+      element.each_element do |element|
+        child_folders << Folder.from_xml(element) if element.name == "folder"
+      end
+      Folder.new(id,name,default,path,child_folders)
+    end
+
+    # Returns true if this folder is the default folder
+    # used when an operation requiring a folder
+    # doesn't specify one (such as when creating a new
+    # diagram)
+    def default?
+      @default
+    end
+
+    # Encodes the elements of a folder path so it can safely go into a URL
+    def self.encode_path_elements(folder_path)
+      encoded = ''
+      folder_path.split(/\//).each do |part|
+        encoded += CGI::escape(part)
+        encoded += "/"
+      end
+      encoded.gsub(/\/$/,'')
+    end
+
+    protected 
+
+    def initialize(id,name,default,path,child_folders)
+      super()
+      @id = id
+      @name = name
+      @default = default
+      @path = path
+      @child_folders = child_folders
+    end
+  end
+end

data/lib/gliffy/gliffy.rb

@@ -0,0 +1,367 @@
+require 'gliffy/rest'
+require 'gliffy/response'
+require 'gliffy/user'
+require 'gliffy/diagram'
+require 'gliffy/folder'
+require 'gliffy/account'
+require 'gliffy/config'
+
+module Gliffy
+
+
+  # A "handle" to access Gliffy on a per-user-session basis
+  # Since most calls to gliffy require a user-token, this class
+  # encapsulates that token and the calls made under it.
+  #
+  # The methods here are designed to raise exceptions if there are problems from Gliffy.
+  # These problems usually indicate a programming error or a server-side problem with Gliffy and
+  # are generally unhandleable.  However, if you wish to do something better than simply raise an exception
+  # you may override handle_error to do something else
+  #
+  class Handle
+
+    # Create a new handle to gliffy for the given user.  Tokens will be requested as needed
+    def initialize(username,token=nil)
+      @username = username
+      @rest = Rest.new
+      @logger = Logger.new(Config.config.log_device)
+      @logger.level = Config.config.log_level
+      if token
+        @rest.current_token = token
+      else
+        update_token(username)
+      end
+    end
+
+    # Run an arbitrary rest call against gliffy, parsing the result.  This allows you
+    # essentially direct access to the underlying Gliffy::Rest, without having to worry about
+    # setting it up.
+    #
+    # [+method+] a rest method, :get, :put, :post, :delete
+    # [+url+] url to request, relative to Gliffy::Config#gliffy_root
+    # [+params+] hash of parameters
+    # [+headers+] hash of HTTP headers
+    #
+    # This will return a Gliffy::Response *if* the method you called returned XML.
+    # If that is not what you want, you should use Gliffy::Rest.
+    def rest_free(method,url,params={},headers={})
+      Response.from_xml(do_simple_rest(method,url,"rest_free",params,headers))
+    end
+
+    # Adds a new user explicitly.  
+    def add_user(username)
+      do_user(:put,username)
+    end
+
+    # Deletes the user from this account.  May not be the user who owns the token for this
+    # session (i.e. was passed to the constructor).  <b>This cannot be undone</b>.
+    def delete_user(username)
+      do_user(:delete,username)
+    end
+
+    # Allows +username+ to access +folder_path+ and all its child folders
+    def add_user_to_folder(username,folder_path)
+      do_user_folder(:put,username,folder_path)
+    end
+
+    # Revokes +username+ access to +folder_path+
+    def remove_user_from_folder(username,folder_path)
+      do_user_folder(:delete,username,folder_path)
+    end
+
+    # Creates a new blank diagram (or based on an existing one)
+    #
+    # [+diagram_name+] the name of the new diagram
+    # [+template_diagram_id+] the id of a diagram to use as a template.  You must have access to this diagram
+    #
+    def create_diagram(diagram_name,template_diagram_id=nil)
+      params = Hash.new
+      params['diagramName'] = diagram_name
+      params['templateDiagramId'] = template_diagram_id if template_diagram_id
+      diagrams = do_simple_rest(:post,'diagrams',"Creating diagram named #{diagram_name}",params)
+      if diagrams.size >= 1
+        return diagrams[0]
+      else
+        raise "Got no diagrams, but creation was successful."
+      end
+    end
+
+    # Creates a folder with the given name.  The parent path should already exist
+    def create_folder(folder_path)
+      do_folder(:put,folder_path)
+    end
+
+    # deletes the diagram with the given id.  <b>This cannot be undone</b>
+    def delete_diagram(diagram_id)
+      do_simple_rest(:delete,"diagrams/#{diagram_id}","Deleting diagram #{diagram_id}")
+    end
+
+    # Deletes a folder, moving all diagrams in it to the default folder. 
+    # The folder must be empty
+    # <b>This cannot be undone</b>
+    def delete_folder(folder_path)
+      folder_path = Folder.encode_path_elements(folder_path)
+      do_simple_rest(:delete,"folders/#{folder_path}","Deleting folder #{folder_path}")
+    end
+
+    # Returns an array of User objects representing the admins of the account
+    def get_admins
+      do_simple_rest(:get,'admins','Getting admins for account')
+    end
+
+    # Gets the diagram as an image, possibly saving it to a file.
+    #
+    # [+diagram_id+] the id of the diagram to get
+    # [+options+] a hash of options controlling the diagram and how it's fetched
+    #             [<tt>:size</tt>] one of :thumbnail, :small, :medium, or :large (default is :large)
+    #             [<tt>:file</tt>] if present, the diagram is written to the named file
+    #             [<tt>:mime_type</tt>] the mime type to retrie.  You can also use :jpeg, :png and :svg as shortcuts (default is :jpeg)
+    #             [<tt>:version</tt>] if present, the version number to retrieve (default is most recent)
+    #
+    # returns the bytes of the diagram if file was nil, otherwise, returns true
+    #
+    def get_diagram_as_image(diagram_id,options={:mime_type => :jpeg})
+      params,headers = create_diagram_request_info(options)
+      update_token
+      extension = extension_for(options[:mime_type])
+      extension = ''
+      bytes = @rest.get(url("diagrams/#{diagram_id}#{extension}"),params,headers)
+      response = nil
+      begin
+        response = Response.from_xml(bytes)
+      rescue
+        response = nil
+      end
+
+      if response.respond_to?(:success?) && !response.success?
+        handle_error(response,"While getting bytes of diagram #{diagram_id}")
+      else
+        if options[:file]
+          fp = File.new(options[:file],'w')
+          fp.puts bytes
+          fp.close
+          true
+        else
+          bytes
+        end
+      end
+    end
+
+    # returns the URL that would get the diagram in question.  Same parameters as get_diagram_as_image
+    def get_diagram_as_url(diagram_id,options={:mime_type => :jpeg})
+      params,headers = create_diagram_request_info(options)
+      update_token
+      extension = extension_for(options[:mime_type])
+      @rest.create_url(url("diagrams/#{diagram_id}#{extension}"),params)
+    end
+
+    def extension_for(mime_type)
+      case mime_type
+      when :jpeg
+        return ".jpg"
+      when :png
+        return ".png"
+      when :svg
+        return ".svg"
+      end
+      ""
+    end
+
+    # GliffyDiagram getDiagramMetaData (integer $diagramId)
+    def get_diagram_meta_data(diagram_id)
+      params = {'diagramId' => diagram_id}
+      diagrams = do_simple_rest(:get,'diagrams',"Getting meta data for diagram #{diagram_id}",params)
+      diagrams[0]
+    end
+
+    # Gets a list of diagrams, either for the given folder, or the entire account
+    def get_diagrams(folder_path=nil)
+      folder_path = Folder.encode_path_elements(folder_path) if folder_path
+      url = (folder_path ? "folders/#{folder_path}/" : "") + "diagrams"
+      do_simple_rest(:get,url,"Get all diagrams in " + (folder_path ? folder_path : "account"))
+    end
+
+    # Gets the link that can be used <b>by this user while his token is valid</b> to edit the diagram.
+    #
+    # [+diagram_id+] the id of the diagram to edit
+    # [+return_url+] if present represents the URL to return the user to after they have completed their editing.  You should not urlencode this, it will be done for you
+    # [+return_text+] the text that should be used in Gliffy to represent the "return to the application" button.
+    #
+    # returns a Gliffy::LaunchLink that contains the complete URL to be used to edit the given diagram and behave as described.  The GliffyLaunchLink also contains the diagram name, which can be used for linking.  Note that the url is relative to the Gliffy website
+    def get_edit_diagram_link(diagram_id,return_url=nil,return_text=nil)
+      params = Hash.new
+      params['returnURL'] = CGI::escape(return_url) if return_url
+      params['returnText'] = CGI::escape(return_text) if return_text
+
+      do_simple_rest(:get,"diagrams/#{diagram_id}/launchLink","Getting launch link for diagram #{diagram_id}",params)
+    end
+
+    # array getFolders ()
+    def get_folders()
+      do_simple_rest(:get,'folders','Getting folders for account')
+    end
+
+    # Gets the folders that +username+ has access to, in nested form
+    def get_user_folders(username)
+      do_simple_rest(:get,"users/#{username}/folders","Getting folders for user #{username}")
+    end
+
+    # Gets the users in the given folder, or in the entire account
+    #
+    # [+folder_path+] if present, returns users with access to this folder
+    def get_users(folder_path=nil)
+      url = ''
+      if (folder_path)
+        folder_path = Folder.encode_path_elements(folder_path)
+        url += "folders/#{folder_path}/"
+      end
+      url += 'users'
+      do_simple_rest(:get,url,"Getting users for " + (folder_path ? "folder #{folder_path}" : 'account'))
+    end
+
+    # returns the user token if it exists
+    def current_token()
+      @rest.current_token
+    end
+
+    # move diagram +diagram_id+ to folder path +folder_path+
+    def move_diagram(diagram_id,folder_path)
+      folder_path = Folder.encode_path_elements(folder_path)
+      do_simple_rest(:put,"folders/#{folder_path}/diagrams/#{diagram_id}","Moving #{diagram_id} to folder #{folder_path}")
+    end
+
+    # Updates the user.
+    #
+    # [+username+] user to update
+    # [+attributes+] has of attributes to change.
+    #                [<tt>:email</tt>] email address
+    #                [<tt>:password</tt>] password for logging into Gliffy Online
+    #                [<tt>:admin</tt>] true to make them an admin, false to revoke their admin-ness
+    # 
+    def update_user(username,attributes)
+      params = Hash.new
+      params['admin'] = attributes[:admin].to_s if attributes.has_key? :admin
+      params['email'] = attributes[:email] if attributes[:email]
+      params['password'] = attributes[:password] if attributes[:password]
+      do_simple_rest(:put,"users/#{username}","Updating #{username}",params)
+    end
+
+    # Updates the user's token, if he needs it
+    #
+    #   [+force+] if true, the token is updated regardless
+    def update_token(force=false)
+      if force || !@rest.current_token || @rest.current_token.expired?
+        @logger.debug('Forcing a new token') if force
+        @logger.debug('No current token') if !@rest.current_token
+        @rest.current_token = nil
+        token = Response.from_xml(@rest.get(url("users/#{@username}/token")))
+        if (token.success?)
+          @logger.info("User #{@username} assigned token #{token.token} from Gliffy")
+          @rest.current_token = token
+        else
+          handle_error(token)
+        end
+      else
+        @logger.debug('Not getting a new token')
+      end
+    end
+
+    # Override this if you want error handling that doesn't rasie an exception
+    #
+    # [+error_response+] an Error object that holds the error from Gliffy
+    # [+action_cause+] a string describing the action being taken when the error ocurred
+    def handle_error(error_response,action_cause=nil)
+      msg = ""
+      msg += "While #{action_cause}: " if action_cause
+      msg += error_response.to_s
+      raise msg
+    end
+
+    private
+
+    def do_user(method,username)
+      do_simple_rest(method,"users/#{username}","#{rest_to_text(method)} user #{username}")
+    end
+
+    def do_folder(method,folder_path)
+      folder_path = Folder.encode_path_elements(folder_path)
+      do_simple_rest(method,"folders/#{folder_path}","#{rest_to_text(method)} folder #{folder_path}")
+    end
+
+    def do_user_folder(method,username,folder_path)
+      folder_path = Folder.encode_path_elements(folder_path)
+      do_simple_rest(method,"folders/#{folder_path}/users/#{username}","#{rest_to_text(method)} #{username} to #{folder_path}")
+    end
+
+    def create_diagram_request_info(options)
+      mime_type = options[:mime_type]
+      params = Hash.new
+      params['size'] = size_to_param(options[:size]) if options[:size]
+      params['version'] = options[:version] if options[:version]
+      headers = Hash.new
+      if mime_type.is_a? Symbol
+        headers['Accept'] = mime_type_to_header(mime_type)
+      else
+        headers['Accept'] = mime_type
+      end
+      [params,headers]
+    end
+
+    def do_simple_rest_helper(method,url_fragment,description,params=nil,headers={},first=false)
+      update_token
+      response = Response.from_xml(@rest.send(method,url(url_fragment),params,headers))
+      if !response.success?
+        if first
+          @logger.warn("Possible token problem, try again after updating token")
+          update_token true
+          response = do_simple_rest_helper(method,url_fragment,description,params,headers,false)
+        else
+          handle_error(response,description)
+        end
+      end
+      response
+    end
+
+    def do_simple_rest(method,url_fragment,description,params=nil,headers={})
+      do_simple_rest_helper(method,url_fragment,description,params,headers,true)
+    end
+    
+
+    def url(fragment)
+      "/accounts/#{Config.config.account_name}/#{fragment}"
+    end
+
+    def mime_type_to_header(mime_type_symbol)
+      case mime_type_symbol
+      when :jpeg: 'image/jpeg'
+      when :jpg: 'image/jpg'
+      when :png: 'image/png'
+      when :svg: 'image/svg+xml'
+      else raise "#{mime_type_symbol} is not a known mime type"
+      end
+    end
+    def size_to_param(size)
+      return nil if !size
+      case size 
+      when :thumbnail: 'T'
+      when :small: 'S'
+      when :medium: 'M'
+      when :large: 'L'
+      else raise "#{size} is not a supported size"
+      end
+    end
+
+    def rest_to_text(method)
+      case method
+      when :put : 'Creating'
+      when :delete : 'Deleting'
+      when :post : 'Updating'
+      when :get : 'Getting'
+      else
+        raise "Unknown method #{method.to_s}"
+      end
+    end
+
+
+  end
+end