Fieldtype
As of version 1.2, CE Tweet comes with an awesome (Matrix-compatible) fieldtype. A fieldtype is a type of custom field that can be used in your Channel Entries. This fieldtype enables you to easily search for tweets and assign them to your entries. You can then display them in your templates in a variety of different ways.
Custom Field Setup
You probably already know how to do this, but to create a custom field, you go to Admin -> Channel Administration -> Channel Fields. You then click on the Field Group you want to add your field to (or create a new Field Group). To add a new field to your group, click on the "Create a New Channel Field" button. Select CE Tweet as the type, and give your field a label and a short name.
Usage
Now that we have our custom field made, we can edit (or create) an entry in the channel that the field group is assigned to. This is the fun part.
The field is designed with a split view. The tweets that you want saved to your entry are on the left, and the search area is on the right.
Searching
You can search using the standard Twitter search operators (see here for more details). In addition to the standard operators, you can also paste in a Twitter status URL (like http://twitter.com/thoughtful_web/status/211170382890270720), or use the custom id: syntax to look up a specific tweet (ex: id:211170382890270720).
There is no need to press a submit button to trigger the search; it updates as you type. If there are more results available, then previous and next links will appear above and below the results, allowing you to page through as many results as are available.
Assigning Tweets
You can either assign entries via good ol’ drag ‘n’ drop, or by clicking on the plus (to add) or minus (to remove) icons. That’s all there is to it!
Template Display
There are a few easy ways to display the entries in your template:
Standard Loop
This simply allows you to loop through the results and output the twitter ids. The available variables are {tweet_id} and {count}. You can also specify a variable prefix via the prefix= parameter:
{software_tweet prefix="hello"}
<p>{hello:count}: {hello:tweet_id}</p>
{/software_tweet}
{/exp:channel:entries}
oEmbed
If you set the type="oembed" parameter, your output will seemlessly be changed to oembed tags. All of the parameters of the oembed tag can be used as if you were using that tag, except the id= parameter has already been set (magically).
Note: Make sure to add the Twitter Web Intents script (see the Intents Script Tag for more details):
Are there any #eecms addons that load a template into another template without processing it as an embed?
— Leevi Graham (@leevigraham) July 2, 2012
#eecms show or hide content based on logged in member group(s). Introducing Clique. http://t.co/r5VtrApn
— Encaffeinated (@encaffeinated) July 2, 2012
{software_tweet type="oembed"}{html}{/software_tweet}
{/exp:channel:entries}
Note: The output from this tag is not cached automatically. Each time a Twitter oEmbed tag is displayed, it counts as a hit against the API limit. For this reason (and because cached results are faster), it is strongly recommended to always use some form of caching with this tag. Check out ExpressionEngine® native tag caching or CE Cache for caching options.
Show tag
Finally, you can have full control over your Twitter output, just like when using the show tag tag, buy simply setting type="show". All of the show tag parameters can be used, but the id= parameter has already been set.
Note: Make sure to add the Twitter Web Intents script (see the Intents Script Tag for more details):
<div class="ce_tweet_holder group">
{software_tweet type="show" parse="inward"}
<div class="ce_tweet">
<div class="ce_tweet_left">
<a class="ce_tweet_username" href="http://twitter.com/{user_screen_name}" target="_blank"><img src="{user_profile_image_url}" alt="" /></a>
</div><!-- .ce_tweet_left -->
<div class="ce_tweet_right">
<div class="ce_tweet_row">
<a class="ce_tweet_username" href="http://twitter.com/{user_screen_name}" target="_blank">{user_name}</a>
<span class="ce_tweet_name">{user_screen_name}</span>
</div><!-- .ce_tweet_row -->
<div class="ce_tweet_row ce_tweet_text">{text}</div>
<div class="ce_tweet_row ce_tweet_actions">
<a class="ce_tweet_time" href="https://twitter.com/{user_screen_name}/statuses/{id_str}" title="{created_at format='%g:%i %A, %M %j%S (%T)'}" target="_blank"><span></span> {created_at_relative}</a>
<a class="ce_tweet_favorite{if favorited} ce_tweet_favorited{/if}" href="https://twitter.com/intent/favorite?tweet_id={id_str}" target="_blank"><span></span> Favorite</a>
<a class="ce_tweet_retweet{if retweeted} ce_tweet_retweeted{/if}" href="https://twitter.com/intent/retweet?tweet_id={id_str}" target="_blank"><span></span> Retweet</a>
<a class="ce_tweet_reply" href="https://twitter.com/intent/tweet?in_reply_to={id_str}" target="_blank"><span></span> Reply</a>
</div><!-- .ce_tweet_row -->
</div><!-- .ce_tweet_right -->
</div><!-- .ce_tweet -->
{/software_tweet}
</div><!-- .ce_tweet_holder -->
{/exp:channel:entries}
Note: The output from this tag is not cached automatically. Each time an oembed tag is displayed, it counts as a hit against the API limit. For this reason (and because cached results are faster), it is strongly recommended to always use some form of caching with this tag. Check out ExpressionEngine® native tag caching or CE Cache for caching options.
Notes and Caveats
Searching is essentially rate free, but when you look up a tweet by its url or id, or load a page that has previously saved tweets in it, each one costs a hit against the rate limit. The rate limit is set at 150 requests per hour by Twitter, and is tied to your IP address. So if you had three Twitter field types in one entry, and each one had 10 saved entries, you would only be able to load the entry 5 times in an hour (3 x 10 x 5 = 150).
Once you run out of hits, you have no choice but to wait until more hits are available. When you are getting low on remaining hits, the fieldtype will warn you. When you run out of hits, the fieldtype will also let you know, and will tell you when the rate limit will be reset. If you run out of hits when loading the page, the fields will become temporarily unavailable. The reason for this is to protect your data from getting lost.
If a saved Tweet is deleted or otherwise unavailable from Twitter, you will be asked if you want to remove it the next time you edit the entry.