SecureForm


Please, note this is a deprecated version of VGS forms library, use VGS Collect instead.


Why you should migrate to VGS Collect?

VGS Collect - is a new version of SecureForm. It will give you access to the new features and improvements we are currently working on. You can use our new library to get the best experience with VGS.

How to migrate?

It’s very easy and requires the following steps.

Step #1. Replace a link to JS library inside your application to the new one generated for your organization:

<!-- Example of an old JS link -->
<script type="text/javascript" src="https://js.verygoodvault.com/js-vgfield-2/<my-organization>.js"></script>

<!-- Example of a new JS link -->
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/1/<my-organization>.js"></script>

Step #2. Change the constructor name from SecureForm.create() to VGSCollect.create():

// Old constructor
SecureForm.create(environment, onUpdateCallback) → Form

// New constructor
VGSCollect.create(environment, onUpdateCallback) → Form

Embedded Fields

Library summary

The SecureForm library is a javascript library that allows you to integrate secure fields with non-secure fields in your page. The secure fields behave like traditional input fields while preventing access to the unsecured data.

Once the fields are initialized the library communicates the state of the fields through a JavaScript callback. The state object includes information about the validity, focused value and if the user has entered information in the field.

Configuration

The library is configured with a whitelist of VGS vaults that it can submit information to. Please let us know if you would like a secureform generated for you exclusive to your organization.

Example javascript file

<script type="text/javascript" src="https://js.verygoodvault.com/js-vgfield-2/my-organization.js"></script>

SecureForm JS Library

SecureForm.create(environment, onUpdateCallback)→ Form

This method is the single entry point into the library. It initializes and returns a Form object.

Arguments

environment String
Name of one of the domains in the whitelist that this form will submit to.

onUpdateCallback Function
Callback that will be called whenever the form state changes. It receives the state object representing the current state.

Returns

Form
Initialized secure form

Form#field(selector, properties)→ Field

Usage example:

secureForm.field('#my-cool-parent', {
  'successColor': '#3c763d',
  'errorColor': '#a94442',
  'lineHeight': '1.5rem',
  'fontSize': '24px',
  'fontFamily': 'Comic Sans',
  'color': '#31708f',
  'placeholder': 'Card number',
  'name': 'cc-number',
  'type': 'card-number',
  'validations': \[\],
});

Arguments

selector String
CSS Selector that points to the element where the field will be added

Properties Object

Configuration object

name required Name of the input field. Will be used when submitting the data.
type required Type of the input field.
validations Array of validations that will be used to calculate the isValid state.
placeholder Text displayed when the field is empty.
successColor Text color when the field is valid
errorColor Text color when the field is invalid
color Text color
lineHeight Line height value.
fontSize Size of text.
fontFamily Font family used in the text.

Available Types:

card-number
card-security-code
card-expiration-date
text
textarea
dropdown
checkbox
radio
password
number
zip-code

Examples

Dropdown

form.field('#car-manufacturer .fake-input', {
        type: 'dropdown',
        name: 'car.manufacturer',
        placeholder:"Car manufacturer",
        options: [
          {value: "volvo", text: "Volvo"},
          {value: "saab", text: "Saab"},
          {value: "opel", text: "Opel"},
          {value: "audi", text: "Audi"}
        ],
        defaultValue: "volvo",
        validations: ['required']
});

Checkbox

form.field('#agreement .fake-input', {
        type: 'checkbox',
        name: 'agreement',
        value: "accept",
        validations: [],
});

Radio

form.field('#profile-visible .fake-input', {
    type: 'radio',
    name: 'profile-visible',
    value: "true",
    validations: []

});

Available Validations:

required
validCardExpirationDate
validCardNumber
validCardSecurityCode

Example Replace Serializer Format:

You could use this to format how you want to receive the data.

Example: maybe you want to take a phone number in a text field as XXX-XXX-XXX but don’t want the dashes, the example below shows how to remove them.

serializers: [{name:"replace", options: {old:"-", new:""}}]

Example Get The Last 4 Digits of Credit Card Numbers

Property last4 is only available on card-number type values. last4 is by default null, it only contains a value when the card number is valid.

Example:

const f = SecureForm.create('development', function(state) {
  $('#my-el').val(state["card.number"].last4);
});

Example use for Credit Card Field only:

f.field('#cc-number .fake-input', {
type: 'card-number',
name: 'card.number',
successColor: 'green',
errorColor: 'red',
placeholder: '4111 1111 1111 1111',
validations: ['required', 'validCardNumber'],
serializers: [{name:"replace", options: {old:" ", new:""}}],
 });

Returns

Field
Initialized field

Form#submit(path, options, callback)→ Form

Submits all of the form fields by executing a POST request.

Usage example:

secureForm.submit('/tokenize', {
  serializer: 'deep',
  data: {
    customerEmail: 'joe@example.com',
  },
  headers: {
    'x-application': 'MyApplication 2.8.3',
  },
}, function(status, response) {
  console.log("Response has been received", status, response);
});

Arguments

path String
The path that the form will be submitted to.

options Object
Options object that can include additional serializer, data and request headers.

callback Function
Callback that will be executed when the HTTPRequest is finished. The callback receives the HTTP status code and the data as two arguments. Additionall error handling of any validatiotns not filled out on the press of submit will be raised up on callback in the following pattern

f.submit('/post', {}, function(status, data)  {}, function(errors) {});

Or more specifically for the function(errors):

function defaultErrorHandler(errors){
  for(let field of Object.keys(errors)){
    console.error(field, errors[field].errorMessages);
  }
}

This will provide the form from being submitted to VGS and then your server.


Other Valid serializers are 'flat' and 'deep'.

Field#focus()

Gives browser focus to the input field.

An example: A credit card form

This example uses a development environment which posts to a service that echoes back the request information without aliasing any information.

Styling

Currently to style the iframe, you need to use single classes and ids that the iframe example shows. Using multiple classes will not apply bootstrap themes to the static-input divs. These are sandboxed entries, but we are working to make more customization available in the way secureform looks in fills without manual css.