Shrimple

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.

Installation

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

gem 'shrimple', git: 'https://github.com/bronson/shrimple'

and execute bundle.

Usage

Render to a file:

require 'shrimple'

s = Shrimple.new( page: { paperSize: { format: 'A4' }} )
s.render_pdf('http://bl.ocks.org/mbostock', to: '/tmp/output.pdf')

Or render to a variable by omitting the destination:

result = Shrimple.new.render_text('http://thingsididlastnight.com')
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?

Configuration

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 = Shrimple.new( page: { zoomFactor: 0.5 }, timeout: 10 )
s.page.paperSize = { border: '3cm', format: 'A4', orientation: 'landscape' }
s.render_pdf('http://joeyh.name/blog/', 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:
s.page.paperSize.orientation = '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