Twitter Pull

Twitter Pull is a small module, the only purpose of which is to allow super-easy embedding of public twitter data like: a user timeline or twitter search results by hashtag or a search term. The emphasis is on making these very specific tasks as easy and straightforward as possible. The purpose of the module is not to be an end-all solution for Twitter.

Intended Audience

The intended audience of the module are developers and designers.

Usage

There're no authentication information or API Keys required. Module only interacts with non-auth APIs. In the end, it all boils down to a single function:

twitter_pull_render ($twitkey, $title = NULL, $num_items = NULL, $themekey = NULL)

ARGUMENTS:

• @param $twitkey
  Twitter key, which can be a username (prepended with @) a hashtag (prepended with #) or a search keyword (no prefix)
• @param $title
  title passed to tpl.php. If you want title to be disabled, pass boolean False.
• @param $num_items
  maximum number of tweets to pull from the Twitter result-set. Can't be more than 20.
• @param $themekey
  Drupal theme key-name to use for theming the output of the Twitter response. Allows providing different tpl.php's for different use-cases. The default is: twitter_pull_listing, which corresponds to a fully-themed twitter-pull-listing.tpl.php in module folder. Please note that underscores become dashes in the TPL name and you may not use dashes in the key name. The tpl.php can be copied to a theme folder for further customization or modified via CSS.

Examples

The following code will print a nicely themed list of the latest 10 tweets from OpenPublish:

<?php if (function_exists('twitter_pull_render')) { print twitter_pull_render('@openpublish', 'OpenPublish', 10); } ?>

Integration from Modules

If you are writing a module code, a more elegant form of integrating with the module (rather than direct output) is to implement hook_twitter_pull_blocks() function:

function twitter_test_twitter_pull_blocks() {
  return array(
    0 => (object) array(
      'delta' => 'twitter_test_0',
      'tweetkey' => 'inadarei',
      'title' => 'Irakli Tweet Feed',
      'name'  => 'Irakli Tweet Feed',    
      'number_of_items' => 5,
      'theme_key' => 'twitter_pull_listing',    
    )
  );
  
}

Please note that title, number_of_items and theme_key are optional keys. Name defaults to "title" key, the other two default to values shown in the code snippet. Please note that if you define a custom theme_key you have to also properly initialize it in a hook_theme of your own (see more below).

Theming

If you decide to use a custom theme_key, you will have to register it with a hook_theme in a module. Unfortunately, there's not a good way for this module to do it. You should use code like following:

function yourmodule_theme() {
  return array(
    'your_custom_theme_key' => array(
      'arguments' => array('tweets' => NULL, 'twitkey' => NULL, 'title' => NULL),
      'template' => 'your-custom-theme-key'
    ),
  );
}

Performance

Output is extensively cached. Default cache period is 20 minutes, but it can be overridden via configuration variables.

What About Twitter Module?

Twitter module is a much more generic solution to Twitter integration in Drupal. Twitter Pull has a more specific goal, which it achieves in simpler, more focused way, is very lightweight, and provides advanced theming and caching, as well as support to Twitter Search API.

At some point the two modules could possibly merge, but at this point they don't really have much in common, except that they both do "something" with Twitter. Things they do are not identical.

How do I use this with Panels, Context etc.?

If you need more flexibility than just printing-out tweet list in a template file, you should write a quick glue module implementing hook_block() according to your specific application logic and calling the twitter_pull_render() function from the hook.

Requirements

This module requires the PHP JSON extension, which is included in PHP 5.2 and later or as a separate extension.

Oauth Dependency

Dependency on OAuth module was introduced due to changes in Twitter API 2.x. See #1781024: Make the Twitter Pull module work when Twitter turns off the version 1 API for more information.