Module: GroupDocs::Signature::FieldMethods

Included in:
Envelope, Form, Template
Defined in:
lib/groupdocs/signature/shared/field_methods.rb

Overview

Envelope and template entities share the same set of field methods.

See Also:

Instance Method Summary collapse

Instance Method Details

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

Adds field for document and recipient.

Examples:

Add field to template

template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
field = GroupDocs::Signature::Field.get!.detect { |f| f.type == :signature }
field.location = { location_x: 0.1, location_y: 0.1, page: 1 }
field.name = "Signer"
document = template.documents!.first
recipient = template.recipients!.first
template.add_field! field, document, recipient

Add field to envelope

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
field = GroupDocs::Signature::Field.get!.detect { |f| f.type == :signature }
field.name = "Signer"
field.location = { location_x: 0.1, location_y: 0.1, page: 1 }
document = envelope.documents!.first
recipient = envelope.recipients!.first
envelope.add_field! field, document, recipient

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 recipient is not GroupDocs::Signature::Recipient

  • (ArgumentError) —

    if field does not specify location



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 95

def add_field!(field, document, recipient, 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}"
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.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}}/#{class_name.pluralize}/#{id}/documents/#{document.file.guid}/recipient/#{recipient.id}/field/#{field.id}"
    request[:request_body] = payload
  end.execute!
end

#assign_field!(field, document, assign_from, assign_to, access = {}) ⇒ Object

Assigns document field to new recipient.

Examples:

Assign template field

template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
document = template.documents!.first
recipient_one = template.recipients![0]
recipient_two = template.recipients![1]
field = template.fields!(document, recipient).first
template.assign_field! field, document, recipient_one, recipient_two

Assign envelope field

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient_one = envelope.recipients![0]
recipient_two = envelope.recipients![1]
field = envelope.fields!(document, recipient).first
envelope.assign_field! field, document, recipient_one, recipient_two

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



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 195

def assign_field!(field, document, assign_from, assign_to, 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}"
  assign_from.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Assign from should be GroupDocs::Signature::Recipient object, received: #{assign_from.inspect}"
  assign_to.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Assign to should be GroupDocs::Signature::Recipient object, received: #{assign_to.inspect}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/signature/{{client_id}}/#{class_name.pluralize}/#{id}/documents/#{document.file.guid}/field/#{field.id}"
    request[:request_body] = { :currentRecipientId => assign_from.id, :newRecipientId => assign_to.id }
  end.execute!
end

#delete_field!(field, access = {}) ⇒ Object

Deletes field.

Examples:

Delete field from template

template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
document = template.documents!.first
recipient = template.recipients!.first
field = template.fields!(document, recipient).first
template.delete_field! field

Delete field from envelope

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient = envelope.recipients!.first
field = envelope.fields!(document, recipient).first
envelope.delete_field! field

Parameters:

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if field is not GroupDocs::Signature::Field



236
237
238
239
240
241
242
243
244
245
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 236

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

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :DELETE
    request[:path] = "/signature/{{client_id}}/#{class_name.pluralize}/#{id}/fields/#{field.id}"
  end.execute!
end

#delete_field_location!(location, field, access = {}) ⇒ Object

Deletes field location.

Examples:

Delete field location in template

template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
document = template.documents!.first
recipient = template.recipients!.first
field = template.fields!(document, recipient).first
location = field.locations.first
template.delete_field_location! location, field

Delete field location in envelope

envelope = GroupDocs::Signature::Envelop.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient = envelope.recipients!.first
field = envelope.fields!(document, recipient).first
location = field.locations.first
envelope.delete_field_location! location, field

Delete field location in form

form = GroupDocs::Signature::Form.get!("g94h5g84hj9g4gf23i40j")
document = form.documents!.first
field = form.fields!(document).first
location = field.locations.first
form.delete_field_location! location, field

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



339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 339

def delete_field_location!(location, field, 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}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :DELETE
    request[:path] = "/signature/{{client_id}}/#{class_name.pluralize}/#{id}/fields/#{field.id}/locations/#{location.id}"
  end.execute!
end

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

Changed in release 1.5.8

Returns an array of fields for document and recipient.

Examples:

Get fields from template

template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
document = template.documents!.first
recipient = template.recipients!.first
template.fields! document, recipient

Get fields from envelope

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient = envelope.recipients!.first
envelope.fields! document, recipient

Parameters:

Options Hash (options):

  • :public (Boolean) —

    Defaults to false

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if document is not GroupDocs::Document

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 40

def fields!(document, recipient, options = {}, access = {})

  document.is_a?(GroupDocs::Document) or raise ArgumentError,
    "Document should be GroupDocs::Document object, received: #{document.inspect}"
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

  client_id = client_id(options[:public])
  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/signature/#{client_id}/#{class_name.pluralize}/#{id}/fields"
  end
  api.add_params(:document => document.file.guid, :recipient => recipient.id, :field => options[:field] )
  json = api.execute!

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

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

Modifies document field.

Examples:

Modify template field

template = GroupDocs::Signature::Template.get!("g94h5g84hj9g4gf23i40j")
document = template.documents!.first
recipient = template.recipients!.first
field = template.fields!(document, recipient).first
field.name = "Field"
template.modify_field! field, document

Modify envelope field

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient = envelope.recipients!.first
field = envelope.fields!(document, recipient).first
field.name = "Field"
envelope.modify_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



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 145

def modify_field!(field, document, recipient, 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}"
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

  # prepare payload
  payload = field.to_hash # field itself
  payload.delete(:locations) # remove locations array
  payload.merge!(field.locations.first.to_hash) # location should added in plain view (i.e. not "locations": [{...}])

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

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

Modifies field location.

Examples:

Modify field location in template

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

Modify field location in envelope

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

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

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 287

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}"
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

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