FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

PresideCMS Extension: Twitter API

v0.5.3 Public

Twitter API Integration for Preside

This extension allows you to configure multiple Twitter accounts in your Preside application, and to interact with the Twitter API.

A major feature is the ability to pull tweet data from Twitter and store it locally.

Benefits

  • Custom rendering of timelines and individual tweets: tweets can be placed and formatted however desired
  • Speed of rendering: tweets are rendered as part of the page (and can be cached if desired), with no external requests to Twitter
  • Indexing: tweets can be indexed and searched both locally and by search engines
  • No tracking: because no 3rd-party widgets are being rendered by your page, no 3rd-party tracking is happening either

Prerequisites

Because of the nature of Twitter statuses, which will very often include emojis, you MUST have your MySQL database set up to use the utf8mb4 character set.

(This is probably best practice these days anyway, especially if your application is going to be storing any user-supplied data.)

Getting started

  1. Add one (or more) Twitter accounts through Data Manager > Twitter > Twitter accounts. You will need to set up API access at Twitter in order to obtain the required access credentials.
  2. You may configure a "start date" for each account - this will be the date from which your tweet history will be imported.
  3. In Task Manager > Twitter, run the Get new tweets task (or wait for it to run on schedule).

The twitter_status Preside object will now hold a local history of all your tweets, and new tweets will continually be added to this.

NOTE: the twitter_status object uses Twitter's own status ID as its ID property

Scheduled tasks

In addition to the Get new tweets task, there are other tasks in the Task Manager:

  • Re-render tweets: this will re-render the body and media content of each local tweet using the default context (see below for more information) and store the result in the twitter_status object
  • Update counts/deletions: these run at different frequencies to update like/retweet counts, and remove from the local system any tweets that have since been deleted. Out of the box, every 10 minutes it will check tweets that were posted in the past day; every 2 hours it will check tweets from the past 30 days; and once a day it will check all locally-stored tweets.

Rendering tweets

A number of default renderers are provided which take the raw data from the API and render it into a formatted tweet that can be included on a web page. This includes linking users, hashtags and URLs, and embedding media items.

The entity renderers provided are:

  • tweet_hashtags
  • tweet_symbols
  • tweet_urls
  • tweet_user_mentions
  • tweet_media_photo
  • tweet_media_video
  • tweet_media_animated_gif

The tweet markup renderers are:

  • tweet_header
  • tweet_in_reply_to
  • tweet_body
  • tweet_media
  • tweet_footer

Finally, there is a tweet renderer which combines the text and media into one formatted HTML block.

Each of these renderers has a default context, which provides a good basis to render tweets for general display. You can override these in your application and style the result as you desire.

By adding alternate contexts for some or all of these renderers, you can create different layouts for your tweets for different display purposes. For example, you might create a featured context which renders some (or all) aspects of the tweet differently.

Helper methods

A number of helper methods are supplied, which proxy to the TwitterRenderingService.

renderTweet()

The renderTweet() helper retrieves an individual tweet from the database and renders it in the specified context (or default context if not supplied):

// Supply a tweet ID
rendered = renderTweet( id=tweetId, context="featured" );

renderTweets()

The renderTweets() helper will render a collection of tweets based on the arguments provided. The method accepts all valid selectData() arguments, which it uses to retrieve relevant tweet records, as well as an optional context:

tweets = renderTweets(
	, filter  = {
		  "account.screen_name" = "sebduggan"
		, is_retweet            = false
		, is_reply              = false
	  }
	, maxRows = 20
	, orderBy = "date_posted desc"
	, context = "default"
);

renderTweetDate()

The renderTweetDate() helper will take a date and format it for display in a tweet header, according to a few simple rules:

  • Datetimes in the past hour will be displayed as a number of minutes (e.g. 32m)
  • Datetimes in the past 24 hours will be displayed as a number of hours (e.g. 14h)
  • Datetimes in the current year will be displayed as date and month (e.g. 12 Jan)
  • Datetimes older than that will be also have a year appended (e.g. 24 Nov, 2019)

The date format automatically renders according to the locale of Lucee (or the current request). The minute suffix (m) and hour suffix (h) can be localised in i18n/twitter.properties.

Default styling and behaviours

CSS

Default styling is provided for the default tweet renderers. This is provided both as Sass and compiled CSS files.

You can include the compiled CSS using Sticker:

event.include( "/css/twitter/" );

Alternatively, you could incorporate and modify these styles in your own site's stylesheets. If using Sass on your website, you could import the Sass source files directly into your own master stylesheet:

@import "../../../application/extensions/preside-ext-twitter-api/assets/css/twitter/twitter";

And, if using Dart Sass (recommended!), you can use @use to import the styles and override the default variables that are set in /assets/css/twitter/twitter.scss. For example, the following would override the aspect ratio of the media items grid so it is displayed as a square:

@use "../../../application/extensions/preside-ext-twitter-api/assets/css/twitter/twitter" (
	$mediaRatio: 100%
);

NOTE: These import paths are relative to the location of the Sass file in your own site which is doing the importing.

Javascript

Javascript is provided to handle some default interactions. This includes a simple lightbox (with no library dependencies) for viewing media items, and opening of Twitter intents (like, retweet, reply) in a popup window.

These can be included using Sticker:

event.include( "/js/twitter/" );

SVG icons

There are a number of SVG icons used by the default renderers which are provided in a single SVG sprite collection. This should be included on any page on which you are rendering tweets (it's not very big, so there's no reason not to simply drop it into the bottom of your site's main layout):

renderViewlet( "twitter.includeSvgs" )

On the roadmap

There will be other functionality added in the future, to interact with other aspects of the Twitter API.

One of the key features will be the ability to post tweets from your application to any of your configured accounts. For instance, you could automatically post a status update if you add a new article or feature.

Changelog

v0.5.3

  • Remove debug code...

v0.5.2

  • Minor tweet layout changes
  • Remove check for site's http/s status: Twitter redirects all requests to https anyway...
  • Add rendering for separate "Replying to..." component

v0.5.1

  • Unique IDs for each rendered tweet's media
  • Add error handling to API calls and tasks

v0.5.0

  • Better rendering of retweets
  • Display datetimes in the past hour as minutes

v0.4.4

  • Change summary to shortDescription in box.json

v0.4.3

  • Fix query filter in rerender tweets task
  • Better logging in rerender task

v0.4.2

  • Sort tweet data grid by date_posted
  • Add indexes to twitter_status object

v0.4.1

  • Store IDs as strings, sort tweets by date_posted

v0.4.0

  • Update documentation
  • Set summary for Forgebox

v0.3.2

  • Move display text to i18n properties
  • Localise formatted date display
  • Accessibility improvements (ARIA)

v0.3.1

  • Refactor CSS source structure
  • Refactor public rendering methods

v0.3.0

  • Add web intents for user links
  • Add SVG icons for tweet actions
  • Refactor tweet renderers for better customisation

v0.2.0

  • Add styles for the default rendered tweets
  • Add metadata and Twitter actions to default renderers
  • Add lightbox for viewing media items
  • Add JS interaction for Twitter intent actions

v0.1.2

  • Rework entity replacement to prevent potential double-replacements

v0.1.1

  • Replace newlines with HTML line breaks in default tweet renderer

v0.1.0

  • Release of initial functionality
    • Configure multiple Twitter accounts with credentials
    • Scheduled tasks to import existing tweets, and run regularly to pick up new ones
    • Scheduled tasks to update like/retweet counts, and to remove deleted tweets
    • Default renderers to convert the API data into a fully-rendered tweet (currently no default styling or interaction handling)
    • Manual task to re-render all saved tweets (e.g. if the renderers have changed)

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
Current
0.5.3 Feb 27 2020 12:46 PM Feb 27 2020 12:46 PM
Version History
0.5.2 Feb 27 2020 12:43 PM Feb 27 2020 12:43 PM
0.5.1 Feb 27 2020 10:48 AM Feb 27 2020 10:48 AM
0.5.0 Feb 27 2020 03:08 AM Feb 27 2020 03:08 AM
0.5.0-SNAPSHOT00032 Feb 27 2020 03:02 AM Feb 27 2020 03:02 AM
0.4.4 Feb 26 2020 03:33 PM Feb 26 2020 03:33 PM
0.4.3 Feb 26 2020 03:27 PM Feb 26 2020 03:27 PM
0.4.2 Feb 26 2020 03:04 PM Feb 26 2020 03:04 PM
0.4.1 Feb 26 2020 02:50 PM Feb 26 2020 02:50 PM
0.4.0 Feb 26 2020 12:17 PM Feb 26 2020 12:17 PM
0.4.0-SNAPSHOT00026 Feb 26 2020 07:51 AM Feb 26 2020 07:51 AM
0.4.0-SNAPSHOT00024 Feb 25 2020 12:06 PM Feb 25 2020 12:06 PM
0.4.0-SNAPSHOT00022 Feb 24 2020 12:50 PM Feb 24 2020 12:50 PM
0.3.2 Feb 26 2020 07:49 AM Feb 26 2020 07:49 AM
0.3.1 Feb 25 2020 12:06 PM Feb 25 2020 12:06 PM
0.3.0 Feb 24 2020 12:49 PM Feb 24 2020 12:49 PM
0.3.0-SNAPSHOT00018 Feb 23 2020 11:07 AM Feb 23 2020 11:07 AM
0.2.1 Feb 24 2020 12:47 PM Feb 24 2020 12:47 PM
0.2.0 Feb 23 2020 11:05 AM Feb 23 2020 11:05 AM
0.2.0-SNAPSHOT00016 Feb 23 2020 10:55 AM Feb 23 2020 10:55 AM
0.2.0-SNAPSHOT00015 Feb 23 2020 09:27 AM Feb 23 2020 09:27 AM
0.2.0-SNAPSHOT00013 Feb 22 2020 05:37 AM Feb 22 2020 05:37 AM
0.2.0-SNAPSHOT00011 Feb 22 2020 05:08 AM Feb 22 2020 05:08 AM
0.1.2 Feb 22 2020 01:36 PM Feb 22 2020 01:36 PM
0.1.1 Feb 22 2020 05:37 AM Feb 22 2020 05:37 AM
0.1.0 Feb 22 2020 05:09 AM Feb 22 2020 05:09 AM
0.1.0-SNAPSHOT00008 Feb 22 2020 05:05 AM Feb 22 2020 05:05 AM
0.1.0-SNAPSHOT00007 Feb 22 2020 05:00 AM Feb 22 2020 05:00 AM
0.1.0-SNAPSHOT00006 Feb 22 2020 04:58 AM Feb 22 2020 04:58 AM
0.1.0-SNAPSHOT00005 Feb 16 2020 04:54 AM Feb 16 2020 04:54 AM
0.1.0-SNAPSHOT00003 Feb 16 2020 04:50 AM Feb 16 2020 04:50 AM
0.1.0-SNAPSHOT00002 Feb 16 2020 04:47 AM Feb 16 2020 04:47 AM
0.1.0-SNAPSHOT00001 Feb 15 2020 05:08 AM Feb 15 2020 05:08 AM

 

$ box install preside-ext-twitter-api

No collaborators yet.
     
  • Feb 15 2020 05:08 AM
  • Feb 27 2020 12:46 PM
  • 112
  • 73
  • 9