If you build it they will (hopefully) come.
While numerous tools for publicly archiving Twitter searches have gone premium or disappeared entirely, I’ve built a new one that works entirely within WordPress. Now I need your help to test it.
About a year ago, I wrote an article about how to archive Twitter chats using the then popular and perfectly functional WhatTheHashtag. Later on the site was suddenly shut down and the service discontinued. Since then, I’ve stumbled from tool to tool, trying to find an equally optimal solution that would allow me to generate HTML containing Tweets and post them on my blog (independent from any other platform) with the greatest amount of speed possible.
No single product was as quick, effective or independent as WhatTheHashtag was. So, I finally got fed up and decided that I’d try to build one myself. I started with Web Journalist Chat (#wjchat), a weekly Twitter chat for journalists because they had the nicest archive I’d seen thus far. I contacted the chat-runner Robert Hernandez, who directed me to Kim Bui, who emailed me the code they used, created by Daniel Thorogood.
When I saw that the code was all pretty understandable by my standards, I decided I could alter it into a WordPress plugin. An associate at George Mason University gave me the idea to make it a shortcode. Thus was the Twitter Search Shortcode born. Here’s a direct download link to the WordPress plugin.
[tooltip content=”I was thinking of you when I built this!” url=”” ]My potential users[/tooltip]
- Conference attendees: Much to the dismay of my followers, I tend to use my Twitter as a note-taking tool during conferences, mapping everything I write on to a hashtag. However, after 7 days, this becomes pretty much impossible to find. So I need a place to store all those tweets for future reference.
- Academics and journalists: Major events are going on, history is forming before our eyes in 140 character chunks. While tools like Storify allow us to capture this to a degree, often too much manual labor is involved to make it practical. Additionally, any Storify content (as I recently discovered to my supreme annoyance) is stored remotely. I needed to automate this process and store it on my own terms.
- Community managers, event managers, PR folk, etc…: We do a ton of work to organize a community around something like a hashtag, a phrase or URL. Sometimes we need to report that information to the higher-ups. It would be nice to show them what people are talking about and have a document to reference for times further in the future than 7 days.
What it needed to do:
- Retrieve as many Tweets as possible and store them on my server.
- Output those tweets as HTML that could be displayed as a story.
- Order them for reading (reverse datetime format).
- Not have to muck about in code every time I wanted to store a different query.
Thankfully, it appears that the current version of the plugin can do all that and more!
The current (0.6) version of the plugin works! Here’s how:
- You enter the appropriate information, including the search term, into a self-contained shortcode.
- Then, when you first load the page or post you placed the shortcode on, it will query up to 1500 tweets and return them to your website.
- The plugin will then spit those tweets out as formatted HTML and display them in your post.
- The plugin will then store that HTML in a post-meta field associated with that particular post.
- On any future loads of the post, the shortcode’s script will detect that there cached data in the unique post-meta field associated with the plugin and will not attempt to query Twitter again.
- All Twitter posts are using a built-in stylesheet.
The options you have when using the plugin:
- The shortcode’s default is the following:
- [searchtwitter for=”Chronotope” within=”” order=”reverse” title=”Twitter Archive for” blackbird=”no”]
- The for option contains the term you are searching Twitter for. Enter it just as you would into http://search.twitter.com. If you are using a hashtag, this is the place to put it: for=”#term”.
- The within option designates a limiting time period. You can specify year in the full four number format as in within=”2012″ or year-month within=”2012-04″ or year-month-day within=”2012-04-28″. This will limit shown tweets by year, month or day. Remember, nothing you can do will change that I can still only pull items from no more than 7 days back. Dates must be in the YYYY-MM-DD format.
- The order option designates if you would like it in reverse or normal order. In reverse order, the tweet captured with the earliest timestamp displayed first and goes in order from there. In normal order, the tweets appear like you would see them on Twitter, with the earliest one first.
- title is the option that designates the wrapped title that precedes the Twitter archive. The text within will be followed by the search term hyperlinked to Twitter’s search page. You can also enter none in this field and no H3 title will be generated.
- The blackbird feature is HIGHLY experimental. The concept is that captured tweets are displayed using the method of the Twitter Blackbird Pie plugin. Using this requires that you have the Blackbird Pie plugin installed. I do not have good error checks working for this part yet, so don’t use it if you don’t know if the plugin is installed and activated. Even beyond all that, there is an additional problem. Each time Blackbird Pie generates one of its very good-looking tweets it queries Twitter’s API. If you have 1500 tweets, or even around 100, Twitter gets upset and stops feeding you anything for a few seconds, enough time for the script to fail. So unless you are collecting a relatively small number of tweets, it is pretty much useless. For now… If you want to turn it on, enter yes into the blackbird option.
- This plugin also gives you the ability to override my styling. Just create a stylesheet named “user-ta-style.css” in your stylesheet directory and it will completely replace the stylesheet I provide.
Right now, I’ve only tested the plugin on a variety of my own personal sites, so I’m putting this out there as a call for help. I need others to examine my work, test it and tell me what’s wrong with it. None of my testing has indicated that it will do anything bad to your WordPress website, so it should be perfectly safe to use. I just want to make sure it does what it is supposed to and works in a way that is understandable to all users.You can download the plugin from my GitHub at the twitter-search-shortcode repository. Currently, there is a folder in there called “testing” and it contains a couple of scripts meant to run as stand-alone files on a server or local server to test out parts of the code. You can use it if you want to mess around with the script and see how it works.
The readme file designates some of the current issues. You can see there and at the repository’s issues page what are the current features and bugs I’m working on for the plugin.
If you know the answers or [tooltip content=”(especially how to convert datestamps)” url=”” ]have solutions[/tooltip] to any of the problems in my code, please tell me by posting here, on the issue, or dedicating a fix to the github.
If you’d like to fork it or reuse the code elsewhere, feel free to do, as long as you give credit to everyone involved, including myself.