Skip to content

Z the Zervicepoint JavaScript API

What is Z API?

It is a JavaScript library that contains actions to manipulate fields. It is based on the popular jQuery language and use a similar syntax.

Syntax

Z(selector).action()
  • Z to a access
  • (selector) to find field(s)
  • action() to be performed on the field(s)

Selector

Allows you to select HTML element(s). Use the selector to find HTML elments based on thier identifier or type.

Define the selector within quotation marks, single or double is only a personal preference. When you write your seletor you have to begin with a hash to say that it is an identifier that should be found and matched. The identifier of a field is defined in the form editor of the service/process. As stated it has to be enclosed with quotation marks so it should look lite this, '#telephone'. Then combine it with the access syntax for the library:

Z('#telephone');

You could also use the selector to find type of fields, lets say that you want to perform a action on all sections in a form:

Z('#[type=fieldset]');

Now that we have the selector sorted we can move on to what we actully want to do with the element.

Action

The library has a couple of defined actions that you can use to manipulate the element(s) in your selector. After your selector you have to put a dot and then the action you intend to use like this:

Z('#telephone').hide();

Example

Z('#')

A selector. You can specify either a identifier of a field or filter by type of a field

Z('#FieldName01');

Z('#[type=checkbox]');
Selector

JavaScript selector

Z('form')

A form selector. Use it to disable or enable submit buttons for forms. Available in version 1.10.1229

Z('form').disable();
Form disable

Form disable

Z('form').enable();
Form enable

Form enable

length

Number of fields in a selector

Z('#[type=inputtext]').length;
// Returns the number of fields of type inputtext
Length

selector length

You can also use length to get amount of input in a field

Length of .val()

length of val()

Length is also useful to check if a call action has returned any data, i.e:

var webservice = 'Get-ZPADUser';
var args = {
    Identity: Z('#Identity').val()
}

Z.call(
    webservice,
    args
).done(
    function (data) {
        if (data.length > 0) {
            //write code
        }
    }
);

Here you see that we use length to check that we have atleast 1 object in the array. Length is useful in JavaScript because all elements has this property.

val()

Returns the values from all fields.

If more than one field is selected by the selector, the values are returned as an array

Get value with val()

val()

val(value)

Sets the value of a field

Z('#inputtext1').val('New value');  
// Sets the value of the field inputtext to "New value"

Z('#dropdown5').val(\[1,2,3,6\]);
// Set values in dropdowns.
Set state with val('')

val()

Dynamic dropdowns must implement the validate function and accept an array as search string.

# Example: 

function Validate($config, [string[]]$search) 
{
    foreach($entry in $search) {
        search -config $config -search $entry
    }
}

# Example with SQL Plugin installed

function Validate($config, [string[]]$search) 
{
    $table = Get-SQLTable -Table SomeTable
    $table.rows().obj
        | Where-Object { $search.contains($_.Name) }
        | Select-Object @{Name="Id";Expression={$_.Id } }, 
                        @{Name="Name";Expression={ $_.Name } }
}

children()

Return all child fields (applies to form sections)

Z('#formsection1').children();
get child elements from selector

children

first()

First field in a selector

Z('#[type=inputtext]').first();
// Returns the first field of type inputtext
Get first item in selector

first

last()

Last field in a selector

Z('#[type=inputtext]').last();
// Returns the first field of type inputtext
Get last item in selector

last

get(index)

Get a specific field in a selector using a specific index

Z('#[type=inputtext]').get(3);
// Returns the third field of type inputtext
Get 3 item in selector

get

disable()

Disable all the fields in the selector, available in version 1.10.1229

Z('#formsection1').children().disable();
Disable child item(s) in selector

disable

enable()

Enable all the fields in the selector, available in version 1.10.1229

Z('#formsection1').children().enable();
Enable child item(s) in selector

enable

hide()

Hide all fields in the selector

Z('#mailAddress').hide();
Hide item(s) in selector

hide field

show()

Show all the fields in the selector

Z('#mailAddress').show();
Show item(s) in selector

show field

toggle(visibility)

Toggle the visibility of all fields in the selector. If a value is passed to the action, the visibility will be controlled by this value

Z('#mailAddress').toggle();

Z('#mailAddress').toggle(true);  //change visibility to show for items in selector

Z('#mailAddress').toggle(false); //change visibility to hide for items in selector
Toggle item(s) in selector

toggle field

Use toggle to change visibility from a checkbox, in this example, the checkbox mail will show and hide the field mailAddress

Z('#mail').change(
    function () {
        Z('#mailAddress').toggle();
    }
);
Toggle visibility based on a checkbox

toggle visibility

visible()

Returns true if the selected field is visible (or an array of true/false values if multiple fields are selected). Available from version 1.30.xxxx

Z('#mailAddress').visible();  
// Returns true if the mailAddress field is visible

spin(switch, [message])

Show/hide the loading indicator and optional message for all the fields in the selector, available in version 1.10.1229

Z('#mailAddress').spin(); //show loading indicator for mailAddress

Z('#mailAddress').spin(false); //hide loading indicator for mailAddress

Z('#mailAddress').spin(true, 'Verifying e-mail address...'); //show loading indicator and message
Use spin to display load icon

spin icon

valid(valid, message, force)

Specifies if the field should be marked as valid or not. The first parameter (optional) specifies a boolean if the field should be valid or not. The second parameter specifies a validation message. If the force parameter is true, the field is validated immediately. Otherwise it's validated when the form is submitted or when some text is entered in the field. Available in version 1.13

Z('#mailAddress').valid(false, 'E-mail address is not unique', true);  
// Sets the field as invalid immediately with a custom message

Z('#mailAddress').valid();  
// Sets the field as valid
Use valid to highlight field(s)

valid

isValid()

Returns true if the selected field is valid (or an array of true/false values if multiple fields are selected). Available from version 1.30.xxxx

Z('#mailAddress').isValid();  
// Returns true if the mailAddress field is valid

require(require)

Specifies if the field is required or not. The first parameter (optional boolean) specifies the required state. Available in version 1.13

NOTE: It won't set require to false if required is set in adminWeb. You have to set Z.require(true) in onLoad if you want to remove require via Z-api.

Z('#inputtext').require(false);
// Set the field as not required

Z('#inputtext').require();
// Set the field as required

Code example

Let´s say you have a checkbox or radiobutton both have two state, true/false or yes/no and depending on the state a field should be shown and you want it to be required. In this code example there is a checkbox called mail and if it is true, a field for mail address is shown and it is required.

Z('#mail').change(
    function () {
        if (Z('#mail').val() === true) {
            Z('#mailAddress').show().require();
        } else {
            Z('#mailAddress').hide().require(false);
        }
    }
);
Use require depending on another field

require

add(value, text, isSelected, suppressChange)

Note: The field(s) returned by the selector has to be unrestricted before you can add or remove value(s)

Add value(s) to a drop down (isSelected and suppressChange are optional)

Z('#dropdown1').add('value2', 'Value 2');
// This value has a text that is displayed in the dropdown
use add() to add office to dropdown

add()

Z('#dropdown1').add('value3', 'Value 3', true);
// This value is selected
use add() to add office to dropdown as selected

add()

Z('#dropdown1').add('value4', 'Value4', false, true);
// The OnChange-script will not run

clear()

Clear content of the field(s) in selector

Z('#dropdown1').clear();  
// Clear all values from dropdown1
use clear() to remove value(s) from dropdown

clear()

displayName(displayName)

Gets or sets the display name of the field(s)

var displayName = Z('#role').displayName();
Z('#role').displayName(displayName + " (business)");  
// Adds a character to the displayname
Update display name of a field

displayName()

description(description)

Gets or sets the description of the field(s)

Z('#role').description("Set business role");
Set description of a field

description()

getItems()

Gets all objects in a field (eg. Dropdown, Radio-list) as an array. See getItem() for more details.

Z('#office').getItems();
Get items of a drop down

getItems()

getItem()

Gets the selected object. If used with a dropdown, returns value, text and if the value is selected

If used with another field type, the value and text are set to the same value and isSelected is true

var item = Z('#office').getItem();  
console.log(item.isSelected); // if the item is selected  
console.log(item.text); // Displayname of the item
console.log(item.value); // Value of the item
Get selected item in drop down

getItem()

getCategories()

Gets all available categories as an array of strings (only applies to dynamic dropdown)

var categories = Z('#startday').getCategories();  
Get categories from drop down

getCategories()

getCategory()

Gets the value of the selected category (only applies to dynamic dropdown)

Z('#startday').getCategory();
Get selected category

getCategory()

currentUser

See currentStore for example

currentStore

Access to the current user's username, name, email, language and culture and the currents store's default culture and language settings. Available in version 1.6

Z.currentUser.culture

Z.currentUser.language

Z.currentUser.email // (New UI)

Z.currentUser.name // (New UI)

Z.currentUser.username // (New UI)

Z.currentStore.defaultCulture

Z.currentStore.defaultLanguage

Actions with function

change()

Triggers OnChange event on the field(s)

Z('#mail').change(
    function () {
        Z('#mailAddress').toggle();
    }
);

submit()

Triggers Submit event on the field(s) (does not actually submit the form)

filter(fn())

Filter the selector based on fn() if it returns true or false

Z('#[type=checkbox]').filter(
    function() {
        return this.val(); //evaluates to true or false
    }
);  
// Returns a new selector that only contains checkboxes that are selected

debounce(function(), quietMilliseconds)

Call the specified function only after it has not been called for quietMilliseconds.

Example 1:

function sayHello(str) {
    console.log(str);
}
var sayHelloDebounce = Z.debounce(sayHello, 1000);
sayHelloDebounce('Will be discarded if the next call is made within 1000 milliseconds');
sayHelloDebounce('This will be shown in the console');

Example 2:

var sayHello = Z.debounce(
    function() { 
        console.log('Hello'); 
    }, 1000
);
sayHello();
sayHello();
// if the time between the calls are less than 1000 milliseconds, one 'Hello' will be written to console, otherwise two 'Hello' will be written 

call()

Call a client web service function and perform actions on the data returned

Z.call( name [,data] [,settings] )

name

Type: String
Name of the data source.

data

Type: PlainObject
A set of key/value pairs matching the datasources parameters.

Returns

zXHR object that provides callback functions when the ajax request is completed.

zXHR support the following actions

Default action to run after call(), the parameter you pass as input to your function is an object with the result from the web service call

done(
    function (data) {
        alert(data);
    }
);

If the call() action should fail, what do you want to happend then

fail(
    function () {
        alert('error');
    }
);

What should always run after call() action

always(
    function () {
        alert('finished');
    }
);

Simple example

Z.call('SearchActiveDirectoryByName').done(function(data) { console.log(data) });

Video demonstration

var identity = Z('#Identity');

var webservice = 'Get-ZPADUser';
var args = {
    Identity: identity.val(),
    Propery: 'Mail'
}

identity.spin(true, 'Loadind user information...')

Z.call(
    webservice,
    args
).done(
    function (data) {
        if (data.length > 0) {
            if (data[0].Mail !== '') {
                Z('#mailAddress').val(data[0].Mail);
                Z('#mailAddress').valid();
            } else {
                Z('#mailAddress').valid(false, 'User has no e-mail address', true);
            }
        } else {
            Z('#mailAddress').valid(false, 'Could not find user', true);
        }
    }
).fail(
    function () {
        Z('#mailAddress').valid(false, 'Could not get data', true);
    }
).always(
    function () {
        identity.spin(false);
    }
);

Working example

//Using the ClientWebService module and SearchActiveDirectoryByName method.
//Code placed on onChange method of a text field.

var field = this;
var data = { search: field.val() + '*' };

Z.call('SearchActiveDirectoryByName', data).done(function (data) {
    field.displayName(data[0].name);
});

call with spin

spin(\[Fields to spin\], \[message\], \[Fields to disable\])

Call a client web service function and show loading indicator with message and disable fields until loading completes. The fields to spin and the fields to disable can be a field instead of a selector, making it possible to pass the current field (this) inside an onload, onchange or onsubmit handler. Available in version 1.10.1229

Z.call(
    'SearchActiveDirectoryByName',
    { search:'a*'}
).spin(
    '#inputtext',
    'Wating for data...',
    '#inputtextarea'
).done(
    function (data) {
        console.log(data)
    }
);