Home

Matt Gifford edited this page Jan 30, 2014 · 8 revisions
Clone this wiki locally

Welcome to monkehTweet

monkehTweet (pronounced monkeyTweet... just go with it) is a ColdFusion wrapper that interacts with the Twitter Rest 1.1 API.

monkehTweet was developed and built with the specific intention of making interacting with and using the Twitter API within your CFML applications incredibly easy and, dare I say it, an enjoyable experience.

Don't just take my word for it. Millions** of developers are using monkehTweet with smiles on their faces.

monkehtweet.riaforge.org is a thing of beauty, nice job @coldfumonkeh

— Ben Forta (@benforta) November 2, 2012

** perhaps not millions

If you experience any bugs or issues when implementing or using the library please post it to either the RIAForge issue tracker or as an issue here on the Github repository.

It may also be worth first checking the frequently asked questions / issues page here in the wiki.

Getting Started

Requirements

  • ColdFusion 8 or later
  • Railo 3.2.2 or later

Overview

monkehTweet consists of one core CFC: com.coldfumonkeh.monkehTweet

This CFC is the only one you will need to interact with and is a service layer to all underlying components and available methods.

No mappings are required to get up and running, although you naturally have freedom to place the library wherever you choose to on your server and map away to your heart's content.

Installation

Download and unzip the package (or fork / clone from the repository) to your desired location on your server (examples in this wiki and the code itself assume the package has been placed in the web root).

You should then see the following structure:

  • /com
  • /installation
  • Application.cfc
  • README.md
  • authorize.cfm
  • index.cfm
  • post.cfm

The default demo application does not interact with any database or datasource, and as such you do not have to set anything in the ColdFusion administrator.

Twitter Application Setup

To interact with the Twitter API you will need to create and register an application with Twitter which will generate the consumer key and consumer secret token values. These are required parameters to send into the monkehTweet init() method for component instantiation.

Creating your application

Here are the steps required to set this up:

  • Visit http://dev.twitter.com and sign in with the account name you wish to use
  • Hover over your user profile image in the top right of the page and select My Applications from the drop down menu
  • Click Create a new application
  • Enter in your application name, description, website AND callbackURL as shown in the example below.

Note: You MUST set a callback URL in the field. If you leave it blank, Twitter will assume you are running an Out Of Bounds application and any requests to the authentication endpoint will fail. The URL does not have to be the exact URL you will use (we will set that in the monkehTweet code which we'll see later) but a URL must be provided.

Once submitted (and you've navigated the CAPTCHA images and agreed to the developer terms and conditions) you will be presented with your application screen which includes the following tabs:

OAuth Consumer Tokens

Your OAuth settings will also be visible, which includes the all-important consumer key and consumer secret values. Make a note of these, as you will need them when instantiating the monkehTweet component.

These consumer values are the bare minimum needed to get up and running with monkehTweet. If you're happy with this, proceed to the next step to start coding and instantiate monkehTweet.

Setting Application Type

By default your Twitter application is granted with read-only permission. If you want to be able to post updates or access direct messages on behalf of a user you will need to change the permission model.

  • Click the Settings tab and change the application type to whichever access role you need. You can be greedy if you want to and go for full access. Remember, when a user authenticates against your application they do have the ability to refuse your permissions.

Single User Access

Having a "Me Party"? You may just want to use your application to interact with your own Twitter account and no one elses. If that is the case you can of course authenticate against your own application but Twitter will let you generate the access token and access secret values directly from the application details screen.

  • Within the Details tab scroll to the bottom and click the Create my access token button

Wait for Twitter to generate your access details. You may need to refresh the page after 20 seconds.

You should then be presented with your access token and access token secret values. Make a note of these as you will need to add them into the monkehTweet init() method when instantiating the component.

Once you have these details you can proceed to the next step to start coding and instantiate monkehTweet.

Limitations

Remaining Functionality

monkehTweet does nto currently include any of the methods to interact with the Twitter Stream API.

Testing

monkehTweet has been tested on the Adobe ColdFusion platform and Railo. It has yet to be tested on OpenBlueDragon.