class TXTextControl::ReportingCloud::ReportingCloud

The main class. @attr username [String] The user name. @attr password [String] The password. @attr base_uri [String] The API base url. Is set to “https://api.reporting.cloud

by default.

@attr api_version [String] The API version. Is set to “v1” by default. @attr read_timeout [Integer] The timeout for HTTP requests in seconds. Is set to

+10+ by default.

@author Thorsten Kummerow (@thomerow)

Attributes

api_version[RW]
base_uri[RW]
password[RW]
read_timeout[RW]
username[RW]

Public Class Methods

new(username, password, base_url = nil) click to toggle source

@param username [String] The user name. @param password [String] The password. @param base_url [String] The API base url. Is set to “https://api.reporting.cloud

by default.
# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 53
def initialize(username, password, base_url = nil)
  base_url ||= DEFAULT_BASE_URI
  @username = username
  @password = password
  @api_version = DEFAULT_VERSION
  @read_timeout = DEFAULT_TIMEOUT   
  @base_uri = URI.parse(base_url)
end

Public Instance Methods

append_documents(append_body, return_format = :pdf, test = false) click to toggle source

Combines documents by appending them divided by a new section, paragraph or nothing. @param append_body [TXTextControl::ReportingCloud::AppendBody] The AppendBody object

contains the templates and a DocumentSettings object.

@param return_format [Symbol] The format of the created document. Possible

values are +:pdf+, +:rtf+, +:doc+, +:docx+, +:html+, +:tx+ and +:txt+.

@param test [Boolean] Specifies whether it is a test run or not. A test run is

not counted against the quota and created documents contain a watermark.

@return [String] The resulting document as a Base64 string.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 138
def append_documents(append_body, return_format = :pdf, test = false)
  unless append_body.is_a?(TXTextControl::ReportingCloud::AppendBody)
    raise ArgumentError, "append_body must be an AppendBody instance."
  end

  # Create query parameters
  params = {
    :returnFormat => return_format,
    :test => test
  }

  # Send request
  res = request("/document/append", :post, params, append_body)
  if res.kind_of? Net::HTTPSuccess
    return res.body.remove_first_and_last
  else
    raise res.body 
  end        
end
check_text(text, language) click to toggle source

Checks text for spelling errors. @param text [String] The text to spell check. @param language [String] The language that is used to spell check the

specified text.

@return [Array<IncorrectWord>] An array of incorrect words.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 380
def check_text(text, language)
  # Parameter validation
  unless !text.nil? && !text.to_s.empty?
    raise ArgumentError, "The given text must not be empty."
  end        
  unless !language.nil? && !language.to_s.empty?
    raise ArgumentError, "A language must be defined."
  end        
  
  # Create query parameters
  params = {
    :text => text,
    :language => language
  }

  res = request("/proofing/check", :get, params)
  if res.kind_of? Net::HTTPSuccess
    incorrect_words = Array.new
    data = JSON.parse(res.body, object_class: OpenStruct)
    data.each do |elem|
      incorrect_words.push(IncorrectWord.from_camelized_hash(elem))
    end          
    return incorrect_words
  else
    raise res.body
  end          
end
convert_document(template_data, return_format = :pdf, test = false) click to toggle source

Converts a document to another format. @param template_data [String] The source document encoded as a Base64 string.

The supported document formats are +.rtf+, +.doc+, +.docx+, +.html+, +.pdf+ and +.tx+.

@param return_format [Symbol] The format of the created document.

Possible values are: +:pdf+, +:rtf+, +:doc+, +:docx+, +:html+, +:tx+ and +:txt+.

@param test [Boolean] Specifies whether it is a test run or not. A test run is not

counted against the quota and created documents contain a watermark.

@return [String] The created document encoded as a Base64 string.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 292
def convert_document(template_data, return_format = :pdf, test = false)
  # Parameter validation
  TemplateDataValidator.validate(template_data)
  
  # Create query parameters
  params = {
    :returnFormat => return_format,
    :test => test
  }

  res = request("/document/convert", :post, params, template_data)
  if res.kind_of? Net::HTTPSuccess
    # Remove leading and trailing quote from string
    # (inexplicably JSON.parse chokes on simple strings)
    return res.body.remove_first_and_last
  else
    raise res.body 
  end                
end
create_api_key() click to toggle source

Creates and returns a new API key. @return [String] The new API key.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 453
def create_api_key
  res = request("/account/apikey", :put)
  if res.kind_of? Net::HTTPSuccess
    return res.body.remove_first_and_last
  else
    raise res.body 
  end                
end
delete_api_key(key) click to toggle source

Deletes a given API Key from the account. @param key [String] The key to delete from the account.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 464
def delete_api_key(key)
  # Parameter validation
  unless !key.nil? && !key.to_s.empty?
    raise ArgumentError, "The given key must not be empty."
  end        

  # Create query parameters
  params = {
    :key => key
  }

  res = request("/account/apikey", :delete, params)
  raise res.body unless res.kind_of? Net::HTTPSuccess
end
delete_template(template_name) click to toggle source

Deletes a template from the template storage. @param template_name [String] The filename of the template to be deleted

from the template storage.

@return [void]

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 203
def delete_template(template_name)
  # Parameter validation
  TemplateNameValidator.validate(template_name)
  
  res = request("/templates/delete", :delete, { :templateName => template_name })
  unless res.kind_of? Net::HTTPSuccess
    raise res.body 
  end
end
download_template(template_name) click to toggle source

Returns the selected template from the storage. @param template_name [String] The filename of the template in the template storage. @return [String] The template document data as a Base64 encoded string.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 233
def download_template(template_name)
  # Parameter validation
  TemplateNameValidator.validate(template_name)

  res = request("/templates/download", :get, { :templateName => template_name })        
  if res.kind_of? Net::HTTPSuccess
    return res.body.remove_first_and_last
  else
    raise res.body
  end
end
find_and_replace(find_and_replace_body, template_name = nil, return_format = :pdf, test = false) click to toggle source

Executes a find and replace on a template. @param find_and_replace_body [FindAndReplaceBody] The request body. @param template_name [String] The name of the template in the template storage.

If no template is specified, the template must be included in the FindAndReplaceBody 
object of this request.

@param return_format [Symbol] The format of the created document.

Possible values are: +:pdf+, +:rtf+, +:doc+, +:docx+, +:html+, +:tx+ and +:txt+.

@param test [Boolean] Specifies whether it is a test run or not. A test run is not

counted against the quota and created documents contain a watermark.

@return [String] The created document encoded as a Base64 string.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 338
def find_and_replace(find_and_replace_body, template_name = nil, return_format = :pdf, test = false)
  # Parameter validation
  unless !find_and_replace_body.nil? && (find_and_replace_body.kind_of? FindAndReplaceBody) 
    raise ArgumentError, "Request body must be of type FindAndReplaceBody."
  end
  unless template_name.nil? || !template_name.to_s.empty?
    raise ArgumentError, "Template name must be a non empty string."
  end        
  
  # Create query parameters
  params = {
    :returnFormat => return_format,
    :templateName => template_name,
    :test => test
  }

  res = request("/document/findandreplace", :post, params, find_and_replace_body)
  if res.kind_of? Net::HTTPSuccess
    # Remove leading and trailing quote from string
    # (inexplicably JSON.parse chokes on simple strings)
    return res.body.remove_first_and_last
  else
    raise res.body 
  end                
end
get_account_settings() click to toggle source

Returns the account settings. @return [AccountSettings] The account settings.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 160
def get_account_settings
  res = request("/account/settings", :get)
  if res.kind_of? Net::HTTPSuccess
    return AccountSettings.from_camelized_hash(JSON.parse(res.body))
  else
    raise res.body
  end
end
get_api_keys() click to toggle source

Returns all available API Keys of the current account. @return [Array<String>] All available API Keys of the current account.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 481
def get_api_keys 
  res = request("/account/apikeys", :get)
  if res.kind_of? Net::HTTPSuccess
    keys = Array.new
    data = JSON.parse(res.body, object_class: OpenStruct)
    data.each do |elem|
      keys.push(APIKey.new(elem.key, elem.active))
    end
    return keys
  else
    raise res.body
  end        
end
get_available_dictionaries() click to toggle source

Returns all available dictionary names. @return [Array<String>] Available dictionary names.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 410
def get_available_dictionaries
  res = request("/proofing/availabledictionaries", :get)
  if res.kind_of? Net::HTTPSuccess
    return JSON.parse(res.body)
  else
    raise res.body
  end                
end
get_suggestions(word, language, max) click to toggle source

Returns suggestions for a misspelled word. @param word [String] The incorrect word that has to be determined for suggestions. @param language [String] The language that is used to spell check the specified text. @param max [Integer] The maximum number of suggestions that has to be determined. @return [Array<String>] Suggestions for a misspelled word.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 424
def get_suggestions(word, language, max)
  # Parameter validation
  unless !word.nil? && !word.to_s.empty?
    raise ArgumentError, "The given text must not be empty."
  end        
  unless !language.nil? && !language.to_s.empty?
    raise ArgumentError, "A language must be defined."
  end        
  unless max.is_a? Integer 
    raise ArgumentError, "max must be an integer"
  end
  
  # Create query parameters
  params = {
    :word => word,
    :language => language,
    :max => max
  }

  res = request("/proofing/suggestions", :get, params)
  if res.kind_of? Net::HTTPSuccess
    return JSON.parse(res.body)
  else
    raise res.body
  end        
end
get_template_count() click to toggle source

Returns the number of templates in the template storage. @return [Integer] The number of templates in the template storage.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 80
def get_template_count
  res = request("/templates/count", :get)
  if res.kind_of? Net::HTTPSuccess
    return Integer(res.body)
  else
    raise res.body
  end
end
get_template_info(template_name) click to toggle source

Returns information about a template including merge fields and merge blocks. @param template_name [String] The filename of the template in the template

storage to retrieve the information for.

@return [TemplateInfo] The template information.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 316
def get_template_info(template_name)
  # Parameter validation
  TemplateNameValidator.validate(template_name)

  res = request("/templates/info", :get, { :templateName => template_name })
  if res.kind_of? Net::HTTPSuccess
    return TemplateInfo.from_camelized_hash(JSON.parse(res.body))
  else
    raise res.body
  end
end
get_template_page_count(template_name) click to toggle source

Returns the number of pages of a template in the template storage. @param template_name [String] The filename of the template in the template

storage to retrieve the number of pages for.

@return [Integer] The number of pages in the template.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 272
def get_template_page_count(template_name)
  # Parameter validation
  TemplateNameValidator.validate(template_name)
  
  res = request("/templates/pagecount", :get, { :templateName => template_name })
  if res.kind_of? Net::HTTPSuccess
    return Integer(res.body)
  else
    raise res.body
  end        
end
get_template_thumbnails(template_name, zoom_factor, from_page = 1, to_page = 0, image_format = :png) click to toggle source

Returns a list of thumbnails of a specific template. @param template_name [String] The filename of the template in the template storage. @param zoom_factor [Integer] An Integer value between 1 and 400 to set the

percentage zoom factor of the created thumbnail images.

@param from_page [Integer] An Integer value that specifies the first page. @param to_page [Integer] An Integer value that specifies the last page. @param image_format [Symbol] Defines the image format of the returned thumbnails.

Possible values are +:png+, +:jpg+, +:gif+ and +:bmp+.

@return [Array<String>] An array of Base64 encoded images.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 178
def get_template_thumbnails(template_name, zoom_factor, from_page = 1, to_page = 0, image_format = :png)
  # Prepare query parameters
  params = {
    :templateName => template_name,
    :zoomFactor => zoom_factor,
    :fromPage => from_page,
    :toPage => to_page,
  }
  if image_format != :png
    params[:imageFormat] = image_format 
  end
  
  # Send request
  res = request("/templates/thumbnails", :get, params)
  if res.kind_of? Net::HTTPSuccess
    return JSON.parse(res.body)
  else
    raise res.body
  end        
end
list_fonts() click to toggle source

Lists all available fonts. @return [Array<String>] An array containing the names of all available fonts.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 366
def list_fonts
  res = request("/fonts/list", :get)
  if res.kind_of? Net::HTTPSuccess
    return JSON.parse(res.body)
  else
    raise res.body
  end        
end
list_templates() click to toggle source

Lists all templates from the template storage. @return [Array<Template>] An array of Template objects.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 64
def list_templates
  res = request("/templates/list", :get)
  if res.kind_of? Net::HTTPSuccess
    templates = Array.new
    data = JSON.parse(res.body, object_class: OpenStruct)
    data.each do |elem|
      templates.push(Template.new(elem.templateName, elem.modified, elem.size))
    end
    return templates
  else
    raise res.body
  end
end
merge_document(merge_body, template_name = nil, return_format = :pdf, append = false, test = false) click to toggle source

Merges and returns a template from the template storage or an uploaded template with JSON data. @param return_format [Symbol] The format of the created document. Possible

values are +:pdf+, +:rtf+, +:doc+, +:docx+, +:html+, +:tx+ and +:txt+.

@param merge_body [MergeBody] The MergeBody object contains the datasource

as a JSON data object and optionally, a template encoded as a Base64 string.

@param template_name [String] The name of the template in the template storage.

If no template name is specified, the template must be uploaded in the 
MergeBody object of this request.

@param append [Boolean] Specifies whether the documents should be appened

to one resulting document when more than 1 data row is passed.

@param test [Boolean] Specifies whether it is a test run or not. A test run is

not counted against the quota and created documents contain a watermark.

@return [Array<String>] An array of the created documents as

Base64 encoded strings.
# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 104
def merge_document(merge_body, template_name = nil, return_format = :pdf, append = false, test = false)
  if !template_name.to_s.empty? && !merge_body.template.nil?   # .to_s.empty: check for nil or ''
    raise ArgumentError, "Template name and template data must not be present at the same time."
  elsif template_name.to_s.empty? && merge_body.template.nil?
    raise ArgumentError, "Either a template name or template data have to be present."
  end
  
  # Create query parameters
  params = {
    :returnFormat => return_format,
    :append => append,
    :test => test
  }
  unless template_name.to_s.empty? 
    params[:templateName] = template_name
  end
  
  # Send request
  res = request("/document/merge", :post, params, merge_body)
  if res.kind_of? Net::HTTPSuccess
    return JSON.parse(res.body)
  else
    raise res.body 
  end        
end
template_exists?(template_name) click to toggle source

Checks whether a template exists in the template storage. @param template_name [String] The filename of the template to be

checked for availability in the template storage.

@return [Boolean] Returns if the template with the given name exists in

the template storage.
# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 250
def template_exists?(template_name)
  # Parameter validation
  TemplateNameValidator.validate(template_name)

  res = request("/templates/exists", :get, { :templateName => template_name })                       
  if res.kind_of? Net::HTTPSuccess
    case res.body
      when "true"
        return true
      when "false"
        return false
      else raise "Unknown response value received." 
    end
  else
    raise res.body
  end
end
upload_template(template_name, template_data) click to toggle source

Stores an uploaded template in the template storage ( +*.doc+, +*.docx+, +*.rtf+ and +*.tx+) @param template_name [String] The filename of the template in the template storage.

Existing files with the same filename will be overwritten.

@param template_data [String] A document encoded as a Base64 string.

The supported formats are DOC, DOCX, RTF and TX.

@return [void]

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 219
def upload_template(template_name, template_data)
  # Parameter validation
  TemplateNameValidator.validate(template_name)
  TemplateDataValidator.validate(template_data)
  
  res = request("/templates/upload", :post, { :templateName => template_name }, template_data)
  unless res.kind_of? Net::HTTPSuccess
    raise res.body 
  end        
end

Private Instance Methods

query_string_from_hash(hash) click to toggle source

Generates a query string from a hash

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 546
def query_string_from_hash(hash)
  return "?" + hash.collect { |k, v| "#{k}=#{CGI::escape(v.to_s)}" }.join('&') unless hash.nil?
  return ""
end
request(request_uri, request_type = :get, params = nil, body = nil) click to toggle source

Performs a HTTP request of a given type. @param request_type [Symbol] The type of the request. Possible values are :get, :post and :delete. @param params [Hash] The query parameters. @param body [Object, Hash, String] The request body. @return [Net::HTTPResponse] The HTTP response.

# File lib/txtextcontrol/reportingcloud/reportingcloud.rb, line 502
def request(request_uri, request_type = :get, params = nil, body = nil)
  # Generate query string from given parameters
  query_string = query_string_from_hash(params)
  
  http = Net::HTTP.new(@base_uri.host, @base_uri.port)
  http.use_ssl = @base_uri.scheme == "https"
  http.read_timeout = read_timeout
  
  # Get correct request type
  req_type = nil
  case request_type
    when :get
      req_type = Net::HTTP::Get
    when :post
      req_type = Net::HTTP::Post
    when :delete 
      req_type = Net::HTTP::Delete
    when :put
      req_type = Net::HTTP::Put
    else raise "Unknown HTTP request type."
  end 
  
  # Create HTTP request
  req = req_type.new("/#{@api_version}#{request_uri}#{query_string}", initheader = { "Content-Type" => "application/json" })
  req.basic_auth(@username, @password);
  # If body data is present, use it directly if it is a string or
  # else convert it to json
  if !body.nil?
    if body.kind_of? String
      req.body = "\"" + body + "\""
    elsif body.kind_of? Hash
      req.body = body.to_json
    elsif body.respond_to?(:to_camelized_hash)
      req.body = body.to_camelized_hash.to_json
    elsif body.respond_to?(:to_hash)
      req.body = body.to_hash.to_json
    end
  end
  # Send request
  return http.request(req)
end