Class: GroupDocs::Document

Inherits:
Api::Entity show all
Extended by:
Extensions::Lookup
Includes:
Api::Helpers::AccessMode, Api::Helpers::Status
Defined in:
lib/groupdocs/document.rb

Defined Under Namespace

Classes: Annotation, Change, Field, MetaData, Rectangle, View

Constant Summary

Constants included from Api::Helpers::Status

Api::Helpers::Status::STATUSES

Constants included from Api::Helpers::AccessMode

Api::Helpers::AccessMode::MODES

Instance Attribute Summary collapse

Attributes included from Api::Helpers::Status

#status

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Extensions::Lookup

find!, find_all!

Methods inherited from Api::Entity

#inspect, #to_hash

Constructor Details

#initialize(options = {}, &blk) ⇒ Document

Creates new GroupDocs::Document.

You should avoid creating documents directly. Instead, use #to_document instance method of GroupDocs::Storage::File.

Raises:

  • (ArgumentError) —

    If file is not passed or is not an instance of GroupDocs::Storage::File



104
105
106
107
108
 
# File 'lib/groupdocs/document.rb', line 104

def initialize(options = {}, &blk)
  super(options, &blk)
  file.is_a?(GroupDocs::Storage::File) or raise ArgumentError,
    "You have to pass GroupDocs::Storage::File object: #{file.inspect}."
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &blk) ⇒ Object

Pass all unknown methods to file.



535
536
537
 
# File 'lib/groupdocs/document.rb', line 535

def method_missing(method, *args, &blk)
  file.respond_to?(method) ? file.send(method, *args, &blk) : super
end

Instance Attribute Details

#file ⇒ Object 



54
55
56
 
# File 'lib/groupdocs/document.rb', line 54

def file
  @file
end

#output_formats ⇒ Array<Symbol>

Returns output formats in human-readable format.

Returns:

  • (Array<Symbol>) 


60
61
62
 
# File 'lib/groupdocs/document.rb', line 60

def output_formats
  @output_formats
end

#outputs ⇒ Object 



58
59
60
 
# File 'lib/groupdocs/document.rb', line 58

def outputs
  @outputs
end

#process_date ⇒ Time

Converts timestamp which is return by API server to Time object.

Returns:

  • (Time) 


56
57
58
 
# File 'lib/groupdocs/document.rb', line 56

def process_date
  @process_date
end

Class Method Details

.all!(path = '/', access = {}) ⇒ Array<GroupDocs::Storage::Document>

Returns an array of all documents on server.

Parameters:

  • path (String) (defaults to: '/') —

    Starting path to look for documents

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

  • (Array<GroupDocs::Storage::Document>) 


24
25
26
 
# File 'lib/groupdocs/document.rb', line 24

def self.all!(path = '/', access = {})
  Storage::File.all!(path, access).map(&:to_document)
end

.views!(options = { page_index: 0 }, access = {}) ⇒ Array<GroupDocs::Document::View>

Returns an array of views for all documents.

Parameters:

  • options (Hash) (defaults to: { page_index: 0 })
  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (options):

  • :page_index (Integer) —

    Page to start with

  • :page_size (Integer) —

    Total number of entries

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/groupdocs/document.rb', line 39

def self.views!(options = { page_index: 0 }, access = {})
  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/doc/{{client_id}}/views"
  end
  api.add_params(options)
  json = api.execute!

  json[:views].map do |view|
    Document::View.new(view)
  end
end

Instance Method Details

#access_mode!(access = {}) ⇒ Symbol

Returns access mode of document.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

  • (Symbol) —

    One of :private, :restricted or :public access modes



118
119
120
121
122
123
124
125
126
 
# File 'lib/groupdocs/document.rb', line 118

def access_mode!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/doc/{{client_id}}/files/#{file.id}/accessinfo"
  end.execute!

  parse_access_mode(json[:access])
end

#access_mode_set!(mode, access = {}) ⇒ Symbol Also known as: access_mode=

Sets access mode of document.

Parameters:

  • mode (Symbol) —

    One of :private, :restricted or :public access modes

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

  • (Symbol) —

    Set access mode



137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/groupdocs/document.rb', line 137

def access_mode_set!(mode, access = {})
  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/doc/{{client_id}}/files/#{file.id}/accessinfo"
  end
  api.add_params(mode: parse_access_mode(mode))
  json = api.execute!

  parse_access_mode(json[:access])
end

#add_questionnaire!(questionnaire, access = {}) ⇒ Object

Adds questionnaire to document.

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Raises:

  • (ArgumentError) —

    if questionnaire is not GroupDocs::Questionnaire object



379
380
381
382
383
384
385
386
387
388
 
# File 'lib/groupdocs/document.rb', line 379

def add_questionnaire!(questionnaire, access = {})
  questionnaire.is_a?(GroupDocs::Questionnaire) or raise ArgumentError,
    "Questionnaire should be GroupDocs::Questionnaire object, received: #{questionnaire.inspect}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/merge/{{client_id}}/files/#{file.guid}/questionnaires/#{questionnaire.id}"
  end.execute!
end

#annotations!(access = {}) ⇒ Array<GroupDocs::Document::Annotation>

Returns an array of annotations.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



445
446
447
448
449
450
451
452
453
454
455
456
 
# File 'lib/groupdocs/document.rb', line 445

def annotations!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/ant/{{client_id}}/files/#{file.guid}/annotations"
  end.execute!

  json[:annotations].map do |annotation|
    annotation.merge!(document: self)
    Document::Annotation.new(annotation)
  end
end

#changes!(access = {}) ⇒ Object

Returns an array of changes in document.

Examples:

document_one = GroupDocs::Document.find!(:name, 'CV.doc')
document_two = GroupDocs::Document.find!(:name, 'Resume.doc')
job = document_one.compare!(document_two)
sleep(5) # wait for server to finish comparing
result = job.documents!.first
result.changes!

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String) 


517
518
519
520
521
522
523
524
525
526
527
528
529
 
# File 'lib/groupdocs/document.rb', line 517

def changes!(access = {})
  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/comparison/{{client_id}}/comparison/changes"
  end
  api.add_params(resultFileId: file.guid)
  json = api.execute!

  json[:changes].map do |change|
    Document::Change.new(change)
  end
end

#compare!(document, access = {}) ⇒ GroupDocs::Job

Schedules a job for comparing document with given.

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

Raises:

  • (ArgumentError) —

    if document is not GroupDocs::Document object



487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/groupdocs/document.rb', line 487

def compare!(document, access = {})
  document.is_a?(GroupDocs::Document) or raise ArgumentError,
    "Document should be GroupDocs::Document object, received: #{document.inspect}"

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/comparison/{{client_id}}/comparison/compare"
  end
  api.add_params(source: file.guid, target: document.file.guid)
  json = api.execute!

  Job.new(id: json[:job_id])
end

#convert!(format, options = {}, access = {}) ⇒ GroupDocs::Job

Converts document to given format.

Examples:

document = GroupDocs::Document.find!(:name, 'CV.doc')
job = document.convert!(:docx)
sleep(5) # wait for server to finish converting
original_document = job.documents!.first
converted_file = original_file.outputs.first
converted_file.download!(File.dirname(__FILE__))

Parameters:

  • format (Symbol)
  • options (Hash) (defaults to: {})
  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (options):

  • :email_results (Boolean) —

    Set to true if converted document should be emailed

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/groupdocs/document.rb', line 303

def convert!(format, options = {}, access = {})
  options.merge!(new_type: format)

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/async/{{client_id}}/files/#{file.guid}"
  end
  api.add_params(options)
  json = api.execute!

  Job.new(id: json[:job_id])
end

#create_questionnaire!(questionnaire, access = {}) ⇒ GroupDocs::Questionnaire

Creates questionnaire and adds it to document.

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

Raises:

  • (ArgumentError) —

    if questionnaire is not GroupDocs::Questionnaire object



401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/groupdocs/document.rb', line 401

def create_questionnaire!(questionnaire, access = {})
  questionnaire.is_a?(GroupDocs::Questionnaire) or raise ArgumentError,
    "Questionnaire should be GroupDocs::Questionnaire object, received: #{questionnaire.inspect}"

  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/merge/{{client_id}}/files/#{file.guid}/questionnaires"
    request[:request_body] = questionnaire.to_hash
  end.execute!

  questionnaire.id = json[:questionnaire_id]
  questionnaire
end

#datasource!(datasource, options, access = {}) ⇒ GroupDocs::Job

Creates new job to merge datasource into document.

Parameters:

  • datasource (GroupDocs::DataSource)
  • options (Hash)
  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (options):

  • :new_type (Boolean) —

    New file format type

  • :email_results (Boolean) —

    Set to true if converted document should be emailed

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

Raises:

  • (ArgumentError) —

    if datasource is not GroupDocs::DataSource object

  • (ArgumentError) —

    if options does not contain :new_type and/or :email_results



332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/groupdocs/document.rb', line 332

def datasource!(datasource, options, access = {})
  datasource.is_a?(GroupDocs::DataSource) or raise ArgumentError,
    "Datasource should be GroupDocs::DataSource object, received: #{datasource.inspect}"
  (options[:new_type].nil? || options[:email_results].nil?) and raise ArgumentError,
    "Both :new_type and :email_results should be passed, received: #{options.inspect}"

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/merge/{{client_id}}/files/#{file.guid}/datasources/#{datasource.id}"
  end
  api.add_params(options)
  json = api.execute!

  Job.new(id: json[:job_id])
end

#details!(access = {}) ⇒ Hash

Returns document details.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

  • (Hash) 


466
467
468
469
470
471
472
473
474
 
# File 'lib/groupdocs/document.rb', line 466

def details!(access = {})
  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/comparison/{{client_id}}/comparison/document"
  end
  api.add_params(guid: file.guid)
  api.execute!
end

#fields!(access = {}) ⇒ Array<GroupDocs::Document::Field>

Returns an array of document fields.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/groupdocs/document.rb', line 206

def fields!(access = {})
  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/doc/{{client_id}}/files/#{file.guid}/fields"
  end
  api.add_params(include_geometry: true)
  json = api.execute!

  json[:fields].map do |field|
    Document::Field.new(field)
  end
end

#formats!(access = {}) ⇒ Array<Symbol>

Returns array of file formats document can be converted to.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

  • (Array<Symbol>) 


159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/groupdocs/document.rb', line 159

def formats!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/doc/{{client_id}}/files/#{file.id}/formats"
  end.execute!

  json[:types].split(';').map do |format|
    format.downcase.to_sym
  end
end

#metadata!(access = {}) ⇒ GroupDocs::Document::MetaData

Returns document metadata.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/groupdocs/document.rb', line 179

def metadata!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/doc/{{client_id}}/files/#{file.id}/metadata"
  end.execute!

  Document::MetaData.new do |metadata|
    metadata.id = json[:id]
    metadata.guid = json[:guid]
    metadata.page_count = json[:page_count]
    metadata.views_count = json[:views_count]
    if json[:last_view]
      metadata.last_view = json[:last_view]
      metadata.last_view.document = self
    end
  end
end

#questionnaires!(access = {}) ⇒ Array<GroupDocs::Questionnaire>

Returns an array of questionnaires.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



357
358
359
360
361
362
363
364
365
366
367
 
# File 'lib/groupdocs/document.rb', line 357

def questionnaires!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/merge/{{client_id}}/files/#{file.guid}/questionnaires"
  end.execute!

  json[:questionnaires].map do |questionnaire|
    Questionnaire.new(questionnaire)
  end
end

#remove_questionnaire!(questionnaire, access = {}) ⇒ Object

Detaches questionnaire from document.

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Raises:

  • (ArgumentError) —

    if questionnaire is not GroupDocs::Questionnaire object



426
427
428
429
430
431
432
433
434
435
 
# File 'lib/groupdocs/document.rb', line 426

def remove_questionnaire!(questionnaire, access = {})
  questionnaire.is_a?(GroupDocs::Questionnaire) or raise ArgumentError,
    "Questionnaire should be GroupDocs::Questionnaire object, received: #{questionnaire.inspect}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :DELETE
    request[:path] = "/merge/{{client_id}}/files/#{file.guid}/questionnaires/#{questionnaire.id}"
  end.execute!
end

#respond_to?(method) ⇒ Boolean

Returns:

  • (Boolean) 


539
540
541
 
# File 'lib/groupdocs/document.rb', line 539

def respond_to?(method)
  super or file.respond_to?(method)
end

#sharers!(access = {}) ⇒ Array<GroupDocs::User>

Returns an array of users a document is shared with.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/groupdocs/document.rb', line 228

def sharers!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/doc/{{client_id}}/files/#{file.id}/accessinfo"
  end.execute!

  json[:sharers].map do |user|
    User.new(user)
  end
end

#sharers_clear!(access = {}) ⇒ Object

Clears sharers list.

Parameters:

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

  • nil



276
277
278
279
280
281
282
 
# File 'lib/groupdocs/document.rb', line 276

def sharers_clear!(access = {})
  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :DELETE
    request[:path] = "/doc/{{client_id}}/files/#{file.id}/sharers"
  end.execute![:shared_users]
end

#sharers_set!(emails, access = {}) ⇒ Array<GroupDocs::User>

Sets document sharers to given emails.

If empty array or nil passed, clears sharers.

Parameters:

  • emails (Array) —

    List of email addresses to share with

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

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/groupdocs/document.rb', line 251

def sharers_set!(emails, access = {})
  if emails.nil? || emails.empty?
    sharers_clear!(access)
  else
    json = Api::Request.new do |request|
      request[:access] = access
      request[:method] = :PUT
      request[:path] = "/doc/{{client_id}}/files/#{file.id}/sharers"
      request[:request_body] = emails
    end.execute!

    json[:shared_users].map do |user|
      User.new(user)
    end
  end
end