Launches PhantomJS to render web sites or local files (or have Phantom do pretty much everything). Shrimple started as a set of patches for Shrimp.

Build Status Gem Version


Install PhantomJS, then add this line to your application's Gemfile:

gem 'shrimple', git: ''

and execute bundle.


Render to a file:

require 'shrimple'

s = page: { paperSize: { format: 'A4' }} )
s.render_pdf('', to: '/tmp/output.pdf')

Or render to a variable by omitting the destination:

result ='')
result.stdout   # <== TODO: naming stdout is arcane
=> "Your Mom\n"

Render in the background:

TODO: show background mode TODO: show start_time and finish_time?


Shrimple supports all configuration options provided by PhantomJS (including unanticipated ones added in the future).

Options specified later override those specified earlier, and options passed directly to render only affect that call -- they are not remembered.

s = page: { zoomFactor: 0.5 }, timeout: 10 ) = { border: '3cm', format: 'A4', orientation: 'landscape' }
s.render_pdf('', to: '/tmp/joey.pdf')
  • Set options passed to PhantomJS's command line with config:
    s.config.loadImages = false
    Phantom requires these to be in JSON notation: proxyType instead of --proxy-type.

  • Set options in PhantomJS's web page module with page: = 'landscape'

  • Set options passed to PhantomJS's render call with render:
    s.render = { format: 'jpeg', quality: 85 }

See default_config.rb for the known options all listed in one place.

Shrimple Options

  • background If true, the PhantomJS process will be spawned in the background and Ruby execution will resume immediatley.
    background: false

  • timeout The time in seconds after which the PhantomJS executable is killed. If killed, the render results in an error.
    timeout: nil

  • output / to Specifies the destination file. If you don't specify a destination then the output is buffered into memory and can be retrieved with result.stdout. to is just a more readable synonym for output.

  • stderr The path to save phantom's stderr. Normally it's buffered into memory and can be retrieved with result.stderr

  • onSuccess A Ruby proc to be called when the render succeeds.
    onSuccess = ->(result) { ftp.put(result.stdout) }

  • onError A Ruby proc called when the render fails or is killed.
    onError = ->(result) { page_admin(result.stderr, result.options.to_hash) }

These are more obscure, only necessary if you're trying to use Phantom in an obscure way.

  • input specifies the source file to render. Normally you'd pass this as the first argument to render. Use this option if you want to specify the input file once and render it multiple times. You must specify a valid URL. Use file://test_file.html to specify a file on the local filesystem.

  • execuatable a path to the phantomjs exectuable to use. Shrimple searches pretty hard for installed phantomjs executables so there's usually no need to specify this.

  • renderer the render.js script to pass to Phantom. Probably only useful for testing.

Changes to Shrimp

  • Added background mode (even works in JRuby >1.7.4).
  • Allows configuring pretty much anything: proxies, userName/password, scrollPosition, jpeg quality, etc.
  • Prevents potential shell attacks by ensuring options aren't passed on the command line.
  • Better error handling.
  • Removed middleware. In my app, background mode made it unnecessary. Besides, I could never get it to work reliably.

Shrimp, the original project, is Copyright © 2012 adeven (Manuel Kniep). It is free software, and may be redistributed under the MIT License (see LICENSE.txt).

Shrimple is also Copyright © 2013 Scott Bronson and may be redistributed under the same terms.