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 }
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.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



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 86

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



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 184

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



225
226
227
228
229
230
231
232
233
234
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 225

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



325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 325

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, access = {}) ⇒ Object

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 (access):

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

Raises:

  • (ArgumentError) —

    if document is not GroupDocs::Document

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



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

def fields!(document, recipient, 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}"

  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)
  json = api.execute!

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

#modify_field!(field, document, 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



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 136

def modify_field!(field, document, 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}"

  # 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}/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



273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 273

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