[ class tree: Gliffy ] [ index: Gliffy ] [ all elements ]

Class: Gliffy

Source Location: /Gliffy.php

Class Overview


Primary method of interacting with Gliffy.


Author(s):

  • David Copeland, Chris Kohlhardt

Variables

Constants

Methods



Class Details

[line 83]
Primary method of interacting with Gliffy.

This class should be created per session, and requires a user to be identified with that session. The recommedation is that you create an instance of this class during a user authentication and store it in $_SESSION. Note that a session is established with Gliffy via the user aotuh_token. This class keeps track of the assigned token, and its expiration date, and will attempt to re-acquire a new token if it believes the current one is out of date. You can programmatically re-acquire the token via updateToken(). Also note that there is a 5 minute tolerance, so if the token is going to expire in the next 5 minutes, this class will reacquire it. This should hopefully address any drift between your server and Gliffy's.

All of these methods throw exceptions when an error is received from Gliffy. This allows your code to be a bit more simple, without a lot of error checking, since errors from Gliffy are either programming errors on your part or intermittent errors, such as network errors. You can intercept these errors by using the callback parameter to this class' constructor. In most cases, this is actually recommended so that errors that occur don't interrupt the page being served.




Tags:

author:  David Copeland, Chris Kohlhardt
example:  example


[ Top ]


Class Variables

$_rest =

[line 107]

GliffyREST instance



Tags:

access:  public

Type:   mixed


[ Top ]



Class Methods


constructor Gliffy [line 126]

Gliffy Gliffy( string $username, [function $error_callback = null])

Create a new connection to Gliffy.

This should be done as part of the user authentication/session creation.




Tags:

access:  public


Parameters:

string   $username   the name (or other identifier) of the user. This user should be unique to your account. The user need not exist in Gliffy, although, if he does not, Gliffy will attempt to provision him. If your account has reached it's limit, this will fail, and a GliffyException will be thrown here.
function   $error_callback   if present, this will called instead of an exception being thrown whenever an exception is triggered, except during the execution of this constructor.

[ Top ]

destructor __destruct [line 153]

void __destruct( )

No-op destructor



[ Top ]

method addUser [line 662]

boolean addUser( string $username)

Adds the named user to the account, if sufficient users exist.

An exception here indicates a problem unrelated to the account maximum.




Tags:

return:  true if the user was added, false if the account has already reached its maximum number of users.
access:  public


Parameters:

string   $username   the name of the user to add.

[ Top ]

method addUserToFolder [line 559]

void addUserToFolder( string $folderName, string $username)

Adds the user to the given folder, so that he may have access to that folder's contents.



Tags:

access:  public


Parameters:

string   $folderName   the name of the folder to which the user should be added
string   $username   the user to add (they should exist)

[ Top ]

method createDiagram [line 258]

integer createDiagram( string $diagramName, [int $templateDiagramId = 0])

Creates a new diagram with the given name, possibly based on an existing diagram.



Tags:

return:  the id of the diagram that was created. An exception is thrown if there was a problem.
access:  public


Parameters:

string   $diagramName   the name of this diagram
int   $templateDiagramId   if positive, represents a diagram id to use as the initial version of the new diagram. If omitted, a blank diagram is created. Note that the user whose token is contained in this object must have access to the diagram via this account

[ Top ]

method createFolder [line 508]

void createFolder( string $folderPath)

Creates a folder at the given path. Throws an exception if there was a problem (including the folder already existing)



Tags:

access:  public


Parameters:

string   $folderPath   the path of the folder to create; should be unique within the application

[ Top ]

method deleteDiagram [line 288]

void deleteDiagram( integer $diagramId)

Deletes the diagram.



Tags:

access:  public


Parameters:

integer   $diagramId   the id of the diagram to delete

[ Top ]

method deleteFolder [line 524]

void deleteFolder( string $folderPath)

Deletes the folder with the given path. All diagrams in this folder will move to the default folder (which, incidentially, cannot be deleted).

This throws an exception if the folder didn't exist or there was some other problem.




Tags:

access:  public


Parameters:

string   $folderPath   the name of the folder to delete

[ Top ]

method deleteToken [line 166]

void deleteToken( )

Delete the OAuth token for this user, effectively logging the user out.

Any image links or other request URL's created using this token will become invalid.




Tags:

access:  public


[ Top ]

method deleteUser [line 642]

void deleteUser( string $username)

Deletes the given user (from this acount), which may not be the user whose session owns this object.

If the user doesn't have access to other Gliffy accounts, his record is deleted. This cannot be undone.




Tags:

access:  public


Parameters:

string   $username   the name of the user to delete

[ Top ]

method getAccountInfo [line 788]

void getAccountInfo( )



[ Top ]

method getAdmins [line 709]

array getAdmins( )

Returns the list of "admins" for the account. Admins can mean whatever you want them to mean, however for Gliffy, an admin is simply someone who has access to all Folders of an account.



Tags:

return:  an array of GliffyUser objects
access:  public


[ Top ]

method getDiagramAsImage [line 313]

mixed getDiagramAsImage( integer $diagramId, [string $mime_type = Gliffy::MIME_TYPE_PNG], [string $file = null], [string $size = null], [integer $version = null])

Gets the diagram as an image, possibly saving it to a file.



Tags:

return:  if $file was null, returns the bytes of the diagram, otherwise, returns true
access:  public


Parameters:

integer   $diagramId   the id of the diagram to get
string   $mime_type   the mime type. Note that values that are not MIME_TYPE_JPEG, MIME_TYPE_PNG, or MIME_TYPE_SVG aren't guaranteed to work.
string   $file   if non-null the name of the file to write the diagram to.
string   $size   the size of the diagram. Currently supports "T" (thumbnail), "S" (small), "M" (medium), "L" (large). This sizes are porportions based on the diagram's size. This is ignored if the mime type doesn't support it (e.g. SVG). Null indicates to use Gliffy's default.
integer   $version   the version to get. A value less than or equal to the "num versions" of the diagram will be valid. This is one-based. A value of null means to get the most recent version

[ Top ]

method getDiagramAsURL [line 384]

string getDiagramAsURL( integer $diagramId, [string $mime_type = Gliffy::MIME_TYPE_PNG], [string $size = null], [string $version = null], [boolean $force = false])

Returns a URL to the diagram that can be used in an HTML IMG tag.

This URL is only good as long as the user's token is good, so it should not be use for long-term reference to the diagram. Parameters are the same as for getDiagramAsImage, save for the missing file parameter.




Tags:

return:  a URL to the requested image
access:  public


Parameters:

integer   $diagramId   id of the diagram
string   $mime_type   mime type
string   $size   size (null means full size)
string   $version   which version (null means current)
boolean   $force   if true, put some randomness in the URL to try to keep the browser for caching it

[ Top ]

method getDiagramAsXML [line 784]

void getDiagramAsXML( $diagramId)



Tags:

access:  public


Parameters:

   $diagramId  

[ Top ]

method getDiagramMetaData [line 463]

GliffyDiagram getDiagramMetaData( integer $diagramId)

Returns meta-data about a particular diagram.

Note that an anonymous user will get a 401/Unauthorized, if they attempt to get meta data about a non-public diagram. To make things easier, this method will return a GliffyDiagram object. This way "null" can be viewed as a bad diagram id, an exception can be viewed as an legitimate problem and a non-null return as something usable. If the user owning this Gliffy object is anonymous, and the returned diagram is not public, you will know that they recieved a 401 from the back-end.




Tags:

return:  the diagram's info, or null if it wasn't found
access:  public


Parameters:

integer   $diagramId   the id of the diagram

[ Top ]

method getDiagrams [line 416]

array getDiagrams( [string $folderPath = null])

Gets a list of diagrams, either for the entire account, or for the given folder.



Tags:

return:  an array of GlifyDiagram objects representing the diagrams in the given context. Throws an exception if there was some problem. Shouldn't return null
access:  public


Parameters:

string   $folderPath   if present, returns a list of diagrams in the folder only. This is the full path/name of the folder

[ Top ]

method getEditDiagramLink [line 487]

String getEditDiagramLink( integer $diagramId, [string $returnURL = null], [string $returnText = null])

Builds a returns a Gliffy editor launch link for the given diagram id



Tags:

return:  this 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. Throws an exception if there was a problem
access:  public


Parameters:

integer   $diagramId   the id of the diagram to edit
string   $returnURL   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
string   $returnText   the text that should be used in Gliffy to represent the "return to the application" button.

[ Top ]

method getFolders [line 539]

a getFolders( )

Returns all folders in this account.



Tags:

return:  ROOT GliffyFolder object which contains sub-folders as children
access:  public


[ Top ]

method getUserDiagrams [line 727]

array getUserDiagrams( [string $username = null])

Gets all diagrams that the user can access



Tags:

return:  an array of GliffyDiagram objects, sorted by name, that represent all diagrams in all folders to which the given user has access
access:  public


Parameters:

string   $username   if null, the user whose session this is will be used

[ Top ]

method getUserFolders [line 623]

array getUserFolders( string $username)

Returns the folders the given user has access to.



Tags:

return:  an array of GliffyFolder objects.
access:  public


Parameters:

string   $username   the name of the user to check

[ Top ]

method getUsers [line 595]

array getUsers( [string $folderName = null])

Returns all users in the account, or in the folder specified.



Tags:

return:  an array of GliffyUser objects.
access:  public


Parameters:

string   $folderName   if not null, returns a list of users who have access to that folder. If null, all users in the account are returned.

[ Top ]

method hasToken [line 177]

void hasToken( )

Returns true if this object has a token for the user. This makes no call to the server and will not try to update the user's token.



Tags:

access:  public


[ Top ]

method moveDiagram [line 443]

void moveDiagram( integer $diagramId, string $folderPath)

Moves the diagram from its current folder to the new folder (if the user owning this session

has access to the diagram




Tags:

access:  public


Parameters:

integer   $diagramId   the id of the diagram to move
string   $folderPath   the path of the folder to move it to

[ Top ]

method removeUserFromFolder [line 577]

void removeUserFromFolder( string $folderName, stinrg $username)

Removes the user from the given folder.



Tags:

access:  public


Parameters:

string   $folderName   the name of the folder from which to remove the user
stinrg   $username   the name of the user to remove

[ Top ]

method updateDiagramContent [line 748]

void updateDiagramContent( $diagramId, $content)



Tags:

access:  public


Parameters:

   $diagramId  
   $content  

[ Top ]

method updateToken [line 190]

GliffyUserToken updateToken( [boolean $force = false])

Update the user's token, if it needs it. This gets the user token from Gliffy, which can have one of three effects:

  • If the user exists and has a valid token, it is returned
  • If the user exists and has no token, or an expired one, a new one is created and returned
  • If the user is unknown to gliffy, they are provisioned
Whatever the outcome, the internal state of this object is updated with the new token.




Tags:

return:  token, or null if there was a problem.
access:  public


Parameters:

boolean   $force   if true, the token is requested from the server regardless of this object's internal state.

[ Top ]

method updateUser [line 686]

void updateUser( string $username, [boolean $admin = null], [string $email = null], [string $password = null])

Updates the user's information.

This is useful for three things:

  • manage account "admins"
  • if you wish to store actual user emails with their gliffy accont for simplified association
  • if you wish to allow users to access your Gliffy data via the Gliffy website. With the email and password, they will be able to login to Gliffy outside of your application.




Tags:

access:  public


Parameters:

string   $username   the user to update
boolean   $admin   if non-null, sets this user's admin status (null indicates no change should be made)
string   $email   the email address to give them. This must be unique to all of Gliffy. null indicates no change
string   $password   the password to give them so that they can access Gliffy via the Gliffy website. null indicates no change

[ Top ]


Class Constants

EXPIRE_TOLERANCE =  300

[line 97]


[ Top ]

IMAGE_ERROR =  "http://www.gliffy.com/go/images/apiIntegrationProblem.png"

[line 95]

A static image you can use to indicate there is an error when viewing an image of a diagram


[ Top ]

IMAGE_NO_PERMISSION =  "http://www.gliffy.com/go/images/apiPermissionProblem.png"

[line 93]

A static image you can use to indicate there is a permission problem for viewing an image of a diagram


[ Top ]

MIME_TYPE_JPEG =  "image/jpeg"

[line 86]

Mime type for JPEG images


[ Top ]

MIME_TYPE_PNG =  "image/png"

[line 88]

Mime type for PNG images


[ Top ]

MIME_TYPE_SVG =  "image/svg+xml"

[line 90]

Mime type for SVG images


[ Top ]



Documentation generated on Wed, 01 Apr 2009 18:11:08 -0700 by phpDocumentor 1.4.1