CFAviary

CFAviary is a ColdFusion wrapper for the new Aviary Effects API. This wrapper encapsulates all the Effects API methods, and has some convenience functions for parsing XML responses from the API.

CFAviary is completely free and open-source, so feel free to branch the GitHub repo.  Enjoy!

Look and Feel

• GitHub Repository
• Demo Page
• Aviary Effects API
• Real World App

Usage

Using CFAviary is very simple. To get started with using the wrapper, simply create a new instance of the Aviary component:

<cfscript>
Aviary = new com.aviary(api_key=”xxxxx”,secret=”xxxxxx”,response_format=url.format);
</cfscript>

Each Aviary API invocation requires a hashed signature, which is based on your api_key, your api secret token, and a concatenation of all parameters for the given method. Within Aviary.cfc, a structure is created called “baseparams” which houses the root parameters which are used in every single API call, regardless of methods. From there, the methods smartly add the necessary parameters to each call to form a valid signature.

Methods

init()

init() initializes the instance of the Aviary component. It creates the baseparams structure that is used in each method for the hashed signature creation.

gettime()

gettime() is an Aviary API method which returns the current UNIX timestamp of the Aviary service. You can use this to compare timestamps, although it is really only useful if you’re already submitting a valid timestamp!

getfilters()

getfilters() is an Aviary API method which returns a listing of all available filters for use within the Effects API.

upload()

upload() is an Aviary API method which allows you to upload a file to Aviary’s service. It returns the url of the processed image, so you can use the same url later on for other API methods.

renderoptions()

renderoptions() is an Aviary API method which returns a image divided into a grid of smaller images, each of which is mapped to a configuration object of rendering parameters. You can store these configuration options, and use them when a user chooses one of the grid images to pass to the render() method.

render()

render() is an Aviary API method which takes a configuration object returned from renderoptions() (or a custom built one), applies the filter configuration to an image path, and returns the url of the post-processed image.

createsig()

createsig() is a generic method which works to create a valid hashed “signature” for each of the Aviary API methods.

createunixtimestamp()

createunixtimestamp() creates a valid UNIX timestamp which can be used in Aviary API methods.

createrenderparameterxml()

createrenderparameterxml() is a helper method for creating a valid XML string to be used for the renderparameters argument of the render() Aviary API method.

saveimage()

saveimage() is a simple convenience method for saving an image to the server on which CF is running.

formatupload()

formatupload() is a convenience method for converting the XML returned from the upload() method into JSON. You can safely adjust this method to fit your application’s needs.

formatfilters()

formatfilters() is a convenience method for converting the XML returned from the getfilters() method into JSON. You can safely adjust this method to fit your application’s needs.

formatrenderoptions()

formatrenderoptions() is a convenience method for converting the XML returned from the renderoptions() method into JSON. You can safely adjust this method to fit your application’s needs.

formatrender()

formatrender() is a convenience method for converting the XML returned from the render() method into JSON. You can safely adjust this method to fit your application’s needs.

Changelog

Version 1.2.1 (6-2-11)

• After a discussion with the API devs, CFAviary is now running 100% JSON! No more XML (woot!). And the people rejoiced!

Version 1.2 (5-27-11)

• Changed datatype of renderparameters argument of the renderoptions() method from array to string. This is more in keeping with the API itself, and will be more flexible if this argument can ever be a JSON string, rather than a string of XML

Version 1.1 (5-26-11)

• Added JSON support for all methods (simply init() with response_format=”json”)
• Fixed a bug in Aviary.cfc that leaked some variables on subsequent method calls
• Added AviaryCF_JSON.js and handler_json.cfm to showcase JSON support