Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/josephschmitt/simplebird

A simple, performant page for viewing your downloaded Twitter archive that works on desktop, tablet, and mobile. Visit http://joe.sh/tweets for a live example.
https://github.com/josephschmitt/simplebird

Last synced: 6 months ago
JSON representation

A simple, performant page for viewing your downloaded Twitter archive that works on desktop, tablet, and mobile. Visit http://joe.sh/tweets for a live example.

Awesome Lists containing this project

README 

        
# Simplebird

Simplebird is a small, fast, simple implementation of Grailbird Twitter archive. Its goal is to load the minimum amount of data as quickly as possible to display your past tweets. It also aims to be viewable and performant on desktop machines as well as touch and mobile devices.



# Requirements

For the most part, Simplebird is self-contained and can be run on your local computer by opening the index.html file (see caveat at the bottom of this page). However, for more advanced features such as Search, you'll need to have a web server running, either locally on your computer, or hosted remotely. The server itself has no other requirements other than being able to serve files ([Apache](http://www.apache.org/), [nginx](http://wiki.nginx.org/Main), etc.);



# Installation

If you haven't already done so, you'll need to request your Twitter Archive from Twitter. Go to [https://twitter.com/settings/account](https://twitter.com/settings/account) and scroll to the bottom of the page, where you'll see the "Request your archive" button, like so:



[![Request your archive](http://cl.ly/PC3G/image.png)](https://twitter.com/settings/account)



Within a few minutes you should get an email from Twitter with a link to your archive. Click on that link, download the Zip archive of your tweets, and extract it somewhere. You'll need this in a second.



Next, download or clone Simplebird and grab the `tweets/` directory, preferably uploading it to your web server. Then, open up the folder you got from your Twitter archive, copy the `data/` directory, and paste it inside the `tweets/` folder you hopefully just uploaded to your server. Open index.html, and you should see your tweets.



# Using clean urls

Deep linking was introduced into Simplebird in version 0.3, using the `?date=` query parameter. However, in version 0.3.3, clean url support was added, turning urls such as `tweets/?date=2012_03` into `tweets/2012_03`. To get this working, you'll have to go through a couple extra steps:



1. Set up the following Config variables in `tweets/index.html` at the script block near the bottom of the page:



    
Config.useCleanUrl      //defaults to false. Set this to true to enable clean url support

Config.baseUrl          //defaults to "/tweets". Set this to the directory of your Simplebird installation on your server, relative to the root URL.



2. Add absolute paths in `tweets/index.html` pointing to the CSS and JavaScript files on your server. If you just took the `tweets/` directory and placed it in your server root, the paths would be `/tweets/css/style.css`, `/tweets/js/lib.js`, and `/tweets/js/simplebird.min.js`. You might be able to skip this, but if you do, urls ending in a trailing slash will probably break.



3. Enable support for your new URLs on your server. If you're running Apache, you can do this by setting up a RewriteRule in your `.htaccess` file to redirect the deep-linked pages back to index.html. Here's the one I have on my server:



    
# Redirect deep linked tweets

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^tweets/(.*)/?$ tweets/index.html [L]



# How search works

Simplebird v0.5 brought with it the ability to search through your past tweets. However, since the point of this project is to be as self-contained as possible, that means that the search has to happen on the Front End via JavaScript. This isn't the fastest method to do search, and therefore the search results experience is a little different than what you might be used to with something like Google:



1. Immediately after initiating your search, Simplebird will perform that search on whatever months of tweets you've already loaded. If you haven't browsed around yet, then only the current month will be searched. If you clicked around a bit before searching, the search will be done on how ever many months you clicked on (and therefore loaded in your browser). This is so that *something* comes back as a search result as quickly as possible. At the bottom of the results, you'll see it says “Looking for more results”.



2. After the initial search is performed, Simplebird will load in *all* of your tweets and then re-do the search on those. This **will** take a while, especially if you've been tweeting since 2007.



3. Once the backlog search is complete, Simplebird will update the results page with the results from all of your past tweets. The “Looking for more results” text will be gone, and you'll hopefully have a nice, accurate search results page, sorted by relevancy.



# Building the project

The source files for this project depend on SASS for StyleSheet sanity and UglifyJS to keep the requests and file size small. If you don't want to use either of them, just point the `` tags in `tweets/index.html` to the CSS and non-min JS equivalents. However, if you'd like to make use of SASS and Uglify and you have [NodeJS](http://nodejs.org/) installed, you can do so via the included [Grunt](http://gruntjs.com) tasks.



# Using Grunt

Once you have the repo cloned, run the following command in your terminal at the root directory of the project to download and install the dependencies:



 `npm install`



 Once they've been installed, you can run one of these commands: 



 `grunt`

 This will run all the below commands in order.



 `grunt sass` 

 This will compile the SASS files.



 `grunt concat`

 This will concatenate the pre-minified JavaScript library files.



 `grunt uglify` 

 This will compile the JavaScript files.



 `grunt watch` 

 This will automatically listen for file changes and compile them using one of the two above commands.



# Local file caveat

Technically speaking, Simplebird *can* be run by just opening the file directly in your browser. However, some browsers have implemented a security policy that won't let you load remote assets if you open the HTML file directly from your computer. There are three ways around this: 



 1. Don't open the file locally, upload it to a server instead.

 2. Open the `tweets/` directory using a locally installed web server (Apache or Nginx, or python and node's built-in simple web servers).

 3. If you *really* want to open the file locally, you can change the security policy for your browser, as detailed here: [https://github.com/mrdoob/three.js/wiki/How-to-run-things-locally](https://github.com/mrdoob/three.js/wiki/How-to-run-things-locally)