Kentico Xperience 13 documentation and ASP.NET Core

Most documentation about running Xperience applications under ASP.NET Core can be found in a dedicated section: Developing Xperience applications using ASP.NET Core. The rest of the documentation still applies, but some code samples and scenarios might need slight modifications for Core projects.

All major differences between the MVC 5 and Core platforms are summarized in Migrating to ASP.NET Core.

×

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. All of 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.

Multiple object selection not supported for pages

It is currently not supported to select multiple pages using the content selector. The selector only allows you to select a single page.

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 in your view. Provide an options object with the following properties as a parameter of the function (see the example below):

Required properties
PropertyDescription
tabsAn 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:

  • type – a string property that contains information about what type of objects were selected in the dialog ("page", "media" or "attachment").
  • items – a property that contains an array of objects of the respective type. Within this callback function, you need to ensure displaying the selected files using the properties available in the returned objects and ensure the propagation of the objects selected in the selector to the widget or form component which opened the selector.

To propagate the selected objects from the selector to the component which invoked the selector:

  • use the updateProperty custom event if the selector was opened from a widget through an inline editor.
  • modify the value of the input element if the selector was opened from a form component.
Optional properties
PropertyDescription
defaultTabA 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

  • type – a property that contains a string with information about what type of object will be preselected in the dialog and what tab will be opened initially. Possible values are:
    • page – identification by node GUID
      • Alternatively, you can set the selector to use identification by node alias path using the identifierMode property in pageOptions
    • media – idendification by file GUID
    • attachment – identification by attachment GUID
  • items – an array of objects, each of which contains a value property with the identifier of respective pre-selected item. For example, using node GUIDs for pages: [{ value: "9d807714-1e7d-4d13-9d5f-24fef15f9654" }, { value: "0f194882-cea8-4481-a322-328f0af07b69" }]
selectedItemsLimit

Configures the maximum number of objects allowed to be selected:

  • 0 – no limit.
  • n – at most n files can be selected at once.

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:

  • allowedExtensions – A semicolon-delimited string of file extensions that specify the allowed file extensions for the files to be selected. When no allowed extensions are specified, all extensions are displayed. For example, ".gif;.png;.jpg;.jpeg".
pageOptions

An object that contains properties to customize the page selector tab. You can configure the following properties:

  • rootPath – a string property that limits the selection of pages to a subtree with root specified by its node alias path (e.g. "/Products/Coffee-grinders"). Only the specified page and its sub-pages can be selected. If not specified, the whole content tree is allowed.
  • identifierMode – a string property that determines what identifier is used for the pages specified in the selectedItems property:
    • guid (default value) – pages are indetified by their node GUID
    • path – pages are indetified by their node alias path
mediaOptions

An object that contains properties to customize the media file selector tab. You can configure the following properties:

  • allowedExtensions – A semicolon-delimited string of file extensions that specify the allowed file extensions for the files to be selected. The listed extensions need to form a subset of allowed extensions specified in the Media file allowed extensions site settings key. When no allowed extensions are specified, all files with the extensions from the site settings key can be selected. For example, ".gif;.png;.jpg;.jpeg".
  • libraryName – A string code name of a (single) media library from which you can select files in the selector. If not specified, the selector allows selecting from all media libraries of the current site for which the user has permissions.

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
PropertyDescription
name

A string property representing the name of the file.

extensionA string property representing the file type extension.
fileGuidA 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.

liveSiteUrlA 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.

mimeTypeA string property representing the MIME type of the file.
sizeA number property representing the size of the file in bytes.
titleA string property representing the title of the selected file.
descriptionA string property representing the description of the file.
isValidA 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
PropertyDescription
name

A string property representing the name of the file.

extensionA string property representing the file type extension.
fileGuidA 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.

liveSiteUrlA 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.

mimeTypeA string property representing the MIME type of the file.
sizeA number property representing the size of the file in bytes.
titleA string property representing the title of the selected file.
descriptionA string property representing the description of the file.
folderPathA string property representing the relative path to the folder within the media library containing the selected file.
libraryNameA string property representing the name of the library from which the file was selected.
siteNameA string property representing the name of the site to which the file (i.e. the media library) belongs.
isValidA 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
PropertyDescription
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.

nodeAliasPathA string property representing the node alias path of the page.
nodeGuidA 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.

liveSiteUrlA string property representing the relative live site (published version) URL on which you can access the selected page.
isValidA 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.

Example - Opening the content selector in an inline editor using the API
(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);
        });
    }
  });
})();

Was this page helpful?