Twitter integration with full control, cache mechanism and oAuth

[anon68757951]

##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###

1. Head over to Github and download the .zip file (or do a pull from the CLI).
2. Extract all files from the .zip to the root of your site (be sure you don’t overwrite existing files!).
3. 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).

5. Head over to site\config\_config.php
6. 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.
7. 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).
8. 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 to assets\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…

1. You did activate all the settings in the sites blueprint.
2. You copy / pasted all required tokens in the site\config\config.php.
3. You linked the assets\twitter\ .JS and (optional) .CSS file in your header and footer.
4. 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;

1. 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).
2. 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.
3. 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).
4. A <div id="twitter-feed"></div> will be created on the place where the .php function is called.
5. 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

[lukasbestle]

Great idea!

Some feedback on doing stuff the Kirby way™:

• Configuration like the cache time doesn’t need to be regularly changed and is rather a design decision by the developer of the site. So it belongs in the config.php file.
• The API token can also be stored in the config.php to enable users to simply overwrite the plugin files with a new version and don’t lose the configuration.
• You can use the Kirby cache to store the tweets. Example code: Cache::set('dmotion-twitter-tweets', 'some json', <expiration time in minutes>);. You can then use a route to serve the file again. Advantage: You don’t have to hardcode a file destination which means that the assets directory can be structured by the user in whatever way.

[anon68757951]

Thanks for the feedback - I really like that approach and will update the plugin (and update the post here).

I’m rather new to Kirby, so I’m learning how to use it API’s and structure right now

[lukasbestle]

That’s why there is a Kirby forum.

[anon68757951]

That’s why I’m contributing my little creatures

Anyhow - I’ve updated the plug-in with these new features;

• All settings (besides the cache-time* ) are now placed in config.php
• The asset-path is now not constant, but can also be changed in config.php
• Little update of the code… make it more consistent with the amount of variables.

*) As for the caching-time, I do understand someone will not change this that often… but I wanted easy access for my client to all core settings… so I decided to keep it in the panel.

I can imagine that you most of the times want a caching-time of two hours…

…but sometimes you can have a social media campaign that requires a real-time stream of your tweets…

…and it’s nice if a client can handle that for himself (or a social media marketeer), without the dazzle of contacting a developer first.

[aftereffectsmagic]

Hi there,

What happened to this plugin? It’s no longer available.