=== Tweet This ===
Contributors: richardxthripp
Donate link: http://richardxthripp.thripp.com/donate/
Tags: api, automatic, automatically, bitly, bookmarking, community, connect, delicious, facebook, integrate, integration, is.gd, link, links, microblogging, myspace, networking, notify, oauth, page, pages, post, posts, redirect, scheduling, sharing, shortener, social, social bookmarking, social media, stumbleupon, th8.us, tinyurl, tweet, tweeting, tweets, twitter, update, updates, urls
Requires at least: 2.3
Tested up to: 3.0.1
Stable tag: 1.7.3

Adds a "Tweet This Post" link to every post, shortens URLs, and can
automatically tweet new, scheduled, and old blog posts using OAuth.

== Description ==

Adds a "Tweet This Post" link to every post, shortens URLs, and can
automatically tweet new, scheduled, and old blog posts and pages using OAuth.
Includes support for the Bit.ly API. Also includes Plurk, Yahoo Buzz,
Delicious, Digg, Facebook, MySpace, Ping.fm, Reddit, and StumbleUpon options.

`Version 1.7.3 adds a "Write Tweet" submenu under the Posts menu if you have
provided your Twitter OAuth keys. You can write a tweet directly from this
page, or schedule one to be posted at a future date (will create a MySQL table
wp_tweet_this_scheduled). Your latest scheduled tweets will be displayed here
(up to 100), but it is currently not possible to edit or delete them so you
will have to use phpMyAdmin (or delete the tweets from your Twitter account
after they are published). 1.7.3 also includes miscellaneous refinements.`

Normally, posting a link to Twitter takes up a lot of space. Though they
shorten URLs with Bit.ly, it doesn't happen till after you post your tweet,
so the length of the original URL takes away from your 140 characters.

While your readers might go to Bit.ly, copy and paste the blog post's
permalink, shorten the URL, copy that new URL, go to Twitter, and paste it
into the box, this plugin merges all that into one step.

This plugin makes short URLs like http://yourblog.com/?p=1234, then displays a
link to Twitter for each post, with an optional icon (twelve choices). This is
done automatically for each post as needed. You can choose a URL shortener
including Adjix.com, Bit.ly, Is.gd, Metamark.net, Snurl.com, Th8.us,
TinyURL.com, and Tweetburner.com. Each shortened URL is cached as a custom
field in the postmeta table to keep load times fast. The cached records are
updated or deleted as needed when you edit a post's permalink, delete a post,
change your site's permalink structure, or change URL services.

This plugin can also tweet new blog posts automatically, if you provide
your Twitter credentials in the options. Then a "Send to Twitter" checkbox
appears when writing a new post, along with a text box so you can change the
tweet text for that specific blog post. As of 1.7, OAuth is used.

Copyright 2008 - 2010  Richard X. Thripp  (email: richardxthripp@thripp.com)
Released under Version 2 of the GNU General Public License as published by
the Free Software Foundation, or, at your option, any later version.

Tweet This borrows code from these WordPress plugins: Twitter Tools by Alex
King and WP to Twitter by Joe Dolson. Tweet This uses these external libraries:
JSON-PHP by Michal Migurski, OAuth.php by Andy Smith, twitteroauth.php by
Abraham Williams, and ext-conv-links by Muhammad Arfeen. Sascha Assbach created
all the icons saying "Tweet This" or "Twitter Das," and I used his icons as
templates for the extended services. Graham Smith created tt-twitter4.png and
tt-twitter-micro2.png.

== Installation ==

Before you begin, please make sure your server has PHP 5 and Curl enabled.

1. Upload the `tweet-this` folder to `/wp-content/plugins/`.
2. If you're using WordPress MU and want this plugin active for all blogs,
	move `tweet-this.php` to `/wp-content/mu-plugins/` at this point.
3. Else, activate the plugin through the 'Plugins' menu in WordPress.
4. Tweet This icons should automatically appear on every post and page!
	Go to Settings > Tweet This to set up auto-tweeting or change stuff.
5. Optionally, delete readme.txt and the screenshots folder to save space.

== Changelog ==

`1.7.3: 2010-09-06: Added a "Write Tweet" submenu under the Posts menu if you
have provided your Twitter OAuth keys. You can write a tweet directly from this
page, or schedule one to be posted at a future date (will create a MySQL table
wp_tweet_this_scheduled). Your latest scheduled tweets will be displayed here
(up to 100), but it is currently not possible to edit or delete them so you
will have to use phpMyAdmin (or delete the tweets from your Twitter account
after they are published). 1.7.3 also includes miscellaneous refinements.

1.7.2: 2010-09-03: Recommended update.
* Auto-tweeting now works on WordPress pages.
* Added options "Enable automatic tweeting on posts" (on by default),
  "Enable automatic tweeting on pages" (on by default), and
  "'Send to Twitter' defaults to checked on unpublished pages"
  (off by default) to Settings > Tweet This > Automatic Tweeting.
* Added ten entries to the FAQ (all noes).
* Credited Alex King, Joe Dolson, Michal Migurski, Andy Smith,
  Abraham Williams, Sascha Assbach, and Graham Smith in the readme.
* Added HTTP error code message in the Tweet This section on the
  Write Post screen if automatic tweeting fails.
* Bugfix: Customized auto tweet text will not be overwritten when
  a post or page is updated after being published.
* Bugfix: All custom fields are now deleted when a post or page is deleted.
* Other small changes.

1.7.1: 2010-09-01: A small update.
* The Twitter API policy team has warned me that directing Tweet This users to
  title their Twitter application "Tweet This" with a link to the download page
  is not allowed. The suggested name, description, and website in the options
  is now your own.
* Options menu redesigned with horizontal rules and Automatic Tweeting section.
* Whitespace is now automatically trimmed from OAuth and bit.ly keys.
* Bugfix: Hashtags fixed for real in Tweet This links and automatic tweets.

1.7: 2010-08-30: Added OAuth support, Bit.ly API support, and fixed many bugs.
* Added OAuth support and removed basic authentication.
* Added support for the Bit.ly API; enter your username and API key
  in the options.
* Extended compatibility up to WordPress 3.0.1.
* Local URLs like http://yourblog.com/?p=1234 replace Th8.us as the
  default URL service.
* Added warning that Th8.us adds advertising in an iFrame above your website.
* Added warning that using a custom URL service may add hundreds of URLs to
  that service's database.
* MySpace links no longer append "Powered by Tweet This."
* Added tweet_this_manual() function to insert Tweet This manually into your
  template files.
* Added donation suggestions at bottom of options.
* Short URL lengths updated: bit.ly is now 20 characters (was 19), Snurl is 23
  (was 22), and TinyURL is 26 (was 25).
* Default link text for Delicious, Facebook, MySpace, and Reddit is now
  "Post to [Site]" instead of just [Site].
* Retweeting a post now only requires deleting the tt_tweeted custom field
  instead of changing the values of two custom fields.
* Bugfix: Automatic tweeting fixed in WordPress 2.9 and later
  (thanks Kieron Atkinson).
* Bugfix: Duplicate custom fields will no longer be created on posts
  (thanks Michael Tully).
* Bugfix: Hashtags are now properly rendered in automatic tweets
  (thanks kgagne).
* Bugfix: get_tweet_this_trim_title() is now prevented from truncating a post
  title in the middle of a multi-byte Unicode chracter (thanks Thomas Parisot).
* Bugfix: Tweet This URLs will no longer start with https:// if blog admin is
  using SSL (thanks Puneet).`

Older versions: http://richardxthripp.thripp.com/tweet-this-version-history/

== Frequently Asked Questions ==

= How do I make Tweet This show on posts, but NOT on pages? =

Go to Settings > Tweet This, click "Advanced Options,"
check "Hide Tweet This on pages," and click "Save Options."

= How does OAuth automatic tweeting work? =

Register for Twitter OAuth and enter your application keys in Settings > Tweet
This > Automatic Tweeting. There are also instructions there. Then, look for
the box titled Tweet This on the Write Post screen and check "Send to Twitter."
If you want this enabled by default, check "'Send to Twitter' defaults to
checked on unpublished posts" in Settings > Tweet This > Automatic Tweeting.

= Why is automatic tweeting not working? =

Make sure you have entered your OAuth keys correctly. Click "Test Twitter
OAuth" in Settings > Tweet This > Automatic Tweeting to verify. On your Twitter
application settings, "Default Access type" must be set to "Read & Write."
Also, make sure you have checked "Send to Twitter" on the Write Post screen.

= How does the "Write Tweet" page work? =

After you enter your OAuth keys, a new submenu titled "Write Tweet" will appear
under the Pages menu. From this page, you can not only write tweets, but
schedule future tweets to a MySQL table `wp_tweet_this_scheduled`. URLs
entered here are automatically shortened using Bit.ly (this is the only
available option) if the tweet text exceeds 140 characters. A prefix function
is included, and you can see a list of up to 100 of your latest scheduled
tweets. Note that it is currently not possible to edit or delete scheduled
tweets so you will have to use phpMyAdmin (or delete the tweets from your
Twitter account after they are published).

= How do scheduled tweets work? =

The schedule tweet function on the Write Tweet page adds a row to the
`wp_tweet_this_scheduled` MySQL table with the scheduled date, the tweet text,
and the status set to "future". When the first tweet is scheduled, an option is
added to the `wp_options` table titled `tweet_this_last_cron` with the value of
(time() - 86400). On every page load, (time() - 600) is compared to this
option; if it is greater, it has been more than ten minutes since the last
scheduled tweets were processed, so `tweet_this_init` attempts to publish all
the tweets with a status of "future" and a scheduled date in the past. If this
succeeds, the tweet's status is set to "publish"; if it fails, it is set to
"fail". Scheduled tweeting requires that someone actually visits your blog
after the scheduled date. The scheduled tweet is not triggered until a page is
loaded. Automatic tweets on scheduled posts are much simpler: the function to
publish the tweet is simply attached to the `publish_post` hook.

= How does the cache work? =

Cached short URLs are saved to the postmeta table when a visitor views posts.
For any future pageloads, those URLs are loaded, instead of pinging the Th8.us
API (or Bit.ly, TinyURL, etc.). As long as the post's permalink doesn't change,
the short URL from the third-party service doesn't change.

The cache is invalidated by setting the existing short URLs in the postmeta
table to "getnew" as needed. By reusing the old fields instead of replacing
them, I don't bump up the `meta_id` counter needlessly. When the next person
visits that post, the `get_tweet_this_short_url` function in Tweet This
sees this and gets a new short URL.

What triggers a cached URL as invalid? When you save a post (including editing
and publishing), the cache is invalidated in case you changed the permalink.
Secondly, when you change URL services under Settings > Tweet This or change
permalink structures under Options > Permalinks, all the cached URLs are set
to "getnew". Finally, if you change "Use 'www.' instead of 'http://' in
shortened URLs" or "Don't shorten URLs under 30 characters," or import
new settings, the cache is invalidated. If you move your blog to a different
directory or domain name, just change URL services and then change back
to trigger a refresh of the cache.

When you deactivate the plugin, all the cached URLs are deleted.

= How does importing and exporting options work? =

In the options menu, there is a section titled "Import / Export Options." This
is as simple as can be: the export is a raw dump of the `tweet_this_settings`
row from the `wp_options` table, and to import, you just paste that dump in the
import text area. Click "Import Options," and your current options will be
replaced. Your OAuth keys are included, so don't share it with anyone.

= How does setting a custom short URL service work? =

You enter the API's path with [LONGURL] as the long URL. For TinyURL,
for example, you would enter "http://tinyurl.com/api-create.php?url=[LONGURL]".
Then Tweet This uses that service for all its short URLs. The API must accept
HTTP GET requests (not POST), and it must output a plain-text short URL
(no HTML, XML, or arrays) with the http prefix.

= How does the editable Tweet This text box work? =

One of the options for the Twitter icon in the Tweet This Options is
"Editable text box." This gives your readers a text box with character counter
so they can change the tweet on your site before going to Twitter. When you
click the submit button, an interstitial is loaded which parses and sends the
new tweet text, forwarding the reader to Twitter. Then it is the same as the
regular options: the reader can edit the tweet further on Twitter, or submit.

= How does the tt-config.php file work? =

Tweet This ships with the file named as `tt-config-sample.php`. This way,
if you rename it to tt-config.php to use it, you can still upload future
versions of Tweet This right over the old directory, because your customized
tt-config.php file will not be overwritten. Once you rename it, there are
several options you can set in it that are too advanced or cannot be included
in the regular options menu.

= Can I use the Tweet This functions in my theme? =

Yes. Within the loop, these functions are available:

`tweet_this_manual() : Echoes all the Tweet This links and disables regular
output. Useful for moving the Tweet This links above each post. If you want to
insert Tweet This below where it is normally inserted, you must add the line
"remove_filter('the_content', 'insert_tweet_this');" before this function.

tweet_this($service, $tweet_text, $link_text, $title_text, $icon_file,
$a_class, $img_class, $img_alt) : Echoes a Tweet This link. This is only
useful if you disable automatic insertion in the settings.  You can leave
the arguments blank like '' to use your settings from the options page.
These values are permitted for the $services argument: 'twitter', 'plurk',
'buzz', 'delicious', 'digg', 'facebook', 'myspace', 'ping', 'reddit', 'su'.
The $icon_file argument is for the filename of an image from the
/tweet-this/icons/ folder. Example: tweet_this('twitter',
'@richardxthripp [TITLE] [URL]', '[BLANK]', 'Share on Twitter [[URL]]',
'de/tt-twitter-big3-de.png', 'tweet-this', 'tt-image', 'Post to Twitter').
$icon_file can be set to "noicon" for a text-only link.

tweet_this_url($tweet_text, $service) : Echoes the Tweet This URL, which is
like http://twitter.com/home/?status=Tweet+This+http://37258.th8.us by
default. Optional tweet_text argument overrides "Tweet Text" from the
options menu. $service can be 'twitter' or 'plurk', or omitted for Twitter.
Sample usage: tweet_this_url('@richardxthripp [TITLE] [URL]', 'twitter').

tweet_this_short_url() : Just echoes the short URL for the post
(Local, Th8.us, TinyURL, etc.), cached if possible.

tweet_this_trim_title() : URL-encodes get_the_title(), truncates it at the
nearest word if it's overly long, and echoes.

tt_option($key) : like get_option(), but specifically for Tweet This
settings. Useful for retrieving settings from the database.
Example: tt_option('tt_url_service'). Requires echo.`

You can prefix these functions with `get_` to return the
data without echoing, for further manipulation by PHP.

= Can I disable Tweet This on a specific post or page? =

Yes: add a custom field titled `tweet_this_hide` with the value of "true".

= Can I just use the Tweet This functions without it adding icons to my blog? =

Sure! Activate the plugin, go to Settings > Tweet This,
uncheck "Insert Tweet This," and click "Save Options."

= If I change URL services, will the old URLs continue to work? =

Yes. The short URLs are on third-party servers (Th8.us, Bit.ly, TinyURL, etc.),
and they should never delete them.

= Can Tweet This support many authors and their Twitter accounts on one blog? =

No. Automatic tweeting only works with one account per blog.

= Can I use variables such as [AUTHOR], [CATEGORY], [DATE], and [TAGS]? =

No, only [TITLE] and [URL].

= Can I change the order of the extended services? =

No.

= Can I use short URLs from an external plugin such as YOURLS or Pretty Link? =

No.

= Can I change the tweet text on a post-by-post basis? =

No.

= Does Tweet This provide a widget of my latest tweets? =

No.

= Does Tweet This let me write new tweets from my dashboard? =

Yes: from the "Write Tweet" page under the "Pages" menu.

= Can I use full-length URLs instead of URLs that end with "/?p=1234"? =

No.

= Can I set Tweet This to fetch short URLs on demand, instead of in advance? =

No.

= Does Tweet This provide click stats? =

No, but you can use Bit.ly and enter your API key to get stats from Bit.ly.

== Screenshots ==

1. Tweet This options page: all sections closed.
2. Tweet This options page: all sections opened.
3. The Write Tweet page, having just scheduled a tweet.
4. A post with Tweet This links.
5. Arriving at Twitter after clicking link.
6. Auto-tweet options on Write Post screen.