Class: TXTextControl::ReportingCloud::ReportingCloud

Inherits:
Object
  • Object
show all
Defined in:
lib/txtextcontrol/reportingcloud/reportingcloud.rb

Overview

The main class.

Author:

  • Thorsten Kummerow (@thomerow)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(username, password, base_url = nil) ⇒ ReportingCloud

Returns a new instance of ReportingCloud

Parameters:

  • username (String) —

    The user name.

  • password (String) —

    The password.

  • base_url (String) (defaults to: nil) —

    The API base url. Is set to “https://api.reporting.cloud” by default.



53
54
55
56
57
58
59
60
 
# 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

Instance Attribute Details

#api_version ⇒ String

The API version. Is set to “v1” by default.

Returns:

  • (String) —

    the current value of api_version



42
43
44
 
# File 'lib/txtextcontrol/reportingcloud/reportingcloud.rb', line 42

def api_version
  @api_version
end

#base_uri ⇒ String

The API base url. Is set to “https://api.reporting.cloud” by default.

Returns:

  • (String) —

    the current value of base_uri



42
43
44
 
# File 'lib/txtextcontrol/reportingcloud/reportingcloud.rb', line 42

def base_uri
  @base_uri
end

#password ⇒ String

The password.

Returns:

  • (String) —

    the current value of password



42
43
44
 
# File 'lib/txtextcontrol/reportingcloud/reportingcloud.rb', line 42

def password
  @password
end

#read_timeout ⇒ Integer

The timeout for HTTP requests in seconds. Is set to 10 by default.

Returns:

  • (Integer) —

    the current value of read_timeout



42
43
44
 
# File 'lib/txtextcontrol/reportingcloud/reportingcloud.rb', line 42

def read_timeout
  @read_timeout
end

#username ⇒ String

The user name.

Returns:

  • (String) —

    the current value of username



42
43
44
 
# File 'lib/txtextcontrol/reportingcloud/reportingcloud.rb', line 42

def username
  @username
end

Instance Method Details

#append_documents(append_body, return_format = :pdf, test = false) ⇒ String

Combines documents by appending them divided by a new section, paragraph or nothing.

Parameters:

  • append_body (TXTextControl::ReportingCloud::AppendBody) —

    The AppendBody object contains the templates and a DocumentSettings object.

  • return_format (Symbol) (defaults to: :pdf) —

    The format of the created document. Possible values are :pdf, :rtf, :doc, :docx, :html, :tx and :txt.

  • test (Boolean) (defaults to: false) —

    Specifies whether it is a test run or not. A test run is not counted against the quota and created documents contain a watermark.

Returns:

  • (String) —

    The resulting document as a Base64 string.



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# 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) ⇒ Array<IncorrectWord>

Checks text for spelling errors.

Parameters:

  • text (String) —

    The text to spell check.

  • language (String) —

    The language that is used to spell check the specified text.

Returns:



380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# 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) ⇒ String

Converts a document to another format.

Parameters:

  • template_data (String) —

    The source document encoded as a Base64 string. The supported document formats are .rtf, .doc, .docx, .html, .pdf and .tx.

  • return_format (Symbol) (defaults to: :pdf) —

    The format of the created document. Possible values are: :pdf, :rtf, :doc, :docx, :html, :tx and :txt.

  • test (Boolean) (defaults to: false) —

    Specifies whether it is a test run or not. A test run is not counted against the quota and created documents contain a watermark.

Returns:

  • (String) —

    The created document encoded as a Base64 string.



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# 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 ⇒ String

Creates and returns a new API key.

Returns:

  • (String) —

    The new API key.



453
454
455
456
457
458
459
460
 
# 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) ⇒ Object

Deletes a given API Key from the account.

Parameters:

  • key (String) —

    The key to delete from the account.



464
465
466
467
468
469
470
471
472
473
474
475
476
477
 
# 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) ⇒ void

This method returns an undefined value.

Deletes a template from the template storage.

Parameters:

  • template_name (String) —

    The filename of the template to be deleted from the template storage.



203
204
205
206
207
208
209
210
211
 
# 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) ⇒ String

Returns the selected template from the storage.

Parameters:

  • template_name (String) —

    The filename of the template in the template storage.

Returns:

  • (String) —

    The template document data as a Base64 encoded string.



233
234
235
236
237
238
239
240
241
242
243
 
# 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) ⇒ String

Executes a find and replace on a template.

Parameters:

  • find_and_replace_body (FindAndReplaceBody) —

    The request body.

  • template_name (String) (defaults to: nil) —

    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.

  • return_format (Symbol) (defaults to: :pdf) —

    The format of the created document. Possible values are: :pdf, :rtf, :doc, :docx, :html, :tx and :txt.

  • test (Boolean) (defaults to: false) —

    Specifies whether it is a test run or not. A test run is not counted against the quota and created documents contain a watermark.

Returns:

  • (String) —

    The created document encoded as a Base64 string.



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
 
# 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 ⇒ AccountSettings

Returns the account settings.

Returns:



160
161
162
163
164
165
166
167
 
# File 'lib/txtextcontrol/reportingcloud/reportingcloud.rb', line 160

def 
  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 ⇒ Array<String>

Returns all available API Keys of the current account.

Returns:

  • (Array<String>) —

    All available API Keys of the current account.



481
482
483
484
485
486
487
488
489
490
491
492
493
 
# 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 ⇒ Array<String>

Returns all available dictionary names.

Returns:

  • (Array<String>) —

    Available dictionary names.



410
411
412
413
414
415
416
417
 
# 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) ⇒ Array<String>

Returns suggestions for a misspelled word.

Parameters:

  • word (String) —

    The incorrect word that has to be determined for suggestions.

  • language (String) —

    The language that is used to spell check the specified text.

  • max (Integer) —

    The maximum number of suggestions that has to be determined.

Returns:

  • (Array<String>) —

    Suggestions for a misspelled word.



424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# 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 ⇒ Integer

Returns the number of templates in the template storage.

Returns:

  • (Integer) —

    The number of templates in the template storage.



80
81
82
83
84
85
86
87
 
# 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) ⇒ TemplateInfo

Returns information about a template including merge fields and merge blocks.

Parameters:

  • template_name (String) —

    The filename of the template in the template storage to retrieve the information for.

Returns:



316
317
318
319
320
321
322
323
324
325
326
 
# 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) ⇒ Integer

Returns the number of pages of a template in the template storage.

Parameters:

  • template_name (String) —

    The filename of the template in the template storage to retrieve the number of pages for.

Returns:

  • (Integer) —

    The number of pages in the template.



272
273
274
275
276
277
278
279
280
281
282
 
# 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) ⇒ Array<String>

Returns a list of thumbnails of a specific template.

Parameters:

  • template_name (String) —

    The filename of the template in the template storage.

  • zoom_factor (Integer) —

    An Integer value between 1 and 400 to set the percentage zoom factor of the created thumbnail images.

  • from_page (Integer) (defaults to: 1) —

    An Integer value that specifies the first page.

  • to_page (Integer) (defaults to: 0) —

    An Integer value that specifies the last page.

  • image_format (Symbol) (defaults to: :png) —

    Defines the image format of the returned thumbnails. Possible values are :png, :jpg, :gif and :bmp.

Returns:

  • (Array<String>) —

    An array of Base64 encoded images.



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# 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 ⇒ Array<String>

Lists all available fonts.

Returns:

  • (Array<String>) —

    An array containing the names of all available fonts.



366
367
368
369
370
371
372
373
 
# 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 ⇒ Array<Template>

Lists all templates from the template storage.

Returns:

  • (Array<Template>) —

    An array of Template objects.



64
65
66
67
68
69
70
71
72
73
74
75
76
 
# 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) ⇒ Array<String>

Merges and returns a template from the template storage or an uploaded template with JSON data.

Parameters:

  • return_format (Symbol) (defaults to: :pdf) —

    The format of the created document. Possible values are :pdf, :rtf, :doc, :docx, :html, :tx and :txt.

  • merge_body (MergeBody) —

    The MergeBody object contains the datasource as a JSON data object and optionally, a template encoded as a Base64 string.

  • template_name (String) (defaults to: nil) —

    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.

  • append (Boolean) (defaults to: false) —

    Specifies whether the documents should be appened to one resulting document when more than 1 data row is passed.

  • test (Boolean) (defaults to: false) —

    Specifies whether it is a test run or not. A test run is not counted against the quota and created documents contain a watermark.

Returns:

  • (Array<String>) —

    An array of the created documents as Base64 encoded strings.



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# 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) ⇒ Boolean

Checks whether a template exists in the template storage.

Parameters:

  • template_name (String) —

    The filename of the template to be checked for availability in the template storage.

Returns:

  • (Boolean) —

    Returns if the template with the given name exists in the template storage.



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# 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) ⇒ void

This method returns an undefined value.

Stores an uploaded template in the template storage ( *.doc, *.docx, *.rtf and *.tx)

Parameters:

  • template_name (String) —

    The filename of the template in the template storage. Existing files with the same filename will be overwritten.

  • template_data (String) —

    A document encoded as a Base64 string. The supported formats are DOC, DOCX, RTF and TX.



219
220
221
222
223
224
225
226
227
228
 
# 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