Class: GroupDocs::Document

Inherits:
Api::Entity show all
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 collapse

ACCESS_MODES = 
{
  private:    0,
  restricted: 1,
  inherited:  2,
  public:     3,
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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



110
111
112
113
114
 
# File 'lib/groupdocs/document.rb', line 110

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.



542
543
544
 
# File 'lib/groupdocs/document.rb', line 542

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

Instance Attribute Details

#file ⇒ Object 



47
48
49
 
# File 'lib/groupdocs/document.rb', line 47

def file
  @file
end

#order ⇒ Object 



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

def order
  @order
end

#output_formats ⇒ Array<Symbol>

Returns output formats in human-readable format.

Returns:

  • (Array<Symbol>) 


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

def output_formats
  @output_formats
end

#outputs ⇒ Object 



51
52
53
 
# File 'lib/groupdocs/document.rb', line 51

def outputs
  @outputs
end

#process_date ⇒ Time

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

Returns:

  • (Time) 


49
50
51
 
# File 'lib/groupdocs/document.rb', line 49

def process_date
  @process_date
end

#status ⇒ Symbol

Converts status to human-readable format.

Returns:

  • (Symbol) 


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

def status
  @status
end

Class Method Details

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

Returns an array of views for all documents.

Parameters:

  • options (Hash) (defaults to: {})
  • 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:



32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/groupdocs/document.rb', line 32

def self.views!(options = {}, 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



124
125
126
127
128
129
130
131
132
 
# File 'lib/groupdocs/document.rb', line 124

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



143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/groupdocs/document.rb', line 143

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: ACCESS_MODES[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



382
383
384
385
386
387
388
389
390
391
 
# File 'lib/groupdocs/document.rb', line 382

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:



448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
 
# File 'lib/groupdocs/document.rb', line 448

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!

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

#changes!(access = {}) ⇒ Object

Returns an array of changes in document.

Examples:

document_one = GroupDocs::Storage::Folder.list![0].to_document
document_two = GroupDocs::Storage::Folder.list![1].to_document
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) 


524
525
526
527
528
529
530
531
532
533
534
535
536
 
# File 'lib/groupdocs/document.rb', line 524

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



494
495
496
497
498
499
500
501
502
503
504
505
506
507
 
# File 'lib/groupdocs/document.rb', line 494

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::Storage::Folder.list!.first.to_document
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:



309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/groupdocs/document.rb', line 309

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



404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/groupdocs/document.rb', line 404

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) (defaults to: {})
  • 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



337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/groupdocs/document.rb', line 337

def datasource!(datasource, options = {}, access = {})
  datasource.is_a?(GroupDocs::DataSource) or raise ArgumentError,
    "Datasource should be GroupDocs::DataSource object, received: #{datasource.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) 


473
474
475
476
477
478
479
480
481
 
# File 'lib/groupdocs/document.rb', line 473

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:



212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/groupdocs/document.rb', line 212

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


165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/groupdocs/document.rb', line 165

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].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:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/groupdocs/document.rb', line 185

def metadata!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/doc/{{client_id}}/files/#{file.guid}/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:



360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/groupdocs/document.rb', line 360

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



429
430
431
432
433
434
435
436
437
438
 
# File 'lib/groupdocs/document.rb', line 429

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) 


546
547
548
 
# File 'lib/groupdocs/document.rb', line 546

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:



234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/groupdocs/document.rb', line 234

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



282
283
284
285
286
287
288
 
# File 'lib/groupdocs/document.rb', line 282

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:



257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/groupdocs/document.rb', line 257

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