The Code:
(function(_name, _ns) {
...
})("TWITTER");
By default, the class that gets created is named TWITTER.
Rather than just assuming that you dont already have something named TWITTER that exists in the global namespace, however, this name is easily overrideable.
To call it something other than TWITTER, just change the string that is passed in to whatever you want the class to be named. We'll take care of the rest.
(If you do change the name, however, just make sure that anywhere the documentation says "new TWITTER();", you change your code accordingly to reflect the new name);
You also may have noticed the second param that is not being used by default (_ns). If you want to add this class into an already existing object, you will use that param. You would still use the first param (_name) to declare what you would want the name of the class to be, but you would use the second param to pass in a *STRING* representation of where you want the class to be placed within the existing object you want to add it to.
for example, if you already have a defined library like:
var MyAwesomeLibrary = { thatDoesntHave:{ twitterYet : {} } };
You could add this class into that library by modifying the last section as follows:
(function(_name, _ns) {
...
})("TWITTER", "MyAwesomeLibrary.thatDoesntHave.twitterYet"); // you need the quotes... this param has to be a string.
Once you have created an instance of your class, you will be able to call the following methods:
(see the pages that relate to each corresponding method ( http://apiwiki.twitter.com/Twitter-API-Documentation ) for the possible paramters to be used in each call, and the response issued from each one.
additional parameters available to every method:
error: a function that will get executed on an error in requesting the link (timeout, 404, etc);
cb_scope: if you would like your callback or error functions to be called with a scope other than window (default) pass that object in to the function as the cb_scope parameter, and that object will be used as the scope of the call: (callback.call(cb_scope);)
some notes...
you dont need json2.js.. .that is only used in the test html page in order to stringify the JSON results for output.
the responses from the search and trends api calls have the array of results buried one level deep in the response object. this is normalized in the way the data is preprocessed before being handed off to the callback function that you define and pass in. You can always expect "data" that is passed in to the function to be the actual meat of the response. In these methods, any other info that is contained in the response, other than the meat, is added into an object that is accessible via the second "meta" param to the function.
whenever there is an option of using id, user_id, or screen_name as a param, use the param named "id" (this can usually accept either the user_id or screen_name)
your callback function can be an anonymous function created inline in the param object passed to each function, it will be wrapped, stored in a global callback cache (on the object already created... no further global namespace pollution) and the appropriate string will be added to the url to invoke your function on the data loading, but should use the param name "callback" regardless of if you use a named function or an anonymous function.
the callback function takes 2 params... data, which will store the meat of the response, and meta, which may contain additional info returned with the response if there is any
var t = new TWITTER();
t.search({q:"tiger woods", callback:function(data, meta) { /* do something here */ }});
t.trends({callback:function(data, meta) { /* do something here */ }});
t.trends.current({callback:function(data, meta) { /* do something here */ }});
t.trends.daily({callback:function(data, meta) { /* do something here */ }});
t.trends.weekly({callback:function(data, meta) { /* do something here */ }});
t.statuses.public_timeline({callback:function(data, meta) { /* do something here */ }});
t.statuses.user_timeline({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.statuses.show({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.statuses.friends({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.statuses.followers({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.users.show({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.lists.list_statuses({user:"jeffreytierney", list_id:document.getElementById("lists_list_statuses_list_id").value, callback:function(data, meta) { /* do something here */ }});
t.friendships.show({source_screen_name:"jeffreytierney", target_screen_name:"yourscreenname, callback:function(data, meta) { /* do something here */ }});
t.friends.ids({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.followers.ids({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.favorites({id:"jeffreytierney", callback:function(data, meta) { /* do something here */ }});
t.account.rate_limit_status({callback:function(data, meta) { /* do something here */ }});