Aoi Tori Documentation

This is the documentation for the WordPress plugin Aoi Tori created & maintained by Paul Robinson.

This plugin helps you display your Twitter timeline on your website via a simple widget or, for more advanced users, a PHP function that can be placed anywhere in your active theme.

Using this plugin you can easily change the colors of various Tweet features (@replies, hashtags), select a template for displaying tweets and even customize the margin/padding. For more advanced users you can add your own custom CSS (or use SCSS syntax) and even create your own template using the built in template editor.

Table of contents

1. Features
2. Requirements
3. Installation
4. Setup
   1. Widget
   2. PHP Function
5. Usage
6. Options
   1. API Keys
   2. Template
   3. Styles
   4. Advanced CSS
7. Template Customization
8. Developers
9. ToDo
10. Bugs
11. Support
12. License
13. Refunds
14. Miscellaneous

Features

• Simple authorization with Twitter
• Custom options page
• Easy to use widget
• PHP Function - for more advanced users
• Pre-Built tweet display templates
• Custom Templates - for more advanced users
• Easily customize colors
• Easily customize margins/paddings
• and more...

Requirements

Due to some of the technologies used in the creation of this plugin it will only work if you have the prerequisites required. There shouldn't be anything here that your host doesn't already have readily available as most of these are pretty common, but they are listed here in case you wish to query your host about them.

• PHP 5.3.10 or greater (PHP 5.5 is recommended)
• cURL PHP Extension
• cURL must be able to make HTTPS calls to securely contact Twitter

Installation

Because this is a premium plugin and is not hosted by the WordPress plugin directory you cannot install it by finding it in your WordPress dashboard and clicking install. Thankfully though there is still a very easy way to install this plugin.

1. Login to your WordPress admin
2. Go to Plugins → Add New
3. Click Upload Plugin
4. Click the button and select the zip file you downloaded when you purchased the plugin
5. Click the upload button
6. That's it, just hit activate and the plugin will be ready for you to set up

If you prefer, or for some reason you are unable to use the plugin upload installer, you can install the plugin the old fashioned way. Using FTP. If you are familiar with FTP this should be a cinch, but here are some quick instructions.

1. Login to your server via FTP/SFTP (SFTP is highly recommended)
2. Navigate to the root of your WordPress install, depending on your host you may already be there, or it may be in a folder called public_html, htdocs, or www
3. Navigate to wp-content/plugins
4. Upload the contents of the zip file you downloaded when purchasing the plugin into that folder
5. Login to your WordPress admin
6. Go To Plugins
7. That's it, just hit activate and the plugin will be ready for you to set up

On activation for the first time the plugin will load a splash screen to give you a brief run down of the features available. This will also be used on major updates to highlight any new features, similar to the way WordPress use it on major version updates.

Setup

Setup is simple, once you have installed the plugin using the instructions above. Visit Settings → Aoi Tori to setup the plugin's options.

First visit the License tab and input the license code you received when you purchased the plugin. You will have been presented with the license code on the completed purchase screen, but you will also have received it via your purchase confirmation email. This license will allow you to update the plugin for free, for life. For more information on the license please visit the License section.

When you visit the plugin's option page you will see instructions on how to obtain and use your Twitter application keys. Please follow those to complete the setup of the plugin. For reference here are the instructions.

1. Go to the Twitter Application Management website. Click Create New App.
2. Enter details based on the following.
   • Name: The name for your application. Can be whatever you wish, but cannot include the word Twitter.
   • Description: A short description for your application. Again, can be whatever you wish.
   • Website: Just enter your home web address.
   • Callback URL: Leave this field blank. If you fill this field in it will may cause an error, please leave it blank.
3. Read & agree to the developer terms and press Create your Twitter application.
4. Click on the Keys and Access Tokens tab. Now copy:
   • Consumer Key
   • Consumer Secret
   • Access Token
   • Access Token Secret
5. Go back to the plugin's options page and click the API Keys tab. Enter these keys in the relevent fields & hit Save
6. After you hit save the page will reload. Please check the small status message displayed under the keys to see if your keys were valid or not. It should display a green message if successful. If it displays a red message please refer to the support section at the end of these docs for help.
7. If you wish you can go back to the Twitter Application Management and click Change App Permissions and set them to Read only as Aoi Tori does not need write permissions.

Once you have saved the keys and they have been deemed valid you can display your Tweets on your website using 2 different methods.

Widget

You can use a widget to display your tweets. To do that follow these instructions.

1. Go to Appearence → Widgets
2. Open up the widgetized area you wish to add the widget to
3. Look for the Aoi Tori Widget in the list of widgets to the left
4. Drag the widget over to the widgetized area you opened previously
5. Adjust the options as needed

PHP Function

More advanced users that are familiar with PHP & their theme can use the PHP function provided to have the tweets output anywhere you wish, not just in a widgetized area.

To use the function just use twitterStreamOutput($args, $echo) somewhere in your theme. I advise creating a child theme if you are using a purchased or WordPress theme directory theme as any updates will wipe edits such as this. More on creating a child theme can be found in the WordPress Codex.

More information on the parameters that can be passed to the function can be found in the Usage section.

Note: Currently the widget & PHP function use the options you have set via the options page, other than changing the options passed to Twitter it is currently not possible to override the options page settings such as colors and template used. The ability to do this via the PHP function may be added in a future update. There are no plans to add the same feature to the widget, but if demand is high enough it may be added.

Usage

Using the widget is very simple. Just add the widget to a widgetized area in your theme, as described above, set your options and you are ready to go. Hints are built into the widget so there is no need to reference this file if you use the widget. However if you are using the PHP function it has a few options available.

twitterStreamOutput(array $args, bool $echo)

The PHP function has two parameters. The first should be passed as an Array and can contain any of the options listed below. It determines the data returned from Twitter. The second parameter should be a Boolean and determines if the data returned should be echoed straight to the page or returned for further processing.

screen_name

Place a Twitter Screen Name in this option to display the tweets of that user. This can be any username, but trying to display the tweets of a private account will produce an error from Twitter. The only exception is if your tweets are private and you have created the app which authorized Twitter. Default: empty

count

Determines the number of tweets returned from the Twitter timeline. This can be any number up to 3200. Default: 10

exclude_replies

If set to false this will exclude any tweet that starts with a reply to another Twitter screen name. Tweets that contain a mention anywhere else in the tweet will still be returned. Note that Twitter removes replies after retrieving the tweets so if this option is set to false Twitter may return less than the total number of tweets you requested. Default: false

include_rts

If set to false this will exclude retweets. As with replies if this option is set to false the retweets are removed by Twitter after retrieving the tweets so Twitter may return less than the total number of tweets you requested. Default: false

cache_time

Determines how long the data returned from Twitter should be cached for. Data is cached using a WordPress transient. The cache time you specify is passed to the expiration parameter of the set_transient() function. Since it is provided in minutes it is converted to seconds using the MINUTES_IN_SECONDS constant. Default: 30

Options Page

The options available in the options page are mostly self explanatory however they are listed here for a more detailed look at what each item does. They are split into their tabs. Note that the Instructions & FAQ tabs are missing as they are just there for information purposes.

API Keys

Consumer Key

This holds the Consumer Key generated by Twitter's Application Management system. It is used (along with the 3 other keys) to authorize you with Twitter to retrieve data from their API.

Consumer Secret

This holds the Consumer Secret generated by Twitter's Application Management system. It is used (along with the 3 other keys) to authorize you with Twitter to retrieve data from their API.

oAuth Access Token

This holds the oAuth Access Token generated by Twitter's Application Management system. It is used (along with the 3 other keys) to authorize you with Twitter to retrieve data from their API.

oAuth Access Token Secret

This holds the oAuth Access Token Secret generated by Twitter's Application Management system. It is used (along with the 3 other keys) to authorize you with Twitter to retrieve data from their API.

Token Validity Check

This checks your keys by making a simple request to Twitter's verify credentials endpoint. If Twitter returns user information and a HTTP 200 then all is okay and the message turns green. If not it will go red.

Template

Tweet Template

Use this to select the template used when displaying tweets. There are currently 3 built-in templates to choose from.

• List Style: Uses a standard unordered list styled to have no bullet points. Your theme's default styling should take over and provide the majority of the styling needed. Some themes do not have different styling for lists in widgetized areas, if this happens please use the margin/padding options to adjust the spacing as needed.
• Paragraph Style: Uses paragraph tags for each tweet. Good for footer widgets or areas where paragraphs would be more suitable.
• Media Object Style: Uses a media object layout as made popular by the Bootstrap framework. The styling built into the plugin will create the Media Object layout, but your theme styling will do the rest.

Enable Custom Template

Use this option to enable the custom template. This will override whichever built-in template has been selected with the code shown in the Template Code option.

Template Code

This box, when the option above is enabled, runs the code typed into the box through the Twig template renderer instead of the built-in template selected. There is only 1 variable available to the template, that is the tweets object returned by Twitter. You can see the data returned by twitter on their Developers website. For more information check the Custom Template section below.

Styles

Hashtag Color

Changes the link color of hashtags displayed in a tweet.

Hashtag Hover Color

Changes the hover link color of hashtags displayed in a tweet.

@reply Color

Changes the link color of @replys displayed in a tweet.

@reply Hover Color

Changes the hover link color of @replys displayed in a tweet.

Hyperlink Color

Changes the link color of Hyperlinks displayed in a tweet.

Hyperlink Hover Color

Changes the hover link color of Hyperlinks displayed in a tweet.

Advanced CSS

Tweets Container

Margin

The margin applied to the container that contains all tweets. Margin is applied to the outside of the element. Must be in a valid CSS format. For example: 5px 3px 5px 3px

Padding

The padding applied to the container that contains all tweets. Padding is applied to the inside of the element. Must be in a valid CSS format. For example: 5px 3px 5px 3px

Tweet Container

Margin

The margin applied to the container that contains a single tweet. This element is inside the Tweets container mentioned above and is repeated for each tweet found. Margin is applied to the outside of the element. Must be in a valid CSS format. For example: 5px 3px 5px 3px

Padding

The padding applied to the container that contains a single tweet. This element is inside the Tweets container mentioned above and is repeated for each tweet found. Padding is applied to the inside of the element. Must be in a valid CSS format. For example: 5px 3px 5px 3px

Custom CSS

You can use this box to add any custom CSS you like. This is a great place to put custom CSS should you wish to apply extra styling to your tweets, to customize the built-in templates, or to apply CSS to a custom template you have created. CSS entered in this box will be maintained over updates. Tip: The custom CSS box also supports the SCSS syntax so you can use features such as selector nesting.

Template Customization

You can create a custom template to display your tweets using the custom template option available via the options page. The template system used is the wonderfully simple Twig templating language that a lot of developers are already familiar with. If you aren't familiar with it, it is very similar to Laravel's Blade. Discussing how to use Twig is too large a subject for this documentation so you can read more on Twig on their website.

The template is passed a single variable by the render method. That variable is called tweets and contains the raw object returned from Twitter. Because of that you have access to all of the data Twitter returned and can output any data you would like from it. To find out all of the data returned you can see a JSON version of the output on Twitter's Developers website. It is important to note that both objects and arrays alike are accessed through dot notation when using Twig, there is no distinction between the two.

There is a example of the code you might use for a custom template already written in the box by default, please use that as a helper for how to create your own. If you would like any help with creating your own template please feel free to send a support request to support@return-true.com, however note that it will not be treated as urgently as bug/support requests.

Along with all of Twig's regular filters there is also one extra custom filter defined by the plugin. This filter called process() expects a single parameter which should be a single Tweet object, because of that it should only be used when looping through each tweet. This filter processes each tweet and replaces textual Hashtags, @replies and URL with hyperlinked versions. The filter has some extra parameters which allow you to choose if certain items should not be processed.

process(object tweet, bool hashtag, bool atreply, bool url)

process() expects the tweet as its first parameter. The last three parameters expect a boolean (true/false) value and represent whether or not the hashtags, atreplies, and URLs should be processes respectively. They are all true by default. If set to false the textual representaion of each item will be left intact instead of converting it to a hyperlink.

Developers

This plugin makes use of Composer to autoload classes. Because this is a WordPress plugin and end-users may have little to no knowledge of how to use Composer, the Composer dependancies have been included in the plugin instead of requiring a composer update to get them. Classes are autoloaded from the vendor folder, as is usual, but they are also loaded from the lib folder. If you are tinkering and are confused as to how some Classes seem to be 'magically' available, the autoloading is the trick to that.

You are free to make to make any modifications to the plugin you wish. Just remember that unless you make a custom copy you will lose any changes if the plugin is updated. You are not, however, permitted to make changes and then redistribute or sell them.

ToDo

This is a list of features that are planned to be added in future versions. There is no particular order, they will just be done as I am able to get to them. Easier/simpler ones will likely be completed first as they naturally take the least amount of time.

• Add the ability to load a custom template from the currently active theme directory as a third alternative to the built-in templates and custom template box.
• Add ability to override options page options via the PHP function call.

Bugs

This is a list of known bugs/issues in the plugin. They will always be minor but will always be fixed in order of seriousness. The plugin will never be released/updated with a known blocking (breaking) bug. If you find a bug please use the email address shown in the support section below to email me as soon as possible.

• Partially visible URLs, generally only seen in Retweets, are hyperlinked. There may however be edge cases where they do not work correctly due to how hyperlinking is implemented. Keep an eye on this one.

Support

If you have any issues, problems or questions I will try my best to help you out as quickly as possible. Here are the best ways to get in touch.

Email

You can email me at support@return-true.com.

Support System

You can use our support ticket system to report a bug, issue, or if you are having trouble getting something to work.

I normally respond as soon as I can, but I give 24-72 hours (3 working days) as a benchmark time for responses.

License

The license provided with this plugin is required to allow you to update the plugin to any new version that is released. Without the license you cannot update the plugin. This license key is displayed after purchase and is set to you via email in the purchase confirmation email. Please keep it safe. If you loose it please contact support and we will try to help you out.

A license will allow you to update the plugin and you may use the license on as many domains as you wish. License uses are tracked each time it is used on a new domain. Your license may be disabled without warning if it is used too activate too many domains too quickly. If this happens you will see a message when trying to save your license key, in this situation please contact support to find out more.

Refunds

Refunds are available within 7 days of purchase, if you change your mind. After that period a refund will only be given if you can show that the plugin is not fit for purpose and you have allowed for a reasonable attempt at fixing the issue.

Miscellaneous

You may have noticed that this plugin has an odd name. It was originally going to be called Twitter Stream Pro as the free version of this plugin is called Twitter Stream. However the plugin is now so far from the original free version in features, and I was worried about using the name Twitter in a commercial plugin, that I decided to rename it.

Aoi Tori (Kanji: 青い鳥 / Katakana: あおいとり) is Japanese for Blue Bird. I am currently learning Japanese and thought it was an interesting name for the plugin. Plus it is still related to Twitter since we all recognise the famous blue bird that Twitter use for their branding. So there you go, now you know why the plugin is called Aoi Tori.