plugins/gallery/README.md

   1 Gallery
   2 ==================
   3
   4 * Allows an article to contain an album of pictures.
   5 * All albums can also be syndicated into a central gallery page.
   6
   7 ## How to Use
   8
   9 1. Group images into folders, with each folder representing an album.
  10 2. Place all album folders within a folder, which should reside under content.
  11 3. Insert `GALLERY_PATH` to your `pelicanconf.py` and set a path to that folder. By default it is `images/gallery`.
  12
  13                 ./content/images/gallery/{your albums}
  14
  15 ### Articles
  16
  17 Attach an album to an article/post by placing a gallery metadata tag with the name of the album.
  18
  19         gallery:album_name
  20
  21 The template has access to the album name.
  22
  23         article.album
  24
  25 And the filename of images within an album.
  26
  27         article.albumimages
  28
  29 ### Gallery Page
  30
  31 Create a page and a gallery template (named gallery.html). And inform pelican to use the gallery template for the page.
  32
  33         template:gallery
  34
  35 The template has access to a dictionary of lists.
  36 The dictionary key is the name of the album and the lists contain the filenames.
  37
  38         page.gallery
  39
  40 ## Examples
  41
  42 ### article.html
  43
  44         <h2><a href="{{ SITEURL }}/pages/gallery.html#{{ article.album }}">{{ article.album }}</a></h2>
  45             <ul>
  46                 {% for image in article.galleryimages %}
  47                 <li><a class="{{ article.album }} cboxElement" href="{{ SITEURL }}/static/images/gallery/{{ article.album }}/{{ image }}"><img src="{{ SITEURL }}/static/images/gallery200x200/{{ article.album }}/{{ image }}"></a></li>
  48                 {% endfor %}
  49             </ul>
  50
  51 ### gallery.html
  52
  53         {% for album, images in page.gallery.iteritems() %}
  54         <h2><a name="{{ album }}">{{ album }}</a></h2>
  55         <ul>
  56             {% for image in images %}
  57             <li><a class="{{ album }} cboxElement" href="{{ SITEURL }}/static/images/gallery/{{album}}/{{ image }}" title="{{ image }}"><img src="{{ SITEURL }}/static/images/gallery200x200/{{album}}/{{ image }}"></a></li>
  58             {% endfor %}
  59         </ul>
  60         {% endfor %}
  61
  62 ### posts/foo.md
  63
  64         title:Foo
  65         gallery:albumname
  66
  67 ### pages/gallery.md
  68
  69         title:All Images
  70         template:gallery
  71
  72 ## Reasoning
  73
  74 The album name and filenames are returned as opposed to the direct path to the images,
  75 to allow flexibility of different thumbnail sizes to be used it different locations of a website.
  76
  77         href="{{ SITEURL }}/static/images/gallery/{{album}}/{{ image }}"
  78         href="{{ SITEURL }}/static/images/gallery200x200/{{album}}/{{ image }}"
  79
  80 It also allows a thumbnail to link to the full image,
  81 as well as the filename extension to be stripped and the title of an image to be displayed along side the title of an album.
  82
  83 ## Recommendation
  84
  85 It is recommended to use this extension along with the thumbnailer plugin.
  86
  87         RESIZE = [
  88             ('gallery', False, 200,200),
  89           ]
  90
  91 You may also wish to use this along with a gallery plugin such as [Colorbox](http://www.jacklmoore.com/colorbox/).