Module: GroupDocs::Signature::FieldMethods

Included in:
Envelope, 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, 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.name == "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.name == "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



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

def add_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}"
  field.location or raise ArgumentError,
    "You have to specify field location, received: #{field.location.inspect}"

  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: true) # create new field flag

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/signature/{{client_id}}/#{pluralized_class_name}/#{id}/documents/#{document.file.guid}/recipient/#{recipient.id}/field/#{field.id}"
    request[:request_body] = payload
  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



174
175
176
177
178
179
180
181
182
183
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 174

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

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



267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 267

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



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

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



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 132

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



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/groupdocs/signature/shared/field_methods.rb', line 222

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}}/#{pluralized_class_name}/#{id}/documents/#{document.file.guid}/recipient/#{recipient.id}/fields/#{field.id}/locations/#{location.id}"
    request[:request_body] = location.to_hash
  end.execute!
end