twitterl

Overview

Twitterl is a set of modules that let you communicate with Twitter service.

Twitterl e_component provides three sets of functions:

the set of functions that do not require authentication to be performed
the set of functions that use plain username/password authentication
the set of functions that use OAuth for authentication

The naming conventions are as follows:

FOO/artiy - for the no authentication functions
FOO_auth/arity+2 - for username/password authentication functions (two first arguments are username and password as strings)
FOO_auth/arity - for OAuth authentication (note the additional function calls should be called before it - see OAuth section for details)

API

The twitterl module exports the following functions:

public_timeline/0
friends_timeline_auth/3, friends_timeline_auth/1
user_timeline/1, user_timeline_auth/3, user_timeline_auth/1
mentions_auth/3, mentions_auth/1
status_show/1, status_show_auth/3, status_show_auth/1
status_update_auth/4, status_update_auth/2
status_destroy_auth/3, status_destroy_auth/1
user_show/1, user_show_auth/3, user_show_auth/1
status_friends/1
status_followers_auth/3, status_followers_auth/1

See Twitter API for descriptions.

OAuth

Twitter service allows us to use OAuth authentication mechanism. In order to use it we must have the oauth Erlang library. It is available for download from Github: http://github.com/tim/erlang-oauth/tree/master. The beam files must be accessible in the Virtual Machine code path.

At first we must acquire the request token. Call twitterl_oauth:get_request_token() somewhere inside your controller. The function, after successful twitter servers communication, should return URL user should be redirected to. There she must allow our component to use her account. When user has visited the twitterl authentication site, our controller should call twitterl_oauth:get_access_token() which will check the component access and save the access token in the user's session. From now user may call the functions suffixed with _auth without providing hers username/password.

Basic type - twitter

Twitterl e_component provides also new basic type named twitter. Wpart is expanding to the same HTML form as on the original site (with nice JS characters counter). Wtype is validating the length of the twit and may also check for the minimum entered letters.

In order to make the wpart:twitter work correctly we should copy two files from the priv/ application directory to the docroot of our project. The files are twitterl.css and twitterl.js. Note the twitterl.js requires jQuery library (which should also be put in the docroot catalogue). Remember also that the files should be served from the docroot directly by setting up dispatcher rules to e.g.:

   1 {static, "^/twitterl.css$", enoent}.
   2 {static, "^/twitterl.js$", enoent}.
   3 {static, "^/jquery.js$", enoent}.

The example HTML page should then look like:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

  <head>
    <title>Erlang Web</title>

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

    <script src="/jquery.js" type="text/javascript"> </script>
    <script src="/twitterl.js" type="text/javascript"> </script>
    
    <link rel="stylesheet" href="/twitterl.css" type="text/css" /> 
  </head>
  
  <body>

    <wpart:twitter />

  </body>

</html>

It should be then rendered to the following form:

During the system start e_component should register the new basic type.

Utilities

The last interesting module, twitterl_utils provides some set of the helper functions that can retrieve the most popular fields from the twitter responses:

id/1, text/1 - for getting the twit id and text content respectively
author_name/1, author_screen_name/1, author_id/1 - for getting the information about twit's author

e_json

WARNING: twitterl component requires the patched version of the e_json module (the negative integer decoding was a little bit buggy) - at least commit no. 262 (available for download from the official bitbucket's account: http://bitbucket.org/etc/erlang-web/src/fabd90f40ad3/lib/eptic-1.3/src/e_json.erl).