List or Library

Name

A unique identifier for the control.

The Name property is used in JavaScript to select a specific control.

fd.spRendered(function(){
    //can access the control using its Name:
    fd.control('Control1');
 });

Read-only

Define whether a user can view or edit the contents of the control:

Editing

Choose between Dialog and Inline editing.

The Dialog mode launches a dialog to create new and modify existing items:

The Inline mode allows you to do it right on the form:

Lock Column

Locks select, edit and delete columns in place for horizontal scrolling.

It also allows to lock other columns:

Height

Height of List or Library control in pixels. Usually, the control takes as much space as necessary to show all items on the page, but if Height is set, the control gets a scrollbar.

Site URL

Define the site URL where the source list or library is located:

List

Select which SharePoint list or library will be used as a source:

View

Select the view to display in the control:

If the list view includes grouping and totals, all of this formatting will be automatically applied to the List or Library control:

Lookup field

If the source list has a lookup field to Parent list, items will automatically be filtered by it:

More on this in the Create forms with related items or documents article.

Root Folder

Specify the name of the folder in the source list. The user will then only see its contents inside the control.

Width

Specify the column width in pixels.

The column can still be dragged by a user on the form to manually resize it:

Width (Edit)

Specify the column width in pixels when a user edits a row in the inline editing mode.

Mode

List or Library control supports column formatters:

Defines the formatting applied to the column:

Select the mode for the column from the dropdown:

• Default – the formatting configured in List View → Column Settings → Format this column:

  

• Custom – a custom formatting template applies.

Custom

Specify a custom template that will be used to format the column:

See custom formatting examples in Customize view of columns article.

Lookup Column Properties

Define lookup column properties when the List or Library control is in inline editing mode. You can configure dynamic filtering for the lookup column, specify how search behaves, set up ordering, and more.

Find more details about the available properties on the Lookup field page.

Wait until control is ready

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

fd.spRendered(function() {
    fd.control('Control1').ready(function(dt) {
        //dt parameter is the same as fd.control('Control1')
        console.log('List or Library is initialized');
    });
    //or
    fd.control('Control1').ready().then(function(dt) {
        //dt parameter is the same as fd.control('Control1')
        console.log('List or Library is initialized');
    });
});

Handle edit event

Execute a function when a control is being edited.

editData passed as an argument to the handler. It is an object that contains fields and methods for manipulating controls of the current row:

• formType — returns the type of the record.

  • ‘New’ — adding a new item.

  • ‘Edit’ — editing an existing item.

• itemId — returns the ID of the current item.

• field(‘InternalName’) — returns Vue-component of corresponding field control.

Example:

// prepopulating Title field of a new record
// in the List or Library control with the title
// of the parent item
fd.control('Control1').$on('edit', function(editData) {
    if (editData.formType === 'New') {
        console.log('editData.itemId');
        //Set Title field value with the value from the parent
        editData.field('Title').value = fd.field('Title').value;
    }
});

More on that in Manipulate fields in inline editing mode article.

Handle change event

Execute a function when a control value has been changed. changeData passed as an argument to the handler. It is an object that contains information about the changes made:

• type — returns type of changes made to related items.

  • ‘add’ — new item has been created

  • ‘addFolder’ — new folder has been created

  • ‘edit’ — item has been changed

  • ‘delete’ — item/file has been deleted

  • ‘upload’ — file has been uploaded

• itemId — returns the ID of the changed item

• itemIds — returns an array of the modified items depending on the value of changeData.type

  • ‘upload’ — returns the array of IDs of the uploaded files

  • ‘delete’ — returns the array of IDs of the deleted files

  • anything else — returns ‘undefined’

// displays an alert message with IDs of the uploaded files
fd.control('Control1').$on('change', function(changeData) {
    if (changeData.type === 'upload') {
        alert(changeData.itemIds);
    }
});

// displays an alert message with ID of the changed item
fd.control('Control1').$on('change', function(changeData) {
    if (changeData.type === 'edit') {
        alert(changeData.itemId);
    }
});

Handle file upload event

Execute a function when the user uploads files to Document Library via the control.

itemIds is an array of IDs of uploaded files.

//log all uploaded files to console
fd.control('Control1').$on('filesUploaded',
    function(itemIds) {
        itemIds.forEach(function(item) {
            console.log(item);
        });
    });

Handle linking items event

Execute a function when saving New Form that has items in Library or List control, that will be tied to the parent via lookup field.

handler function contains parameter object with the following properties:

• itemIds is an array of IDs of uploaded files.

• lookupField is a Lookup field on children items, that binds them to parent.

• parentItemId is an ID of the newly saved Parent item.

//give an alert message when saving New Form
fd.control('Control1').beforeItemsAttach(function(e) {
    return new Promise(function(resolve) {
        var ids = '';
        var message = 'Item(s): ' + e.itemIds.join();
        message += ' attached to Parent with ID: ' + e.parentItemId;
        message += ' via Lookup: ' + e.lookupField;

        alert(message);

        //once resolved, the form will save:
        resolve();
    })
});

Refresh the control

Refresh the List or Library control. If any items or documents were changed, the data presented in List or Library will be updated.

fd.control('Control1').refresh();

Make control read-only

Make a control non-editable or editable again.

fd.control('Control1').readonly;
fd.control('Control1').readonly = true;
fd.control('Control1').readonly = false;

Make row read-only

Make a row read-only depending on the column value. Declare a function that returns true for a row that should be set to read-only.

row passed as an argument to the function and holds column values of the rows.

//disable rows with the status of Completed
fd.control('SPDataTable1').readonlyRow = function(row) {
        return row.Status == 'Completed';
};

//remove function
fd.control('SPDataTable1').readonlyRow = null;

Make items selection non-selectable

Make items non-selectable and selectable again.

fd.control('Control1').selectable;
fd.control('Control1').selectable = false;
fd.control('Control1').selectable = true;

Disable drag and fill

Remove drag and fill functionality from the control.

fd.control('Control1').allowDragAndFill;
fd.control('Control1').allowDragAndFill = false;
fd.control('Control1').allowDragAndFill = true;

Get selected items

Get an array of currently selected items. Can be used to retrieve items, but not to modify them.

var selected = fd.control('Control1').selectedItems;

Change uploading text

Change text that shows during upload, useful for localizations.

fd.control('Control1').uploadingText // 'Uploading...' by default
fd.control('Control1').uploadingText = 'New text'

Configure dialog window

Modify Kendo UI Window configuration, such as width and height of the dialog window.

fd.control('Control1').dialogOptions.height; //returns height
fd.control('Control1').dialogOptions.width //returns width

//set width and height:
fd.control('Control1').dialogOptions = {
    width: 1280,
    height: 720
}

Filter List or Library

Set CAML filtering for the control. It’s empty by default, but contains filter value if you choose Lookup Field in Data Source Editor.

Can also be used to apply custom filtering. Changes are applied dynamically to the control.

fd.control('Control1').ready(function() {
    fd.control('Control1').filter = '<Eq><FieldRef Name="Title"/><Value Type="Text">Test</Value></Eq>';
    fd.control('Control1').refresh();
});

More on that in the Filter related items or documents dynamically article.

Configure Root Folder

Change root folder of the control.

baseRootFolder property specifies starting folder for the control. User cannot go higher than this folder.

rootFolder property specifies current folder for the control.

fd.control('Control1').ready(function() {
    //set base root folder
    fd.control('Control1').baseRootFolder = 'My Folder';
    //set the current folder
    fd.control('Control1').rootFolder = 'My Folder';
});

More on that in Navigate to specific folder dynamically article.

Change source site

The property holds the server-relative URL of the site used as the source of the List or Library control. It can be used to define which SharePoint site will be used as the source.

//set the source site
fd.control('Control1').webUrl = '/sites/MainSite/SubSite';

Change source list

The property holds the server-relative URL of the list or library used as the source for the List or Library control. It can be used to define which SharePoint list or library will be used as the source.

//set the source list or library
fd.control('Control1').listUrl = 'Lists/List1';

Change view

You can switch between views of the source list by list view name or by view ID.

//set the list view by name
fd.control('Control1').viewName = 'All Items';

//set the list view by ID
fd.control('Control1').viewId = 'FEB4302C-617F-4B6B-86F2-9A3F718E4F58';

Work with buttons

Use buttons property that holds all available List or Library buttons in an array of objects.

Can be used to add new buttons, modify or remove existing ones.

Buttons have the following properties:

• class — returns an object, holds button’s CSS classes. Can be used to assign CSS classes with either string or an object. Default class btn cannot be removed or changed, it is not contained in the property.

• click — returns a function, that is executed when a button is clicked. Can be used to assign a new function.

• disabled — return boolean, whether button is disabled or not. Can be used to disable or enable a button.

• icon — returns a string, which matches icon names from Microsoft Fabric Icons. Can be used to add or change button’s icon.

• id — returns a string, a unique identifier of the button. Can be used to find a specific button in the toolbar.

• style — returns a string, which matches button’s HTML property style. Can be used to add styles to a specific button.

• text — returns a string, which matches button’s text. Can be used to retrieve or change button’s text.

//get all buttons
var allButtons = fd.control('Control1').buttons;

//get the New button
var addButton = fd.control('Control1').buttons.find(function(b) {
    return b.id === 'ADD'
})

//get the index of the Refresh button
var indexRefresh = fd.control('Control1').buttons.findIndex(function(b) {
    return b.id === 'REFRESH'
})

//change button's Icon
fd.control('Control1').buttons[1].class  = 'btn-danger';

//add new button
var button = {text: 'Export',
            class: 'btn-secondary',
            visible: true,
            icon: 'PDF',
            iconType: 0,
            click: function() { alert('Exporting!'); }}

fd.control('Control1').buttons.push(button);

//hide button if 0 elements are selected (dynamic)
fd.control('Control1').$watch('selectedItems',
    function(items) {
        fd.control('Control1').buttons[2].visible = items.length > 0 ;
    });

More on that in Add or customize buttons in the toolbar article.

Customize view of columns

Use templates property that holds user-defined templates for specific columns of the control.

fd.control('Control1').templates = {
    // Color Status column based on value
    Status: function(ctx) {
        if (value == 'Unresolved') {
            return '<span style="color:red">' + value + '</span>';
        }
        else if (value == 'Resolved') {
            return '<span style="color:green">' + value + '</span>';
        }
        return '<span>' + value + '</span>';
    }
}

More on that in Customize view of columns article.

Configure widget

You can access the widget used by the control. The widget is based on Kendo UI Grid.

fd.control('Control1').widget;

// change the widget's configuration
fd.control('Control1').widgetOptions = {
    sortable: false
};

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