photograph 0.0.2 → 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ea0a5dcbf3a353549a0009a793780daeeed56e2a
+  data.tar.gz: 648222a1f1475cc98c87c7ae1ab2efd67204cc1c
+SHA512:
+  metadata.gz: f54b2bbc8a8fb484674a6b646458dfd690da18c670b8f2244473bcdaa292e23420c940f93b752c84e525223c5a69ac2d7790765d6626763067d8f267fc6bf871
+  data.tar.gz: 091f1490bd3c72f2a2bd243c2dc2a734ee68fc3f563ab1e8c8c4f96556786cee5e3513c249bf4354b7b59e6b293c6324e302c3b4082df7c3c5104bd2d371fc65

data/README.md

@@ -1,20 +1,13 @@
 # Photograph
 
-Photograph solves the issue of generating previews or thumbnails of
-web-based documents. Think of generating a preview of a Google
-Spreadsheet. As a such document is dom based, it may be difficult to get a preview
-that truly reflects the original content. 
+Photograph allows to take screenshots of webpages, the rendering being
+done by Chrome.
 
-Photograph solves that problem by firing a chrome instance thanks to
-capybara-webkit and sinatra to provides an easy way to interface it to
-your needs. 
+Typically, this can be used to generate screenshots for DOM based
+documents.
 
-Obviously, it supports cropping to avoid reworking the image afterward.
-
-Please remind that having a chrome instance, even if it is being reused
-by all requests is still taking some time, aroung 600ms after the first 
-request on my development machine. *Consider using photograph only if
-you expect the same exact rendering of your 'web documents'*.
+Please remind that having a chrome instance doing the rendering, even if it is launched only once,
+is slow, around 600ms.
 
 ## Installation
 
@@ -32,14 +25,19 @@ Or install it yourself as:
 
 ## Usage
 
+**Using `Artist.shoot!` without a block had been deprecated in 0.3 and
+will raise an exception.**
+
 Photograph can be used either directly through the Photograph::Artist
-class or by its little sinata app. 
+class or by its little sinatra app. 
 
-    @artist = Photograph::Artist.new("http://github.com")
-    @artist.shoot!
+    @artist = Photograph::Artist.new(:url => "http://github.com")
+    @artist.shoot! do |image|
+      image # => MiniMagick instance you can toy with
 
-    @artist.image
-    # => MiniMagick instance you can toy with
+      send_file image.path,
+        :type => :png
+    end
 
 Or 
 
@@ -53,17 +51,11 @@ Or
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
-## Credits
-
-
-Photograph is maintained and funded by Tactilize.
-
-Contributors : 
+## Authors
 
 * Jean-Hadrien Chabran
-
-The names and logos for Tactilize are trademarks of Tactilize.
+* Danial Pearce
 
 ## License
 
-Photograph is Copyright © 2012 Tactilize. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
+Photograph is Copyright © 2013 JHCHABRAN. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/lib/photograph/artist.rb

@@ -1,7 +1,6 @@
 require 'capybara/poltergeist'
 require 'mini_magick'
 
-
 Capybara.default_wait_time = 15
 
 module Photograph
@@ -9,45 +8,77 @@ module Photograph
     attr_accessor :options
     attr_reader :image
 
-    MissingUrlError = Class.new(Exception)
+    class MissingUrlError  < ArgumentError; end
+    class DeprecationError < RuntimeError;  end
+
     DefaultOptions  = {
       :x => 0,          # top left position
       :y => 0,
-      :w => 1280,       # bottom right position
-      :h => 1024,
+      :w => 1280,       # width
+      :h => 1024,       # height
 
       :wait => 0.5,     # if selector is nil, wait 1 seconds before taking the screenshot
       :selector => nil  # wait until the selector matches to take the screenshot
     }
 
-    def self.browser
-      @browser ||= Capybara::Session.new :poltergeist
+    ##
+    # Instanciate a browser instance.
+    #
+    # Typically it's used to supply a Photograph instance your own browser session,
+    # allowing you to reuse it if you're using multiples +Photograph::Artist+
+    # instances.
+    def self.create_browser
+      Capybara::Session.new :poltergeist
     end
 
+    ##
+    # Returns current browser instance.
+    #
+    # If none had been supplied, it creates a new one.
     def browser
-      self.class.browser
+      @options[:browser] ||= self.class.create_browser
     end
 
+    ##
+    # Normalize urls, allowing you to use "google.com" instead of "http://google.com"
+    def normalize_url url
+      unless url.match(/https?:\/\//)
+        url = "http://#{url}"
+      end
+
+      url
+    end
+
+    ##
+    # Creates a new +Photograph::Artist+ and configures it through +options+.
+    #
+    # Cropping is supported through the +x+, +y+, +w+ and +h+ options.
+    #
+    # Options:
+    # * +url+ mandatory, location you want to screenshot
+    # * +wait+ wait amount of seconds before screenshotting. *this is option is ignored if +selector+ is provided.
+    # * +selector+ wait until the provided +selector+ matches a dom node before screenshotting. Typically faster than an arbritrary +wait+ amount, used when your page has some dynamically inserted nodes.
+    # * +x+ top coordinate of the screenshot, default to 0
+    # * +y+ left coordinate of the screenshot, default to 0
+    # * +w+ width of the screenshot, default to 1280
+    # * +h+ height of the screenshot, default to 1024
+    # * +browser+ Capybara instance to use, typically instanciated by +Artist.create_browser+
     def initialize options={}
-      raise MissingUrlError unless options[:url]
+      raise MissingUrlError.new('missing argument :url') unless options[:url]
 
       @options = DefaultOptions.merge(options)
+      @options[:url] = normalize_url(options[:url])
     end
 
+    ##
+    # Takes a screenshot and yield the resulting image.
     def shoot! &block
-      @image = capture
+      raise DeprecationError.new('Using Artist#shoot! without a block had been deprecated') unless block_given?
 
-      if block_given?
-        yield @image
-        clean!
-      else
-        @image
-      end
-    end
-
-    def capture
       browser.visit @options[:url]
 
+      @before_hook.call(browser) if @before_hook
+
       if @options[:selector]
         browser.wait_until do
           browser.has_css? @options[:selector]
@@ -56,30 +87,32 @@ module Photograph
         sleep @options[:wait]
       end
 
-      @tempfile = Tempfile.new(['photograph','.png'])
+      tempfile = Tempfile.new(['photograph','.png'])
 
-      browser.driver.render @tempfile.path,
+      browser.driver.render tempfile.path,
         :width  => options[:w] + options[:x],
         :height => options[:h] + options[:y]
 
-      @image = adjust_image
+      yield adjust_image(tempfile)
+    ensure
+      tempfile.unlink if tempfile
     end
 
-    def adjust_image
-      image = MiniMagick::Image.read @tempfile
+    ##
+    # Crops a given +tempfile+ according to initially given +options+
+    def adjust_image tempfile
+      image = MiniMagick::Image.read tempfile
 
       if options[:h] && options[:w]
         image.crop "#{options[:w]}x#{options[:h]}+#{options[:x]}+#{options[:y]}"
-
-        image.write @tempfile
-
+        image.write tempfile
       end
 
       image
     end
 
-    def clean!
-      @tempfile.unlink
+    def before &block
+      @before_hook = block
     end
   end
 end

data/lib/photograph/service.rb

@@ -2,12 +2,14 @@ require 'sinatra/base'
 require 'sinatra/json'
 
 module Photograph
-  # Preload the chrome instance
-  Artist.browser
-
   class Service < ::Sinatra::Base
     helpers Sinatra::JSON
 
+    # Reuse the same browser instance between requests.
+    def browser
+      @browser ||= Artist.create_browser
+    end
+
     get '/' do
       json :version => Photograph::VERSION
     end
@@ -19,7 +21,8 @@ module Photograph
                           :w   => params["w"].to_i,
                           :h   => params["h"].to_i,
                           :wait => params["wait"].to_f,
-                          :selector => params["selector"]
+                          :selector => params["selector"],
+                          :browser => browser
 
       artist.shoot! do |image|
         send_file image.path,

data/lib/photograph/version.rb

@@ -1,3 +1,3 @@
 module Photograph
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

data/photograph.gemspec

@@ -21,6 +21,8 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'sinatra-contrib'
   gem.add_dependency 'thin'
 
-  gem.add_development_dependency 'rspec', '~> 2.6'
+  gem.add_development_dependency 'rspec', '~> 2.14'
   gem.add_development_dependency 'rake'
+
+  gem.post_install_message = 'DEPRECATION: Artist#shoot! cannot be used without a block anymore. Please check your code, thank you.'
 end

data/spec/photograph/artist_spec.rb

@@ -2,47 +2,81 @@ require 'spec_helper'
 
 module Photograph
   describe Artist do
-    URL = "http://rubygems.org"
+    let(:url) { 'http://rubygems.org' }
+    subject   { Artist.new :url => url }
 
-    it "should instanciate a new artist" do
-      Artist.new :url => URL
-    end
+    describe '.new' do
+      it { expect(subject).to be_kind_of(Artist) }
+
+      it('raises an error when not given a url') do
+        expect{ Artist.new }.to raise_error(Artist::MissingUrlError)
+      end
+
+      it('should leave http version of url untouched as it is already valid') do
+        expect(subject.options[:url]).to eq(url)
+      end
+
+      it('should leave https version of url untouched as it is already valid') do
+        expect(Artist.new(:url => 'https://rubygems.org').options[:url]).to eq('https://rubygems.org')
+      end
 
-    it "should accept a block when shooting" do
-      Artist.new(:url => URL).shoot! do |image|
-        image.should respond_to(:path)
+      it('should prepend http:// to the url if protocol is not present') do
+        expect(Artist.new(:url => 'github.com').options[:url]).to eq('http://github.com')
       end
     end
 
-    it "should raise an error without an url" do
-      expect { Artist.new }.to raise_error(Artist::MissingUrlError)
+    describe '#options' do
+      it('should have default value for x') { expect(subject.options[:x]).to eq(0) }
+      it('should have default value for y') { expect(subject.options[:y]).to eq(0) }
+      it('should have default value for w') { expect(subject.options[:w]).to eq(1280) }
+      it('should have default value for h') { expect(subject.options[:h]).to eq(1024) }
     end
 
-    describe "Default size values" do
-      before(:each) { @artist = Artist.new :url => URL }
+    describe '#shoot!' do
+      context 'when browser has been provided' do
+        let(:browser) { Capybara::Session.new(:poltergeist) }
+        subject       { Artist.new(:url => url, :browser => browser) }
 
-      it "should have default values for x,y : 0,0" do
-        @artist.options[:x].should == 0
-        @artist.options[:y].should == 0
+        it 're-uses the browser provided to Artist#new' do
+          browser.should_receive(:visit)
+          subject.shoot! {}
+        end
       end
 
-      it"should have default values for h,w : 1280, 1024" do
-        @artist.options[:w].should == 1280
-        @artist.options[:h].should == 1024
+      it('should accept a block when shooting') do
+        subject.shoot!{|image| image.should respond_to(:path) }
+      end
+
+      it('should raise an exception if no block was given when shooting') do
+        expect{ subject.shoot! }.to raise_error(Artist::DeprecationError)
       end
-    end
 
-    describe "Cropping" do
-      before(:each) { @artist = Artist.new :url => URL }
+      describe 'Cropping' do
+        subject { Artist.new :url => url, :x => 200, :y => 100, :h => 400, :w => 400 }
+        before { subject.browser.driver.stub(:render) }
 
-      it "should take a screenshot large enough to crop later" do
-        pending
+        xit 'should take a screenshot large enough to crop later' do
+          subject.shoot!
+        end
+      end
+    end
 
-        @artist = Artist.new :url => URL, :x => 200, :y => 100, :h => 400, :w => 400
+    describe "#before" do
+      subject { Artist.new :url => url }
+      before do
+        subject.browser.driver.stub(:visit)
+        subject.browser.driver.stub(:click_link)
+        subject.browser.driver.stub(:render)
+        subject.stub(:adjust_image)
+      end
 
-        Artist.browser.driver.stub :render
+      it('should call the before hook before shooting') do
+        subject.before do |browser|
+          browser.click_link "Use the API"
+        end
 
-        @artist.shoot!
+        allow(subject.browser).to receive(:click_link)
+        subject.shoot! {}
       end
     end
   end

metadata

@@ -1,126 +1,111 @@
 --- !ruby/object:Gem::Specification
 name: photograph
 version: !ruby/object:Gem::Version
-  version: 0.0.2
-  prerelease: 
+  version: 0.0.4
 platform: ruby
 authors:
 - JH. Chabran
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-10 00:00:00.000000000 Z
+date: 2013-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: poltergeist
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: mini_magick
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: sinatra
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: sinatra-contrib
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: thin
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Webservice that screenshots any url
@@ -149,33 +134,27 @@ files:
 - spec/spec_helper.rb
 homepage: https://github.com/jhchabran/photograph
 licenses: []
-post_install_message: 
+metadata: {}
+post_install_message: 'DEPRECATION: Artist#shoot! cannot be used without a block anymore.
+  Please check your code, thank you.'
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -3056213331410753270
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -3056213331410753270
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Webservice that screenshots any url
 test_files:
 - spec/photograph/artist_spec.rb