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