This web site has been retired. Please follow my activities at pztrick.com.

pZtrick.com

the personal site of patrick paul

Jekyll Fancyimage Tag

| Comments

Octopress ships with several Jekyll plugins that allow you to input stuff like code gists or images into your posts by invoking simple Liquid tags which are are replaced with more complicated HTML/CSS/javascript markup automagically. It’s very slick.

One of the vanilla plugins that ships with Octopress is the img Liquid tag:

1
{% img custom_css_class /path/to/image.png 100 100 Caption test %}

This tag means that one can configure the apperance of any image by defining a CSS class and the height/width of an image by describing it thusly in the img Liquid tag. The above tag results in this baked markup:

1
<img class="custom_css_class" src="/path/to/image.png" width="100" height="100" title="Caption test" >

However, this particular img tag was pretty lacking for me, having come from Drupal/CCK where I could easily upload large images to be outputted as small thumbnails linked to large, pretty fancyboxes. The vanilla img tag does not create a smaller thumbnail; it only allows you to shrink it and users would still be downloading the full 900KB image in order to view a scaled 100x100 image. And there was no hyperlink to a larger fancybox image, which is a feature I desire. Two deal-breaking drawbacks.

But I knew I could count on the internets for a better plugin, and so I googled.

Literature Review

There were two fancybox image plugins I found when I did my very sophisticated Google search. These were photos_tag.rb and imgpopup.rb.

photos_tag.rb

The Liquid photo tag was the first fancybox plugin I discovered, and at first pass it seemed to be exactly what I was looking for. The tag produces a thumbnail image that, when clicked, loads a beautiful fancybox with the full image. You can specify a thumbnail image path or use the default pathing scheme.

1
{% photo foobar.jpg default My cool photo %}

However, while it allows the author to specify a thumbnail image to use – it does not automatically create one. This is an advantage for some users of Flickr who already have thumbnail paths to reference, but for local image users there is no thumbnail to link to. Further, it does not have the same functionality as the vanilla plugin to define custom CSS classes for how the thumbnail image is to be displayed.

imgpopup.rb

Of course, my Google search also turned up imgpopup.rb which did generate thumbnail images from any given path. However, the HTML/CSS markup and fanybox generated by this plugin was not as pretty as the former photos_tag.rb plugin (or at least was not what I was looking for). What is a ruby-illiterate developer to do?

My own fork: fancyimage_tag.rb

I ended up hacking all three plugins together. I took the CSS class argument functionality from the vanilla img tag plugin; I took the fancybox javascript and CSS styling from the photo tag plugin; and, finally, I took the ImageMagick resize functionality from the imgpopup tag plugin.

The end result is a plugin that 1) generates a new thumbnail image at deployment, 2) displays the thumbnail in your baked HTML page using any custom CSS class you specify, and 3) hyperlinks a beautiful fancybox to view the full image when clicked. I have registered this plugin with the Liquid tag fancyimage.

Liquid
1
{% fancyimage right /images/fancyimage.jpg 100x200 Example %}
HTML
1
<a href="/images/fancyimage.jpg" class="fancybox" title="Example"><img class="right" src="/thumbs/fancyimage_100x200.jpg" alt="Example" /></a>

Example You should see the fancyimage from the code block above at the right of this text.

I think this is how open source & social coding is supposed to work?

To do

  • Add fancygallery tag as an enhancement (from photos_tag.rb plugin’s gallery tag) [fixed 24 July 2012]
  • Figure out how to generate thumbnail images directly into /public/ folder (instead of to /source/ -> rake generate x2)
  • Generate thumbs in distinct /thumbs/ directory to avoid clutter (and accommodate git ignore thumbs/) [fixed 24 July 2012]
  • Update documentation (in particular, installation procedure)

Pay attention to item 2: users of this plugin should be aware that you will need to rake generate twice before it will appear correctly in the public folder.

fancyalbum Sample

Liquid
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{% fancyalbum 80x100! %}
/uploads/internets/internets1.jpg: Sample Comment 1
/uploads/internets/internets3.jpg: Sample Comment 3
/uploads/internets/internets4.jpg: Sample Comment 4
/uploads/internets/internets5.jpg: Sample Comment 5
/uploads/internets/internets6.jpg: Sample Comment 6
/uploads/internets/internets7.jpg: Sample Comment 7
/uploads/internets/internets8.png: Sample Comment 8
/uploads/internets/internets9.jpg: Sample Comment 9
/uploads/internets/internets10.jpg: Sample Comment 10
/uploads/internets/internets11.jpg: Sample Comment 11
/uploads/internets/internets12.jpg: Sample Comment 12
/uploads/internets/internets13.jpg: Sample Comment 13
/uploads/internets/internets15.jpg: Sample Comment 15
/uploads/internets/internets17.jpg: Sample Comment 17
/uploads/internets/internets18.jpg: Sample Comment 18
{% endfancyalbum %}
HTML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<ul class="gallery">
<li><a href="/uploads/internets/internets1.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 1"><img src="/thumbs/internets1_80x100_abs.jpg" alt="Sample Comment 1" /></a></li>
<li><a href="/uploads/internets/internets3.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 3"><img src="/thumbs/internets3_80x100_abs.jpg" alt="Sample Comment 3" /></a></li>
<li><a href="/uploads/internets/internets4.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 4"><img src="/thumbs/internets4_80x100_abs.jpg" alt="Sample Comment 4" /></a></li>
<li><a href="/uploads/internets/internets5.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 5"><img src="/thumbs/internets5_80x100_abs.jpg" alt="Sample Comment 5" /></a></li>
<li><a href="/uploads/internets/internets6.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 6"><img src="/thumbs/internets6_80x100_abs.jpg" alt="Sample Comment 6" /></a></li>
<li><a href="/uploads/internets/internets7.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 7"><img src="/thumbs/internets7_80x100_abs.jpg" alt="Sample Comment 7" /></a></li>
<li><a href="/uploads/internets/internets8.png" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 8"><img src="/thumbs/internets8_80x100_abs.png" alt="Sample Comment 8" /></a></li>
<li><a href="/uploads/internets/internets9.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 9"><img src="/thumbs/internets9_80x100_abs.jpg" alt="Sample Comment 9" /></a></li>
<li><a href="/uploads/internets/internets10.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 10"><img src="/thumbs/internets10_80x100_abs.jpg" alt="Sample Comment 10" /></a></li>
<li><a href="/uploads/internets/internets11.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 11"><img src="/thumbs/internets11_80x100_abs.jpg" alt="Sample Comment 11" /></a></li>
<li><a href="/uploads/internets/internets12.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 12"><img src="/thumbs/internets12_80x100_abs.jpg" alt="Sample Comment 12" /></a></li>
<li><a href="/uploads/internets/internets13.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 13"><img src="/thumbs/internets13_80x100_abs.jpg" alt="Sample Comment 13" /></a></li>
<li><a href="/uploads/internets/internets15.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 15"><img src="/thumbs/internets15_80x100_abs.jpg" alt="Sample Comment 15" /></a></li>
<li><a href="/uploads/internets/internets17.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 17"><img src="/thumbs/internets17_80x100_abs.jpg" alt="Sample Comment 17" /></a></li>
<li><a href="/uploads/internets/internets18.jpg" class="fancybox" rel="gallery-577c16c55bcdb7c0e34737590ad62408" title="Sample Comment 18"><img src="/thumbs/internets18_80x100_abs.jpg" alt="Sample Comment 18" /></a></li>
</ul>

Gist

Here is my plugin source:


More To-do (Updated 8 July 2013)

  • De-hardcode the styling into separate .erb file (per Disqus comment)
  • Use the Jekyll keep_files list to generate files directly to destination directory (per Gist comment)

Comments