images_gallery 1.0.0.rc

data/README.md

@@ -0,0 +1,84 @@
+Images Gallery Generator Kata
+=============================
+
+Generate a set of static HTML files from an XML representation of EXIF data so users can browse large collections of images.
+
+<img alt="" src="doc/illustration.png"/>
+
+Usage
+-----
+
+```bash
+# Generate a gallery inside spec/tmp from the example source file
+./bin/images_gallery generate spec/fixtures/works.xml spec/tmp
+
+# Read usage intructions:
+./bin/images_gallery help
+
+# Open the images gallery automatically after it was generated
+firefox $(./bin/images_gallery generate spec/fixtures/works.xml spec/tmp/)
+```
+
+Development
+-----------
+
+### Test suite
+
+```bash
+# Run the test suite
+rake
+
+# Run the acceptance test suite only (can be seen as a demo)
+rake features
+# Visit spec/tmp/index.html to browse the sample images
+```
+
+### Parser
+
+The `ImageGallery::Source` relies on the **LibXML** SAX parser to extract the images described in the source XML file (e.g. [`works.xml`][example-source]). That parser is [known to be fast][libxml-benchmarks] and [memory-thrifty][sax-versus-dom].
+
+  [example-source]: spec/fixtures/works.xml
+  [libxml-benchmarks]: https://github.com/xml4r/libxml-ruby#performance
+  [sax-versus-dom]: http://www.saxproject.org/event.html
+
+About
+-----
+
+This kata aims at writing a command-line tool to process **large** XML files which contain images metadata. Part of that metadata is relevant, and the images gallery should allow to preview a collection of thumbnails classified by camera **make** and **model**.
+
+Because the images collections can be really large, [care has been taken][parser] to avoid loading the XML document in memory while parsing it.
+
+  [parser]: https://github.com/gonzalo-bulnes/kata-images_gallery_generator/tree/add-acceptance-test-suite#parser
+
+Yet huges collections to review do also mean you probably don't want to review them without involving your team. That's to say the images gallery deployment is a key aspect of the task at hand, and keeping the files tree as simple as possible is a way to make the deployments as straightforward as possible. No external CSS, nor font, nor javascipts then.
+
+The views/templates pattern makes the design extensible, this galleries generator is no <abbr title="Content Management System">CMS</abbr> however! Priority has been given to simplify as much as possible the rendering engine task. Plain ERb should keep the HTML generation fast, while a basic partials system ensures that adding front-end features remains [a _pomodoro_-sized task][pomodoro].
+
+  [pomodoro]: https://github.com/gonzalo-bulnes/kata-images_gallery_generator/commit/a90590e63f65d0b166c93e709a17a267c9ec119f
+
+The main user interface is the CLI, which was built with [Thor][thor] as a way to make it both user-friendly and extensible. The CLI output was kept minimal, to make easy to insert the **images_gallery** program into any processing pipeline (since we are talking about large amount of data here, then we're probably also talking about processing pipelines).
+
+That's pretty much all... a last word about those [particularly numerous shared specs][shared]. I like to define the "public" API of the main classes this way in order to ensure I keep always at sight which methods I can depend on and which others could lead to tighter undesired coupling. These interfaces are kinds of [consumer-driven contracts][cdc] and keeping them apart helps to remember that.
+
+  [thor]: http://whatisthor.com
+  [shared]: https://github.com/gonzalo-bulnes/kata-images_gallery_generator/tree/add-acceptance-test-suite/spec/support
+  [cdc]: http://martinfowler.com/articles/consumerDrivenContracts.html
+
+License
+-------
+
+    Images Gallery Generator
+    Copyright (C) 2015 Gonzalo Bulnes Guilpain
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rainbow'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RSpec::Core::RakeTask.new(:features) do |config|
+  config.pattern = 'spec/features/**/*_spec.rb'
+end
+
+desc 'Report code quality'
+task :rubycritic do
+
+  # check if the rubycritic code quality reporter is available
+  `which rubycritic`
+  if $?.exitstatus != 0
+    abort <<-eos.gsub /^( |\t)+/, ""
+
+      The #{Rainbow('rubycritic').red} code quality reporter is not available.
+      You may want to install it in order to report the code quality.
+
+      See #https://github.com/whitesmith/rubycritic for intallation instructions.
+
+    eos
+  end
+
+  command = "rubycritic"
+  puts <<-eos.gsub /^( |\t)+/, ""
+
+    #{Rainbow('Report the code quality.').blue}
+    #{command}
+
+  eos
+  success = system('rubycritic')
+  exit_status = $?.exitstatus
+
+  abort unless exit_status == 0
+end
+
+begin
+  require 'inch/rake'
+
+  Inch::Rake::Suggest.new(:inch) do |suggest|
+    suggest.args << "--private"
+    suggest.args << "--pedantic"
+  end
+rescue LoadError
+  desc 'Inch rake task not available'
+  task :inch do
+  abort 'Inch rake task is not available. Be sure to install inch as a gem or plugin'
+  end
+end
+
+task default: [:spec, :inch, :rubycritic]

data/bin/images_gallery

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.push File.join(File.dirname(__FILE__), "/../lib" )
+
+require 'images_gallery/cli'
+
+ImagesGallery::CLI.start(ARGV)

data/config.ru

@@ -0,0 +1,8 @@
+require 'rack'
+
+$:.push File.expand_path("../lib", __FILE__)
+
+require 'images_gallery/test_application'
+
+use Rack::Static, urls: [""], root: ImagesGallery::TestApplication::DEFAULT_TARGET, index: 'index.html'
+run ImagesGallery::TestApplication

data/lib/images_gallery/cli.rb

@@ -0,0 +1,27 @@
+require 'thor'
+
+require 'images_gallery/generator'
+
+module ImagesGallery
+  class CLI < Thor
+
+    desc 'generate SOURCE TARGET', 'Generate a static HTML images gallery in the TARGET directory from the SOURCE file contents.'
+    def generate(source, target=nil, error=STDERR, out=STDOUT)
+      begin
+        out.puts generator.run(source, target)
+      rescue ImagesGallery::SourceFileNotFoundError
+        error.puts 'Please make sure the specified source file exists.'
+      rescue ImagesGallery::TargetDirectoryNotFoundError
+        error.puts 'Please make sure the specified target directory exists.'
+      rescue ImagesGallery::SourceFileInvalidError
+        error.puts 'The source file is invalid. Please check it is well-formed XML.'
+      end
+    end
+
+    private
+
+      def generator
+        @generator ||= Generator.new
+      end
+  end
+end

data/lib/images_gallery/collection.rb

@@ -0,0 +1,15 @@
+require 'images_gallery/image'
+
+module ImagesGallery
+  class Collection < Array
+
+    def makes
+      map { |image| image.make }.uniq.sort
+    end
+
+    def models
+      map { |image| image.model }.uniq.sort
+    end
+
+  end
+end

data/lib/images_gallery/errors.rb

@@ -0,0 +1,6 @@
+module ImagesGallery
+
+  SourceFileNotFoundError = Class.new(LoadError)
+  TargetDirectoryNotFoundError = Class.new(LoadError)
+  SourceFileInvalidError = Class.new(RuntimeError)
+end

data/lib/images_gallery/generator.rb

@@ -0,0 +1,66 @@
+require 'images_gallery/errors'
+require 'images_gallery/source'
+require 'images_gallery/views/index'
+require 'images_gallery/views/make'
+require 'images_gallery/views/model'
+
+module ImagesGallery
+  class Generator
+
+    attr_reader :target
+    private :target
+
+    def run(source, target)
+
+      raise SourceFileNotFoundError unless File.file? source
+      raise TargetDirectoryNotFoundError unless File.directory? target
+
+      @source = Source.new(source)
+      @target = target
+
+      @source.parse
+      files = render_views(@source.images)
+      generate(target, files)
+    end
+
+    private
+
+      def render_views(images)
+        files = {}
+
+        files['index'] = Views::Index.new(images).render
+
+        images.makes.each do |make|
+          images_by_make = Collection.new
+          images.select{ |image| image.make == make }.each do |image|
+            images_by_make << image
+            view = Views::Make.new(images_by_make)
+            files[view.file_identifier(image.make)] = view.render
+
+            images_by_make.models.each do |model|
+              images_by_model = Collection.new
+              images_by_make.select{ |image| image.model == model }.each do |image|
+                images_by_model << image
+                view = Views::Model.new(images_by_model)
+                files[view.file_identifier(image.make, image.model)] = view.render
+              end
+            end
+          end
+        end
+        files
+      end
+
+      def generate(target, files)
+        files.each do |name, content|
+          dir_path = "#{target}/#{name}".gsub('//', '/')
+          file_path = dir_path + '.html'
+          @index_path = file_path if name == 'index'
+          FileUtils.mkdir_p(dir_path) unless File.exists?(dir_path) || (name == 'index')
+          File.open(file_path, 'w') do |file|
+            file.write content
+          end
+        end
+        @index_path
+      end
+  end
+end

data/lib/images_gallery/image.rb

@@ -0,0 +1,19 @@
+module ImagesGallery
+  class Image
+
+    attr_accessor :id, :src, :make, :model
+
+    def make
+      @make || 'Unknown Make'
+    end
+
+    def model
+      @model || 'Unknown Model'
+    end
+
+    def description
+      "Image #{@id}"
+    end
+
+  end
+end

data/lib/images_gallery/source.rb

@@ -0,0 +1,104 @@
+require 'libxml'
+
+require 'images_gallery/collection'
+
+module ImagesGallery
+  class Source
+
+    include LibXML
+    include XML::SaxParser::Callbacks
+
+    attr_reader :images
+
+    # Provides a collection of images to presenters
+    #
+    # Extracts some images attributes from an XML collection of works
+    # and collects the images as plain Ruby objects so other classes
+    # can use them with presentational purpose.
+    #
+    # This class should be able to parse efficiently large XML files.
+    #
+    # file - Path to an XML representation of the images (metadata, EXIF)
+    #
+    # Example:
+    #
+    #     source = ImagesGallery::Source.new('path/to/source.xml')
+    #     source.parse   # creates a Collection of Images
+    #     source.images  # is available after parsing
+    #
+    # Returns a Source object, ready to parse the corresponding XML file.
+    def initialize(file)
+      @file = XML::SaxParser.file(file)
+      @file.callbacks = self
+    end
+
+    def parse
+      @images = Collection.new
+      begin
+        @file.parse
+      rescue LibXML::XML::Error
+        raise SourceFileInvalidError
+      end
+    end
+
+    # Callbacks can't be private, yet they are not part of the public API.
+
+    def on_start_element(element, attributes)
+      @current_element = element
+
+      if element == 'work'
+        @current_image = Image.new
+      end
+
+      if element == 'url' && attributes['type'] == 'small'
+        @current_element = 'thumbnail URL'
+      end
+    end
+
+    def on_end_element(element)
+      if element == 'work'
+        @images << @current_image
+      end
+
+      if element == 'id'
+        @current_image.id = @current_id
+      end
+
+      if element == 'make'
+        @current_image.make = @current_make
+      end
+
+      if element == 'model'
+        @current_image.model = @current_model
+      end
+
+      if @current_element == 'thumbnail URL'
+        @current_image.src = @current_src
+      end
+
+      @current_element = nil
+    end
+
+    def on_characters(char)
+      if @current_element == 'id'
+        @current_id = char
+      end
+
+      if @current_element == 'make'
+        @current_make = char
+      end
+
+      if @current_element == 'model'
+        @current_model = char
+      end
+
+      if @current_element == 'thumbnail URL'
+        @current_src = char
+      end
+    end
+
+    def on_end_document
+      @current_element = nil
+    end
+  end
+end

data/lib/images_gallery/templates/_navigation.html.erb

@@ -0,0 +1,5 @@
+<nav>
+  <% links.each do |link| %>
+    <a class="nav-link" href="<%= link[:href] %>"><%= link[:name] %></a>
+  <% end %>
+</nav>

data/lib/images_gallery/templates/_thumbnails.html.erb

@@ -0,0 +1,13 @@
+<div class="grid">
+  <% images.each do |image| %>
+    <div class="grid-item">
+      <img alt="<%= image.description %>" src="<%= image.src %>"/>
+      <% unless depth == 1 %>
+        <a class="grid-item-details" href="<%= link_to(depth, image.make, image.model) %>" title="Browse all the <%= image.model %> images.">
+          <div><%= image.make %></div>
+          <div><%= image.model %></div>
+        </a>
+      <% end %>
+    </div>
+  <% end %>
+</div>

data/lib/images_gallery/templates/layout.html.erb

@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= title %></title>
+    <style type="text/css">
+      html, body {
+        font-family: "adelle", "Helvetica Neue", Helvetica, Arial, sans-serif;
+        font-size: 1rem;
+      }
+      nav {
+        border: 1px solid #ccc;
+        border-width: 1px 0;
+        margin: 2rem 0;
+      }
+      .nav-link {
+        display: inline-block;
+        line-height: 3rem;
+        padding: 0 1rem;
+        text-decoration: none;
+        text-transform: uppercase;
+      }
+      .grid {
+        max-width: 960px;
+      }
+      .grid-item {
+        border: 1px solid #ccc;
+        display: inline-block;
+        padding: 10px 10px 5px;
+        position: relative;
+        margin: 5px;
+      }
+      .grid-item-details {
+        background-color: rgba(255, 255, 255, 0.9);
+        color: #333;
+        font-size: .8rem;
+        font-variant: small-caps;
+        height: 3rem;
+        left: 0;
+        line-height: 1.2rem;
+        opacity: 0;
+        padding: .2rem 0 10px;
+        position: absolute;
+        width: 100%;
+        bottom: 0;
+        text-align: center;
+        text-decoration: none;
+      }
+      .grid-item:hover .grid-item-details {
+        opacity: 1;
+      }
+    </style>
+    </head>
+  <body>
+    <header>
+      <h1><%= title %></h1>
+      <%= navigation(links) %>
+    </header>
+
+    <%= thumbnails(sample_images) %>
+  </body>
+</html>

data/lib/images_gallery/test_application.rb

@@ -0,0 +1,14 @@
+require 'rack'
+
+require 'images_gallery/generator'
+
+module ImagesGallery
+  class TestApplication
+
+    DEFAULT_TARGET = 'spec/tmp'
+
+    def self.call(env)
+      run Rack::Directory.new(DEFAULT_TARGET).call(env)
+    end
+  end
+end

data/lib/images_gallery/version.rb

@@ -0,0 +1,3 @@
+module ImagesGallery
+  VERSION = '1.0.0.rc'
+end

data/lib/images_gallery/view.rb

@@ -0,0 +1,55 @@
+require 'erb'
+
+module ImagesGallery
+  class View
+
+    # Provides context and helpers to the corresponding template
+    #
+    # Any variable defined in the context of this class will be accessible
+    # from the corresponding ERb template.
+    # See http://ruby-doc.org/stdlib-2.2.2/libdoc/erb/rdoc/ERB.html#method-i-result
+    #
+    # Usage:
+    #
+    # Do not instanciate this class, define subclasses instead an define their
+    # template methods as demonstrated in Views::Index.
+    #
+    # Conventionally, templates could be stored in images_gallery/templates, but
+    # there is no obligation to follow the convention.
+    #
+    # This class not meant to be instanciated, subclasses do return View instances (kind of).
+    def initialize
+      @template = File.new(template)
+    end
+
+    def template
+      raise NotImplementedError
+    end
+
+    def render
+      ERB.new(File.new(template).read).result(binding)
+    end
+
+    def thumbnails(images)
+      template = 'lib/images_gallery/templates/_thumbnails.html.erb'
+      ERB.new(File.new(template).read).result(binding)
+    end
+
+    def navigation(links)
+      template = 'lib/images_gallery/templates/_navigation.html.erb'
+      ERB.new(File.new(template).read).result(binding)
+    end
+
+    def link_to(depth, make, model=nil)
+      ('../' * depth) + file_identifier(make, model) + '.html'
+    end
+
+    def file_identifier(make, model=nil)
+      if model.nil?
+        "#{make.to_filename}"
+      else
+        "#{make.to_filename}/#{model.to_filename}"
+      end
+    end
+  end
+end

data/lib/images_gallery/views/index.rb

@@ -0,0 +1,26 @@
+require 'erb'
+
+require 'images_gallery/view'
+
+module ImagesGallery
+  module Views
+    class Index < ImagesGallery::View
+
+      attr_reader :depth, :links, :sample_images, :title
+      private :depth, :links, :sample_images, :title
+
+      def initialize(images)
+        super()
+
+        @depth = 0
+        @links = images.makes.map{ |make| { name: make, href: link_to(depth, make) } }
+        @sample_images = images.first(10)
+        @title = 'Index'
+      end
+
+      def template
+        'lib/images_gallery/templates/layout.html.erb'
+      end
+    end
+  end
+end

data/lib/images_gallery/views/make.rb

@@ -0,0 +1,28 @@
+require 'erb'
+
+require 'images_gallery/view'
+
+module ImagesGallery
+  module Views
+    class Make < ImagesGallery::View
+
+      attr_reader :depth, :links, :make, :sample_images, :title
+      private :depth, :links, :make, :sample_images, :title
+
+      def initialize(images)
+        super()
+
+        @depth = 0
+        @make = images.first.make
+        @links = [{ name: "Browse all the images", href: link_to(depth, 'index') }]
+        @links += images.models.map{ |model| { name: model, href: link_to(depth, make, model) } }
+        @sample_images = images.first(10)
+        @title = "Images by #{make}"
+      end
+
+      def template
+        'lib/images_gallery/templates/layout.html.erb'
+      end
+    end
+  end
+end

data/lib/images_gallery/views/model.rb

@@ -0,0 +1,29 @@
+require 'erb'
+
+require 'images_gallery/view'
+
+module ImagesGallery
+  module Views
+    class Model < ImagesGallery::View
+
+      attr_reader :depth, :links, :make, :model, :sample_images, :title
+      private :depth, :links, :make, :model, :sample_images, :title
+
+      def initialize(images)
+        super()
+
+        @depth = 1
+        @make = images.first.make
+        @model = images.first.model
+        @links = [{ name: "Browse all the images", href: link_to(depth, 'index') }]
+        @links << { name: "Browse all the #{make} images", href: link_to(depth, make) }
+        @sample_images = images
+        @title = "Images by (#{make}) #{model}"
+      end
+
+      def template
+        'lib/images_gallery/templates/layout.html.erb'
+      end
+    end
+  end
+end

data/lib/images_gallery.rb

@@ -0,0 +1,10 @@
+require 'images_gallery/generator'
+require 'images_gallery/version'
+
+class String
+
+  # Sanitize a name so it can be used as part of an URL
+  def to_filename
+    downcase.gsub(/\W/, '_').gsub(/_+/, '_').gsub(/_\Z/, '')
+  end
+end