ballonizer 0.1.0 → 0.2.0

data/lib/ballonizer.rb

@@ -4,6 +4,7 @@ require 'sequel'
 require 'json'
 require 'htmlentities'
 require 'rack'
+require 'sprockets'
 
 # 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
@@ -16,7 +17,7 @@ require 'rack'
 #
 # 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
+# ballons; access to the old versions of the ballon set of a image (that
 # 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.
@@ -40,12 +41,10 @@ require 'rack'
 # 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.
+# change requests and where provide the assets. Handle the ballon changes request
+# in that url with process_submit. Call instance.ballonize_page over the html
+# documents that can have the images to be ballonized. 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. 
@@ -64,23 +63,93 @@ class Ballonizer
 
   attr_accessor :db, :settings
 
+  # @api private Don't use the methods of this module. They are for internal use only.
+  module Workaround
+    def self.join_uris(base, relative)
+      base = base.end_with?('/') ? base : base + '/'
+      Addressable::URI.parse(base).join(relative).to_s
+    end
+
+    def self.deep_freeze(e)
+      e.each { | v | deep_freeze(v) } if e.is_a?(Enumerable)
+      e.freeze
+    end
+
+    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 that 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
+
+  # The load paths of assets inside the gem and the files inside each path,
+  # in the order they need to be included (the files of the first path need
+  # to be included before the files in the second path, and the files in the
+  # same path need to be included in the specified order).
+  # Give preference to the asset(s)_* and *_html_links methods over this constant.
+  ASSETS = Workaround.deep_freeze([
+    ['vendor/assets/javascripts', [
+      'jquery-2.0.1.js',
+      'jquery.json-2.4.min.js',
+      'jquery-ui-1.10.3.custom.min.js']],
+    ['lib/assets/javascripts', [
+      'ballonizer.js']],
+    ['vendor/assets/stylesheets', [
+      'ui-lightness/jquery-ui-1.10.3.custom.min.css']],
+    ['lib/assets/stylesheets', [
+      'ballonizer.css']]
+  ])
+
   # 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
+    # ballon submition. The value will be used in the javascript snippet that
     # 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.
+    # Define if the javascript code that 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
+    add_js_for_edition: true,
+    # A path string to prefix each href of the css stylesheet links generated
+    # by the js_libs_html_links, and, possibly, added by the ballonize_page
+    # object. Example: if you use Ballonizer.assets_app mapped to '/assets'
+    # then use '/assets' here. This is used with the :add_required_css setting.
+    css_asset_path_for_link: nil,
+    # If the ballonize_page method will add or not the html generated by
+    # #css_html_links (require the :css_asset_path_for_link to be defined).
+    add_required_css: false,
+    # A path string to prefix each js source src generated by the
+    # object. Example: if you use Ballonizer.assets_app mapped to '/assets'
+    # then use '/assets' here. This is used with the
+    # :add_required_js_libs_for_edition setting.
+    js_asset_path_for_link: nil,
+    # If the ballonize_page method will add or not the html generated by
+    # #js_libs_html_links (require the :js_asset_path_for_link to be defined).
+    add_required_js_libs_for_edition: false
   }.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
+  # tables, that 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
@@ -256,7 +325,9 @@ class Ballonizer
   end
 
   # Wrap each image to ballonize with a container, add its ballons to the
-  # container and add the js snippet for the edition initialization.
+  # container and, possibly, add the css and js libs and snippet for the
+  # edition initialization. Don't make any change if the page has no images
+  # to ballonize.
   # @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).
@@ -284,9 +355,15 @@ class Ballonizer
         end
       end
       
+      head = parsed_page.at_css('head')
+      if settings[:add_required_css]
+        head.children.last.add_next_sibling(self.css_html_links)
+      end
+      if settings[:add_required_js_libs_for_edition]
+        head.children.last.add_next_sibling(self.js_libs_html_links)
+      end
       if settings[:add_js_for_edition]
-        parsed_page.at_css('head').children.last
-                   .add_next_sibling(self.js_load_snippet)
+        head.children.last.add_next_sibling(self.js_load_snippet)
       end
     end
     
@@ -310,7 +387,7 @@ class Ballonizer
   # 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).
+  #   that 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
@@ -372,30 +449,118 @@ class Ballonizer
     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
+  # The (X)HTML fragment with the link tags that are added to the page by
+  # ballonize_page if the :add_required_css setting is true (the default
+  # is false). If the :css_asset_path_for_link isn't set (what is the
+  # default) this method return nil.
+  # @return [String,NilClass] A frozen string.
+  def css_html_links
+    return nil unless settings[:css_asset_path_for_link]
+    return @css_html_links if @css_html_links
+
+    link_template = '<link rel="stylesheet" type="text/css" href="PATH" />'
+    css_paths = self.class.asset_logical_paths.select do | p |
+      /^.+\.css$/.match(p)
+    end
 
-      parsed_doc
+    links = css_paths.map do | p |
+      p = Workaround.join_uris(settings[:css_asset_path_for_link], p)
+      link_template.sub('PATH', p)
     end
+
+    @css_html_links = links.join('').freeze
   end
 
-  private_constant :Workaround
+  # The (X)HTML fragment with the script tags that are added to the page by
+  # ballonize_page if the :add_required_js_libs_for_edition setting is true
+  # (the default is false). If the :js_asset_path_for_link isn't set (what
+  # is the default) this method return nil.
+  # @return [String,NilClass] A frozen string.
+  def js_libs_html_links
+    return nil unless settings[:js_asset_path_for_link]
+    return @js_libs_html_links if @js_libs_html_links
+
+    link_template = '<script type="text/javascript" src="PATH" />'
+    js_libs_paths = self.class.asset_logical_paths.select do | p |
+      /^.+\.js$/.match(p)
+    end
+
+    links = js_libs_paths.map do | p |
+      p = Workaround.join_uris(settings[:js_asset_path_for_link], p)
+      link_template.sub('PATH', p)
+    end
+
+    @js_libs_html_links = links.join('').freeze
+  end
+
+  # List of paths (relative to the gem root directory) to the directories with
+  # the css and js provided by the gem.
+  # @return [Array<String>] A frozen array of frozen strings.
+  def self.asset_load_paths
+    return @asset_load_paths if @asset_load_paths
+
+    absolute_lib_dir = File.dirname(File.realpath(__FILE__))
+    ballonizer_gem_root_dir = File.expand_path('../', absolute_lib_dir)
+
+    @asset_load_paths = ASSETS.map do | load_path_and_files |
+      load_path = load_path_and_files.first
+      File.expand_path(load_path, ballonizer_gem_root_dir)
+    end
+
+    @asset_load_paths.flatten!
+    @asset_load_paths.freeze
+  end
+
+  # List of logical paths to the css and js assets. The assets_app respond to
+  # any requisition to one of these paths.
+  # @return [Array<String>] A frozen array of frozen strings.
+  def self.asset_logical_paths
+    return @asset_logical_paths if @asset_logical_paths
+
+    @asset_logical_paths = ASSETS.map do | load_path_and_files |
+      load_path_and_files.last
+    end
+
+    @asset_logical_paths.flatten!
+    @asset_logical_paths.freeze
+  end
+
+  # List of absolute filepaths to the css and js files needed by the client
+  # counterpart and provided by the gem. To all who not want to use assets_app.
+  # @return [Array<String>] A frozen array of frozen strings.
+  # @see Ballonizer.assets_app
+  def self.asset_absolute_paths
+    return @asset_absolute_paths if @asset_absolute_paths
+
+    absolute_lib_dir = File.dirname(File.realpath(__FILE__))
+    ballonizer_gem_root_dir = File.expand_path('../', absolute_lib_dir)
+
+    @asset_absolute_paths = ASSETS.map do | load_path_and_files |
+      relative_load_path, filepaths = *load_path_and_files
+      absolute_load_path = File.expand_path(relative_load_path, ballonizer_gem_root_dir)
+
+      filepaths.map do | filepath  |
+        File.expand_path(filepath, absolute_load_path)
+      end
+    end
+
+    @asset_absolute_paths.flatten!
+    @asset_absolute_paths.freeze
+  end
+
+  # A Rack app that provide the gem css and js. Each call to this method return
+  # a new object (clone). The Sprockets::Environment isn't frozen because it
+  # can't be used with 'run' in a rack app if frozen.
+  # @return [Sprockets::Environment] 
+  # @see Ballonizer.assets_app
+  def self.assets_app
+    # dont freeze because run don't work in a frozen sprockets env
+    return @assets_app.clone if @assets_app
+    @assets_app = Sprockets::Environment.new
+    asset_load_paths.each do | load_path |
+      @assets_app.prepend_path load_path
+    end 
+    @assets_app.clone
+  end 
 end
 

data/spec/ballonizer_spec.rb

@@ -3,6 +3,7 @@ require 'rspec-html-matchers'
 # Avoid to use equivalent-xml, the specs break with cosmetic changes this way
 require 'equivalent-xml'
 require 'stringio'
+require 'rexml/document'
 
 # make the changes in the BD restricted to the example
 RSpec.configure do |c|
@@ -11,6 +12,26 @@ RSpec.configure do |c|
   end
 end
 
+RSpec::Matchers.define :exist_in_filesystem do
+  match do | actual |
+    if actual.respond_to? :all?
+      actual.all? { | filename | File.exist?(filename) }
+    else
+      File.exist? actual
+    end
+  end
+  failure_message_for_should do | actual |
+    if actual.respond_to? :all?
+      "expected #{actual} to be a list of absolute filepaths for existing files or directories"
+    else
+      "expected #{actual} to be a absolute filepath for an existing file or directory"
+    end
+  end
+  description do
+    "be a list of absolute paths for existing files or directories"
+  end
+end
+
 describe Ballonizer do
 
   DB = Sequel.sqlite
@@ -63,8 +84,11 @@ describe Ballonizer do
   # 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_settings_example) do
+    {}
+  end
   let (:ballonizer_new_args_example) do
-    [DB, {}]
+    [DB, ballonizer_settings]
   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:
@@ -123,6 +147,7 @@ describe Ballonizer do
 
   # definitions to be overriden in specific contexts (by doing a clone of the
   # '_example' counterpart and changing what is needed)
+  let (:ballonizer_settings) { ballonizer_settings_example }
   let (:ballonizer_new_args) { ballonizer_new_args_example }
   let (:env)                 { env_example }
   let (:original_page)       { original_page_example.to_s }
@@ -173,6 +198,35 @@ describe Ballonizer do
             end)
           end
         end
+        # TODO: create this specs
+        context 'and the settings define to insert css' do
+          let (:ballonizer_settings) do
+            ballonizer_settings_example.merge({
+              add_required_css: true,
+              css_asset_path_for_link: 'assets/css'
+            })
+          end
+
+          it do
+            # the example html don't have any link tag, so if there one
+            # it was added by the method
+            should have_tag('link', :with => { type: 'text/css' })
+          end
+        end
+        context 'and the settings define to insert js' do
+          let (:ballonizer_settings) do
+            ballonizer_settings_example.merge({
+              # this option is added to avoid a false positive in the test
+              add_js_for_edition: false,
+              add_required_js_libs_for_edition: true,
+              js_asset_path_for_link: 'assets/js'
+            })
+          end
+
+          it do
+            should have_tag('script', :with => { type: 'text/javascript' })
+          end
+        end
       end
       context 'and more than one of them is to be ballonized' do
         let (:original_page) do
@@ -488,7 +542,6 @@ describe Ballonizer do
   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
@@ -535,5 +588,103 @@ describe Ballonizer do
       end
     end
   end
+
+  describe '#css_html_links' do
+    context "when the path for the css isn't configured" do
+      it 'returns nil' do
+        expect(instance.css_html_links).to eq nil
+      end
+    end
+    context 'when the path for the css is configured' do
+      let (:ballonizer_settings) do
+        ballonizer_settings_example.merge({
+          css_asset_path_for_link: 'assets/css'
+        })
+      end
+
+      it 'return a HTML string with links prefixed by the path' do
+        REXML::Document.new("<root>#{instance.css_html_links}</root>")
+                       .root.children.each do | e |
+          expect(e.attributes['href']).to match(/^assets\/css/)
+        end
+      end
+    end
+  end
+
+  describe '#js_libs_html_links' do
+    context "when the path for the js libs isn't configured" do
+      it 'returns nil' do
+        expect(instance.js_libs_html_links).to eq nil
+      end
+    end
+    context 'when the path for the js libs is configured' do
+      let (:ballonizer_settings) do
+        ballonizer_settings_example.merge({
+          js_asset_path_for_link: 'assets/js'
+        })
+      end
+
+      it 'return a HTML string with links prefixed by the path' do
+        REXML::Document.new("<root>#{instance.js_libs_html_links}</root>")
+                       .root.children.each do | e |
+          expect(e.attributes['src']).to match(/^assets\/js/)
+        end
+      end
+    end
+  end
+
+  describe '.asset_load_paths' do
+    it 'return an array of paths who exist in the gem root dir' do
+      # TODO: change to __dir__ when the 2.0 become widely adopted
+      spec_dir = File.dirname(File.realpath(__FILE__))
+      gem_root_dir = File.expand_path('../', spec_dir)
+
+      absolute_load_paths = described_class.asset_load_paths.map do | path |
+        File.expand_path(path, gem_root_dir)
+      end
+
+      expect(absolute_load_paths).to exist_in_filesystem
+    end
+  end
+
+  describe '.asset_absolute_paths' do
+    it 'return an array of absolute filepaths who exist' do
+      expect(described_class.asset_absolute_paths).to exist_in_filesystem
+    end
+  end
+
+  describe '.asset_logical_paths' do
+    it 'return the last part of the asset_absolute_paths' do
+      logical_paths = described_class.asset_logical_paths
+      absolute_paths = described_class.asset_absolute_paths
+
+      are_last_part_of_absolute = logical_paths.all? do | lp |
+        absolute_paths.any? { | ap | ap.end_with? lp }
+      end
+
+      expect(are_last_part_of_absolute).to be_true
+    end
+  end
+
+  describe '.assets_app' do
+    let (:envs) do
+      described_class.asset_logical_paths.map do | asset_logical_path |
+        env_example.merge({
+          'HTTP_HOST' => 'example.net',
+          'SERVER_NAME' => 'example.net',
+          'PATH_INFO' => asset_logical_path,
+          'REQUEST_METHOD' => 'GET',
+          'rack.input' => nil,
+          'CONTENT_TYPE' => nil,
+          'CONTENT_LENGTH' => nil
+        })
+      end
+    end
+    it 'provide the css and js libs required by the gem' do
+      envs.each do | env |
+        expect(described_class.assets_app.call(env)[0]).to eq 200
+      end
+    end
+  end
 end