Global_ps Object

This reference documents the properties and methods available on the global _ps object, and details on using the async queue.

Properties

_ps.Sites Object <String, Site>

An object used internally by _ps to store and reference all of the Site objects. Rather than accessing it directly, you should use one of the methods below, such as getByName() or remove().

_ps.loaded Boolean

A boolean flag indicating if ps.js has finished loading and is ready to use.

Methods

create

Creates a new Site object.

_ps.create(access_id, [name], [options]);

Arguments

Name

Required

Type

Description

access_id

True

String

The unique access_id assigned to your PactSafe Site, which can be found on the Site Settings page within PactSafe.

name

False

String

A name to assign to the Site object. This property is optional for the initial Site, and will default to 's0', but a name must be provided for any additional Sites.

options

False

Object

An object containing properties to set on the Site.

Returns

SiteThe created Site object.

Examples

// Creates a Site with the default configuration.
_ps.create('0207a846-d9bf-4b13-8430-1344e86ff7b1');
// Creates a Site named "pactsafe".
_ps.create('0207a846-d9bf-4b13-8430-1344e86ff7b1', 'pactsafe');
// Creates a Site named "pactsafe", enables localization
// and sets the signer_id to "[email protected]".
_ps.create('0207a846-d9bf-4b13-8430-1344e86ff7b1', 'pactsafe', {
    localized: true,
    signer_id: '[email protected]'
});
// Creates a Site with the default name and disables sending.
_ps.create('0207a846-d9bf-4b13-8430-1344e86ff7b1', null, {
  disable_sending: true
});

remove

Removes a site Object by name.

// The name of your PactSafe Site object.
const name = 'mySite';

_ps.remove(name);

Arguments

NAMEREQUIREDTYPEDESCRIPTION
nameTrueStringThe name of the Site to remove.

Returns

No Return Value

Examples

// Removes the default Site.
_ps.remove('s0');
// Removes a Site named "pactsafe".
_ps.remove('pactsafe');

getByName

Returns a Site object by name.

_ps.getByName(name);

Arguments

NAMEREQUIREDTYPEDESCRIPTION
nameTrueStringThe name of the Site to return.

Returns

SiteThe Site object.

Examples

// Returns a Site that was given the default name.
var site = _ps.getByName('s0');

getAll

Returns all of the Site objects that have been created.

_ps.getAll();

Arguments

No Arguments

Returns

Array<Site>An array containing all of the Site objects.

Examples

// Returns all Sites that have been created.
var sites = _ps.getAll();

getByKey

Returns a Group object by key.

_ps.getByKey(key);

Arguments

NAMEREQUIREDTYPEDESCRIPTION
keyTrueStringThe key of the Group to return.

Returns

BrowsewrapGroup or ClickwrapGroupThe Group object.

Examples

// Returns a Group with the key "login-contracts".
var group = _ps.getByKey('login-contracts');

getAllGroups

Returns all of the Group objects that have been loaded.

_ps.getAllGroups();

Arguments

No Arguments

Returns

Array<BrowsewrapGroup or ClickwrapGroup>An array containing all of the Group objects.

Examples

// Returns all Groups that have been loaded in any Site.
var groups = _ps.getAllGroups();

Event Methods

See the Events reference for a list of available events.

on

Listens for an event to be triggered.

_ps.on(event, callback);

Arguments

NAMEREQUIREDTYPEDESCRIPTION
eventTrueStringThe name of the event to listen for.
callbackTrueFunctionThe callback function to execute when the event is triggered. The arguments that are passed to the function vary between events.

Returns

No Return Value

Examples

// Listens for a Group to be initialized.
_ps.on('initialized', function(key, group) {
  console.log('Group ' + key + ' has been initialized.');
});
// Toggles a form submit button when a Group
// is either validated or invalidated.
_ps.on('valid', function(parameters, group) {
  $('#submit-button').prop('disabled', false);
});
_ps.on('invalid', function(parameters, group) {
  $('#submit-button').prop('disabled', true);
});
// Logs all events to the browser's console.
_ps.on('all', function() {
  console.log(arguments);
});

once

Listens for an event to be triggered once. The event listener is then removed.

_ps.once(event, callback);

Arguments

NAMEREQUIREDTYPEDESCRIPTION
eventTrueStringThe name of the event to listen for.
callbackTrueFunctionThe callback function to execute once the event is triggered. The arguments that are passed to the function vary between events.

Returns

No Return Value

Examples

// Submits the form once the contracts have been accepted.
_ps.once('valid', function(parameters, group) {
  $('#login-form').submit();
});

off

Removes an event listener.

_ps.off([event], [callback]);

Arguments

NAMEREQUIREDTYPEDESCRIPTION
eventFalseStringThe name of the event to remove the listener or listeners from. If blank, all event listeners will be removed from the _ps object.
callbackFalseFunctionThe callback function to remove. If blank, all listeners for the provided event will be removed from the _ps object.

Returns

No Return Value

Examples

// Removes a logging handler that was attached to 'error' events.
_ps.off('error', logger);
// Removes all 'sent' event listeners.
_ps.off('sent');
// Removes all event listeners.
_ps.off();

The Async Queue

_ps()

The async queue is created by the snippet and available for use even before ps.js has finished downloading. The _ps object itself serves as the async command queue function.

Commands can be used to call any method on a Site or Group object asynchronously, forwarding all arguments directly to the method. The ps() function accepts a variety of command formats, which are detailed below.

_ps([siteName.][groupKey:]method, [arg1, arg2, ..., argN]);
_ps([siteName.][groupKey:]method, [parameters]);
_ps(callback);

Arguments

---NAMEREQUIREDTYPEDESCRIPTION
methodTrueStringThe name of the method to invoke on a Site or Group object. To target methods on the default Site, just provide the name of the method. If you have multiple Sites, you will need to prepend the Site's name to the method, separated by a .. To target a Group method, prepend the Group's key, separated by a :.
Option 1arg1, arg2, ..., argNConditionalAnyThe in-line arguments to pass to the method.
Option 2parametersConditionalObjectA single object containing parameter name and value pairs. This format is supported by set, send and retrieve commands.
Option 3callbackTrueFunctionA callback function to execute. All commands in the queue are executed in order, so a callback function can be used to determine when the _ps object is ready, or when the previous set of commands have been run.

Returns

No Return Value

Examples

// Creates a Site.
_ps('create', '0207a846-d9bf-4b13-8430-1344e86ff7b1');
// Sends an "agreed" action from the default Site.
_ps('send', 'agreed', [ 10, 14 ], [ '5589bf606e7b9c1b1deef447', '5589bf606e7b9c1b1deef450' ], 33);
// Sends an "agreed" action from a Site named "pactsafe".
_ps('pactsafe.send', 'agreed', [ 10, 14 ], [ '5589bf606e7b9c1b1deef447', '5589bf606e7b9c1b1deef450' ], 33);
// Sends an "agreed" action with a parameters
// object and an event callback.
_ps('send', 'agreed', {
  contracts: [ 10, 14 ],
  versions: [ '5589bf606e7b9c1b1deef447', '5589bf606e7b9c1b1deef450' ],
  group: 33
  event_callback: function() {
    alert('Action sent.');
  }
});
// Sets the "signer_id" parameter to "[email protected]".
_ps('set', 'signer_id', '[email protected]');
//Sets the properties of the signer
_ps('set', 'custom_data',
{
    first_name: "John",
    last_name: "Walker",
    company_name: "PactSafe",
    title: "Customer Support"
});
// Loads a Group with the key "login-contracts".
_ps('load', 'login-contracts');
//Loads a Group with the key "login-contracts" and passes in custom data for the Signer
_ps('load','login-contracts', {
            custom_data: {
                first_name: "John",
                last_name: "Walker",
                company_name: "PactSafe",
                title: "Customer Support"
            }
});
// Sends an "agreed" action for a Group
// with the key "login-contracts".
_ps('login-contracts:send', 'agreed');
// Adds a callback function to the queue.
_ps(function() {
  alert('All commands have been executed.');
});

Did this page help you?