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.4"

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:



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

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:



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

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:



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

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.expand(signed_token: nil).to_s).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:



149
150
151
152
153
154
 
# File 'lib/htmlcsstoimage.rb', line 149

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:



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

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:



126
127
128
129
 
# File 'lib/htmlcsstoimage.rb', line 126

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):

  • :css (String) —

    The CSS for your image. Gets injected into the webpage.

  • :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:



116
117
118
119
120
121
 
# File 'lib/htmlcsstoimage.rb', line 116

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