The List or Library is a control which allows you to view, edit, add or delete items or documents to related SharePoint List or Document Library from the form.
This control is extremely powerful and versatile — it supports filtering, selecting root folder, uploading multiple documents at once and much more.
Here you can find properties specifically related to the List or Library control.
A unique identifier for the control.
JavaScript
The Name property allows to work with the control via JavaScript code, like this:
fd.spRendered(function(){
//hide the control
fd.control('SPDataTable1').hidden = true;
});
This setting allows you to select which SharePoint List or Document Library will be used as source, and which View will be shown on the form:
You can edit the View to include grouping and totals:
All of this formatting will be automatically applied to the List or Library control:
Data Source also includes Lookup Field — if 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.
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:
Locks select, edit and delete columns in place for horizontal scrolling.
It also allows to lock other columns:
Type in the name of the folder inside List or Library and user will only be able to see its contents inside the control.
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.
Here you can find properties specifically related to the List or Library columns. Click on a column to access its properties.
Specify the column width in pixels.
The column can still be dragged by a user on the form to manually resize it:
Here you can find a property specifically related to the Yes/No column type.
Define how the Yes/No column input is displayed when a user edits a row in the inline editing mode: as a toggle or a checkbox.
List or Library control also supports column formatters, configured in List View → Column Settings → Format this column:
They will display properly on the form:
Defines the formatting applied to the column:
Select the mode for the column from the dropdown:
Default – the formatting configured in the column settings applies.
Plain – no formatting applies.
Custom – a custom formatting template applies. See custom formatting examples in Customize view of columns article.
In this section, you can find basic examples of how to work with the control using JavaScript.
If you are not familiar with the JavaScript framework, get started with the JavaScript basics.
Note
The control is only accessible once the form is rendered, so all calls to the control must be inside fd.spRendered event:
fd.spRendered(function(){
//hide the control
fd.control('Control1').hidden = true;
//show the control
fd.control('Control1').hidden = false;
});
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'); }); });
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.
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 the array of IDs of the uploaded files
// 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);
}
});
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);
});
});
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.
Important
Asynchronous event! Can return a Promise and the corresponding operation will not continue until the promise is resolved.
//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 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 a control non-editable or editable again.
fd.control('Control1').readonly; fd.control('Control1').readonly = true; fd.control('Control1').readonly = false;
Make a row readonly depedning on the column value. Declare a function that returns true for a row that should be set to readonly.
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 non-selectable and selectable again.
fd.control('Control1').selectable; fd.control('Control1').selectable = false; fd.control('Control1').selectable = true;
Remove drag and fill functionality from the control.
fd.control('Control1').allowDragAndFill; fd.control('Control1').allowDragAndFill = false; fd.control('Control1').allowDragAndFill = true;
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 text that shows during upload, useful for localizations.
fd.control('Control1').uploadingText // 'Uploading...' by default fd.control('Control1').uploadingText = 'New text'
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 }
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.
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.
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.
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.
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.