Class: GroupDocs::Signature::Form

Inherits:
Api::Entity show all
Extended by:
ResourceMethods
Includes:
Api::Helpers::SignaturePublic, DocumentMethods, EntityMethods, FieldMethods
Defined in:
lib/groupdocs/signature/form.rb

Constant Summary collapse

STATUSES = 
{
  :draft       => -1,
  :in_progress =>  1,
  :completed   =>  2,
  :archived    =>  3,
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ResourceMethods

resources!

Methods included from FieldMethods

#assign_field!, #delete_field!, #delete_field_location!, #modify_field!

Methods included from DocumentMethods

#add_document!, #remove_document!

Methods included from EntityMethods

#delete!, included, #modify!, #rename!

Methods inherited from Api::Entity

#initialize, #inspect, #to_hash

Methods included from Api::Helpers::Accessor

#alias_accessor

Constructor Details

This class inherits a constructor from GroupDocs::Api::Entity

Instance Attribute Details

#canParticipantDownloadForm ⇒ Object 



98
99
100
 
# File 'lib/groupdocs/signature/form.rb', line 98

def canParticipantDownloadForm
  @canParticipantDownloadForm
end

#createdTimeStamp ⇒ Object 



86
87
88
 
# File 'lib/groupdocs/signature/form.rb', line 86

def createdTimeStamp
  @createdTimeStamp
end

#documentsCount ⇒ Object 



90
91
92
 
# File 'lib/groupdocs/signature/form.rb', line 90

def documentsCount
  @documentsCount
end

#documentsPages ⇒ Object 



92
93
94
 
# File 'lib/groupdocs/signature/form.rb', line 92

def documentsPages
  @documentsPages
end

#fieldsInFinalFileName ⇒ Object 



96
97
98
 
# File 'lib/groupdocs/signature/form.rb', line 96

def fieldsInFinalFileName
  @fieldsInFinalFileName
end

#id ⇒ Object 



78
79
80
 
# File 'lib/groupdocs/signature/form.rb', line 78

def id
  @id
end

#name ⇒ Object 



80
81
82
 
# File 'lib/groupdocs/signature/form.rb', line 80

def name
  @name
end

#ownerGuid ⇒ Object 



82
83
84
 
# File 'lib/groupdocs/signature/form.rb', line 82

def ownerGuid
  @ownerGuid
end

#participantsCount ⇒ Object 



94
95
96
 
# File 'lib/groupdocs/signature/form.rb', line 94

def participantsCount
  @participantsCount
end

#status ⇒ Symbol

Converts status to human-readable format.

Returns:

  • (Symbol) 


100
101
102
 
# File 'lib/groupdocs/signature/form.rb', line 100

def status
  @status
end

#statusDateTime ⇒ Object 



88
89
90
 
# File 'lib/groupdocs/signature/form.rb', line 88

def statusDateTime
  @statusDateTime
end

#templateGuid ⇒ Object 



84
85
86
 
# File 'lib/groupdocs/signature/form.rb', line 84

def templateGuid
  @templateGuid
end

#waterMarkImage ⇒ Object 



104
105
106
 
# File 'lib/groupdocs/signature/form.rb', line 104

def waterMarkImage
  @waterMarkImage
end

#waterMarkText ⇒ Object 



102
103
104
 
# File 'lib/groupdocs/signature/form.rb', line 102

def waterMarkText
  @waterMarkText
end

Class Method Details

.all!(options = {}, access = {}) ⇒ Array<GroupDocs::Signature::Envelope>

Returns a list of all forms.

Parameters:

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

    Hash of options

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

    Access credentials

Options Hash (options):

  • :page (Integer) —

    Page to start with

  • :records (Integer) —

    How many items to list

  • :status_id (Integer) —

    Filter by status identifier

  • :document (String) —

    Filter by document GUID

  • :date (String) —

    Filter by date

  • :name (String) —

    Filter by name

Options Hash (access):

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

Returns:



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/groupdocs/signature/form.rb', line 35

def self.all!(options = {}, access = {})
  status_id = options.delete(:status_id)
  options[:statusId] = status_id if status_id

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = '/signature/{{client_id}}/forms'
  end
  api.add_params(options)
  json = api.execute!

  json[:forms].map do |form|
    new(form)
  end
end

.get!(id, options = {}, access = {}) ⇒ GroupDocs::Signature::Form

Returns form by its identifier.

Parameters:

  • id (String)
  • options (Hash) (defaults to: {})
  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (options):

  • :public (Boolean) —

    Defaults to false

Options Hash (access):

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

Returns:



63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/groupdocs/signature/form.rb', line 63

def self.get!(id, options = {}, access = {})
  if options[:public]
    json = Api::Request.new do |request|
      request[:access] = access
      request[:method] = :GET
      request[:path] = "/signature/public/forms/#{id}"
    end.execute!

    new(json[:form])
  else
    super(id, access)
  end
end

Instance Method Details

#add_field!(field, document, opts = {}, access = {}) ⇒ Object

Adds field for document.

Examples:

form = GroupDocs::Signature::Form.get!("g94h5g84hj9g4gf23i40j")
field = GroupDocs::Signature::Field.get!.detect { |f| f.type == :signature }
field.location = { location_x: 0.1, location_y: 0.1, page: 1 }
document = form.documents!.first
form.add_field! field, document

Parameters:

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if field is not GroupDocs::Signature::Field

  • (ArgumentError) —

    if document is not GroupDocs::Document

  • (ArgumentError) —

    if field does not specify location



296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/groupdocs/signature/form.rb', line 296

def add_field!(field, document, opts = {}, access = {})
  field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
    "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
  document.is_a?(GroupDocs::Document) or raise ArgumentError,
    "Document should be GroupDocs::Document object, received: #{document.inspect}"
  field.location or raise ArgumentError,
    "You have to specify field location, received: #{field.location.inspect}"

  opts[:force_new_field] = true if opts[:force_new_field].nil?
  payload = field.to_hash # field itself
  payload.merge!(field.location.to_hash) # location should added in plain view (i.e. not "location": {...})
  payload.merge!(:forceNewField => opts[:force_new_field]) # create new field flag

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/signature/{{client_id}}/forms/#{id}/documents/#{document.file.guid}/field/#{field.id}"
    request[:request_body] = payload
  end.execute!
end

#archive!(access = {}) ⇒ Object

Archives completed form.

Parameters:

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

    Access credentials

Options Hash (access):

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


243
244
245
246
247
248
249
 
# File 'lib/groupdocs/signature/form.rb', line 243

def archive!(access = {})
  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/forms/#{id}/archive"
  end.execute!
end

#complete!(access = {}) ⇒ Object

Completes form.

Parameters:

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

    Access credentials

Options Hash (access):

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


228
229
230
231
232
233
234
 
# File 'lib/groupdocs/signature/form.rb', line 228

def complete!(access = {})
  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/forms/#{id}/complete"
  end.execute!
end

#create!(options = {}, access = {}) ⇒ Object

Creates form.

Examples:

form = GroupDocs::Signature::Form.new
form.name = "Form"
form.create! template

Parameters:

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

    Hash of options

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

    Access credentials

Options Hash (options):

  • :template_id (String) —

    Template GUID to create form from

  • :assembly_id (Integer) —

    Questionnaire identifier to create form from

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if template is not GroupDocs::Signature::Template



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/groupdocs/signature/form.rb', line 162

def create!(options = {}, access = {})
  template_id = options.delete(:template_id)
  assembly_id = options.delete(:assembly_id)
  options[:templateId] = template_id if template_id
  options[:assemblyId] = assembly_id if assembly_id

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = '/signature/{{client_id}}/form'
    request[:request_body] = to_hash
  end
  api.add_params(options.merge(:name => name))
  json = api.execute!

  self.id = json[:form][:id]
end

#documents!(options = {}, access = {}) ⇒ Array<GroupDocs::Document>

Returns documents array.

Parameters:

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

    Access credentials

Options Hash (options):

  • :public (Boolean) —

    Defaults to false

Options Hash (access):

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

Returns:



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/groupdocs/signature/form.rb', line 190

def documents!(options = {}, access = {})
  client_id = client_id(options[:public])

  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/signature/#{client_id}/forms/#{id}/documents"
  end.execute!

  json[:documents].map do |document|
    id = document[:documentId] || document[:id]
    file = Storage::File.new(:guid => id, :name => document[:name])
    Document.new(document.merge(:file => file))
  end
end

#fields!(document, access = {}) ⇒ Object

Returns an array of fields for document per participant.

Parameters:

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if document is not GroupDocs::Document



260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/groupdocs/signature/form.rb', line 260

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

  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/signature/{{client_id}}/forms/#{id}/documents/#{document.file.guid}/fields"
  end.execute!

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

#fields_in_final_file_name ⇒ Array<String>

Converts field names to human-readable format.

Returns:

  • (Array<String>) 


142
143
144
 
# File 'lib/groupdocs/signature/form.rb', line 142

def fields_in_final_file_name
  @fieldsInFinalFileName.split(',') if @fieldsInFinalFileName
end

#fields_in_final_file_name=(fields) ⇒ Object

Converts array of field names to machine-readable format.

Parameters:

  • fields (Array<String>) 


130
131
132
133
134
135
136
 
# File 'lib/groupdocs/signature/form.rb', line 130

def fields_in_final_file_name=(fields)
  if fields.is_a?(Array)
    fields = fields.join(',')
  end

  @fieldsInFinalFileName = fields
end

#modify_field_location!(location, field, document, recipient, access = {}) ⇒ Object

Modifies field location.

Examples:

Modify field location in template

form = GroupDocs::Signature::Form.get!("g94h5g84hj9g4gf23i40j")
document = form.documents!.first
field = form.fields!(document).first
location = field.locations.first
location.x = 0.123
location.y = 0.123
location.page = 2
form.modify_field_location! location, field, document

Parameters:

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if location is not GroupDocs::Signature::Field::Location

  • (ArgumentError) —

    if field is not GroupDocs::Signature::Field

  • (ArgumentError) —

    if document is not GroupDocs::Document



340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/groupdocs/signature/form.rb', line 340

def modify_field_location!(location, field, document, recipient, access = {})
  location.is_a?(GroupDocs::Signature::Field::Location) or raise ArgumentError,
    "Location should be GroupDocs::Signature::Field::Location object, received: #{location.inspect}"
  field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
    "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
  document.is_a?(GroupDocs::Document) or raise ArgumentError,
    "Document should be GroupDocs::Document object, received: #{document.inspect}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/forms/#{id}/documents/#{document.file.guid}/fields/#{field.id}/locations/#{location.id}"
    request[:request_body] = location.to_hash
  end.execute!
end

#publish!(access = {}) ⇒ Object

Publishes form.

Parameters:

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

    Access credentials

Options Hash (access):

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


213
214
215
216
217
218
219
 
# File 'lib/groupdocs/signature/form.rb', line 213

def publish!(access = {})
  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/forms/#{id}/publish"
  end.execute!
end

#update_from_template!(template, access = {}) ⇒ Object

Updates form adding fields from template.

Parameters:

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if template is not GroupDocs::Signature::Template



365
366
367
368
369
370
371
372
373
374
 
# File 'lib/groupdocs/signature/form.rb', line 365

def update_from_template!(template, access = {})
  template.is_a?(GroupDocs::Signature::Template) or raise ArgumentError,
    "Template should be GroupDocs::Signature::Template object, received: #{template.inspect}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/signature/{{client_id}}/forms/#{form.id}/templates/#{template.id}"
  end.execute!
end