module GroupDocs::Signature::FieldMethods

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

@see GroupDocs::Signature::Envelope @see GroupDocs::Signature::Form @see GroupDocs::Signature::Template

Public Instance Methods

add_field!(field, document, recipient, opts = {}, access = {}) click to toggle source

Adds field for document and recipient.

@example 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

@example 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

@param [GroupDocs::Signature::Field] field @param [GroupDocs::Document] document @param [GroupDocs::Signature::Recipient] recipient @param [Hash] options @option options [Boolean] :force_new_field Set to true to force new field create @param [Hash] access Access credentials @option access [String] :client_id @option access [String] :private_key @raise [ArgumentError] if field is not GroupDocs::Signature::Field @raise [ArgumentError] if document is not GroupDocs::Document @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient @raise [ArgumentError] if field does not specify location

# 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 = {}) click to toggle source

Assigns document field to new recipient.

@example 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

@example 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

@param [GroupDocs::Signature::Field] field @param [GroupDocs::Document] document @param [GroupDocs::Signature::Recipient] assign_from @param [GroupDocs::Signature::Recipient] assign_to @param [Hash] access Access credentials @option access [String] :client_id @option access [String] :private_key @raise [ArgumentError] if field is not GroupDocs::Signature::Field @raise [ArgumentError] if document is not GroupDocs::Document

# 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 = {}) click to toggle source

Deletes field.

@example 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

@example 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

@param [GroupDocs::Signature::Field] field @param [Hash] access Access credentials @option access [String] :client_id @option access [String] :private_key @raise [ArgumentError] if field is not GroupDocs::Signature::Field

# 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 = {}) click to toggle source

Deletes field location.

@example 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

@example 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

@example 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

@param [GroupDocs::Signature::Field::Location] location @param [GroupDocs::Signature::Field] field @param [Hash] access Access credentials @option access [String] :client_id @option access [String] :private_key @raise [ArgumentError] if location is not GroupDocs::Signature::Field::Location @raise [ArgumentError] if field is not GroupDocs::Signature::Field

# 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 = {}) click to toggle source

Changed in release 1.5.8

Returns an array of fields for document and recipient.

@example Get fields from template

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

@example Get fields from envelope

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

@param [GroupDocs::Document] document @param [GroupDocs::Signature::Recipient] recipient @param [String] field_guid Field GUID @param [Hash] options @option options [Boolean] :public Defaults to false @param [Hash] access Access credentials @option access [String] :client_id @option access [String] :private_key @raise [ArgumentError] if document is not GroupDocs::Document @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient

# 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 = {}) click to toggle source

Modifies document field.

@example 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

@example 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

@param [GroupDocs::Signature::Field] field @param [GroupDocs::Document] document @param [Hash] access Access credentials @option access [String] :client_id @option access [String] :private_key @raise [ArgumentError] if field is not GroupDocs::Signature::Field @raise [ArgumentError] if document is not GroupDocs::Document

# 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 = {}) click to toggle source

Modifies field location.

@example 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

@example 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

@param [GroupDocs::Signature::Field::Location] location @param [GroupDocs::Signature::Field] field @param [GroupDocs::Document] document @param [GroupDocs::Signature::Recipient] recipient @param [Hash] access Access credentials @option access [String] :client_id @option access [String] :private_key @raise [ArgumentError] if location is not GroupDocs::Signature::Field::Location @raise [ArgumentError] if field is not GroupDocs::Signature::Field @raise [ArgumentError] if document is not GroupDocs::Document @raise [ArgumentError] if recipient is not GroupDocs::Signature::Recipient

# 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