Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve the readme with syntax color #130

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve the readme with syntax color #130

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 135 additions & 109 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,49 +24,53 @@ gem install wkhtmltoimage-binary

## Usage

# IMGKit.new takes the HTML and any options for wkhtmltoimage
# run `wkhtmltoimage --extended-help` for a full list of options
kit = IMGKit.new(html, :quality => 50)
kit.stylesheets << '/path/to/css/file'
kit.javascripts << '/path/to/js/file'

# Get the image BLOB
img = kit.to_img

# New in 1.3!
img = kit.to_img(:jpg) #default
img = kit.to_img(:jpeg)
img = kit.to_img(:png)

# Save the image to a file
file = kit.to_file('/path/to/save/file.jpg')
file = kit.to_file('/path/to/save/file.png')

# IMGKit.new can optionally accept a URL or a File.
# Stylesheets nor Javascripts can not be added when source is provided as a URL of File.
kit = IMGKit.new('http://google.com')
kit = IMGKit.new(File.new('/path/to/html'))

# Add any kind of option through meta tags
IMGKit.new('<html><head><meta name="imgkit-quality" content="75"...

# Format shortcuts - New in 1.3!
IMGKit.new("hello").to_jpg
IMGKit.new("hello").to_jpeg
IMGKit.new("hello").to_png
```ruby
# IMGKit.new takes the HTML and any options for wkhtmltoimage
# run `wkhtmltoimage --extended-help` for a full list of options
kit = IMGKit.new(html, :quality => 50)
kit.stylesheets << '/path/to/css/file'
kit.javascripts << '/path/to/js/file'

# Get the image BLOB
img = kit.to_img

# New in 1.3!
img = kit.to_img(:jpg) #default
img = kit.to_img(:jpeg)
img = kit.to_img(:png)

# Save the image to a file
file = kit.to_file('/path/to/save/file.jpg')
file = kit.to_file('/path/to/save/file.png')

# IMGKit.new can optionally accept a URL or a File.
# Stylesheets nor Javascripts can not be added when source is provided as a URL of File.
kit = IMGKit.new('http://google.com')
kit = IMGKit.new(File.new('/path/to/html'))

# Add any kind of option through meta tags
IMGKit.new('<html><head><meta name="imgkit-quality" content="75"...

# Format shortcuts - New in 1.3!
IMGKit.new("hello").to_jpg
IMGKit.new("hello").to_jpeg
IMGKit.new("hello").to_png
```

Note: Ruby's buffered I/O means that if you want to write the string data to a file or tempfile make sure to call `#flush` to ensure the contents don't get stuck in the buffer.
Note: Ruby's buffered I/O means that if you want to write the string data to a file or tempfile make sure to call `#flush` to ensure the contents don't get stuck in the buffer.

## Configuration

### `wkhtmltoimage` binary location

If you're on Windows or you installed `wkhtmltoimage` by hand to a location other than `/usr/local/bin` you will need to tell IMGKit where the binary is. You can configure IMGKit like so:

# config/initializers/imgkit.rb
IMGKit.configure do |config|
config.wkhtmltoimage = '/path/to/wkhtmltoimage'
end
```ruby
# config/initializers/imgkit.rb
IMGKit.configure do |config|
config.wkhtmltoimage = '/path/to/wkhtmltoimage'
end
```

You could put the binaries in your bin/ folder and load the correct one depending on the platform and CPU type:

Expand All @@ -88,7 +92,7 @@ end

To get `wkhtmltoimage-linux-amd64` you can get the latest `.deb` (if you are targeting ubuntu) from https://github.com/wkhtmltopdf/packaging/releases

```
```bash
docker run -it -v $(pwd):/data ubuntu:latest /bin/bash
# or with fish
# docker run -it -v (pwd):/data ubuntu:latest /bin/bash
Expand All @@ -101,43 +105,55 @@ cp out/usr/local/bin/wkhtmltoimage bin/wkhtmltoimage-linux-amd64
And for `wkhtmltoimage-macos-amd64` you can download the `.pkg` from https://github.com/wkhtmltopdf/packaging/releases,
install it, then:

```
```bash
mv /usr/local/bin/wkhtmltoimage bin/wkhtmltoimage-macos-amd64
```

### Default image format

May be set to one of [`IMGKit::KNOWN_FORMATS = [:jpg, :jpeg, :png]`](https://github.com/csquared/IMGKit/blob/master/lib/imgkit/imgkit.rb#L2)

config.default_format = :png
```ruby
config.default_format = :png
```

### Prefix for `<meta>` tag options (see **Usage**) :

May be changed from its default (`imgkit-`):

config.meta_tag_prefix = 'imgkit-option'
```ruby
config.meta_tag_prefix = 'imgkit-option'
```

### Additional default options

Any flag accepted by `wkhtmltoimage` may be set thus:

config.default_options = {
:quality => 60
}
```ruby
config.default_options = {
quality: 60
}
```

For a flag which takes no parameters, use `true` for the value:

'no-images' => true
```ruby
'no-images' => true
```

For flags with multiple parameters, use an array:

:cookie => ['my_session', '123BADBEEF456']
```
cookie: ['my_session', '123BADBEEF456']
```

### Overriding options

When initializing an `IMGKit` options may be may be set for the life time of the `IMGKit` object:

IMGKit.new('http://example.com/form', :post => ['my_field', 'my_unique_value'])
```ruby
IMGKit.new('http://example.com/form', :post => ['my_field', 'my_unique_value'])
```

## Heroku

Expand All @@ -150,9 +166,11 @@ version 0.10.0 has worked best for me

assuming its in that location you can just do:

IMGKit.configure do |config|
config.wkhtmltoimage = Rails.root.join('bin', 'wkhtmltoimage-amd64').to_s if ENV['RACK_ENV'] == 'production'
end
```ruby
IMGKit.configure do |config|
config.wkhtmltoimage = Rails.root.join('bin', 'wkhtmltoimage-amd64').to_s if ENV['RACK_ENV'] == 'production'
end
```

If you're not using Rails just replace Rails.root with the root dir of your app.

Expand All @@ -162,63 +180,71 @@ If you're not using Rails just replace Rails.root with the root dir of your app.
### Mime Types
register a .jpg mime type in:

#config/initializers/mime_type.rb
Mime::Type.register "image/jpeg", :jpg
```ruby
#config/initializers/mime_type.rb
Mime::Type.register "image/jpeg", :jpg
```

register a .png mime type in:

#config/initializers/mime_type.rb
Mime::Type.register "image/png", :png
```ruby
#config/initializers/mime_type.rb
Mime::Type.register "image/png", :png
```

### Controller Actions
You can respond in a controller with:

@kit = IMGKit.new(render_to_string)
```ruby
@kit = IMGKit.new(render_to_string)

format.jpg do
send_data(@kit.to_jpg, :type => "image/jpeg", :disposition => 'inline')
end
format.jpg do
send_data(@kit.to_jpg, :type => "image/jpeg", :disposition => 'inline')
end

- or -
- or -

format.png do
send_data(@kit.to_png, :type => "image/png", :disposition => 'inline')
end
format.png do
send_data(@kit.to_png, :type => "image/png", :disposition => 'inline')
end

- or -
- or -

respond_to do |format|
send_data(@kit.to_img(format.to_sym),
:type => "image/#{format}", :disposition => 'inline')
end
respond_to do |format|
send_data(@kit.to_img(format.to_sym),
:type => "image/#{format}", :disposition => 'inline')
end
```

This allows you to take advantage of rails page caching so you only generate the
image when you need to.

## --user-style-sheet workaround
To overcome the lack of support for --user-style-sheet option by wkhtmltoimage 0.10.0 rc2 as reported here http://code.google.com/p/wkhtmltopdf/issues/detail?id=387

require 'imgkit'
require 'restclient'
require 'stringio'

url = 'http://domain/path/to/stylesheet.css'
css = StringIO.new( RestClient.get(url) )

kit = IMGKit.new(<<EOD)
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>coolest converter</title>
</head>
<body>
<div class="cool">image kit</div>
</body>
</html>
EOD

kit.stylesheets << css
```ruby
require 'imgkit'
require 'restclient'
require 'stringio'

url = 'http://domain/path/to/stylesheet.css'
css = StringIO.new( RestClient.get(url) )

kit = IMGKit.new(<<EOD)
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>coolest converter</title>
</head>
<body>
<div class="cool">image kit</div>
</body>
</html>
EOD

kit.stylesheets << css
```

## Paperclip Example

Expand All @@ -236,17 +262,17 @@ Controller:

```ruby
def upload_image
model = Model.find(params[:id])
html = render_to_string
kit = IMGKit.new(html)
img = kit.to_img(:png)
file = Tempfile.new(["template_#{model.id}", 'png'], 'tmp',
:encoding => 'ascii-8bit')
file.write(img)
file.flush
model.snapshot = file
model.save
file.unlink
model = Model.find(params[:id])
html = render_to_string
kit = IMGKit.new(html)
img = kit.to_img(:png)
file = Tempfile.new(["template_#{model.id}", 'png'], 'tmp',
:encoding => 'ascii-8bit')
file.write(img)
file.flush
model.snapshot = file
model.save
file.unlink
end
```

Expand All @@ -257,22 +283,22 @@ end
Contributed by @ticktricktrack

```ruby
class MyClass < ActiveRecord::Base
mount_uploader :snapshot, SnapshotUploader
class MyClass < ActiveRecord::Base
mount_uploader :snapshot, SnapshotUploader

after_create :take_snapshot
after_create :take_snapshot

# private
# private

def take_snapshot
file = Tempfile.new(["template_#{self.id.to_s}", '.jpg'], 'tmp', :encoding => 'ascii-8bit')
file.write(IMGKit.new(self.html_body, quality: 50, width: 600).to_jpg)
file.flush
self.snapshot = file
self.save
file.unlink
end
def take_snapshot
file = Tempfile.new(["template_#{self.id.to_s}", '.jpg'], 'tmp', :encoding => 'ascii-8bit')
file.write(IMGKit.new(self.html_body, quality: 50, width: 600).to_jpg)
file.flush
self.snapshot = file
self.save
file.unlink
end
end
```


Expand Down