jekyll-galleries 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6978dd5f6d6d477aba217497f611471184d9647c
-  data.tar.gz: 548abaae61e0141bf5584f5465e6a1d956134431
+  metadata.gz: 96392eb09f6402ecf36bb1144ab3037ac4431d52
+  data.tar.gz: 52129659e6b1e595d2493e3457823f5c6c653ae9
 SHA512:
-  metadata.gz: deb0e5551b4a08812ba41011ab1a0f05c87745ec6c482b12e48991777147213f09f7761ec1dd8c4311b9584f9b1ef25d93e655956ce4c43d2ad5165fc1f7fb70
-  data.tar.gz: ef1c7537800e331f9a306cec5dcaf1da560c543616d35c735ed3e7aad22600b350768984805e9dfea2df6b11b2537934cd8b8afec160313b1116647758e1457f
+  metadata.gz: cf7c2944dd0d6bcc5703aa252295e457e198830b8c3f8347e3bb25f5320bc27df23b9cb42bd6c61675399d3c22aeb4658ba19a29b83bca9011970dc492753a65
+  data.tar.gz: 1530757ee636776276f8d678130f09822bcfa3ce41986c8b3d28298ed0aa10d229fda40bc2dc8aa544d9978d3c120d28e1b524ca3642e0a351155239eb9cffda

data/ChangeLog

@@ -1,3 +1,12 @@
+== 0.7.2 [2014-02-20]
+
+* Add full documentation
+* Add `Photo` class to store photo information
+
+== 0.7.1 [2014-02-10]
+
+Clean up source code
+
 == 0.7.0 [2014-02-10]
 
 Basic features

data/README.md

@@ -0,0 +1,197 @@
+# jekyll-galleries
+
+By [allenlsy](mailto:cafe@allenlsy.com)
+
+__Jekyll-galleries__ is a Jekyll plugin used for generating photo galleries from image folders.
+
+If you have any questions or any suggestions, I'm very pleased to hear from you. I need your support and ideas to make this plugin better.
+
+---
+
+##### Features:
+
+* Automatically generate galleries from <tt>galleries</tt> folder
+* Provide a convenient to generate galleries index page
+* Load galleries and photos configuration from YAML file
+
+There are two main concept in this plugin:
+
+* __GalleriesPage__: index page displays all the galleries
+* __GalleryPage__: single gallery webpage which shows all the photos in this gallery
+
+### How to use the plugin
+
+Here is an example on how to use this plugin.
+
+##### 1. Setup the plugin
+
+Add `gem 'jekyll-galleries'` to the `Gemfile` in your jekyll project, and then run `bundle` command in shell to install it. Then add `require 'jekyll/galleries'` to `_plugins/_ext.rb`.
+
+There are three attributes which are optional. All of them should be put at the root level of `_config.yml`, if needed.
+
+* `galleries` specifies the extra information of each gallery, using the YAML object format.
+* `gallery_dir` defines which folder in jekyll project stores the all the galleries. Default value is `galleries` if not defined.
+* `gallery_layout` defines the layout __Jekyll-galleries__ will use to render each single gallery. Default value is `gallery`, which uses the `_layouts/gallery.html` as the template.
+
+Check out the example `_config.yml` if you are still not clear.
+
+##### 2. Add galleries to jekyll project
+
+By default, galleries are stored in the `galleries` folder in the jekyll project root path. If you want to change the storing path, you can customize the `gallery_dir` attribute it in `_config.yml` file.
+
+__Jekyll-galleries__ will recognize all the subfolders in `galleries` (or `gallery_dir` specified in `_config.yml`) with the format of `<yyyy-MM-dd>-<NAME>` as a valid gallery folder. Meanwhile it adds `date` (value `yyyy-MM-dd`) and `name` (value `NAME`) attributes to the gallery. In the `name` attributes, space and other characters are allowed. All the files in gallery folder will be loaded to the GalleryPage. So please ensure you have correct image file in the gallery folder.
+
+##### 3. Adding attribute to photos
+
+You can have a `.yml` file with the same name of the gallery folder, to define attributes of each photo in that gallery. Only photos with extra attributes are required in the yaml file. Each photo is identified by the attribute `filename`. For example, if you have an gallery, whose folder name is `2014-01-23-At the beach`, then in a `2014-01-23-At the beach.yml` file, you can config photos like this:
+
+    - filename: IMG_0075.JPG
+      annotation: this is the allenllsy's jekyll-galleries
+    - filename: IMG_1234.JPG
+      annotation: shot at London
+
+Then later you can use the attributes in your template, such as `annotation` in the example above.
+
+Notice that attribute `filename` is required for any photos that as extra attributes.
+
+##### 4. Adding attribute to gallery
+
+Inside the optional `galleries` attribute in `_config.yml`, you can have objects, with attribute `name` the value equals to your gallery name (not containing the date). For example:
+
+    galleries:
+      - name: Sample Gallery
+        subtitle: This is a sample gallery
+
+Then in the template, the gallery will have the attribute `subtitle` that can be rendered.
+
+##### 5. Use attributes in template
+
+Now, the `site.data['galleries']` global variable contains all the gallery pages. It is an array of `GalleryPage` objects. Each `GalleryPage` object has at least three attributes: `name`, `date` and `url`. `url` is URL escaped. You can use them in your galleries index page.
+
+In each gallery page, you have a `page` object. And `page.photos` is an array of `Photo` objects. An `Photo` object has at least `filename` and `url` two attributes. The `url` attribute is also URL escaped, so you don't need to worry about it.
+
+In the example below, you will see how to use attributes in template in more detail.
+
+### Example of Galleries Index page & Gallery page
+
+* Galleries Index page: the index page of all galleries
+* Gallery Page: the page display photos in that gallery
+
+Suppose in the Jekyll project root folder, my file structure is like below:
+
+    galleries/
+    |-2014-01-23-At the beach
+    | -IMG_0001.JPG
+    | -IMG_0005.JPG
+    |-2014-02-01-Chinese New Year
+    | -sing a song.jpg
+    | -having dinner.jpg
+
+##### Galleries index page template
+
+After installing and setting up the plugin, I add a galleries index file `galleries.html` in Jekyll root directory:
+
+    ---
+    layout: base
+    ---
+    {% for gallery in site.data['galleries'] %}
+      <p>
+        <a href="{{ gallery.url }}">{{ gallery.name }}</a>
+        <span>{{ gallery.date }}</span>
+      </p>
+    {% endfor %}
+
+If I want to also add other attributes, such as `excerpt` for some galleries, I can specifies them in `_config.yml`
+
+    galleries:
+      - name: At the beach
+        excerpt: Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
+
+Then I update the `galleries.html` page:
+
+    ---
+    layout: base
+    ---
+    {% for gallery in site.data['galleries'] %}
+      <div>
+        <a href="{{ gallery.url }}">{{ gallery.name }}</a>
+        <span>{{ gallery.date }}</span>
+        {% if gallery.excerpt %}
+        <p>
+          {{ gallery.excerpt }}
+        </p>
+        {% endif %}
+      </div>
+    {% endfor %}
+
+The generated `galleries.html` should be like this:
+
+    <div>
+      <a href="/galleries/2014-02-01-chinese-new-year.html">Chinese New Year</a>
+      <span>2014-02-01</span>
+    </div>
+    <div>
+      <a href="/galleries/2014-01-23-at-the-beach.html">At the beach</a>
+      <span>2014-01-23</span>
+      <p>
+        Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
+      </p>
+    </div>
+
+
+##### Gallery page template
+
+Next, I add a `_layouts/gallery.html` file as my gallery template. This is the template for each single gallery
+
+    ---
+    layout: base
+    ---
+
+    {% for photo in page.photos %}
+      <img src="{{ photo.url }}" style="width:800px;"/>
+      {% if photo.info %}
+      <p>{{ photo.info }}</p>
+      {% endif %}
+      <hr >
+    {% endfor %}
+
+In this template, I take use of the extra attribute `info` of photo. This attribute can be configured in photos config file, eg. `galleries/2014-02-01-Chinese New Year`:
+
+    - filename: 'sing a song.jpg'
+      info: 'We are singing a song'
+
+The photos are identified using the `filename` attribute.
+
+After I run `jekyll build`, it should generate a file `_site/galleries/2014-02-01-chinese-new-year.html`. The content should be like:
+
+    <img src="/galleries/2014-02-02-Chinese%20New%20Year/IMG_0094.JPG" style="width:800px;"/>
+    <hr >
+    <img src="/galleries/2014-02-02-Chinese%20New%20Year/sing%20a%20song.jpg" style="width:800px;"/>
+    <p>We are singing a song</p>
+    <hr >
+
+### License
+
+#### The MIT License
+
+Copyright (c) 2010-2012 University of Cologne,
+Albertus-Magnus-Platz, 50923 Cologne, Germany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/lib/jekyll/galleries.rb

@@ -1,6 +1,6 @@
 module Jekyll
   class GalleryGenerator < Generator
-    attr_accessor :site, :gallery_dir, :gallery_layout
+    attr_accessor :site, :gallery_dir, :gallery_layout, :galleries
     class << self; attr_accessor :site; end
 
     def generate(site)
@@ -10,8 +10,9 @@ module Jekyll
 
       # array of GalleryPage objects
       site.data['galleries'] = []
+
       gallery_dirs = Dir["#{site.source}/#{gallery_dir}/*/"].select { |e| File.directory? e }
-      gallery_dirs.reverse! # sort by date desc
+      gallery_dirs.reverse! # in order to sort by date desc
       gallery_dirs.each do |dir|
         generate_gallery_page(dir)
       end
@@ -22,6 +23,7 @@ module Jekyll
       data = { 'layout' => gallery_layout }
 
       page = GalleryPage.new(site, site.source, self.gallery_dir, gallery_dir, data)
+
       site.pages << page
 
       site.data['galleries'] << page
@@ -32,19 +34,42 @@ module Jekyll
   class GalleryPage < Page
     # Valid post name regex.
     MATCHER = /^(\d+-\d+-\d+)-(.*)$/
+    CONFIG_GALLERIES_ATTR = 'galleries'
 
-    attr_accessor :site, :url, :name, :slug
+    attr_accessor :url, :name, :slug, :date
 
-    def initialize(site, base, gen_dir, dir, data={})
+    def initialize(site, base, gen_dir, gallery_dir, data={})
       self.content = data.delete('content') || ''
       self.data = data
 
-      super(site, base, gen_dir, File.basename(dir) )
+      gallery_dir_name = File.basename gallery_dir
+      super(site, base, gen_dir, gallery_dir_name)
+
+      # load photos configuration
+      photos_config_filepath =  "#{base}/#{site.config['gallery_dir']}/#{self.date}-#{self.name}.yml"
+      photos_config = YAML.load(File.open(photos_config_filepath).read) if File.exists?(photos_config_filepath)
+
+      # generating photos
+      self.url = "/#{gen_dir}/#{self.date}-#{self.slug}.html" # gallery page url
+      self.data['url'] = URI.escape self.url 
 
-      # url, photos
-      self.url = "/#{gen_dir}/#{self.data['slug']}.html"
-      self.data['url'] = URI.escape self.url
-      self.data['photo_urls'] = Dir["#{base}/#{gen_dir}/#{self.name}/*"].map { |e| URI.escape("/#{gen_dir}/#{self.name}/#{File.basename e}") }
+      # For each photo, initial attributes are `filename` and `url`
+      photos = Dir["#{gallery_dir}/*"].map { |e| { filename: File.basename(e), url: URI.escape("/#{gen_dir}/#{gallery_dir_name}/#{File.basename e}") } } # basic photos attributes
+
+      self.data['photos'] = [] # storing an array of Photo
+      photos.each do |photo|
+        photo_data = {}
+        photo_data = photos_config.find { |e| e['filename'] == photo[:filename] } if photos_config
+        self.data['photos'] << Photo.new(photo[:filename], photo[:url], photo_data)
+      end
+
+      # gallery page configuration
+      if site.config[CONFIG_GALLERIES_ATTR]
+        attr = site.config[CONFIG_GALLERIES_ATTR].find { |e| e['name'] == self.name}
+        if attr
+          attr.each { |k, v| self.data[k] = v }
+        end
+      end
     end
 
     def read_yaml(*)
@@ -59,14 +84,28 @@ module Jekyll
       m, date, name = *name.match(MATCHER)
 
       # self.data['date'] = Time.parse(date)
-      self.data['date'] = date
-      self.data['name'] = name
-      self.data['slug'] = name
+      self.data['date'] = self.date = date
+      self.data['name'] = self.name = name
+      self.data['slug'] = self.slug = name.gsub(/[^0-9a-z ]/i, '').downcase.gsub(/ /, '-')
     rescue ArgumentError
       raise FatalException.new("Gallery #{name} does not have a valid date.")
     end
   end
 
+  class Photo
+    attr_accessor :filename, :url, :data
+
+    def initialize(filename, url, options=nil)
+      self.filename = filename
+      self.url = url
+      self.data = options || {}
+    end
+
+    def to_liquid
+      self.data.merge({ 'url' => self.url })
+    end
+  end
+
   class YamlToLiquid < Liquid::Tag
     def initialize(tag_name, arg, tokens)
       super
@@ -87,4 +126,3 @@ module Jekyll
 end
 
 Liquid::Template.register_tag('yaml_to_liquid', Jekyll::YamlToLiquid)
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-galleries
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.2
 platform: ruby
 authors:
 - allenlsy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-10 00:00:00.000000000 Z
+date: 2014-02-20 00:00:00.000000000 Z
 dependencies: []
 description: Jekyll plugin to automatically generate photo gallery (album) from image
   folder.
@@ -19,7 +19,7 @@ extra_rdoc_files: []
 files:
 - lib/jekyll/galleries.rb
 - ChangeLog
-- README.rdoc
+- README.md
 - Rakefile
 homepage: http://github.com/allenlsy/jekyll-galleries
 licenses:
@@ -53,6 +53,7 @@ rubygems_version: 2.1.11
 signing_key: 
 specification_version: 4
 summary: Jekyll plugin to automatically generate photo gallery (album) from image
-  folder.
+  folder. It provides easy configuration to customize the attribute, for using them
+  in galleries index page
 test_files: []
 has_rdoc: 

data/README.rdoc

@@ -1,61 +0,0 @@
-= jekyll-galleries
-
-By allenlsy <mailto:cafe@allenlsy>
-
-Jekyll-galleries is a Jekyll plugin used for generating photo galleries from image folders.
-
-<tt>_config.yml</tt>:
-
-  gallery_dir: galleries
-  gallery_layout: gallery
-
-Sample layout for gallery index, which you can make a <tt>galleries.html</tt> in Jekyll root directory:
-
-  {% for gallery in site.data['galleries'] %}
-    <p>
-      <a href="{{ gallery.url }}">{{ gallery.name }}</a>
-      <span>{{ gallery.date }}</span>
-    </p>
-  {% endfor %}
-
-Sample layout for one gallery page, which normally you will put it as <tt>_layouts/gallery.html</tt>:
-
-  ---
-  layout: base
-  ---
-  {% for photo_url in page.photos %}
-    <p>
-      <img src="{{ photo_url }}" />
-    </p>
-  {% endfor %}
-
-== Links
-
-<b></b>
-Source code:: <http://github.com/allenlsy/jekyll-galleries>
-RubyGem:: <http://rubygems.org/gems/jekyll-galleries>
-
-== License
-
-=== The MIT License
-
-Copyright (c) 2010-2012 University of Cologne,
-Albertus-Magnus-Platz, 50923 Cologne, Germany
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.