Class: Gliffy::Handle

Inherits:
Object
  • Object
show all
Defined in:
lib/gliffy/handle.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_root, edit_api_root, credentials, http = nil, logger = nil) ⇒ Handle

Create a new handle to Gliffy

api_root

root URL (without the protocol) of where to connect to Gliffy

edit_api_root

root URL (without the protocol) of where to connect to Gliffy for the edit link only

credentials

a Credentials object to use for access

http

override of http access class (use at your own risk; must be substituable for HTTPart)

logger

logger instance, if you don’t want the default



46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/gliffy/handle.rb', line 46

def initialize(api_root,edit_api_root,credentials,http=nil,logger=nil)
  @credentials = credentials
  @request = Request.new(api_root,credentials)
  @edit_link_request = Request.new(edit_api_root,credentials)
  @request.http = http if !http.nil?
  @logger = logger || Logger.new(STDOUT)
  @logger.level = Logger::INFO
  @request.logger = @logger
  if !@credentials.has_access_token?
    update_token
  end
  @error_callback = nil
end

Instance Attribute Details

#error_callback=(value) ⇒ Object (writeonly)

Use this to override what happens when an error from Gliffy is received. The default (or nil) is to raise the exception that was generated. If you want to override this provide a block that takes the response that was received (which will be a hash-like object from HTTParty, possibly nil) and the exception that was generated (the message of which will have been parsed from Gliffy’s XML if that was possible):

# If we got an HTTParty response, try to print out the body and the Gliffy message
# Otherwise, barf
handle.response = Proc.new do |response,exception|
  if response && response.respond_to? :body
    puts exception.to_str
    puts response.body
  else
    raise exception
  end
end



38
39
40
 
# File 'lib/gliffy/handle.rb', line 38

def error_callback=(value)
  @error_callback = value
end

#logger ⇒ Object (readonly)

Get access to the logger (useful for controlling log messages)



15
16
17
 
# File 'lib/gliffy/handle.rb', line 15

def logger
  @logger
end

#request ⇒ Object (readonly)

Get access to the Request (useful for hacking or testing)



17
18
19
 
# File 'lib/gliffy/handle.rb', line 17

def request
  @request
end

#token ⇒ Object (readonly)

Get access to the current token (useful for caching to disk)



19
20
21
 
# File 'lib/gliffy/handle.rb', line 19

def token
  @token
end

Instance Method Details

#account_admins ⇒ Object

Get admins of your account. Returns users



81
82
83
 
# File 'lib/gliffy/handle.rb', line 81

def 
  make_request(:get,"#{account_url}/admins.xml")
end

#account_documents(show = nil) ⇒ Object

Returns all documents in the account

show

if nil, all documents are returned; if :public only public are returned.



87
88
89
90
91
92
93
 
# File 'lib/gliffy/handle.rb', line 87

def (show=nil)
  if show.nil?
    make_request(:get,"#{account_url}/documents.xml")
  else
    make_request(:get,"#{account_url}/documents.xml",:public => show == :public)
  end
end

#account_folders ⇒ Object

Returns all folders in the account



96
97
98
 
# File 'lib/gliffy/handle.rb', line 96

def 
  make_request(:get,"#{account_url}/folders.xml")
end

#account_get(show_users = true) ⇒ Object

Returns account meta data

show_users

if true, include the list of users in this account



102
103
104
 
# File 'lib/gliffy/handle.rb', line 102

def (show_users=true)
  make_request(:get,"#{account_url}.xml", :showUsers => show_users)[0]
end

#account_users ⇒ Object

Get users in your account



107
108
109
 
# File 'lib/gliffy/handle.rb', line 107

def  
  make_request(:get,"#{account_url}/users.xml")
end

#anything(method, url, params = {}, parse = false, link = false) ⇒ Object 



291
292
293
 
# File 'lib/gliffy/handle.rb', line 291

def anything(method,url,params={},parse=false,link=false)
  make_request(method,url,params,parse,link)
end

#delete_token ⇒ Object

Delete the current token



75
76
77
78
 
# File 'lib/gliffy/handle.rb', line 75

def delete_token
  make_request(:delete,token_url)
  @credentials.clear_access_token
end

#document_create(name, folder_path = nil, template_id = nil, type = :diagram) ⇒ Object

Create a new document

name

Name of the new document

folder_path

Path in which to place the document initially (nil to use default)

template_id

document id of a document to copy when initializing this new document (nil to make a blank one)

type

If Gliffy ever supports other document types, use this

Returns a document representing the document that was created.



118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/gliffy/handle.rb', line 118

def document_create(name,folder_path=nil,template_id=nil,type=:diagram)
  params = { 
    :documentName => name,
    :documentType => type
  }
  params[:templateDiagramId] = template_id if !template_id.nil? 
  params[:folderPath] = normalize_folder_path(folder_path) if !folder_path.nil? 
  documents = make_request(:create,"#{account_url}/documents.xml",params)
  return nil if documents.nil? 
  documents[0]
end

#document_delete(document_id) ⇒ Object

Delete an existing document



131
132
133
 
# File 'lib/gliffy/handle.rb', line 131

def document_delete(document_id)
  make_request(:delete,document_url(document_id))
end

#document_edit_link(document_id, return_url, return_text = 'Return') ⇒ Object

Get the link to edit a document



189
190
191
192
193
194
195
 
# File 'lib/gliffy/handle.rb', line 189

def document_edit_link(document_id,return_url,return_text='Return')
  update_token
  @edit_link_request.link_for(:GET,'',{ 
    :launchDiagramId => document_id, 
    :returnURL => return_url, 
    :returnButtonText=> return_text})
end

#document_get(document_id, type = :jpeg, size = :L, version = nil) ⇒ Object

Get a document; returning the actual bytes

document_id

identifier of the document

type

document type. Types known to work:

:jpeg

  • JPEG

:png

  • PNG

:svg

  • SVG (for Visio import)

:xml

  • Gliffy proprietary XML format (for archiving)

size

size to show, from biggest to smallest: :L, :M, :S, :T

version

The version to get, or nil to get the most recent



151
152
153
154
155
156
157
158
159
160
 
# File 'lib/gliffy/handle.rb', line 151

def document_get(document_id,type=:jpeg,size=:L,version=nil)
  params = { :size => size }
  params[:version] = version if !version.nil?
  response = make_request(:get,document_url(document_id,type),params,false)
  if (type == :xml) || (type == :svg)
    response.body
  else
    response
  end
end

#document_get_metadata(document_id, show_revisions = false) ⇒ Object

Get meta-data about a document.

document_id

identifier of the document

show_revisions

if true, include info about the documents’ revision history



138
139
140
 
# File 'lib/gliffy/handle.rb', line 138

def document_get_metadata(document_id,show_revisions=false)
  make_request(:get,document_metadata_url(document_id),:showRevisions => show_revisions)[0]
end

#document_get_public_url(document_id, size = :L) ⇒ Object

Gets the public link to the document, which is static and not dependent on the key or authorization. This isn’t formally part of the Gliffy API, but is convienient. The document must be public and you can only get it in JPG format.

document_id

identifier of the document

size

size to show, from biggest to smallest: :L, :M, :S, :T



169
170
171
 
# File 'lib/gliffy/handle.rb', line 169

def document_get_public_url(document_id,size=:L)
  "http://www.gliffy.com/pubdoc/#{document_id}/#{size.to_s}.jpg"
end

#document_get_url(document_id, type = :jpg, size = :L, version = nil) ⇒ Object

Get a link to a document

document_id

identifier of the document

type

document type. Types known to work:

:jpg

  • JPEG

:png

  • PNG

:svg

  • SVG (for Visio import)

:xml

  • Gliffy proprietary XML format (for archiving)

size

size to show, from biggest to smallest: :L, :M, :S, :T

version

The version to get, or nil to get the most recent



182
183
184
185
186
 
# File 'lib/gliffy/handle.rb', line 182

def document_get_url(document_id,type=:jpg,size=:L,version=nil)
  params = { :size => size }
  params[:version] = version if !version.nil?
  make_request(:get,document_url(document_id,type),params,false,true)
end

#document_move(document_id, new_path) ⇒ Object

Move a document to a different folder



198
199
200
 
# File 'lib/gliffy/handle.rb', line 198

def document_move(document_id,new_path)
  make_request(:move,folders_url(new_path) + "/documents/#{document_id}.xml")
end

#document_update(document_id, options) ⇒ Object

Update a document’s meta-data or content

document_id

identifier of document to update

options

data to update; omission of an option will not change it

:name

change the name

:public

if false, will remove public statues, if true, will make public

:content

if present, should be the gliffy XML content to update (don’t use this unless it’s crucial)



208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/gliffy/handle.rb', line 208

def document_update(document_id,options)
  if (options[:content])
    make_request(:update,document_url(document_id),{:content => options[:content]})
  end
  if (options[:name] || options[:public])
    params = {}
    params[:documentName] = options[:name] if options[:name]
    params[:public] = options[:public] if options[:public]
    make_request(:update,document_metadata_url(document_id),params)
  end
end

#folder_add_user(path, username) ⇒ Object

Add a user to a folder



221
222
223
 
# File 'lib/gliffy/handle.rb', line 221

def folder_add_user(path,username)
  make_request(:update,folder_users_url(path,username),{:read => true, :write => true})
end

#folder_create(path) ⇒ Object

Create a new folder

path

the path to the folder, each path separated by a forward slash. If this starts with a forward slash it will attempt to make folder with the exact given path. This will probably fail. If this DOESN’T start with a slash, this will make the folder inside ROOT, which is what you want. So, don’t start this with a slash.



230
231
232
 
# File 'lib/gliffy/handle.rb', line 230

def folder_create(path)
  make_request(:create,"#{folders_url(path)}.xml")
end

#folder_delete(path) ⇒ Object

Delete a folder

path

the path to the folder. See folder_create.



236
237
238
 
# File 'lib/gliffy/handle.rb', line 236

def folder_delete(path)
  make_request(:delete,"#{folders_url(path)}.xml")
end

#folder_documents(path) ⇒ Object

Get the documents in a folder

path

the path to the folder whose documents to get



242
243
244
 
# File 'lib/gliffy/handle.rb', line 242

def folder_documents(path)
  make_request(:get,"#{folders_url(path)}/documents.xml")
end

#folder_remove_user(path, username) ⇒ Object

Remove a user from access to the folder



253
254
255
 
# File 'lib/gliffy/handle.rb', line 253

def folder_remove_user(path,username)
  make_request(:update,folder_users_url(path,username),{:read => false, :write => false})
end

#folder_users(path) ⇒ Object

Get users with access to the folder

path

the path to the folder whose users to get



248
249
250
 
# File 'lib/gliffy/handle.rb', line 248

def folder_users(path)
  make_request(:get,"#{folders_url(path)}/users.xml")
end

#update_token(force = false) ⇒ Object

Updates the token being used if there isn’t one in the credentials, or by forcing

force

always attempt to update the token



63
64
65
66
67
68
69
70
71
72
 
# File 'lib/gliffy/handle.rb', line 63

def update_token(force=false)
  if !@credentials.has_access_token? || force
    @logger.debug("Requesting new token " + (force ? " by force " : " since we have none "))
    response = @request.create(token_url,
                               :description => @credentials.description,
                               :protocol_override => :https)
    @token = Response.from_http_response(response)
    @credentials.update_access_token(@token)
  end
end

#user_create(username) ⇒ Object

Create a new user

username

the name to give this user



259
260
261
 
# File 'lib/gliffy/handle.rb', line 259

def user_create(username)
  make_request(:create,"#{account_url}/users.xml",{ :userName => username })
end

#user_delete(username) ⇒ Object

Delete an existing user



264
265
266
 
# File 'lib/gliffy/handle.rb', line 264

def user_delete(username)
  make_request(:delete,"#{user_url(username)}.xml")
end

#user_documents(username = '$username') ⇒ Object

Get the documents a user has access to (this is potentially expensive, as it results in multiple calls to gliffy)

username

if provided, get documents for the given username, otherwise get them for the logged-in user



271
272
273
 
# File 'lib/gliffy/handle.rb', line 271

def user_documents(username='$username')
  return user_documents_helper(username,user_folders(username))
end

#user_folders(username = '$username') ⇒ Object

Get the folders a user has access to

username

if provided, get folders for the given username, otherwise get them for the logged-in user



277
278
279
 
# File 'lib/gliffy/handle.rb', line 277

def user_folders(username='$username')
  make_request(:get,"#{user_url(username)}/folders.xml")
end

#user_update(username, options) ⇒ Object

Update a user’s meta-data

username

the username to operate on

options

the options for updating their info. Any omitted option will not change that value on the server.

:email

sets their email address

:password

sets their password for logging into gliffy.com

:admin

if true, sets them to be an admin; if false, revokes their admin privs



287
288
289
 
# File 'lib/gliffy/handle.rb', line 287

def user_update(username,options)
  make_request(:update,user_url(username),options)
end