##Kirby meets Twitter##
Another day, another plugin; this time I created a Twitter plugin, which can be fully customized from the panel.
Of course you can simply place a Twitter widget on your page, but those are embedded in an iFrame - meaning you don’t have access to the styling and function of the content.
An alternative is making use of the Twitter oAuth API - which embeds the tweets straight in your codes, so you can manipulate the DOM, styling, animation, etc… of every single tweet.
In order to make things easier (and be able to fine-tune it from the panel) I decided to create this plug-in; it uses some (official and opensource) libraries and they are stitched together in the plug-in.
###All options are tweakable, and optional###
- Set a title / caption for your Tweet list.
- Select a cache time (the interval that ‘pings’ the Twitter server in order to avoid their API query-limit).
- The amount of tweets shown (range 0 to 9 - can be customized by hand).
- Show / hide a (relative) time-stamp under every tweet.
- Show / hide the username (@twitter) above a tweet.
- Toggle the appearance of the avatar image.
- Integrated oAuth support.
###Installation###
- Head over to Github and download the .zip file (or do a pull from the CLI).
- Extract all files from the .zip to the root of your site (be sure you don’t overwrite existing files!).
- Head over to
site\blueprints\example.php
This is an example of the site.txt
blueprint and does contain some form-elements you need in order to customize / fine-tune the appearance of your tweets (see the option-list above).
Be sure to place all the Twitter-fields in site.txt
so you can access the settings side-wide, and not only at a specific page.
Go to the panel of your site, choose site options
and fill in all the options (be sure to press save
so all the settings are saved and ready to use).
- Head over to
site\config\_config.php
- This is an important step, because the plugin uses the official oAuth-tokens in order to make use of the Twitter API. So, please - read carefully.
- Fill in all the tokens / keys which are now populated with
xxxxxxxxxx
- if you haven’t done already, you can generate those tokens for free at https://dev.twitter.com/apps/ (or do a search for the Twitter the oauth-signature-generator). - You can also alter the other (default) settings here - like the amount of tweets that is queried (
defaults at 9
) and the path of the main assets (defaults toassets\twitter\
and does include Javascript and an (optional) style-sheet).
If you do change the asset-path, be sure you also change any existing asset-paths in your html-code.
Okay, you’re almost done! Let’s check…
- You did activate all the settings in the
sites blueprint
. - You copy / pasted all required tokens in the
site\config\config.php
. - You linked the
assets\twitter\
.JS and (optional) .CSS file in your header and footer. - Final step - show the tweets!
In order to show the tweets, you simply place this code in a template (single page) of snippet (e.g. in the footer) <?php showTweets(); ?>
When this little function is called, it does these things;
- Check the age of the cached tweet list (it’s cached in
\assets\twitter\tweets.js
- when this file is not already there, it will be created automatically - so don’t worry). - When the cached file is older than your cache settings from the panel (can be real-time, 24 hr and everything in between) it will query Twitters API, using the tokens you’ve created.
- The cached file will be update and used during the new cache time-window (so you don’t have to query Twitter for every pageview, except when the settings are set to real-time, of course).
- A
<div id="twitter-feed"></div>
will be created on the place where the .php function is called. - Finally, all the tweets (cached or fresh) will show up in that
<div>
using the settings from the panel.
###That’s it!###
Well… all most… in order to function, the plug-in requires at least jQuery (included in the .zip file - but most existing sites all ready have it).
And once again - be sure to have site\assets\twitter\twitter.js
embedded in your page (check the example setup at site\templates\example.php
).
The plug-in comes with some basic styling for the tweets (site\assets\twitter\twitter.css
) but you can manually override this, or create your own styling (basically the tweet-list is a <ul><li>...</li></ul>
wrapped in an unique identifier.
If you want the spinning bird during the load-time (and before every timestamp) you have to include Font Awesome to your site (the .css is included in the .zip file - the fonts not, to keep the .zip as lean and mean as possible).
In order to see the plug-in working on the fly, you can once again head over to site\templates\example.php
(after you’ve set your settings and tokens). This is an empty Kirby page, containing all the assets you need (besides the Font Awesome fonts - they can be downloaded here and placed in \asssets\fonts
if you want to have the bird pop-upped.
###Finally###
If you have set your tokens right and did save all the settings, you will have a nice Tweet list, integrated on your site - like on the screenshots or animation.
- the settings in the panel
- basic example of your tweets
###Disclaimer###
The tweets in the example are very old; I never use Twitter