Person or Group

Wait until field is ready

Wait until the field is loaded. The ready method returns a promise that is resolved when the field has been fully initialized and is ready to work with.

fd.field('Field1').ready(function(field) {
    // alert selected user's name
    alert(field.value.value.DisplayText);
});
//or
fd.field('Field1').ready().then(function(field) {
    // alert selected user's name
    alert(field.value.value.DisplayText);
});

Get or set field value

Get or set the field value in a single selection mode:

//return field value as an object
fd.field('Field1').value;

//get display text
var name = fd.field('Field1').value.DisplayText;

//set field value
fd.field('Field1').value = 'user@mail.com';

Get or set the field value in a multiple selection mode:

//return field value as an array of objects
fd.field('Field1').value;

//set field value
fd.field('Field1').value = ['user@mail.com', 'user2@mail.com'];

Handle change event

Execute a function when a field value has been changed:

fd.field('Field1').$on('change', function(value) {
    //log new value to browser's console
    console.log(value);
});

Make field required

Make a field required or optional:

//make field required
fd.field('Field1').required = true;

//make field not required
fd.field('Field1').required = false;

Disable field

Make a field non-editable. The field value can still be changed with JavaScript and saved:

//disabled field
fd.field('Field1').disabled = true;

//enable field
fd.field('Field1').disabled = false;

Get HTML element

Access HTML element inside the field in order to modify it, hide it, or do something else.

//access field's control
var htmlField = fd.field('Field1').$el;

//access field's block, which includes title and control
var htmlFullField = fd.field('Field1').$parent.$el;

Hide field

Hide a field from a user. The field value can still be accessed and changed with JavaScript.

//hide field
fd.field('Field1').hidden = true;

//show field
fd.field('Field1').hidden = false;

Clear field

Clear field value.

fd.field('Field1').clear();

Validate users

With a custom validator, you can validate number of users or other information about selected users, before the form is submitted:

fd.spRendered(function(){
    fd.field('Users').validators.push({
        name: 'Length validator',
        error: 'No more than 6 users can be selected',
        validate: function(value) {
            if (value.length > 6) {
                return false;
            }

            return true;
        }
    });
});

Configure widget

You can access the widget used by the field. The widget is based on Kendo UI DropDownList in regular mode, and in multiple selection mode it is based on Kendo UI MultiSelect.

// get the widget
fd.field('Field1').widget

// change the widget's configuration
fd.field('Field1').widgetOptions = { template: '<span style="font-weight: bold">#: data.DisplayText #</span>' }

widgetOptions is the same as widget.setOptions({}) but can be defined before widget initialization.

Change dropdown item template

With widget options, you can customize the appearance of the dropdown items.

For example, you can display both the username and the department in the dropdown with the following code:

fd.spBeforeRender(function() {
    var template = '';
    template += '# if (data.EntityData.Email) { #';
    template += '<img alt="" src="' + fd.webUrl + '/_layouts/15/userphoto.aspx?accountname=#:data.EntityData.Email#&size=S"';
    template += ' class="k-state-default photo" width="40" height="40" /># }';
    template += 'else { # <div class="initials" style="background:#= data._initialsColor #"><span>#: data._initials #</span></div> # } #';
    template += '<div class="ml-2 text-truncate">';
    template += '#: data.DisplayText #';
    template += '# if (data.EntityData.Department) { # <span class="d-block text-muted small">#: data.EntityData.Department # </span> # } #';
    template += '</div>';
    fd.field('Field1').widgetOptions = {
        template: template
    }
});