Using content selector JavaScript API
The content selector JavaScript API provides an alternative way to integrate functionality of the built-in selectors into your project. The built-in selectors utilize this API in their implementation, but each selector is configured to list different items of content and has different return values.
If you need to customize a selector dialog, you can use this content selector JavaScript API to create a custom selector dialog that meets your needs. The API also allows you to open selectors from custom code. For example, it can be used to invoke selector dialogs directly from within a widget’s inline editor.
To open the content selector (its modal dialog), use the window.kentico.modalDialog.contentSelector.open(options) function. To call this function, make sure you have the page builder scripts loaded on the given page. Provide an options object with the following properties as a parameter of the function (see the example below):
Required properties | |
Property | Description |
tabs | An array of strings that specifies which object types will be available for selection. You can configure the selector to be able to process various object types, but you can only select objects of one type within one selection. Possible values are “attachment”, “media”, and “page”. |
applyCallback | A callback function invoked when the attachment file selector’s confirmation button is clicked. The parameter of the callback function contains an object that has two properties:
To propagate the selected objects from the selector to the component which invoked the selector:
|
Optional properties | |
Property | Description |
defaultTab | A string property that specifies which of the available tabs is shown as default when the selector is opened. If the selectedItems property is specified, it overrides this property. |
selectedItems | An object that specifies which values are pre-selected when the selector is opened. The object contains two properties
|
selectedItemsLimit | Configures the maximum number of objects allowed to be selected:
If not specified, the default value is 1 (single object selection). |
attachmentOptions | An object that contains properties to customize the attachment selector tab. You can configure the following properties:
|
pageOptions | An object that contains properties to customize the page selector tab. You can configure the following properties:
|
mediaOptions | An object that contains properties to customize the media file selector tab. You can configure the following properties:
|
In addition to the properties listed above, the content selector modal dialog shares the following properties with the general modal dialog from which it is derived: title, theme, width, maximized, applyButtonText, cancelButtonText, cancelCallback.
The following tables describe objects which represent a selected piece of content (a page, an attachment, or a media file) returned by the content selector. You can access these properties in the applyCallback function to display the selected attachments/files/pages and information about them. If you need to persistently store the selected objects for later use, storing only GUIDs of the objects is usually sufficient.
Attachment object properties | |
Property | Description |
name | A string property representing the name of the file. |
extension | A string property representing the file type extension. |
fileGuid | A string property representing the GUID of the selected file. |
url | A string property representing the relative preview (latest edited version) URL on which you can access the selected file. |
liveSiteUrl | A string property representing the relative live site (published version) URL on which you can access the selected file. |
thumbnailUrls | A property representing the preview URLs of the image file’s thumbnails. Not all file types support thumbnails (e.g. .pdf files). The property consists of three string URLs, each for a different typified size of the thumbnail: small, medium, and large. |
mimeType | A string property representing the MIME type of the file. |
size | A number property representing the size of the file in bytes. |
title | A string property representing the title of the selected file. |
description | A string property representing the description of the file. |
isValid | A boolean value indicating whether the selected file is valid (e.g. if the file was not deleted after being selected). If false, the object’s other properties might not be correctly set. |
Media file object properties | |
Property | Description |
name | A string property representing the name of the file. |
extension | A string property representing the file type extension. |
fileGuid | A string property representing the GUID of the selected file. |
url | A string property representing the relative preview URL on which you can access the selected file. |
liveSiteUrl | A string property representing the relative live site URL on which you can access the selected file. |
thumbnailUrls | A property representing the preview URLs of the image file’s thumbnails. Not all file types support thumbnails (e.g. .pdf files). The property consists of three string URLs, each for a different typified size of the thumbnail: small, medium, and large. |
mimeType | A string property representing the MIME type of the file. |
size | A number property representing the size of the file in bytes. |
title | A string property representing the title of the selected file. |
description | A string property representing the description of the file. |
folderPath | A string property representing the relative path to the folder within the media library containing the selected file. |
libraryName | A string property representing the name of the library from which the file was selected. |
siteName | A string property representing the name of the site to which the file (i.e. the media library) belongs. |
isValid | A boolean value indicating whether the selected file is valid (e.g. if the file was not deleted from the media library after being selected). If false, the object’s other properties might not be correctly set. |
Page object properties | |
Property | Description |
name | A string property that contains the title of the page, as displayed in the content tree. |
nodeId | The ID of the selected node in the database. |
nodeAliasPath | A string property representing the node alias path of the page. |
nodeGuid | A string property representing the GUID of the selected node in the database. |
url | A string property representing the relative preview (latest edited version) URL on which you can access the selected page. |
liveSiteUrl | A string property representing the relative live site (published version) URL on which you can access the selected page. |
isValid | A boolean property, which indicates whether the page is a valid page to be selected in the dialog (user has permissions to view the page, the page has not been deleted while the dialog was opened, etc.). |
icon | A string property that contains the icon class used with the page in the UI. |
The following example showcases a script of an inline editor that opens a content selector configured to select images from a media library. The inline editor’s value in this example is a string property containing a GUID that identifies the selected image file.
(function () {
// Registers the 'image-selector' inline editor within the page builder scripts
window.kentico.pageBuilder.registerInlineEditor("image-selector", {
init: function (options) {
var button = options.editor.querySelector("button");
button.addEventListener("click", function () {
// Sets the options object with individual properties
var dialogOptions = {
tabs: ["media"],
selectedItems: {
type: "media",
items: [{value: options.propertyValue}]
},
mediaOptions: {
libraryName: "Graphics",
allowedExtensions: ".gif;.png;.jpg;.jpeg"
},
// Defines the applyCallback function invoked on click of the selector's confirmation button
applyCallback: function (data) {
items = data.items;
if (items && items.length) {
// 'newItem' is a media file object
var newItem = items[0];
// You can now access its properties
console.log(newItem.name);
console.log(newItem.title);
// Checks if the image isn't already selected
if (options.propertyValue && newItem.fileGuid === options.propertyValue[0].fileGuid) {
return {
closeDialog: true
};
}
// Creates a custom event that notifies the widget about a change in the value of a property
var event = new CustomEvent("updateProperty", {
detail: {
value: [{ fileGuid: newItem.fileGuid }],
name: options.propertyName
}
});
options.editor.dispatchEvent(event);
return {
closeDialog: true
};
}
}
};
// Opens the selector modal dialog
window.kentico.modalDialog.contentSelector.open(dialogOptions);
});
}
});
})();