ballonizer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9b02cccd0f9fc456b32c0172a91aa790b3d06132
+  data.tar.gz: 0ca2e4a60db0d971dc0b1aa443e208efef0d7a5b
+SHA512:
+  metadata.gz: f6fdc80bedf5f03cca40990d7608acd67e402f6c4e21923610389c20a285a2639a50eedd8456e983584303bf405e5ce1cf7764cce9f35a9e87e6887dbb965027
+  data.tar.gz: d599207ecde8c8dd194a05c5b4582ec0ccda398def397d26618a9526cd1242a91e3197c18bbea8d0b279d3b640dd3f8050dc23c6c1e11cddea82a1d681396b5e

data/Rakefile

@@ -0,0 +1,63 @@
+require 'rspec/core/rake_task'
+require 'jshintrb/jshinttask'
+require 'jasmine-headless-webkit'
+require 'sequel'
+require 'ballonizer'
+
+Jasmine::Headless::Task.new('jasmine') do |t|
+  t.colors = true
+  t.keep_on_error = true
+  t.jasmine_config = 'spec/javascripts/support/jasmine.yml'
+end
+
+RSpec::Core::RakeTask.new :spec
+
+Jshintrb::JshintTask.new :jshint do |t|
+  t.pattern = '{lib/ballonizer/*.js,spec/javascripts/*.js}'
+  t.options = {
+    bitwise: true,
+    camelcase: true,
+    es3: true,
+    immed: true,
+    indent: 4,
+    latedef: true,
+    strict: true,
+    curly: true,
+    eqeqeq: true,
+    eqnull: true,
+    immed: true,
+    noarg: true,
+    trailing: true,
+    unused: true,
+    jquery: true,
+    white: true
+  }
+end
+
+namespace :db do
+  desc 'Create/Reset the tables used by ballonizer in a database, the default' +
+       'database is the example (examples/ballonizer_app/test.db), but you' +
+       'can specify one with "rake db:reset[\'sqlite:///absolute/path/to/' +
+       'database_name.db\']" (check sequel support to another databases).'
+  task :reset, :database_path do | t, args |
+    database_path = args[:database_path] || 'sqlite://examples/ballonizer_app/test.db'
+    Sequel.connect(database_path) do | db |
+      # The order is important, can throw Foreign Key Constraint Violation otherwise
+      tables = [:ballonized_image_ballons,
+                :ballonized_image_versions,
+                :images,
+                :ballons]
+      db.drop_table?(*tables)
+      Ballonizer.create_tables(db)
+    end
+  end
+end
+
+desc 'Run an example of the lib use in http://localhost:9292'
+task :example do
+  sh 'rackup examples/ballonizer_app/config.ru'
+end
+
+desc 'Run the ruby and the javascript module specs and the jshint'
+task :default => [:spec, :jasmine, :jshint]
+

data/lib/ballonizer.rb

@@ -0,0 +1,401 @@
+require 'nokogiri'
+require 'addressable/uri'
+require 'sequel'
+require 'json'
+require 'htmlentities'
+require 'rack'
+
+# This gem provides mechanisms to allow ballons (or speech bubbles) to be
+# added/removed/edited over images of a HTML or XHTML document and to be
+# persisted. The edition of the ballons is possible by the javascript module
+# provided by this gem. The persistence is allowed by the Ballonizer class.
+# The Ballonizer class is basically a wrapper around the database used to
+# persist the ballons, and offer methods to process the requests made by
+# the client side (by a form created by the javascript module), and to modify
+# a (X)HTML document adding the ballons of the image over it.
+#
+# This class lacks a lot of features like: access to an abstraction of the
+# ballons, images and their relationship; control over users who edit the
+# ballons; access to the old versions of the ballon set of a image (who
+# are stored in the database, but only can be accessed directly by the
+# Sequel::Database object). It's a work in progress, be warned to use
+# carefully and motivated to contribute.
+#
+# The JavaScript library used to allow edition in the client side works
+# as follows: double click over the image add a ballon, double click over
+# a ballon allow edit the text, when the ballon lose the focus it returns
+# to the non-edition state, a ballon without text (or only with spaces) it's
+# automatically removed when lose focus, drag the ballon change its position
+# (restricted to image space), drag ballon by the right-bottom handle
+# resize the ballon (also restricted to image space). Any change in the ballons
+# make visible a button fixed in the right-top corner of the browser viewport.
+# Every time a ballons is changed (or added/removed) the json of a hidden
+# form is updated. The button submits this json by POST request to the url
+# configured by :form_handler_url setting.
+#
+# To the image be 'ballonized' it have to match the :img_to_ballonize_css_selector.
+# The 'ballonized' term here means: have the ballons added over the image in
+# ballonize_page.
+#
+# To use this class with your (rack isn't?) app you need to: create the
+# necessary tables in a Sequel::Database object with Ballonizer.create_tables;
+# create a ballonizer instance with the url where you gonna handle the ballon
+# change requests. Handle the ballon changes request in that url with
+# process_submit. Call instance.ballonize_page over the html documents who can
+# have the images to be ballonized. Include the jquery, jquery-json, jquery-ui,
+# and ballonizer javascript libraries in the page (provided by the gem); Include
+# the ui-lightness and ballonizer css in the page (provided by the gem).
+# Check if the image match the css selector :img_to_ballonize_css_selector.
+#
+# What's explained above is basically the example you can access with
+# 'rake example' and is in the examples/ballonizer_app/config.ru file. 
+# You can reset the database with 'rake db:reset' (and if you pass an argument
+# as 'rake db:reset[postgres://user:password@host:port/database_name]'
+# you can create the tables in the database already used by your app).
+# The tables names are: images, ballons, ballonized_image_versions,
+# ballonized_image_ballons.
+#
+class Ballonizer
+  
+  # The superclass of any error explicitly raised by the Ballonizer class.
+  class Error < ArgumentError; end
+  # The class used in exceptions related to a invalid value for a submit.
+  class SubmitError < Error; end
+
+  attr_accessor :db, :settings
+
+  # The default #settings
+  DEFAULT_SETTINGS = {
+    # The css selector used to define the elements to ballonize.
+    img_to_ballonize_css_selector: 'img.to_ballonize',
+    # A url to be used in the client-side action attribute of the form for
+    # ballon submition. The value will be used in the javascript snippet who
+    # initialize the ballonizer client javascript allowing ballon edition
+    # (and consequently creating the form).
+    form_handler_url: '#',
+    # Define if the javascript code who allow edition will be added to the page.
+    # (this don't refer to the jquery-* libs and the ballonizer.js only the
+    # snippet to execute when the page is ready)
+    add_js_for_edition: true
+  }.freeze.each { | _, v| v.freeze }
+
+  # Create a new Ballonizer object from a Sequel Database (with the expected
+  # tables, who can be created with Ballonizer.create_tables) and a optional
+  # hash of settings.
+  # @param db [Sequel::Database] A Sequel::Database with tables as described
+  # @param settings [Hash{Symbol => String}] A optional hash of settings. The
+  #   default value and explanation of each option are documented in the
+  #   DEFAULT_SETTINGS constant.
+  # @return [Ballonizer] A new ballonizer instance.
+  # @see Ballonizer.create_tables
+  def initialize(db, settings = {})
+    @db = db
+    @settings = DEFAULT_SETTINGS.merge(settings)
+  end
+
+  # Convenience method for process_submit_json, extract the json from the
+  # request, validate and pass to the method.
+  # @param env A env Rack hash.
+  # @return [Ballonizer] The self, to allow chaining.
+  # @raise [JSON::ParserError, Ballonizer::SubmitError] 
+  # @see process_submit_json
+  def process_submit(env, time = nil)
+    request = Rack::Request.new(env)
+    submit_json = request['ballonizer_data']
+    valid_submit_json?(submit_json, true)
+    process_submit_json(submit_json, time)
+  end
+
+  # Verify if the json is a valid output from the client counterpart.
+  # If the argument is valid untaint, otherwise taint (unless it's frozen).
+  # If the second parameter argument is true the method will throw
+  # exceptions when the input is invalid.
+  # @param submit_json [String] A JSON String.
+  # @param throw_exceptions [FalseClass,TrueClass] Define behaviour when the
+  #   input is invalid. If true throw exceptions, otherwise only return false.
+  #   Default value: false (don't throw exceptions).
+  # @return [true, false]
+  # @raise [JSON::ParserError, Ballonizer::SubmitError]
+  # @see valid_submit_hash?
+  # @note This is a instance method because, in the future, the validation
+  #   can depend of instance settings.
+  def valid_submit_json?(submit_json, throw_exceptions=false)
+    parsed_submit = JSON.parse(submit_json)
+    valid_submit_hash?(parsed_submit, true)
+    submit_json.untaint unless submit_json.frozen?
+    true
+  rescue JSON::ParserError, SubmitError => e
+    submit_json.taint unless submit_json.frozen?
+    raise e if throw_exceptions
+    false
+  end
+
+  # Act as #valid_submit_json, but over a already parsed json and don't
+  # (un)taint the hash.
+  # @param submit_hash [Hash] A parsed JSON.
+  # @return [true, false]
+  # @raise [Ballonizer::SubmitError]
+  # @see valid_submit_json?
+  # @note This is a instance method because, in the future, the validation
+  #   can depend of instance settings.
+  def valid_submit_hash?(submit_hash, throw_exceptions=false)
+    if submit_hash.empty?
+      fail SubmitError, "the submit request is empty"
+    end
+
+    submit_hash.each do | img_src, ballons |
+      unless img_src.is_a?(String)
+        # TODO: validate if valid URI?
+        # TODO: define img_src max lenght?
+        fail SubmitError, "the image src is a '#{img_src.class}' and not a String"
+      end
+      unless Addressable::URI.parse(img_src).absolute?
+        fail SubmitError, "the image src ('#{img_src.class}') is not an absolute URI"
+      end
+      unless ballons.is_a?(Array)
+        fail SubmitError, "the image with src '#{img_src}' is key of a " +
+                          "'#{ballons.class}' and not a Array"
+      end
+
+      ballons.each do | ballon |
+        unless ballon["text"].is_a?(String)
+          fail SubmitError, "the ballon text is a '#{ballon.class}' and not" +
+                            " a String"
+        end
+        if ballon["text"].empty?
+          fail SubmitError, "the ballon text is empty"
+        end
+        [:top, :left, :width, :height].each do | bound_name |
+          bound = ballon[bound_name.to_s]
+          unless bound.is_a?(Fixnum) || bound.is_a?(Float)
+            fail SubmitError, "the #{bound_name.to_s} (#{bound.to_s}) isn't" +
+                              " a Fixnum or Float (is a '#{bound.class.to_s}')"
+          end
+          unless bound >= 0 && bound <= 1
+            fail SubmitError, "the #{bound_name.to_s} (#{bound.to_s}) isn't"
+                              " between 0 and 1 (both inclusive)"
+          end
+        end
+
+        ballon_end = {}
+        ballon_end[:x] = ballon["top"] + ballon["height"]
+        ballon_end[:y] = ballon["left"] + ballon["width"]
+
+        [:x, :y].each do | axis |
+          if ballon_end[axis] > 1
+            fail SubmitError, "the ballon with text #{ballon["text"]} is trespassing" +
+                              " the #{ {x: "right side", y: "bottom"} [axis] }" +
+                              " of the image"
+          end
+        end
+      end
+    end
+
+    # if pass everything above return true
+    true
+  rescue SubmitError => exception
+    # HACK: "don't use exceptions for flow control", but this is the most DRY
+    # way...
+    if throw_exceptions then raise exception else false end
+  end
+
+  # Receive a untainted json (assume as validated by #valid_submit_json?)
+  # and add it to the database. 
+  # @param submit_json [String] A untainted JSON string. Validated with #valid_submit_json?.
+  # @param time [Time] A Time instance to be used in place of Time.now. Optional.
+  # @return [Ballonizer] The self, to allow chaining.
+  # @raise [SecurityError] If the input is tainted.
+  def process_submit_json(submit_json, time = nil)
+    fail SecurityError, 'the input is tainted' if submit_json.tainted?
+    process_submit_hash(JSON.parse(submit_json), time)
+  end
+
+  # Behave as process_submit_json except that takes a already parsed json (hash)
+  # and don't check if it's tainted.
+  # @param submit_hash [Hash] A JSON hash. Validate with #valid_submit_json?.
+  # @param time [Time] A Time instance to be used in place of Time.now. Optional.
+  # @return [Ballonizer] The self, to allow chaining.
+  def process_submit_hash(submit_hash, time = nil)
+    time = Time.now unless time
+    self.db.transaction do
+      images = self.db[:images]
+      db_ballons = self.db[:ballons]
+      ballonized_image_versions = self.db[:ballonized_image_versions]
+      ballonized_image_ballons = self.db[:ballonized_image_ballons]
+
+      submit_hash.each do | img_src, ballons |
+        img_src = Addressable::URI.parse(img_src).normalize.to_s
+        db_image = images.first({img_src: img_src})
+        image_id, version = nil, nil
+
+        if db_image
+          image_id = db_image[:id]
+          version = ballonized_image_versions.where({image_id: image_id})
+                                              .max(:version) + 1
+        else
+          image_id = images.insert({img_src: img_src})
+          version = 1
+        end
+
+        ballonized_image_versions.insert({
+          image_id: image_id,
+          version: version,
+          time: time
+        })
+        ballons.each do | ballon |
+          db_ballon = db_ballons.first(ballon)
+          ballon_id = db_ballon ? db_ballon[:id] : db_ballons.insert(ballon)
+          ballonized_image_ballons.insert({
+            image_id: image_id,
+            version: version,
+            ballon_id: ballon_id,
+          })
+        end
+      end
+    end
+  end
+
+  # Wrap each image to ballonize with a container, add its ballons to the
+  # container and add the js snippet for the edition initialization.
+  # @param page [String] The (X)HTML page.
+  # @param page_url [String] The url of the page to be ballonized, necessary
+  #   to make absolute the src attribute of img (if it's relative).
+  # @param settings [Hash{Symbol => String}] Optional. If not provided the
+  #   #settings will be used.
+  # @return [String] The page ballonized (new string).
+  def ballonize_page(page, page_url, settings = {})
+    settings = self.settings.merge(settings)
+
+    parsed_page = Workaround.parse_html_or_xhtml(page)
+    selector = settings[:img_to_ballonize_css_selector]
+    imgs = parsed_page.css(selector)
+
+    unless imgs.empty?
+      imgs.wrap('<div class="ballonizer_image_container" ></div>')
+
+      imgs.each do | img |
+        img_src = img['src']
+        absolute_normal_src = Addressable::URI.parse(page_url)
+                                              .join(img_src)
+                                              .normalize.to_s
+        ballons = last_ballon_set_of_image(absolute_normal_src)
+        ballons.each do | ballon |
+          img.add_previous_sibling(self.class.create_ballon_node(ballon))
+        end
+      end
+      
+      if settings[:add_js_for_edition]
+        parsed_page.at_css('head').children.last
+                   .add_next_sibling(self.js_load_snippet)
+      end
+    end
+    
+    parsed_page.to_s
+  end
+
+  # @api private Don't use this method. It is for internal use only.
+  def self.create_ballon_node(ballon_data)
+    text = HTMLEntities.new.encode(ballon_data[:text])
+
+    style = ''
+    [:top, :left, :width, :height].each do | sym |
+      # transform ratio [0,1] to percent [0, 100]
+      style = style + "#{sym}: #{(ballon_data[sym] * 100)}%;"
+    end
+
+    "<p class='ballonizer_ballon' style='#{style}'>#{text}</p>"
+  end
+
+  # @api private
+  # Don't use this method. It is for internal use only.
+  # @note This method don't make distinction between a image in the database
+  #   without any ballons (removed in the last version, by example) or a image
+  #   who isn't in the database (both return a empty array).
+  def last_ballon_set_of_image(img_src)
+    db_image = self.db[:images].first({img_src: img_src})
+    if db_image
+      image_id = db_image[:id]
+      version = self.db[:ballonized_image_versions].where({image_id: image_id})
+                                                   .max(:version)
+      self.db[:ballonized_image_ballons]
+          .join(:ballons, { ballonized_image_ballons__version: version,
+                            ballonized_image_ballons__image_id: image_id,
+                            ballonized_image_ballons__ballon_id: :ballons__id
+                          }).select(:text, :top, :left, :width, :height).all
+    else
+      []
+    end
+  end
+
+  # Return a String with the snippet added to the pages to allow edition in them.
+  # @return [String] The added snippet. Already with the <script/> tag around it.
+  def js_load_snippet
+    <<-end
+      <script type="text/javascript">
+        $(document).ready(function() {
+          Ballonizer('#{self.settings[:form_handler_url]}',
+                     '.ballonizer_image_container',
+                     $('body'));
+        })
+      </script>
+    end
+  end
+
+  # Executes the create_table operations over the Sequel::Database argument.
+  # @param db [Sequel::Database] The database where create the tables.
+  # @return [void]
+  def self.create_tables(db)
+    db.create_table(:images) do
+      primary_key :id
+      String :img_src, :size => 255, :unique => true, :allow_null => false
+    end
+    db.create_table(:ballons) do
+      primary_key :id
+
+      String :text, :size => 255, :allow_null => false
+      Float :top, :allow_null => false
+      Float :left, :allow_null => false
+      Float :width, :allow_null => false
+      Float :height, :allow_null => false
+    end
+    db.create_table(:ballonized_image_versions) do
+      Integer :version
+      foreign_key :image_id, :images
+      DateTime :time, :allow_null => false
+      primary_key [:version, :image_id]
+    end
+    db.create_table(:ballonized_image_ballons) do
+      Integer :version
+      foreign_key :image_id, :images
+      foreign_key :ballon_id, :ballons
+      foreign_key [:version, :image_id], :ballonized_image_versions
+    end
+  end
+
+  # @api private Don't use the methods of this module. They are for internal use only.
+  module Workaround
+    def self.parse_html_or_xhtml(doc)
+      # If you parse XHTML as HTML with Nokogiri and use to_s after the markup can be messed up
+      # 
+      # Example:     <meta name="description" content="not important" />
+      #   becomes    <meta name="description" content="not important" >
+      # To avoid this we parse a document who is XML valid as XML, and, otherwise as HTML
+      parsed_doc = nil
+      begin
+        # this also isn't a great way to do this
+        # the Nokogiri don't have exception classes, this way any StandardError will be silenced
+        options = Nokogiri::XML::ParseOptions::DEFAULT_XML &
+                    Nokogiri::XML::ParseOptions::STRICT &
+                    Nokogiri::XML::ParseOptions::NONET
+        parsed_doc = Nokogiri::XML::Document.parse(doc, nil, nil, options)
+      rescue
+        parsed_doc = Nokogiri::HTML(doc)
+      end
+
+      parsed_doc
+    end
+  end
+
+  private_constant :Workaround
+end
+

data/spec/ballonizer_spec.rb

@@ -0,0 +1,539 @@
+require 'ballonizer'
+require 'rspec-html-matchers'
+# Avoid to use equivalent-xml, the specs break with cosmetic changes this way
+require 'equivalent-xml'
+require 'stringio'
+
+# make the changes in the BD restricted to the example
+RSpec.configure do |c|
+  c.around(:each) do |example|
+    DB.transaction(:rollback=>:always){example.run}
+  end
+end
+
+describe Ballonizer do
+
+  DB = Sequel.sqlite
+
+  def self.populate_ballonizer_tables_with_test_data(db, time)
+    db[:images].insert({img_src: 'http://comic-translation.com/tr/pt-BR/a_comic/imgs/1.jpg'})
+    db[:images].insert({img_src: 'http://comic-translation.com/tr/pt-BR/a_comic/imgs/2.jpg'})
+    db[:images].insert({img_src: 'http://comic-translation.com/tr/pt-BR/a_comic/imgs/3.jpg'})
+
+    db[:ballons].insert({ text: 'first ballon of first image',
+                          top: 0, left: 0, width: 0.5, height: 0.5 })
+    db[:ballons].insert({ text: 'second ballon of first image',
+                          top: 0.5, left: 0.5, width: 0.5, height: 0.5 })
+    db[:ballons].insert({ text: 'first ballon of second image',
+                          top: 0, left: 0, width: 0.5, height: 0.5 })
+    db[:ballons].insert({ text: 'second ballon of second image',
+                          top: 0.5, left: 0.5, width: 0.5, height: 0.5 })
+    db[:ballons].insert({ text: 'first ballon of third image',
+                          top: 0, left: 0, width: 0.5, height: 0.5 })
+    db[:ballons].insert({ text: 'second ballon of third image',
+                          top: 0.5, left: 0.5, width: 0.5, height: 0.5 })
+
+    # both ballons added in the first version
+    db[:ballonized_image_versions].insert({image_id: 1, version: 1, time: time})
+    db[:ballonized_image_ballons].insert({image_id: 1, version: 1, ballon_id: 1})
+    db[:ballonized_image_ballons].insert({image_id: 1, version: 1, ballon_id: 2})
+
+    # second ballon added in the second version
+    db[:ballonized_image_versions].insert({image_id: 2, version: 1, time: time})
+    db[:ballonized_image_ballons].insert({image_id: 2, version: 1, ballon_id: 3})
+    db[:ballonized_image_versions].insert({image_id: 2, version: 2, time: time})
+    db[:ballonized_image_ballons].insert({image_id: 2, version: 2, ballon_id: 3})
+    db[:ballonized_image_ballons].insert({image_id: 2, version: 2, ballon_id: 4})
+
+    # both added in first version, but second removed in the second version
+    db[:ballonized_image_versions].insert({image_id: 3, version: 1, time: time})
+    db[:ballonized_image_ballons].insert({image_id: 3, version: 1, ballon_id: 5})
+    db[:ballonized_image_ballons].insert({image_id: 3, version: 1, ballon_id: 6})
+    db[:ballonized_image_versions].insert({image_id: 3, version: 2, time: time})
+    db[:ballonized_image_ballons].insert({image_id: 3, version: 2, ballon_id: 5})
+  end
+
+  Ballonizer.create_tables(DB)
+  self.populate_ballonizer_tables_with_test_data(DB, Time.at(0))
+
+  def deep_copy(v)
+    JSON.parse(JSON.generate(v))
+  end
+
+  # Definitions ending with '_example' are to be cloned and defined in a
+  # context without the sufix. Definitions without the sufix are used in the
+  # specs and may require the definition of some without '_example' counterparts.
+  let (:ballonizer_new_args_example) do
+    [DB, {}]
+  end
+  # TODO: This isn't a valid Rack env, to turn it in a valid env will be
+  # necessary to add all obrigatory 'rack.' variables described in:
+  # http://rack.rubyforge.org/doc/SPEC.html
+  # (the missing are the hijack related and the .errors)
+  let (:env_example) do
+    form_data = StringIO.new(Addressable::URI.form_encode({
+        ballonizer_data: JSON.generate(submit_hash)
+    }))
+    { 'HTTP_HOST' => 'proxysite.net',
+      'SCRIPT_NAME' => '',
+      'PATH_INFO' => '/pt_BR-ballon_translate/comic/',
+      'QUERY_STRING' => '',
+      'SERVER_NAME' => 'proxysite.net',
+      'SERVER_PORT' => '80',
+      'REQUEST_METHOD' => 'POST',
+      'HTTP_VERSION' => 'HTTP/1.1',
+      'CONTENT_LENGTH' => form_data.size.to_s,
+      'CONTENT_TYPE' => 'application/x-www-form-urlencoded',
+      'rack.url_scheme' => 'http',
+      'rack.input' => form_data,
+      'rack.version' => [1, 0],
+      'rack.multithread' => false,
+      'rack.multiprocess' => false,
+      'rack.run_once' => false
+    }
+  end
+  let (:original_page_example) do
+    doc = <<-END
+      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+      <html xmlns="http://www.w3.org/1999/xhtml">
+        <head>
+          <title>A title</title>
+          <meta http-equiv="content-type" content="application/xhtml+xml; charset=UTF-8" />
+        </head>
+        <body>
+        </body>
+      </html>
+    END
+
+    Nokogiri::XML::Document.parse(doc)
+  end
+  let (:page_url_example) do
+    'http://comic-translation.com/tr/pt-BR/a_comic/'
+  end
+  let (:settings_example) do
+    {}
+  end
+  let (:submit_json_example) do
+    '{"http://imgs.xkcd.com/comics/cells.png":[{"left":0,"top":0,"width":1,"height":0.23837209302325582,"text":"When you see a claim that a common drug or vitamin \"kills cancer cells in a petri dish\", keep in mind:"},{"left":0.0963302752293578,"top":0.9273255813953488,"width":0.7798165137614679,"height":0.055232558139534885,"text":"So does a handgun."}]}'
+  end
+  let (:submit_hash_example) do
+    JSON.parse(submit_json_example)
+  end
+
+  # definitions to be overriden in specific contexts (by doing a clone of the
+  # '_example' counterpart and changing what is needed)
+  let (:ballonizer_new_args) { ballonizer_new_args_example }
+  let (:env)                 { env_example }
+  let (:original_page)       { original_page_example.to_s }
+  let (:page_url)            { page_url_example }
+  let (:settings)            { settings_example }
+  let (:submit_json)         { submit_json_example }
+  let (:submit_hash)         { submit_hash_example }
+
+  # Definition who need others (no *_example)
+  let (:instance) { described_class.new(*ballonizer_new_args) }
+  let (:ballonized_page) do
+    instance.ballonize_page(original_page, page_url, settings)
+  end
+
+  # TODO: verify if the style property has the correct values
+  describe '#ballonize_page' do
+    subject { ballonized_page }
+
+    context 'when the page has no img elements to ballonize' do
+      it "don't make changes in the page" do
+        should be_equivalent_to(original_page)
+      end
+    end
+    context 'when the page has img elements to ballonize' do
+      context 'and one of them have .to_ballonize class' do
+        let (:original_page) do
+          page_with_images = original_page_example.clone
+          img1 = "<img alt='A test image' class='other_class to_ballonize' src='imgs/1.jpg' />"
+          img2 = "<img alt='A second test image' class='yet_another_class' src='imgs/2.jpg' />"
+          page_with_images.at_css('body') << img1 << img2
+          page_with_images.to_s
+        end
+        it 'add a container around the img' do
+          should have_tag('div', :with => { class: 'ballonizer_image_container' }) do
+            with_tag('img', :with => { alt: 'A test image' })
+          end
+        end
+        context 'and it have ballons in the database' do
+          it 'add the ballons inside the container' do
+            # the parentheses of the 'should' are necessary, otherwise the
+            # conditions inside the block are silently not tested
+            should(have_tag('div', :with => { class: 'ballonizer_image_container' }) do
+              with_tag("img[alt='A test image']")
+              with_tag('p', { text: 'first ballon of first image',
+                              with: { class: 'ballonizer_ballon' }})
+              with_tag('p', { text: 'second ballon of first image',
+                              with: { class: 'ballonizer_ballon'}})
+            end)
+          end
+        end
+      end
+      context 'and more than one of them is to be ballonized' do
+        let (:original_page) do
+          page_with_images = original_page_example.clone
+          # the first image in the db is used in the other test, don't need to
+          # be reused
+          img2 = "<img alt='the second test image' class='to_ballonize' src='imgs/2.jpg' />"
+          img3 = "<img alt='the third test image' class='yet_another_class to_ballonize' src='imgs/3.jpg' />"
+          img4 = "<img alt='the fourth test image' class='an unimportant class' src='imgs/4.jpg' />"
+          page_with_images.at_css('body') << img2 << img3 << img4
+          page_with_images.to_s
+        end
+        it 'add a container around the imgs' do
+          # TODO: DRY this test
+          should(have_tag('div', :with => { class: 'ballonizer_image_container' }) do
+            with_tag('img', :with => { alt: 'the second test image' })
+          end)
+          should(have_tag('div', :with => { class: 'ballonizer_image_container' }) do
+            with_tag('img', :with => { alt: 'the third test image' })
+          end)
+        end
+        context 'and they have ballons in the database' do
+          it 'add the ballons inside the containers' do
+            # TODO: break this spec in smaller parts, this specificate more
+            # than one thing
+            should(have_tag('div', :with => { class: 'ballonizer_image_container' }) do
+              # the second image have two versions, the second ballon is added
+              # in the second version, so here we verify if the ballonize_page
+              # recover the ballons of the last version
+              with_tag('img', :with => { alt: 'the second test image' })
+              with_tag('p', { text: 'first ballon of second image',
+                              with: { class: 'ballonizer_ballon' }})
+              with_tag('p', { text: 'second ballon of second image',
+                              with: { class: 'ballonizer_ballon' }})
+            end)
+            should(have_tag('div', :with => { class: 'ballonizer_image_container' }) do
+              # the third image have two versions, the second ballon is removed
+              # in the second version, so here we verify if the ballonize_page
+              # do not use a ballon of an old version in the image
+              with_tag('img', :with => { alt: 'the third test image' })
+              with_tag('p', { text: 'first ballon of third image',
+                              with: { class: 'ballonizer_ballon' }})
+              without_tag('p', { text: 'second ballon of third image',
+                                 with: { class: 'ballonizer_ballon' }})
+            end)
+          end
+        end
+      end
+      context 'and no one of them have the .to_ballonize class' do
+        let (:original_page) do
+          page_with_images = original_page_example.clone
+          page_with_images.at_css('body')
+                          .add_child "<img alt='A test image' src='/a/path/to/the/image.jpg' >"
+          page_with_images.to_s
+        end
+        it "don't add a container around the imgs" do
+          should_not have_tag('div', :with => {
+            class: 'ballonizer_image_container'
+          })
+        end
+        it "don't add the links of the required javascript and css" do
+          # the callback will be called only if a image was ballonized?
+          should_not have_tag('link')
+        end
+      end
+    end
+  end
+
+  describe '#valid_submit_json?' do
+    subject { instance.valid_submit_json? submit_json }
+
+    shared_examples 'common behavior for invalid input' do
+
+      it { should be_false }
+
+      it 'taint the input' do 
+        instance.valid_submit_json? submit_json
+        expect(submit_json.tainted?).to be_true
+      end
+
+      context 'but frozen' do
+        let (:frozen_submit_json) { deep_copy(submit_json).freeze }
+        let (:method_call) do
+          lambda { instance.valid_submit_json? submit_json }
+        end
+
+        it "shouldn't taint the input" do
+          # an attempt to taint a frozen object will raise a RuntimeError
+          expect(method_call).to_not raise_error
+        end
+      end
+      context 'when the second argument is true' do
+        let (:method_call) do
+          lambda { instance.valid_submit_json?(submit_json, true) }
+        end
+
+        # necessary define the 'exception_type' let variable in the context
+        # who will use this shared_examples
+        it { expect(method_call).to raise_error(exception_type) }
+      end
+    end
+
+    # NOTE: All cases who throw a Ballonizer::SubmitError are verified
+    # in the #valid_submit_hash? (who is used by the #valid_submit_json?)
+    context 'with invalid input' do
+      context '(a malformed json)' do
+        let (:submit_json) { 'not a valid json' }
+        let (:exception_type) { JSON::ParserError }
+
+        include_examples 'common behavior for invalid input'
+      end
+      context '(invalid submit data)' do
+        let (:submit_json) { '{}' }
+        let (:exception_type) { described_class::SubmitError }
+
+        include_examples 'common behavior for invalid input'
+      end
+    end
+
+    context 'with valid input' do
+      it { should be_true }
+
+      it 'untaint the input' do 
+        instance.valid_submit_json? submit_json.taint
+        expect(submit_json.tainted?).to be_false
+      end
+
+      context 'but frozen' do
+        let (:frozen_tainted_submit_json) do
+          deep_copy(submit_json).taint.freeze
+        end
+        let (:method_call) do
+          lambda { instance.valid_submit_json? submit_json }
+        end
+
+        it "shouldn't untaint the input" do
+          # an attempt to taint a frozen object will raise a RuntimeError
+          expect(method_call).to_not raise_error
+        end
+      end
+      context 'when the second argument is true' do
+        let (:method_call) do
+          lambda { instance.valid_submit_json?(submit_json, true) }
+        end
+
+        it { expect(method_call).to_not raise_error }
+      end
+    end
+  end
+
+  # TODO: validate ballon text and url size < 255; if the url is a url;
+  #       extra fields in the hash?
+  describe '#valid_submit_hash?' do
+    subject { instance.valid_submit_hash? submit_hash }
+
+    # To be used in all contexts where the input is invalid
+    shared_examples 'and the second argument is true' do
+      # If this context isn't added the message don't appear in the output
+      # of the 'rspec -fd' and the lets and subjects are merged (what can
+      # create some nasty bugs)
+      context 'and the second argument is true' do
+        let (:method_call) do
+          lambda { instance.valid_submit_hash?(submit_hash, true) }
+        end
+
+        it { expect(method_call).to raise_error(described_class::SubmitError) }
+      end
+    end
+
+    context "when the bounds aren't numbers between 0 and 1" do
+      let (:submit_hash) do
+        deep_copy(submit_hash_example)[submit_hash_example.keys.first]
+                                      .first.update({ top: 10 })
+      end
+
+      it { should be_false }
+
+      include_examples 'and the second argument is true'
+    end
+
+    context "when the text isn't a non-empty String" do
+      let (:submit_hash) do
+        deep_copy(submit_hash_example)[submit_hash_example.keys.first]
+                                      .first.update({ text: "" })
+      end
+
+      it { should be_false }
+
+      include_examples 'and the second argument is true'
+    end
+
+    [:x, :y].each do | axis |
+
+      position, size = { x: ["left", "top"], y: ["top", "height"] }[axis]
+
+      context "when the #{position} plus #{size} is greater than one" do
+        let (:submit_hash) do
+          h = deep_copy(submit_hash_example)
+          first_ballon = h[h.keys.first].first
+          first_ballon[position] = 0.75
+          first_ballon[size] = 0.5
+          h
+        end
+
+        it { should be_false }
+
+        include_examples 'and the second argument is true'
+      end
+    end
+
+    context 'when the submit contain a image without ballons' do
+      let (:submit_hash) do
+        { submit_hash_example.keys.first => [] }
+      end
+
+      it { should be_true }
+    end
+    context 'when the hash is valid' do
+      it { should be_true }
+
+      context 'and the second argument is true' do
+        let (:method_call) do
+          lambda { instance.valid_submit_hash?(submit_hash, true) }
+        end
+
+        it { expect(method_call).to_not raise_error(described_class::SubmitError) }
+        it { expect(method_call.call).to be_true }
+      end
+    end
+  end
+
+  describe '#process_submit_hash' do
+    # TODO: Add context "when the submit refer to two or more images?"
+    context 'when its the first submit of a image' do
+      let(:submit_hash) do
+        # the keys are String because hashs parsed from JSON are this way
+        { 'http://comic-translation.com/tr/pt-BR/a_comic/imgs/4.jpg' => [
+          { 'text' => 'the first ballon of the fourth image',
+            'left' => 0, 'top' => 0, 'width' => 0.5, 'height' => 0.5 },
+          { 'text' => 'the second ballon of the fourth image',
+            'left' => 0.5, 'top' => 0.5, 'width' => 0.5, 'height' => 0.5 },
+        ]}
+      end
+
+      let (:original_page) do
+        page_with_images = original_page_example.clone
+        img = "<img alt='A fourth test image' class='to_ballonize' src='imgs/4.jpg' />"
+        page_with_images.at_css('body') << img
+        page_with_images.to_s
+      end
+
+      it 'the ballonize_page add the ballons to the image' do
+        instance.process_submit_hash(submit_hash, Time.at(0))
+        expect(ballonized_page).to have_tag('p',
+          { text: 'the first ballon of the fourth image',
+            with: { class: 'ballonizer_ballon' } }
+        )
+        expect(ballonized_page).to have_tag('p',
+          { text: 'the second ballon of the fourth image',
+            with: { class: 'ballonizer_ballon' } }
+        )
+      end
+    end
+    context 'when the submit refer to a image already with ballons' do
+      let(:submit_hash) do
+        # the keys are String because hashs parsed from JSON are this way
+        { 'http://comic-translation.com/tr/pt-BR/a_comic/imgs/1.jpg' => [
+          # the "(... version)" added to avoid reutilize a ballon (what is
+          # not the objective of the test here)
+          { 'text' => 'the first ballon (version 2) of the first image',
+            'left' => 0, 'top' => 0, 'width' => 0.5, 'height' => 0.5 },
+          { 'text' => 'the second ballon (version 2) of the first image',
+            'left' => 0.5, 'top' => 0.5, 'width' => 0.5, 'height' => 0.5 },
+        ]}
+      end
+
+      let (:original_page) do
+        page_with_images = original_page_example.clone
+        img = "<img alt='A test image' class='to_ballonize' src='imgs/1.jpg' />"
+        page_with_images.at_css('body') << img
+        page_with_images.to_s
+      end
+
+      it 'the ballonize_page use the new ballons' do
+        instance.process_submit_hash(submit_hash, Time.at(0))
+        expect(ballonized_page).to have_tag('p',
+          { text: 'the first ballon (version 2) of the first image',
+            with: { class: 'ballonizer_ballon' } }
+        )
+        expect(ballonized_page).to have_tag('p',
+          { text: 'the second ballon (version 2) of the first image',
+            with: { class: 'ballonizer_ballon' } }
+        )
+      end
+    end
+  end
+
+  describe '#process_submit_json' do
+    # As process_submit_json use process_submit_hash (it's only a convenience
+    # method) we don't test the rest of its behaviour (who is already covered
+    # in #process_submit_hash)
+    context 'when the input is tainted' do
+      let (:submit_json) do
+        submit_hash_example.clone.taint
+      end
+
+      it do
+        expect {
+          instance.process_submit_json(submit_json)
+        }.to raise_error(SecurityError)
+      end
+    end
+  end
+
+  describe '#process_submit' do
+    
+    # As process_submit use the #valid_submit_json? and #process_submit_hash
+    # we only make the tests here for example and its not the ideia cover the
+    # cases already covered in the specs of the two methods
+    context 'when the input is invalid' do
+      # The submit hash is used to define the env_example
+      # (and in consequence the env)
+      let (:submit_hash) do
+        # this input is invalid because the text field can't be empty
+        { 'http://comic-translation.com/tr/pt-BR/a_comic/imgs/4.jpg' => [
+          { 'text' => '', 'left' => 0, 'top' => 0, 'width' => 0.5, 'height' => 0.5 }
+        ]}
+      end
+      
+      it do
+        expect { instance.process_submit(env) }.to raise_error(
+          described_class::SubmitError
+        )
+      end
+    end
+
+    context 'when the input is valid' do
+      # this code is almost the same as the used in #process_submit_hash,
+      # think in some way to DRY up this
+      let(:submit_hash) do
+        { 'http://comic-translation.com/tr/pt-BR/a_comic/imgs/4.jpg' => [
+          { 'text' => 'the first ballon of the fourth image',
+            'left' => 0, 'top' => 0, 'width' => 0.5, 'height' => 0.5 }
+        ]}
+      end
+      
+      let (:original_page) do
+        page_with_images = original_page_example.clone
+        img = "<img alt='A fourth test image' class='to_ballonize' src='imgs/4.jpg' />"
+        page_with_images.at_css('body') << img
+        page_with_images.to_s
+      end
+
+      it 'the ballonize_page add the ballons to the image' do
+        instance.process_submit(env)
+        expect(ballonized_page).to have_tag('p',
+          { text: 'the first ballon of the fourth image',
+            with: { class: 'ballonizer_ballon' } }
+        )
+      end
+    end
+  end
+end
+

metadata

@@ -0,0 +1,245 @@
+--- !ruby/object:Gem::Specification
+name: ballonizer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Henrique Becker
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.48'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.48'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: htmlentities
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.3'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: equivalent-xml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: jshintrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.4
+- !ruby/object:Gem::Dependency
+  name: jasmine-headless-webkit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.4
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+- !ruby/object:Gem::Dependency
+  name: rspec-html-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A ruby+javascript library to allow add and edit speech bubbles over images
+  in a (X)HTML page and persist the ballons.
+email: henriquebecker91@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/ballonizer.rb
+- spec/ballonizer_spec.rb
+- Rakefile
+homepage: http://rubygems.org/gems/ballonize
+licenses:
+- Public domain
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.2
+signing_key: 
+specification_version: 4
+summary: 'ballonize: to allow colaborative edition of ballons in images'
+test_files:
+- spec/ballonizer_spec.rb
+has_rdoc: true