|
1 === Twitter Tools === |
|
2 Tags: twitter, tweet, integration, post, digest, notify, integrate, archive, widget |
|
3 Contributors: alexkingorg. crowdfavorite |
|
4 Requires at least: 2.3 |
|
5 Tested up to: 2.8.3 |
|
6 Stable tag: 2.0 |
|
7 |
|
8 Twitter Tools is a plugin that creates a complete integration between your WordPress blog and your Twitter account. |
|
9 |
|
10 == Details == |
|
11 |
|
12 Twitter Tools integrates with Twitter by giving you the following functionality: |
|
13 |
|
14 * Archive your Twitter tweets (downloaded every 10 minutes) |
|
15 * Create a blog post from each of your tweets |
|
16 * Create a daily or weekly digest post of your tweets |
|
17 * Create a tweet on Twitter whenever you post in your blog, with a link to the blog post |
|
18 * Post a tweet from your sidebar |
|
19 * Post a tweet from the WP Admin screens |
|
20 * Pass your tweets along to another service (via API hook) |
|
21 |
|
22 |
|
23 == Installation == |
|
24 |
|
25 1. Download the plugin archive and expand it (you've likely already done this). |
|
26 2. Put the 'twitter-tools.php' file into your wp-content/plugins/ directory. |
|
27 3. Go to the Plugins page in your WordPress Administration area and click 'Activate' for Twitter Tools. |
|
28 4. Go to the Twitter Tools Options page (Options > Twitter Tools) to set your Twitter account information and preferences. |
|
29 |
|
30 |
|
31 == Configuration == |
|
32 |
|
33 There are a number of configuration options for Twitter Tools. You can find these in Options > Twitter Tools. |
|
34 |
|
35 == Showing Your Tweets == |
|
36 |
|
37 = Widget Friendly = |
|
38 |
|
39 If you are using widgets, you can drag Twitter Tools to your sidebar to display your latest tweets. |
|
40 |
|
41 |
|
42 = Template Tags = |
|
43 |
|
44 If you are not using widgest, you can use a template tag to add your latest tweets to your sidebar. |
|
45 |
|
46 `<?php aktt_sidebar_tweets(); ?>` |
|
47 |
|
48 |
|
49 If you just want your latest tweet, use this template tag. |
|
50 |
|
51 `<?php aktt_latest_tweet(); ?>` |
|
52 |
|
53 |
|
54 == Hooks/API == |
|
55 |
|
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: |
|
57 |
|
58 `aktt_add_tweet` (action) |
|
59 |
|
60 Your plugin function will receive an `aktt_tweet` object as the first parameter. |
|
61 |
|
62 Example psuedo-code: |
|
63 |
|
64 `function my_status_update($tweet) { // do something here }` |
|
65 `add_action('aktt_add_tweet', 'my_status_update')` |
|
66 |
|
67 --- |
|
68 |
|
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. |
|
70 |
|
71 `tweet_blog_post_url` (filter) |
|
72 |
|
73 Your plugin function will receive the URL as the first parameter. |
|
74 |
|
75 Example psuedo-code: |
|
76 |
|
77 `function my_short_url($long_url) { |
|
78 // do something here - return the shortened URL |
|
79 $short_url = my_short_url_func($long_url); |
|
80 return $short_url; |
|
81 }` |
|
82 `add_filter('tweet_blog_post_url', 'my_short_url')` |
|
83 |
|
84 --- |
|
85 |
|
86 `aktt_do_tweet` (filter) |
|
87 |
|
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. |
|
89 |
|
90 Example psuedo-code: |
|
91 |
|
92 `function dont_tweet($tweet) { |
|
93 if (some condition) { |
|
94 // will not tweet |
|
95 return false; |
|
96 } |
|
97 else { |
|
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. |
|
167 |
|
168 |
|
169 == Frequently Asked Questions == |
|
170 |
|
171 = Who is allowed to post a Tweet from within WordPress? = |
|
172 |
|
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). |
|
174 |
|
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? = |
|
176 |
|
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. |
|
178 |
|
179 = Does Twitter Tools use a URL shortening service by default? = |
|
180 |
|
181 No, Twitter Tools sends your long URL to Twitter and Twitter chooses to shorten it or not. |
|
182 |
|
183 As of version 2.0 a plugin to do this with the Bit.ly service is included as an option. |
|
184 |
|
185 = Can Twitter Tools use a URL shortening service? = |
|
186 |
|
187 Yes, Twitter Tools includes a filter: |
|
188 |
|
189 `tweet_blog_post_url` |
|
190 |
|
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. |
|
192 |
|
193 As of version 2.0 a plugin to do this with the Bit.ly service is included as an option. |
|
194 |
|
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 |
|
203 |
|
204 == Changelog == |
|
205 |
|
206 = 2.0 = |
|
207 |
|
208 * Added various hooks and filters to enable other plugins to interact with Twitter Tools. |
|
209 * Added option to set blog post tweet prefix |
|
210 * Added CSS classes for elements in tweet list |
|
211 * Initial release of Bit.ly for Twitter Tools - enables shortening your URLs and tracking them on your Bit.ly account. |
|
212 * Initial release of #hashtags for Twitter Tools - enables adding hashtags to your blog post tweets. |
|
213 * Initial release of Exclude Category for Twitter Tools - enables not tweeting posts in chosen categories. |