D3 Tips and Tricks v4

Monday, 31 December 2012

Loading a thumbnail into Gist for bl.ocks.org d3 graphs


The following post is a portion of the D3 Tips and Tricks document which it free to download. To use this post in context, consider it with the others in the blog or just download the pdf  and / or the examples from the downloads page:-)
--------------------------------------------------------

This description will start on the assumption that the user already has a GitHub / Gist account set up and running. It's purpose is to demonstrate how to upload an image as a file named thumbnail.png to a Gist so that when viewing the users home page on bl.ocks.org you see a nice little preview of what a visitor can anticipate when they go toy look at your work :-)

This description is a fleshed out version of the one provided by Christophe Viau on Google Groups (https://groups.google.com/forum/?fromgroups=#!topic/d3-js/FBosXiTB9Pc).

Setting the scene:

There you are a fresh faced d3.js user keen to share your work with the world. You set yourself up a GitHub / Gist account and put your code into a gist.  
Your graph is a thing of rare beauty and the community needs to marvel at your brilliance. Of course this is a breeze with bl.ocks.org. Once you have all the code sorted and any data files accessible, bl.ocks.org can display the graph with the code and can even open the graph in its own window. The person responsible for bl.ocks.org? Mike Bostock of course (wherever does he get the time?).

So clicking on the bl.ocks.org button on the gist page takes you to see your graph.
Wow! Impressive.

So you think that will make a fine addition to your collection of awesome graphs and if you click on your GitHub user name that is in the top left of the screen you go to a page that lays out all your graphs with a thumbnail giving a sneak preview of what the user can expect.
Aww... Rats! There's a nice place holder, but no pretty picture.

Hang on, what had Mike said on the bl.ocks.org main page?

The main source code for your example should be named index.html. You can also include a README.md using Markdown, and a thumbnail.png for preview.

Ahh.. you need to include a thumbnail.png file in your Gist!

So how to get it there? Well Gist is a repository, so what you need to do is to put the code in there somehow. Now from the Gist web page this doesn't appear to be a nice (gui) way to do this. So from here you will need to suspend your noob status and hit the command line.

The good news (if you're a windows user (and sorry, I haven't done this in Linux or on a Mac)) is that as part of the GitHub for windows installation a command line tool was installed as well! So you're going to use the Git Shell.

Enough of the scene setting. Let's git going :-).

Right, I'm going to describe the steps here in a pretty verbose fashion with pretty pictures and everything, but at the end I will put a simple set of steps in the form that Christophe Viau outlined on Google Groups.

First you will want to have your image ready. It needs to be a png with dimensions of 230 x 120 pixels. It should also be less than 50kB in size.

Now go to your public Gist that you have already set up and copy the link in the “Clone this gist” box.
(this should look something like https://gist.github.com/4414436.git)

Now you're going to clone this gist to a local repository using the Git Shell. Open it up from the desktop icon and you should see something like the following;
So you can clone the gist to a local folder with the command;
git clone https://gist.github.com/4414436.git

(or if you're using OSX, Alex Hornbake (see comments) has mentioned that the following command should be used to clone the gist using ssh (Thanks Alex!))

git clone git@gist.github.com:4414436.git

(The url is the one copied from the 'Clone this gist' box.)
 This will create a folder with the id (the number) of the gist in your local GitHub working directory.
And there it is (Ooo... Look almost New Years!).

Copy your thumbnail.png file into this directory.

Back to the Git Shell and change into the directory (4414436) . We can now add the thumbnail.png file to the gist with the command;
git add thumbnail.png

And now commit it to your gist with the following command in the Git Shell;
git commit -m "Thumbnail image added"

Now we need to push the commit to the remote gist (you may be asked for your GitHub user name and password if you haven't done this before) with the following command;
git push

OK, now you can go back to the web page for your gist and refresh it and scroll on down...
Woo Hoo!

(I know it doesn't look like much, but this is a VERY simple graph :-)).

Now for the real test. Go back to your home page for your blocks on bl.ocks.org and refresh the page.
Oh yes. You may now bask in the sweet glow of victory. And as a little bit of extra fancy, if you move your mouse over the image it translates up slightly!

Wrap up.

The steps to get your thumbnail into the gist aren't exactly point and click, but the steps you need to take are fairly easy to follow. As promised, here is the abridged list of steps that will avoid you going through the several previous pages.
  1. Create your public gist on https://gist.github.com/
  2. Get an image ready (230 x 120 pixels, named thumbnail.png)
  3. Under "Clone this gist", copy the link (i.e., https://gist.github.com/4414436.git)
  4. If you have the command line git tools (Git Shell), clone this gist to a local folder:
    git clone https://gist.github.com/4414436.git (or git clone git@gist.github.com:4414436.git  for OSX)
    It will add a folder with the gist id as a name (i.e., 4414436) under the current working directory.
  5. Navigate to this folder via the command line in Git Shell: cd 4414436 (dir 4414436 on windows)
  6. Navigate to this folder in file explorer and add your image (i.e., thumbnail.png)
  7. Add it to git from the command line: git add test.png
  8. Commit it to git: git commit -m "Thumbnail added"
  9. Push this commit to your remote gist (you may need your Github user name and password):
    git push
  10. Go back and refresh your Gist on https://gist.github.com/ to confirm that it worked
  11. Check your blocks home page and see if it's there too. http://bl.ocks.org/<yourusername>
Just to finish off. A big thanks to Christophe Viau for the hard work on finding out how it all goes together and if there are any errors in the above description I have no doubt they will be mine.


The above description (and heaps of other stuff) is in the D3 Tips and Tricks document that can be accessed from the downloads page of d3noob.org.

15 comments:

  1. Hey, thanks for the instructions. I was looking for this, but I'm using OSX.

    For OSX you need to first clone the Gist via SSH instead of HTTPS
    "git clone git@gist.github.com:GistNumber.git"
    instead of
    "git clone https://gist.github.com/4414436.git"

    ReplyDelete
    Replies
    1. For the Mac, at least, there is another option which is pretty easy as well. After doing the "git clone " at the command line, drag the generated folder into GitHub for Mac (http://mac.github.com/). Then simply drag the image file into the GitHub for Mac folder and commit. That's it. So, D3 Noob should like this...just one command line action and then it is all GUI :-)

      Delete
    2. Boy, that would be a dream. Sadly, I'm not a Mac guy :-(, so no gui for me. I will add this tidbit into the book though. Thanks Fern!

      Delete
  2. Hey great! Many thanks Alex. I've included this gem in the post above and am currently generating a new special edition of D3 Tips and Tricks (https://leanpub.com/D3-Tips-and-Tricks) with it in as well (Including full attribution of course :-)). Thanks again.

    ReplyDelete
  3. No worries. Thanks for the great D3 resource.

    ReplyDelete
  4. Replies
    1. Cheers. The big thanks should go to Christophe Viau as he knew what to do, I just wrote it down :-).

      Delete
  5. Note that @mbostock's [gist to clone all gists](https://gist.github.com/mbostock/3883098) is esp handy if you're regularly adding thumbnails to your blocks.

    ReplyDelete
    Replies
    1. Sorry for not knowing more about this, but does this mean that you could clone multiple gists, add in the thumbnails locally and then update? (thanks for the info by the way :-))

      Delete
  6. [It's been suggested](http://stackoverflow.com/questions/16425770/how-do-you-upload-images-to-a-gist) that the `gist-img` shell script enables you to upload thumbnail images. That's at least half true. It automates the base64 encoding of png images prior to upload with @defunkt's gist CLI tool, so you end up uploading the encoded text file. If @mbostock enables the decoding of base64 encoded thumbnail files (`thumbnail.png.B64`) on bl.ocks.org, this would be handy indeed!

    ReplyDelete
  7. Many thanks to you ! Very instructive.

    ReplyDelete
  8. brilliant. Would never have been able to figure this out without the above. Thumbnail takes a little while to show in bl.ocks I guess, can see it on github though which looks very promising

    ReplyDelete
    Replies
    1. Glad this helped. Although I am grateful for the kind assistance of all around good guy Christophe Viau for pointing me in the right direction. Yeah, there is a potential for delay since bl.ocks.org caches for up to 5 minutes (http://bost.ocks.org/mike/block/#update)

      Delete
  9. You might want to point to Mike's new gistup utility (https://github.com/mbostock/gistup/), which certainly helps streamline gist/repo generation. See "Let's Make a Block" (http://bost.ocks.org/mike/block/#advanced) for an overiew. Additional tips for thumbnail generation/sizing can be found here: http://visfest.com/d3unconf/how-to.html

    ReplyDelete
  10. Thanks so much for this! I had been searching the web for simple documentation of using git with gist, and was very happy to stumble across this. It was exactly what I needed and the instructions were super easy to follow. Thanks again.

    ReplyDelete