	<h1 class="title"><span class="caps">TXP</span> Tweet (arc_twitter for Textpattern)</h1>

	<ol>
		<li><a href="#arc_twitter_author">Author</a></li>
		<li><a href="#arc_twitter_installation">Installation / Uninstallation</a></li>
		<li><a href="#arc_twitter_tag">The arc_twitter tag</a></li>
		<li><a href="#arc_twitter_search_tag">The arc_twitter_search tag</a></li>
		<li><a href="#arc_twitter_tweet_button_tag">The arc_twitter_tweet_button tag</a></li>
		<li><a href="#arc_twitter_follow_button_tag">The arc_twitter_follow_button tag</a></li>
		<li><a href="#arc_twitter_tweet_url">The arc_twitter_tweet_url tag</a></li>
		<li><a href="#arc_twitter_tinyurl">The arc_twitter_tinyurl tag</a></li>
		<li><a href="#arc_twitter_caching">Caching</a></li>
		<li><a href="#arc_twitter_prefs">Preferences</a></li>
		<li><a href="#arc_twitter_article">Tweeting articles</a></li>
		<li><a href="#arc_twitter_admin">The Twitter tab</a></li>
	</ol>

	<p><span class="caps">TXP</span> Tweet provides access to your Twitter account through both the admin interface and the public side of your site. Update Twitter when you post a new article (with article-by-article opt out option), update and view your Twitter feed through the admin Twitter tab, and display Twitter feeds on your site.</p>

	<p>Requirements:-</p>

	<ul>
		<li>Textpattern 4.5+</li>
		<li><span class="caps">PHP</span> 5 and cURL</li>
	</ul>

	<h2 class="section" id="arc_twitter_author">Author</h2>

	<p><a href="http://andy-carter.com">Andy Carter</a>. For other Textpattern plugins by me visit my <a href="http://andy-carter.com/txp">Plugins page</a>.</p>

	<p>Contributors: Andy Carter, Phil Wareham and Tommy Schmucker.</p>

	<p>Thanks to <a href="http://manfre.net/">Michael Manfre</a> for inspiration for the article tweet part of this plugin based on his <span class="tag">mem_twitter</span> plugin.  Additional thanks to the great Textpattern community for helping to test this plugin and for suggesting new features. The OAuth part of the plugin is thanks to <a href="http://twitter.com/abraham">Abraham Williams</a>.</p>

	<h2 class="section" id="arc_twitter_installation">Installation / Uninstallation</h2>

	<p>To install go to the &#8216;plugins&#8217; tab under &#8216;admin&#8217; and paste the plugin code into the &#8216;Install plugin&#8217; box, &#8216;upload&#8217; and then &#8216;install&#8217;. The plugin will be automatically activated.</p>

	<p>Before you start using <span class="tag">arc_twitter</span> you will need to make sure that the cache directory is writable. See the &#8216;Caching&#8217; subsection below for further information.</p>

	<p><span class="tag">arc_twitter</span> should now be ready for use on the public-side of your site.</p>

	<p>To unlock the admin features of this plugin you will need to associate your site with a Twitter account by connecting to Twitter from the plugin&#8217;s options screen. Click on the link to connect to Twitter, you will be asked to login to Twitter, clicking this link will temporarily take you to the Twitter site where you will be asked to login and approve access for <span class="caps">TXP</span> Tweet to read and write to your Twitter account. If all is successful you will be returned to the options screen and your user name will appear.</p>

	<p>At any time you can disassociate your Twitter account with <span class="caps">TXP</span> Tweet via your Twitter account preferences on the <a href="http://www.twitter.com">Twitter website</a>.</p>

	<p>To uninstall <span class="tag">arc_twitter</span> simply delete the plugin from the &#8216;Plugins&#8217; tab.  This will remove the plugin code, delete related preferences and drop the <span class="tag">arc_twitter</span> table from your Textpattern database.</p>

	<h2 class="section" id="arc_twitter_tag">The arc_twitter tag</h2>

	<h3>Syntax</h3>

	<p>&lt;txp:arc_twitter user=&quot;drmonkeyninja&quot; /&gt;</p>

	<h3>Usage</h3>

	<table>
		<tr>
			<th>Attribute</th>
			<th>Description</th>
			<th>Default</th>
			<th>Example</th>
		</tr>
		<tr>
			<td>user</td>
			<td>Twitter user name</td>
			<td> <em>arc_twitter username</em></td>
			<td>user=&quot;drmonkeyninja&quot;</td>
		</tr>
		<tr>
			<td>retweets</td>
			<td>1 to include retweets, 0 to exclude them from the feed</td>
			<td>0</td>
		</tr>
		<tr>
			<td>replies</td>
			<td>1 to include replies, 0 to exclude them from the feed</td>
			<td>1</td>
		</tr>
		<tr>
			<td>limit</td>
			<td>Maximum number of tweets to display (max. 200)</td>
			<td>10</td>
			<td>limit=&quot;25&quot;</td>
		</tr>
		<tr>
			<td>fetch</td>
			<td>Maximum number of tweets to retrieve from Twitter (max. 200)<sup class="footnote"><a href="#fn209229727352a0a74923850">1</a></sup></td>
			<td>0</td>
			<td>fetch=&quot;50&quot;</td>
		</tr>
		<tr>
			<td>full_urls</td>
			<td>1 to display full <span class="caps"><span class="caps">URL</span></span>s, 0 for t.co <span class="caps"><span class="caps">URL</span></span>s</td>
			<td>0</td>
		</tr>
		<tr>
			<td>dateformat</td>
			<td>Format that update dates will appear as</td>
			<td> <em>Archive date format</em></td>
			<td>dateformat=&quot;%b %Oe, %I:%M %p&quot;</td>
		</tr>
		<tr>
			<td>label</td>
			<td>Label for the top of the list</td>
			<td> <em>no label</em></td>
			<td>label=&quot;My Twitter timeline&quot;</td>
		</tr>
		<tr>
			<td>labeltag</td>
			<td>Independent wraptag for label</td>
			<td> <em>unset</em></td>
			<td>labeltag=&quot;h3&quot;</td>
		</tr>
		<tr>
			<td>break</td>
			<td><span class="caps"><span class="caps">HTML</span></span> tag (without brackets), or string, used to separate the updates</td>
			<td>li</td>
			<td>break=&quot;br&quot;</td>
		</tr>
		<tr>
			<td>wraptag</td>
			<td><span class="caps"><span class="caps">HTML</span></span> tag to be used as the wraptag, without brackets</td>
			<td> <em>unset</em></td>
			<td>wraptag=&quot;ul&quot;</td>
		</tr>
		<tr>
			<td>class</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute for wraptag</td>
			<td>arc_twitter</td>
			<td>class=&quot;twitter&quot;</td>
		</tr>
		<tr>
			<td>class_posted</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute applied to span tag around posted date</td>
			<td>arc_twitter-posted</td>
		</tr>
	</table>

	<p id="fn209229727352a0a74923850" class="footnote"><sup>1</sup> Twitter&#8217;s <span class="caps">API</span> counts the number of tweets to return before applying some of the filters, so the response can be fewer tweets than expected. To help avoid this you can set a <em>fetch</em> limit that is higher than the display <em>limit</em> that you want to output. If <em>fetch</em> is less than <em>limit</em> the latter will be used instead.</p>

	<h3>Example usage</h3>

	<p>&lt;txp:arc_twitter user=&quot;drmonkeyninja&quot; limit=&quot;5&quot; wraptag=&quot;ul&quot; break=&quot;li&quot; dateformat=&quot;%b %Oe, %I:%M %p&quot; /&gt;</p>

	<p>Produces a bullet point list of the last 5 Twitter updates from drmonkeyninja&#8217;s Twitter feed with a defined date format to override the default archive date format.</p>

	<h2 class="section" id="arc_twitter_search_tag">The arc_twitter_search tag</h2>

	<h3>Syntax</h3>

	<p>&lt;txp:arc_twitter_search hashtags=&quot;txp&quot; /&gt;</p>

	<h3>Usage</h3>

	<table>
		<tr>
			<th>Attribute</th>
			<th>Description</th>
			<th>Default</th>
			<th>Example</th>
		</tr>
		<tr>
			<td>search</td>
			<td>Comma separated list of search words</td>
			<td> <em>unset</em></td>
			<td>search=&quot;txp,textpattern&quot;</td>
		</tr>
		<tr>
			<td>hashtags</td>
			<td>Comma separated list of hashtags to search for (not including the hash)</td>
			<td> <em>unset</em></td>
			<td>hashtags=&quot;txp,textpattern&quot;</td>
		</tr>
		<tr>
			<td>reply</td>
			<td>Username of tweets in reply to</td>
			<td> <em>unset</em></td>
			<td>reply=&quot;twitter&quot;</td>
		</tr>
		<tr>
			<td>mention</td>
			<td>Username of user mentioned in tweets (<i>i.e.</i> tweets containing @username)</td>
			<td> <em>unset</em></td>
			<td>mention=&quot;twitter&quot;</td>
		</tr>
		<tr>
			<td>limit</td>
			<td>Maximum number of tweets to display (max. 200)</td>
			<td>10</td>
			<td>limit=&quot;25&quot;</td>
		</tr>
		<tr>
			<td>full_urls</td>
			<td>1 to display full <span class="caps"><span class="caps">URL</span></span>s, 0 for t.co <span class="caps"><span class="caps">URL</span></span>s</td>
			<td>0</td>
		</tr>
		<tr>
			<td>dateformat</td>
			<td>Format that update dates will appear as</td>
			<td> <em>Archive date format</em></td>
			<td>dateformat=&quot;%b %Oe, %I:%M %p&quot;</td>
		</tr>
		<tr>
			<td>label</td>
			<td>Label for the top of the list</td>
			<td> <em>no label</em></td>
		</tr>
		<tr>
			<td>labeltag</td>
			<td>Independent wraptag for label</td>
			<td> <em>unset</em></td>
		</tr>
		<tr>
			<td>break</td>
			<td><span class="caps"><span class="caps">HTML</span></span> tag (without brackets), or string, used to separate the updates</td>
			<td>li</td>
		</tr>
		<tr>
			<td>wraptag</td>
			<td><span class="caps"><span class="caps">HTML</span></span> tag to be used as the wraptag, without brackets</td>
			<td> <em>unset</em></td>
		</tr>
		<tr>
			<td>class</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute for wraptag</td>
			<td>arc_twitter_search</td>
		</tr>
		<tr>
			<td>class_user</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute applied to span tag around user name</td>
			<td>arc_twitter-user</td>
		</tr>
		<tr>
			<td>class_posted</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute applied to span tag around posted date</td>
			<td>arc_twitter-posted</td>
		</tr>
	</table>

	<h3>Example usage</h3>

	<p>&lt;txp:arc_twitter_search search=&quot;plugin&quot; hashtags=&quot;txp,textpattern&quot; limit=&quot;25&quot; /&gt;</p>

	<p>Produces a list of tweets containing the word &#8216;plugin&#8217; and the hashtags &#8216;#txp&#8217; and &#8216;#textpattern&#8217;. The tag will return a maximum of 25 tweets.</p>

	<h2 class="section" id="arc_twitter_retweet_tag">The arc_twitter_tweet_button tag</h2>

	<p>Outputs the Twitter tweet button (formerly &lt;txp:arc_twitter_retweet /&gt;).</p>

	<h3>Syntax</h3>

	<p>&lt;txp:arc_twitter_tweet_button /&gt;</p>

	<h3>Usage</h3>

	<table>
		<tr>
			<th>Attribute</th>
			<th>Description</th>
			<th>Default</th>
			<th>Example</th>
		</tr>
		<tr>
			<td>user</td>
			<td>Twitter user name to quote</td>
			<td> <em>arc_twitter username</em></td>
			<td>user=&quot;drmonkeyninja&quot;</td>
		</tr>
		<tr>
			<td>url</td>
			<td><span class="caps"><span class="caps">URL</span></span> to tweet</td>
		</tr>
		<tr>
			<td>text</td>
			<td>Tweet text</td>
		</tr>
		<tr>
			<td>follow1</td>
			<td>Suggested Twitter account to follow, for example your own</td>
			<td>A Twitter user to recommend</td>
			<td>follow1=&quot;Textpattern&quot;</td>
		</tr>
		<tr>
			<td>follow2</td>
			<td>As follow1</td>
			<td> <em>unset</em></td>
		</tr>
		<tr>
			<td>lang</td>
			<td>Language</td>
			<td>en</td>
			<td>lang=&quot;es&quot;</td>
		</tr>
		<tr>
			<td>count</td>
			<td>Count box position, options: none, horizontal or vertical</td>
			<td>horizontal</td>
			<td>count=&quot;none&quot;</td>
		</tr>
		<tr>
			<td>include_js</td>
			<td>Whether or not to include the widget JavaScript</td>
			<td>1</td>
			<td>include_js=&quot;0&quot;</td>
		</tr>
		<tr>
			<td>optimise_js</td>
			<td>Optimise the JavaScript by using a local script rather than that hosted on the Twitter site</td>
			<td>0</td>
			<td>optimise_js=&quot;1&quot;</td>
		</tr>
		<tr>
			<td>class</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute applied to the tweet button</td>
			<td>twitter-share-button</td>
		</tr>
	</table>

	<h2 class="section" id="arc_twitter_follow_button_tag">The arc_twitter_follow_button tag</h2>

	<p>Outputs the Twitter follow button (an alternative version is included in arc_twitter_intents).</p>

	<h3>Syntax</h3>

	<p>&lt;txp:arc_twitter_follow_button /&gt;</p>

	<h3>Usage</h3>

	<table>
		<tr>
			<th>Attribute</th>
			<th>Description</th>
			<th>Default</th>
			<th>Example</th>
		</tr>
		<tr>
			<td>user</td>
			<td>Twitter user name to follow</td>
			<td> <em>arc_twitter username</em></td>
			<td>user=&quot;drmonkeyninja&quot;</td>
		</tr>
		<tr>
			<td>lang</td>
			<td>Language</td>
			<td>en</td>
			<td>lang=&quot;es&quot;</td>
		</tr>
		<tr>
			<td>count</td>
			<td>Whether or not the follower count is shown</td>
			<td>1</td>
			<td>count=&quot;0&quot;</td>
		</tr>
		<tr>
			<td>include_js</td>
			<td>Whether or not to include the widget JavaScript</td>
			<td>1</td>
			<td>include_js=&quot;0&quot;</td>
		</tr>
		<tr>
			<td>optimise_js</td>
			<td>Optimise the JavaScript by using a local script rather than that hosted on the Twitter site</td>
			<td>0</td>
			<td>optimise_js=&quot;1&quot;</td>
		</tr>
		<tr>
			<td>class</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute applied to the follow button</td>
			<td>twitter-follow-button</td>
		</tr>
	</table>

	<h2 class="section" id="arc_twitter_tweet_url">arc_twitter_tweet_url</h2>

	<p>Returns the <span class="caps">URL</span> of the Twitter status for an article.</p>

	<h3>Syntax</h3>

	<p>&lt;txp:arc_twitter_tweet_url /&gt;</p>

	<p>&lt;txp:arc_twitter_tweet_url&gt;Link text&lt;/txp:arc_twitter_tweet_url&gt;</p>

	<h3>Usage</h3>

	<table>
		<tr>
			<th>Attribute</th>
			<th>Description</th>
			<th>Default</th>
			<th>Example</th>
		</tr>
		<tr>
			<td>id</td>
			<td>Textpattern article ID</td>
			<td> <em>current article</em></td>
			<td>id=&quot;1&quot;</td>
		</tr>
		<tr>
			<td>title</td>
			<td>Title attribute of the link</td>
			<td> <em>unset</em></td>
		</tr>
		<tr>
			<td>class</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute applied to the link</td>
			<td> <em>unset</em></td>
		</tr>
	</table>

	<h2 class="section" id="arc_twitter_tinyurl">arc_twitter_tinyurl</h2>

	<p>Returns the shortened <span class="caps">URL</span> of the article used for the Twitter update.</p>

	<h3>Syntax</h3>

	<p>&lt;txp:arc_twitter_tinyurl /&gt;</p>

	<p>&lt;txp:arc_twitter_tinyurl&gt;Link text&lt;/txp:arc_twitter_tinyurl&gt;</p>

	<h3>Usage</h3>

	<table>
		<tr>
			<th>Attribute</th>
			<th>Description</th>
			<th>Default</th>
			<th>Example</th>
		</tr>
		<tr>
			<td>id</td>
			<td>Textpattern article ID</td>
			<td> <em>current article</em></td>
			<td>id=&quot;1&quot;</td>
		</tr>
		<tr>
			<td>title</td>
			<td>Title attribute of the link</td>
			<td> <em>unset</em></td>
		</tr>
		<tr>
			<td>class</td>
			<td><span class="caps"><span class="caps">CSS</span></span> class attribute applied to the link</td>
			<td> <em>unset</em></td>
		</tr>
	</table>

	<h2 class="section" id="arc_twitter_caching">Caching</h2>

	<p>In order to prevent excessive repeatitive calls to the Twitter website it is recommended to cache results. Twitter limits the number of calls through the <span class="caps">API</span>, and continuous calls will result in Twitter closing to further requests. By default, arc_twitter caches for 30 minute intervals.</p>

	<table>
		<tr>
			<th>Attribute</th>
			<th>Description</th>
			<th>Default</th>
			<th>Example</th>
		</tr>
		<tr>
			<td>caching</td>
			<td>&#8216;1&#8217; to cache feed, &#8216;0&#8217; to turn caching off (not recommended)</td>
			<td>1</td>
			<td>caching=&quot;1&quot;</td>
		</tr>
		<tr>
			<td>cache_dir</td>
			<td>Absolute path to the cache directory (must be writable)</td>
			<td> <em>arc_twitter preferences</em></td>
		</tr>
		<tr>
			<td>cache_time</td>
			<td>Time in minutes that the cache files are stored before being refreshed</td>
			<td>5</td>
			<td>cache_time=&quot;30&quot;</td>
		</tr>
	</table>

	<p>The admin side of this plugin enforces caching, apart from when it is posting to Twitter (<i>e.g.</i> when posting or deleting an update).</p>

	<h2 class="section" id="arc_twitter_prefs">Preferences</h2>

	<p>You can access the plugins core preferences from either the Preferences or Plugins tabs in admin. Setup your Twitter account (you will be asked to connect via Twitter and this needs doing before you can use the plugin) and change the cache directory using arc_twitter&#8217;s preferences. Without providing your account login details the admin area features of this plugin will be inactive.</p>

	<p>You can select the <span class="caps">URL</span> shortener method you want to use to link back to your article on Twitter. Please note that if you select smd_short_url you will need to have installed and activated the <a href="http://textpattern.org/plugins/1099/smd_short_url"><span class="tag">smd_short_url</span> plugin</a> developed by Stef Dawson.</p>

	<h2 class="section" id="arc_twitter_article">Tweeting articles</h2>

	<p>By default arc_twitter will post an update to Twitter including a shortened <span class="caps">URL</span> to your article. Only live and active articles will be sent to Twitter, <i>i.e.</i> articles posted in the future or as sticky articles will not be sent. If your article is successfully submitted to Twitter the update will appear in place of the Twitter option on the right-hand-side of the article edit screen.</p>

	<p>Tweets are sent in the following format: <em>Tweet prefix</em> <em>Article title</em> <em>Shortened <span class="caps">URL</span></em> <em>Tweet suffix</em>. You can change the prefix and suffix on an article-by-article basis by changing the tweet options under &#8216;Update Twitter&#8217; on the article editor screen. The default <em>Tweet prefix</em> can be set under the <span class="tag">arc_twitter</span> preferences screen (the default on installation is &#8220;Just posted:&#8221;).</p>

	<p>Please note that once an article has been tweeted the tweet cannot be edited.</p>

	<h2 class="section" id="arc_twitter_admin">The Twitter tab</h2>

	<p>Under the Extensions tab (this can be changed from the plugin&#8217;s preference page) a new Twitter tab should appear once you have connected your site to your Twitter account. From here you will be able to submit new Twitter updates, view basic account statistics, and check out your recent updates (including the option to delete your tweets).</p>