2 Tags: twitter, tweet, integration, post, digest, notify, integrate, archive, widget

     2 Contributors: alexkingorg, crowdfavorite

     3 Contributors: alexkingorg. crowdfavorite

     3 Tags: twitter, tweet, integration, post, notify, integrate, archive, widget, shortcode, social

     4 Requires at least: 2.3

     4 Requires at least: 3.4

     5 Tested up to: 2.8.3

     5 Tested up to: 3.4.2

     6 Stable tag: 2.0

     6 Stable tag: 3.0.3

     7 License: GPLv2

     8 License URI: http://www.gnu.org/licenses/gpl-2.0.html

    10 == Details ==

    12 == Description ==

    14 * Archive your Twitter tweets (downloaded every 10 minutes)

    16 * Connect multiple Twitter accounts (via Social)

    17 * Archive the tweets from your Twitter accounts (downloaded every 10 minutes)

    16 * Create a daily or weekly digest post of your tweets

    19 * Create a tweet on Twitter whenever you post in your blog, with a link to the blog post (via Social)

    17 * Create a tweet on Twitter whenever you post in your blog, with a link to the blog post

    20 * Browse your tweets locally by @mention, #hashtag or user account (optionally display these publicly)

    18 * Post a tweet from your sidebar

    21 

    19 * Post a tweet from the WP Admin screens

    22 Twitter Tools leverages Social's connection to Twitter so that you don't have to create an app and copy keys around. It supports multiple accounts (must be authorized as "global" accounts in Social) with settings on a per-account basis.

    20 * Pass your tweets along to another service (via API hook)

    26 2. Put the 'twitter-tools.php' file into your wp-content/plugins/ directory.

    30 2. Put the 'twitter-tools' directory into your wp-content/plugins/ directory.

    28 4. Go to the Twitter Tools Options page (Options > Twitter Tools) to set your Twitter account information and preferences.

    32 4. Go to the Twitter Tools Options page (Settings > Twitter Tools) to set up your Twitter information and preferences.

    29 

    33 

    30 

    34 

    31 == Configuration ==

    35 == Upgrading ==

    32 

    36 

    33 There are a number of configuration options for Twitter Tools. You can find these in Options > Twitter Tools.

    37 If you have upgraded from an older version of Twitter Tools, your data will need to be converted to the new Twitter Tools format. On the Twitter Tools Options page you will see a prompt to upgrade if appropriate. Follow the steps to convert your data.

    34 

    38 

    35 == Showing Your Tweets ==

    39 Twitter Tools now stores complete Twitter data along with your basic tweet content. Over time, Twitter Tools will request this data for upgraded tweets. This process make take a few days, as only 10 tweets are requested per hour (to avoid egatively impacting your rate limit).

    36 

    40 

    37 = Widget Friendly =

    41 

    38 

    42 == Connecting Accounts ==

    39 If you are using widgets, you can drag Twitter Tools to your sidebar to display your latest tweets.

    43 

    40 

    44 Any Twitter accounts connected on the Social settings page are available for Twitter Tools. You can enable them on a per-account account basis, as well as specifying per-account preferences for creating blog posts, etc. (on the Twitter Tools options screen).

    41 

    45 

    42 = Template Tags =

    46 

    43 

    47 == Managing your Tweets ==

    44 If you are not using widgest, you can use a template tag to add your latest tweets to your sidebar.

    48 

    45 

    49 You can view, edit and delete (or unpublish) the local copy of your Tweets right in your WordPress admin. Navigate the tweets from the "Tweets" menu item and manage them just as you would any other post type. Twitter Tools does not know if you've deleted a tweet on Twitter, so you'll need to also delete the copy of the tweet from the admin to remove it from your WordPress site.

    46 `<?php aktt_sidebar_tweets(); ?>`

    50 

    47 

    51 

    48 

    52 == Displaying your Tweets ==

    49 If you just want your latest tweet, use this template tag.

    53 

    50 

    54 Twitter Tools include options to create URLs for your local tweets using the following scheme:

    51 `<?php aktt_latest_tweet(); ?>`

    55 

    52 

    56 - single tweet: http://alexking.org/tweets/253580615113400321

    53 

    57 - account archive: http://alexking.org/tweet-accounts/alexkingorg

    54 == Hooks/API ==

    58 - @mention archive: http://alexking.org/tweet-mentions/sogrady

    55 

    59 - #hashtag archive: http://alexking.org/tweet-hashtags/monktoberfest

    56 Twitter Tools contains a hook that can be used to pass along your tweet data to another service (for example, some folks have wanted to be able to update their Facebook status). To use this hook, create a plugin and add an action to:

    60 

    57 

    61 You can enable public URLs for your tweets in your Twitter Tools settings. If you choose not to enable public URLs for your tweets, you can still vuew and manage them from within the admin screens.

    58 `aktt_add_tweet` (action)

    62 

    59 

    63 = Shortcode =

    60 Your plugin function will receive an `aktt_tweet` object as the first parameter.

    64 

    61 

    65 You can use a shortcode to display a list of tweets.

    62 Example psuedo-code:

    66 

    63 

    67 	[aktt_tweets account="alexkingorg"] 

    64 `function my_status_update($tweet) { // do something here }`

    68 

    65 `add_action('aktt_add_tweet', 'my_status_update')`

    69 If you want, you can specify some additional parameters to control how many tweets are displayed:

    66 

    70 

    67 ---

    71 	[aktt_tweets account="alexkingorg" count="5" offset="0"]

    68 

    72 

    69 Twitter Tools also provides a filter on the URL sent to Twitter so that you can run it through an URL-shortening service if you like.

    73 You can also choose to explicitly include or exclude replies and retweets:

    70 

    74 

    71 `tweet_blog_post_url` (filter)

    75 	[aktt_tweets account="alexkingorg" include_rts="0" include_replies="1"]

    72 

    76 

    73 Your plugin function will receive the URL as the first parameter.

    77 If you want to limit the tweets to specific @mentions or #hashtags, you can to that as well:

    74 

    78 

    75 Example psuedo-code:

    79 	[aktt_tweets account="alexkingorg" mentions="crowdfavorite,twittertools" hashtags="wordpress,plugin,twittertools"]

    76 

    80 

    77 `function my_short_url($long_url) {

    81 = Widget =

    78 	// do something here - return the shortened URL 

    82 

    79 	$short_url = my_short_url_func($long_url);

    83 The options for the shortcode are also available for the Twitter Tools widget via a few settings.

    80 	return $short_url;

    84 

    81 }`

    85 = Create Blog Posts =

    82 `add_filter('tweet_blog_post_url', 'my_short_url')`

    86 

    83 

    87 Twitter Tools can create a blog post from each of your Tweets. This feature can be enabled on a per-account basis. If there is an image included in the media data of the tweet Twitter Tools will try to save that image as the featured image for the post and append it to the blog post content.

    84 ---

    88 

    85 

    89 Please note that this will take effect for all future tweets, it does not retroactively create posts for older tweets (though you could pretty easily script it to do so if you desired).

    86 `aktt_do_tweet` (filter)

    90 

    87 

    91 

    88 Returning false in this hook will prevent a tweet from being sent. One parameter is sent, the Tweet object to be sent to Twitter.

    92 == Customization ==

    89 

    93 

    90 Example psuedo-code:

    94 Twitter Tools is designed to be customizable via the standard hook/filter API. If you find you need additional hooks (or to suggest other bug fixes and enhancements) please create a pull request on GitHub.

    91 

    95 

    92 `function dont_tweet($tweet) {

    96 https://github.com/crowdfavorite/wp-twitter-tools

    93 	if (some condition) {

    97 

    94 		// will not tweet

    98 Get creative! Here are some examples of ways to use more of the full Twitter data to create links back into Twitter where appropriate:

    95 		return false;

    99 

    96 	}

   100 - linking to the original tweet on Twitter

    97 	else {

   101 - linking to "in reply to" tweets

    98 		// must return the $tweet to send it

    99 		return $tweet;

   100 	}

   101 }`

   102 `add_filter('aktt_do_tweet', 'dont_tweet')`

   103 

   104 ---

   105 

   106 `aktt_do_blog_post_tweet` (filter)

   107 

   108 Returning false in this hook will prevent a blog post Tweet from being sent. Two parameters are passed, the Tweet object to be sent to Twitter and the Post generating the Tweet.

   109 

   110 Example psuedo-code:

   111 

   112 `function dont_post_tweet($tweet, $post) {

   113 	if (some condition) {

   114 		// will not tweet

   115 		return false;

   116 	}

   117 	else {

   118 		// must return the $tweet to send it

   119 		return $tweet;

   120 	}

   121 }`

   122 `add_filter('aktt_do_blog_post_tweet', 'dont_post_tweet', 10, 2)`

   123 

   124 ---

   125 

   126 `aktt_do_tweet_post` (filter)

   127 

   128 Returning false in this hook will prevent a blog post from being created from a Tweet. Two parameters are passed, the data to be used in the post and the Tweet object.

   129 

   130 Example psuedo-code:

   131 

   132 `function dont_tweet_post($post, $data) {

   133 	if (some condition) {

   134 		// will not post

   135 		return false;

   136 	}

   137 	else {

   138 		// must return the $data for a post to be created

   139 		return $data;

   140 	}

   141 }`

   142 `add_filter('aktt_do_tweet_post', 'dont_tweet_post', 10, 2)`

   143 

   144 ---

   145 

   146 `aktt_tweets_to_digest_post` (filter)

   147 

   148 Allows you to make changes the tweets that will be included in a digest post.

   149 

   150 ---

   151 

   152 `aktt_options_form` (action)

   153 

   154 Allows you to add to the Twitter Tools settings page.

   155 

   156 ---

   157 

   158 `aktt_post_options` (action)

   159 

   160 Allows you to add to the Twitter Tools box on the New Post page (requires the option to tweet on blog posts to be enabled).

   161 

   162 == Known Issues ==

   163 

   164 * If you change your blog post notification tweet prefix, the previous blog post notification might not be correctly recognized as a blog post tweet. This is only under very rare conditions due to timing issues.

   165 * Only one Twitter account is supported (not one account per author).

   166 * Tweets are not deleted from the tweet table in your WordPress database when they are deleted from Twitter. To delete from your WordPress database, use a database admin tool like phpMyAdmin.

   171 = Who is allowed to post a Tweet from within WordPress? =

   106 = What if I don't want to use Social's comment display? =

   172 

   107 

   173 Anyone who has a 'publish_post' permission. Basically, if you can post to the blog, you can also post to Twitter (using the account info in the Twitter Tools configuration).

   108 All of Social's features (broadcasting, comment display, looking for responses on Twitter and Facebook and the ability to log in with Twitter or Facebook) can be disabled on Social's settings screen.

   174 

   109 

   175 = What happens if I have both my tweets posting to my blog as posts and my posts sent to Twitter? Will it cause the world to end in a spinning fireball of death? = 

   110 = Will Twitter Tools pull in my entire tweet archive from Twitter? =

   176 

   111 

   177 Actually, Twitter Tools has taken this into account and you can safely enable both creating posts from your tweets and tweets from your posts without duplicating them in either place.

   112 Twitter Tools starts archiving from the time you enable it. It does not try to download your entire tweet history. However, there is code in Twitter Tools that can be scripted to download and import tweets. You can put together the pieces with your own code to create the combination of features you desire. Here's an Gist to get you started:

   178 

   113 

   179 = Does Twitter Tools use a URL shortening service by default? =

   114 https://gist.github.com/3470627

   180 

   115 

   181 No, Twitter Tools sends your long URL to Twitter and Twitter chooses to shorten it or not.

   116 == Screenshots ==

   182 

   117 

   183 As of version 2.0 a plugin to do this with the Bit.ly service is included as an option.

   118 1. Show your tweets on your site (optional).

   184 

   119 2. Tweets can be viewed by account, @mention or #hashtag.

   185 = Can Twitter Tools use a URL shortening service? =

   120 3. Manage your tweets in the standard WordPress admin interface.

   186 

   121 4. View tweets by @mention, #hashtag, etc.

   187 Yes, Twitter Tools includes a filter:

   122 5. Easy interface to for per-account settings.

   188 

   123 

   189 `tweet_blog_post_url`

   124 

   190 

   125 == Upgrade Notice ==

   191 as of version 1.6. Plugins for this filter may already exist, or you can create your own. The plugin needs to attach to this filter using the standard WordPress `add_filter()` function and return a URL that will then be passed with your blog post tweet.

   126 

   192 

   127 Version 3.0.3 is a recommended bug fix release.

   193 As of version 2.0 a plugin to do this with the Bit.ly service is included as an option.

   128 

   194 

   129 Version 3.0 is a complete rewrite that utilizes <a href="http://wordpress.org/extend/plugins/social/">Social</a> to make connecting your Twitter account easy. It is compatibile with the latest Twitter API changes as of October 11, 2012. Please see the <a href="http://alexking.org/blog/2012/10/12/twitter-tools-3-0-faq">FAQ</a> for more details.

   195 = Is there any way to change the 'New Blog Post:' prefix when my new posts get tweeted? =

   196 

   197 Yes, as of version 2.0 you can change this on the Options page.

   198 

   199 = Can I remove the 'New Blog Post:' prefix entirely? =

   200 

   201 No, this is not a good idea. Twitter Tools needs to be able to look at the beginning of the tweet and identify if it's a notification from your blog or not. Otherwise, Twitter Tools and Twitter could keep passing the blog posts and resulting tweets back and forth resulting in the 'spinning fireball of death' mentioned above.

   202