Class: HTMLCSSToImage

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/htmlcsstoimage.rb,
lib/htmlcsstoimage/version.rb

Defined Under Namespace

Classes: ApiResponse

Constant Summary collapse

SIGNED_URL_TEMPLATE = 
Addressable::Template.new("https://hcti.io/v1/image/{template_id}/{signed_token}{/format*}{?query*}")
VERSION = 
"0.1.1"

Instance Method Summary collapse

Constructor Details

#initialize(user_id: ENV["HCTI_USER_ID"], api_key: ENV["HCTI_API_KEY"]) ⇒ HTMLCSSToImage

Creates an instance of HTMLCSSToImage with API credentials.

If credentials are not provided, will try to use environment variables.
`HCTI_USER_ID` and `HCTI_API_KEY`.

Parameters:

  • user_id (String) (defaults to: ENV["HCTI_USER_ID"]) —

    the user_id for the account.

  • api_key (String) (defaults to: ENV["HCTI_API_KEY"]) —

    the api_key for the account.

See Also:



36
37
38
 
# File 'lib/htmlcsstoimage.rb', line 36

def initialize(user_id: ENV["HCTI_USER_ID"], api_key: ENV["HCTI_API_KEY"])
  @auth = { username: user_id, password: api_key }
end

Instance Method Details

#create_image(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse

Converts HTML/CSS to an image with the API

Parameters:

  • html (String) —

    This is the HTML you want to render. You can send an HTML snippet (`<div>Your content</div>`) or an entire webpage.

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :css (String) —

    The CSS for your image.

  • :google_fonts (String) —

    [Google fonts](docs.htmlcsstoimage.com/guides/using-google-fonts/) to be loaded. Example: `Roboto`. Multiple fonts can be loaded like this: `Roboto|Open Sans`

  • :selector (String) —

    A CSS selector for an element on the webpage. We'll crop the image to this specific element. For example: `section#complete-toolkit.container-lg`

  • :ms_delay (Integer) —

    The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time.

  • :device_scale (Double) —

    This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.

  • :render_when_ready (Boolean) —

    Set to true to control when the image is generated. Call `ScreenshotReady()` from JavaScript to generate the image. [Learn more](docs.htmlcsstoimage.com/guides/render-when-ready/).

  • :viewport_width (Integer) —

    Set the width of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.

  • :viewport_height (Integer) —

    Set the height of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.

Returns:

See Also:



56
57
58
59
60
61
 
# File 'lib/htmlcsstoimage.rb', line 56

def create_image(html, params = {})
  body = { html: html }.merge(params).to_json
  options = { basic_auth: @auth, body: body, query: { includeId: true } }

  self.class.post("/v1/image", options)
end

#create_image_from_template(template_id, template_values = {}, params = {}) ⇒ Object

Creates a signed URL for generating an image from a template This URL contains the template_values in it. It is signed with HMAC so that it cannot be changed by anyone without the API Key.

Does not make any network requests.

Parameters:

  • template_id (String) —

    The ID for the template

  • template_values (Hash) (defaults to: {}) —

    A hash containing the values to replace in the template

See Also:



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/htmlcsstoimage.rb', line 86

def create_image_from_template(template_id, template_values = {}, params = {})
  template = SIGNED_URL_TEMPLATE.partial_expand({
    template_id: template_id,
    query: template_values
  })

  query = Addressable::URI.parse(template.generate).query
  digest = OpenSSL::Digest.new('sha256')
  signed_token = OpenSSL::HMAC.hexdigest(digest, @auth[:password], CGI.unescape(query))

  url = template.expand({
    signed_token: signed_token
  }).to_s

  ApiResponse.new(url: url)
end

#create_template(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse

Creates an image template

Parameters:

  • html (String) —

    This is the HTML you want to render. You can send an HTML snippet (`<div>Your content</div>`) or an entire webpage.

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :name (String) —

    A short name to identify your template max length 64

  • :description (String) —

    Description to elaborate on the use of your template max length 1024

  • :css (String) —

    The CSS for your image.

  • :google_fonts (String) —

    [Google fonts](docs.htmlcsstoimage.com/guides/using-google-fonts/) to be loaded. Example: `Roboto`. Multiple fonts can be loaded like this: `Roboto|Open Sans`

  • :selector (String) —

    A CSS selector for an element on the webpage. We'll crop the image to this specific element. For example: `section#complete-toolkit.container-lg`

  • :ms_delay (Integer) —

    The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time.

  • :device_scale (Double) —

    This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.

  • :render_when_ready (Boolean) —

    Set to true to control when the image is generated. Call `ScreenshotReady()` from JavaScript to generate the image. [Learn more](docs.htmlcsstoimage.com/guides/render-when-ready/).

  • :viewport_width (Integer) —

    Set the width of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.

  • :viewport_height (Integer) —

    Set the height of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.

Returns:

See Also:



147
148
149
150
151
152
 
# File 'lib/htmlcsstoimage.rb', line 147

def create_template(html, params = {})
  body = { html: html }.merge(params).to_json
  options = { basic_auth: @auth, body: body }

  self.class.post("/v1/template", options)
end

#delete_image(image_id) ⇒ Object

Deletes an image

Parameters:

  • image_id (String) —

    The ID for the image you would like to delete

See Also:



68
69
70
71
72
73
74
 
# File 'lib/htmlcsstoimage.rb', line 68

def delete_image(image_id)
  response = self.class.delete("/v1/image/#{image_id}", basic_auth: @auth)

  return true if response.success?

  response
end

#templates(params = {}) ⇒ Object

Retrieves all available templates

See Also:



124
125
126
127
 
# File 'lib/htmlcsstoimage.rb', line 124

def templates(params = {})
  options = params.merge({ basic_auth: @auth })
  self.class.get("/v1/template", options)
end

#url_to_image(url, params = {}) ⇒ Object

Generate a screenshot of a URL

Parameters:

  • url (String) —

    The fully qualified URL to a public webpage. Such as htmlcsstoimage.com.

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :selector (String) —

    A CSS selector for an element on the webpage. We'll crop the image to this specific element. For example: `section#complete-toolkit.container-lg`

  • :ms_delay (Integer) —

    The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time.

  • :device_scale (Double) —

    This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.

  • :render_when_ready (Boolean) —

    Set to true to control when the image is generated. Call `ScreenshotReady()` from JavaScript to generate the image. [Learn more](docs.htmlcsstoimage.com/guides/render-when-ready/).

  • :viewport_width (Integer) —

    Set the width of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.

  • :viewport_height (Integer) —

    Set the height of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.

See Also:



114
115
116
117
118
119
 
# File 'lib/htmlcsstoimage.rb', line 114

def url_to_image(url, params = {})
  body = { url: url }.merge(params).to_json
  options = { basic_auth: @auth, body: body, query: { includeId: true } }

  self.class.post("/v1/image", options)
end