davetron5000-gliffy 0.1.7 → 0.2.0

data/README.rdoc

@@ -1,70 +1,197 @@
-<em>The Gliffy API is currently in private beta.  This will be a Ruby implementation to access your Gliffy account.</em>
+This is the Ruby client library for interacting with Gliffy[http://www.gliffy.com].  It's main function is for you to integrate Gliffy documents into the workflow of another application.
 
-This consists of a Ruby client for Gliffy as well as a simple command line tool to access your Gliffy account using that client.
+= Getting Started
 
-== Client Library
+    sudo gem install gliffy
 
-Main entry point is Gliffy::Handle, though you should look at Gliffy::Config for configuration options.  Here's an example of getting the list of diagrams and then downloading the first one as a JPEG
+= Overview
 
-    require 'gliffy'
+The main entry point to Gliffy is Gliffy::Handle, which provides high-level access to most features available from the API.  You should instantiate one of these objects per <i>user session</i>.  To create it, you will need to create and populate an instance of the Credentials class.  This class is constructed almost entirely from static data about your Gliffy account, so you will probably configure an instance of this globally.
+
+This is then used (along with the API root to Gliffy) to create an instance of Gliffy::Handle.  Objects of this class provide access to the features you will need to integrate Gliffy into your app's workflow.
+
+== Example
 
-    Gliffy::Config.config.api_key='aa9d0e8d-449b-44ad-904a-bf87deb7c403'
-    Gliffy::Config.config.secret_key='a52585f7-5952-4229-8bbe-b5787521b571'
-    Gliffy::Config.config.account_name='Initech'
+Suppose you have created a group blog application using Rails and wish to give Blog authors the ability to use Gliffy diagrams.  In <tt>config/initializers/gliffy.rb</tt> you might configure values for the Credential object
 
-    handle = Gliffy::Handle.new('lumberg@initech.com')
+    $gliffy_api_key = 'your-consumer-key-here'
+    $gliffy_secret = 'your-secret-here'
+    $gliffy_app_description = 'My Awesome Group Blog',
+    $gliffy_account_id = 655321
+    $gliffy_root = 'www.gliffy.com/api/v1'
+    $gliffy_edit_root = 'www.gliffy.com/gliffy'
 
-    diagrams = handle.get_diagrams
-    diagram_name_safe = diagrams[0].name.gsub(/ /,'_')
-    handle.get_diagram_as_image(diagrams[0].id,:mime_type => :jpeg,:file=>"#{diagram_name_safe}.jpg")
+Then, in your <tt>sessions_controller.rb</tt>:
+
+    require 'gliffy'
+    
+    def create
+      self.current_user = User.authenticate(params[:email],params[:password])
+      if logged_in?
+        # Whatever you do when they log in successfully
+        # Then create the credentials object
+        cred = Credentials.new(\
+          $gliffy_api_key,
+          $gliffy_secret,
+          $gliffy_app_description,
+          $gliffy_account_id,
+          self.current_user.username)
+        session[:gliffy] = Gliffy::Handle.new($gliffy_root,$gliffy_edit_root,cred)
+    end
 
-The Gliffy::Handle is a <b>user-session based connection</b> to Gliffy.  You shoudl therefore engineer your application to keep one of these per user who will access Gliffy and *not* make a global instance.
+Now you can use the gliffy handle in a controller or a view.  Perhaps you'd make an action to create a new document and send the user to edit it:
 
-* RDoc is available a http://davetron5000.github.com/gliffy
-* Source is available at http://github.com/davetron5000/gliffy/tree/master
+    def create
+      new_doc = session[:gliffy].document_create(params[:name])
+      redirect_to(session[:gliffy].document_edit_link(new_doc.document_id,
+                  {:returnURL => url_for(:controller => 'return_from_gliffy'),
+                   :returnButtonText => 'Back to My Awesome Blog'})) 
+    end
 
-== Command Line Client
+== Digging Deeper
 
-+gliffy+ +help+ shows a list of commands.  Currently, there are:
+If you wish to bypass the high-level API, you can interact with Gliffy directly via the Gliffy::Request class, which allows you to make arbitrary requests against the Gliffy API, but takes care of signing your URLs and all OAuth things that need to be done:
 
-[+delete+] Delete a diagram (also: del,rm)
-[+edit+]   Edit a diagram 
-[+get+]    Download a diagram as an image to a file 
-[+help+]   Show commands 
-[+list+]   List all diagrams in the account (also: ls)
-[+new+]    Create a new diagram 
-[+url+]    Get the URL for an image 
+    # Create a Credentials object as normal
+    request = Gliffy::Request.new('www.gliffy.com/api/v1',credentials)
+    # The method name maps directly to Gliffy's "action" parameters
+    response = request.delete('accounts/$account_id/documents/12345')
 
-=== Configuration
+You can manipulate the response directly, or attempt to parse it using the Gliffy::Response object:
 
-The first time you run the client, it will create a base configuration in your home directory called <tt>.gliffyrc</tt>, and will ask you to provide it with four pieces of information:
+    model = Response.from_http_response(response)
 
-[API Key] This is the API Key given to you by Gliffy
-[Secret Key] This is the Secret Key given to you by Gliffy.  <b>Do not check this value into source control</b>
-[Account Name] Your account's name.  This should've been provided with your API Key
-[Username] The username to work under.  The command line client only allows single-user access to your Gliffy account.  If you just signed up for Gliffy, this is probably the email address you used to sign up
+= Command Line Client
 
-If you are not on OS X, you will want to configure two other options, and you can do this by editing your <tt>.gliffyrc</tt> directly:
+This also comes with a command line client that can serve as an example of using the API.  The command-line client is quite
+usable in its own right:
 
-[<tt>open_image</tt>] Configures the command for opening an image from the command line.  This should be a string of the form <tt>command %s</tt> where <tt>%s</tt> will be replaced with the name of the image file to open.
-[<tt>open_url</tt>] Configures the command for opening an url from the command line.  This should be a string of the form <tt>command %s</tt> where <tt>%s</tt> will be replaced with the name of the url to open.
+    gliffy help
 
-The other options are all documented in Gliffy::Config.  Note that your most previously received user token is stored here as well, to keep from getting it every time the client is run.
+This will list all the commands you can give to the +gliffy+ command.  You can't do *everything* with the command line that you can with the full API, but you can do quite a bit
 
-=== Example
+    # set up your account
+    > gliffy config
 
+    # List all documents in your account
     > gliffy ls
-    1573119 Deployment Artifacts
-    1569470 Monthly_Eligible
-    1569477 Monthly_Ineligibile
-    1569478 Quarterly_Eligible
-    1569479 Quarterly_Ineligibile
-    > gliffy get 1569479
-    Quarterly_Ineligibile.jpg
-    > gliffy get 1569479 -d ~/Downloads -t png
-    /Users/davec/Downloads/Quarterly_Ineligibile.png
-    > gliffy edit 1569470
-    # You are sent to gliffy.com in your browser to edit that diagram
-    > gliffy new -e "Class Diagram"
-    # You are sent to gliffy.com to edit the new diagram 
 
+    # Create a new document
+    > gliffy new "My New Document"
+    Created document 123456 - My New Document
+
+    # Edit it
+    > gliffy edit 123456
+
+    # Make a new folder
+    > gliffy mkdir awesome
+
+    # Move our new document there
+    > gliffy mv 123456 awesome
+
+    # Get it as a PNG
+    > gliffy get -t png 123456
+    Wrote 123456_L.png
+
+    # Get help on a command
+    > bin/gliffy help get
+    view [options] 
+        View a diagram as an image, or download it
+
+    Options:
+        -p, --publicurl                                - Get the Public URL only (if
+                                                         possibe)
+        -s, --size=L, M, S, T                          - Size (default: L)
+        -t, --type=jpeg, png, svg, xml                 - File Type (default: jpeg)
+        -u, --url                                      - Get the URL only
+        -v, --version=version number (omit for latest) - Version
+    
+= Design
+
+== Domain Objects
+
+Instead of creating explicit objects for each domain object in Gliffy, we always return a Response object, that uses method_missing to implement accessors for data returned from Gliffy.  These implicit accessors should return typed values and are named accordingly:
+* If the name in the XSD[http://www.gliffy.com/developer/apidocs/xsddoc/] has dashes, underscores are used here
+* If the item is a boolean, its boolean value is available with a "?" at the end
+* The id field is available as type_id, e.g. document_id
+* Date fields are converted to Time objects
+* Any field in the response that was not known about in this code will be available as a String, based on the above rules
+
+So, if you requested document meta data, you would have the following accessors available:
+
+* document.document_id
+* document.is_private?
+* document.is_public?
+* document.num_versions
+* document.mod_date # returns a Time
+* document.create_date # returns a Time
+* document.published_date # returns a Time
+* document.owner # Returns a Response that responds to user accessors
+* document.versions # Returns an array of Response objects that act like versions
+
+== HTTP Layer
+
+Request implements the HTTP layer, and is based on HTTParty.  Since all Gliffy URLs have an "action" HTTP param in them, this action is the method name, followed by the URL on which to perform that action (this is not a REST action, but specific to Gliffy).  You can optionally include other HTTP params, however those needed for authentication and signing are taken care of.  Request will examine the Credential object used to create the Request object, sign the request, make the request and return the result.  It will look at the result only enough to determine if it's an error, or a failure.  See the RubyDoc for more on how this works.
+
+= Development
+
+== Gems
+
+You will need:
+
+ * hanna 0.1.7, available via `gem install mislav-hanna`
+ * httparty 0.4.2 or better
+ * ruby-hmac 0.3.2 or better
+ * gli 0.1.6 or better
+ 
+All of these save for hanna are installed if you installed the gem.
+
+== Unit Tests
+
+Make sure you get at least 100% statement coverage of the code you write via Unit Tests.
+
+Sometimes the test that two nonces shouldn't be the same fails.  This occurs, because they are generated in pretty much the same instant AND when the random number generator generates the same number twice in a row.  Usually if you run tests again, things pass.
+
+== Integration Tests
+
+This code is capable of running integration tests against Gliffy's integration test servers.
+If you would like to run these tests, you must contact Gliffy for the information needed.
+You could technically run integration tests against your own Gliffy account on their production 
+server, but this may delete or change your account's data and is not recommended.  Once you
+have the information from Gliffy, create the file `test/it_cred.rb` as follows:
+
+    $account_id = # integration tests account id
+    $username = # integration tests admin user name
+    $oauth_consumer_key = # integration test account consumer key
+    $oauth_consumer_secret = # integration test account consumer secret
+    $api_root = # integration test server API endpoint
+    $http_auth_username = # integration test server HTTP Auth username
+    $http_auth_password = # integration test server HTTP Auth password
+
+== Functional Tests
+
+The functional tests perform actual workflows against a Gliffy server and, as such, are more fragile.  If something is wrong in your environment (or with Gliffy), you could leave the test account in a weird state.  As such, you should create a new account using a test-only API call.  This can be done via
+
+    rake setup_account
+
+This requires that it_cred.rb is set up and runs test/setup_account.rb.  This will create the file functest_cred.rb with the necessary information to access the newly created account.  The accounts seem to get reset every day, so you will not be able to reliably automate this.  That being said, the only way to get 100% coverage is to run these tests.
+
+Each functional test assumes the following:
+
+* The account name is 'Ruby Client Test Account'
+* The account id is 1000001
+* The only user is testuser@gliffy.com
+* There are no documents/diagrams
+* The only folder is ROOT
+
+Each test will put data into Gliffy, query it, and remove it, thus leaving the account in the same state.
+
+To fully test the edit launch link, run
+
+    rake TEST_LINK=true functest
+
+This will print out the launch link and pause the testing.  Copy/Paste this into your browser to make sure it works and then come back to the console and hit return.  Do not do this for automated builds.
+
+== JUnit output
+
+I monkeypatched the Ruby unit test classes to output JUnit-style XML when the tests are run.  I believe this file gets overridden with each type of test, but you only really should care about it for the `test` target.  The file is called `junit_output.xml`.

data/bin/gliffy

@@ -1,36 +1,312 @@
 #!/usr/bin/ruby
-#
-$: << File.expand_path(File.dirname(__FILE__) + '/../lib') 
-$: << File.expand_path(File.dirname(__FILE__) + '/../ext') 
-
-require 'gliffy/cli'
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+$: << File.expand_path(File.dirname(__FILE__) + '/../ext')
 require 'rubygems'
 require 'gli'
+require 'etc'
+require 'gliffy'
+
+$description = 'Gliffy Command Line Client'
+
 include GLI
 
-pre do |global_options,command,options,args|
-  if global_options[:version]
-    puts "#{$0} v#{Gliffy::VERSION}"
-    false
-  elsif !Gliffy::CLIConfig.instance.load
-    puts "Problem loading config"
+desc 'Location of your gliffy configuration'
+default_value Etc.getpwuid.dir + '/.gliffyrc'
+arg_name 'path to gliffy config file'
+flag [:config]
+
+#desc 'Use gob-go instead of the real gliffy (devs only)'
+#switch [:gobgotest]
+
+desc 'Delete a folder'
+arg_name 'path (relative to ROOT) of folders you want delete'
+command [:rmdir,:rd] do |c|
+  c.action do |global_options,options,args|
+    args.each do |path|
+      $handle.folder_delete(path)
+      puts "Deleted #{path}"
+    end
+  end
+end
+
+desc 'Create a new folder'
+arg_name 'folders you want created inside the ROOT folder'
+command [:mkdir,:md] do |c|
+  c.action do |global_options,options,args|
+    args.each do |path|
+      $handle.folder_create(path)
+      puts "Created #{path}"
+    end
+  end
+end
+
+desc 'Move diagram to a new folder'
+arg_name 'document_id full_folder_path'
+command [:mv,:move] do |c|
+  c.action do |global_options,options,args|
+    if args.length == 2
+      $handle.document_move(args[0],args[1])
+    else
+      raise "Must specify the document id and folder path only"
+    end
+  end
+end
+
+desc 'List folders'
+command [:lsf,:lsfolders] do |c|
+  def output_folder(f)
+    puts f.path
+    f.child_folders.each do |child|
+      output_folder(child)
+    end
+  end
+
+  c.action do |global_options,options,args|
+    folders = $handle.account_folders
+    folders.each do |folder|
+      output_folder(folder)
+    end
+  end
+end
+
+desc 'List diagram ids and names'
+arg_name 'Folder to list, omit for all folders'
+command [:ls,:list] do |c|
+
+  c.desc 'Show id, public?, versions, owner, update date, name'
+  c.switch :l
+
+  c.desc 'Sort by id'
+  c.switch :i
+
+  c.desc 'Sort by mod date'
+  c.switch :t
+
+  c.action do |global_options,options,args|
+    if args.size == 1
+      documents = $handle.folder_documents(args[0])
+    elsif args.size == 0
+      documents = $handle.user_documents
+    else
+      raise "Either zero or one folder names are supported"
+    end
+
+    sorted = documents.sort{|a,b| a.name <=> b.name} if !options[:i] && !options[:t]
+    sorted = documents.sort{|a,b| a.mod_date <=> b.mod_date} if options[:t]
+    sorted = documents.sort{|a,b| a.document_id <=> b.document_id} if options[:i]
+
+    sorted.each do |doc|
+      if options[:l]
+        printf "%8d %s %4d %20s  %18s  %s\n",doc.document_id,doc.is_public? ? "P" : "-",doc.num_versions,doc.owner.username[0..19],doc.mod_date.strftime("%Y-%m-%d %H:%M:%S"),doc.name
+      else
+        puts "#{doc.document_id} - #{doc.name}"
+      end
+    end
+  end
+end
+
+desc 'Delete a diagram'
+command [:rm,:delete] do |c|
+  c.action do |global_options,options,args|
+    args.each do |document_id|
+      $handle.document_delete(document_id)
+      puts "Deleted #{document_id}"
+    end
+  end
+end
+
+desc 'Edit a diagram'
+command :edit do |c|
+
+  c.desc 'URL to return to after editing is complete'
+  c.default_value 'http://www.gliffy.com'
+  c.flag [:u,:url]
+
+  c.desc 'Text on the "Return" button in Gliffy'
+  c.default_value 'Return'
+  c.flag [:t,:text]
+
+  c.desc 'Command to run to open URL in browser'
+  c.default_value RUBY_PLATFORM =~ /^universal-darwin/ ? 'open' : nil
+  c.flag [:o,:openwith]
+
+  c.action do |global_options,options,args|
+    if args.length == 1
+      url = $handle.document_edit_link(args[0],options[:u],options[:t])
+      opened = false
+      if options[:o]
+        opened = system "#{options[:o]} \"#{url}\""
+      end
+      if !opened
+        puts "Problem running #{options[:o]}" if options[:o]
+        puts "Go here in your browser"
+        puts url
+      end
+    else
+      $stderr.puts "Provide exactly one document id"
+    end
+  end
+end
+
+desc 'View a diagram as an image, or download it'
+command [:view,:get] do |c|
+
+  c.desc 'File Type'
+  c.default_value 'jpeg'
+  c.arg_name 'jpeg, png, svg, xml'
+  c.flag [:t,:type]
+
+  c.desc 'Size'
+  c.default_value 'L'
+  c.arg_name 'L, M, S, T'
+  c.flag [:s,:size]
+
+  c.desc 'Version'
+  c.arg_name 'version number (omit for latest)'
+  c.flag [:v,:version]
+
+  c.desc 'Get the URL only'
+  c.switch [:u,:url]
+
+  c.desc 'Get the Public URL only (if possibe)'
+  c.switch [:p,:publicurl]
+
+  c.action do |global_options,options,args|
+    args.each do |document_id|
+      version = options[:v]
+      version_name = ''
+      version_name = "_V#{version}" if version
+      if options[:u]
+        puts $handle.document_get_url(document_id,options[:t].to_sym,options[:s].to_sym,version)
+      elsif options[:p]
+        document = $handle.document_get_metadata(document_id)
+        if document.is_public?
+          # This isn't formally documented in the API so we put it here
+          puts "http://www.gliffy.com/pubdoc/#{document.document_id}/#{options[:s]}.jpg"
+        else
+          puts "Document is not public"
+          puts $handle.document_get_url(document_id,options[:t].to_sym,options[:s].to_sym,version)
+        end
+      else
+        bytes = $handle.document_get(document_id,options[:t].to_sym,options[:s].to_sym,version)
+        filename = "#{document_id}_#{options[:s]}#{version_name}.#{options[:t]}"
+        File.open(filename,'wb') do |f|
+          f.write(bytes)
+        end
+        puts "Wrote #{filename}"
+      end
+    end
+  end
+end
+
+desc 'Create a new diagram'
+arg_name 'Name of the diagram'
+command :new do |c|
+
+  c.desc 'Full path to the folder in which this diagram should ilve'
+  c.flag [:f,:folder]
+
+  c.desc 'Id of a document to use as a template'
+  c.flag [:t,:template]
+
+  c.action do |global_options,options,args|
+    if args.length > 0
+      new_document = $handle.document_create(args.join(" "),options[:f],options[:t])
+      puts "Created document #{new_document.document_id} - #{new_document.name}"
+    else
+      $stderr.puts "You must supply the diagram name"
+    end
+  end
+end
+
+desc 'Modify configuration (currently only create)'
+command :config do |c|
+
+  c.desc 'Force a recreation of your config file, even if it exists'
+  c.switch :force
+
+  c.action do |global_options,options,args|
+    if $config.nil? || options[:force]
+      puts "What is account ID?"
+      id = $stdin.gets.chomp
+      puts "What is your Consumer Key?"
+      key = $stdin.gets.chomp
+      puts "What is your Consumer Secret?"
+      secret = $stdin.gets.chomp
+      puts "What is the username or email address of an admin user?"
+      user = $stdin.gets.chomp
+      puts "About to create your configuration with the following information:"
+      puts "Account ID      : #{id}"
+      puts "Consumer Key    : #{key}"
+      puts "Consumer Secret : #{secret}"
+      puts "User Name       : #{user}"
+      puts 
+      puts "OK? (Y/N)"
+      response = $stdin.gets
+      if response =~ /^[Yy]/
+        cred = Gliffy::Credentials.new(key,secret,$description,id,user)
+        write_config(cred,global_options[:config])
+        puts "Wrote config to #{global_options[:config]}"
+      else
+        puts "Aborted"
+      end
+    else
+      $stderr.puts "You already have a config; edit it by hand or use --force to recreate"
+    end
+  end
+end
+
+pre do |global,command,options,args|
+  require 'yaml'
+  message = nil
+  begin
+  $config = File.open(global[:config]) { |f| YAML::load(f) }
+  rescue
+    message = "No config file found at #{global[:config]}\nUse #{$0} config to create one"
+    $config = nil
+  end
+  if $config.nil? && command.name != :config
+    $stderr.puts message if !message.nil?
     false
-  elsif command && command.name != :help
-    previous_token = Gliffy::CLIConfig.instance.config[:current_token]
-    Gliffy::Config.config.log_level = Logger::DEBUG if global_options[:v]
-    $gliffy = Gliffy::Handle.new(Gliffy::CLIConfig.instance.config[:username],previous_token)
-    true
   else
+    if !command || command.name != :config
+      if global[:gobgotest]
+        puts "Going against gob-go -- developers only!"
+        class HTTPartyAuth
+          def post(url)
+            HTTParty.post(url,:basic_auth => {:username => 'gobgotest' , :password => 'gobgotest'})
+          end
+        end
+        $handle = Gliffy::Handle.new(
+          'gob-go-stable.gliffy.com/api/1.0',
+          'gob-go-stable.gliffy.com/gliffy',
+          $config,HTTPartyAuth.new)
+      else
+        $handle = Gliffy::Handle.new(
+          'www.gliffy.com/api/1.0',
+          'www.gliffy.com/gliffy',
+          $config)
+      end
+      token = $handle.update_token
+      write_config($config,global[:config])
+    end
     true
   end
 end
 
-desc 'show version'
-switch :version
-
-desc 'be more verbose'
-switch :v
+post do |global,command,options,args|
+  # Post logic here
+end
 
-require 'gliffy/commands'
+on_error do |exception|
+  # Error logic here
+  # return false to skip default error handling
+  true
+end
 
+def write_config(cred,config)
+  File.open(config,'w') do |out|
+    YAML.dump(cred,out)
+  end
+end
 GLI.run(ARGV)