Selectors for page builder components

Selectors are system form components that enable users to select pages from a site's content tree, media files from a site's media libraries, and unsorted page attachments attached to pages via the Attachments tab and use them in the properties of page builder form components.

The selectors return a collection of identifiers representing the chosen items. You can use these identifiers to access objects in the logic of your page builder components. For example, when developing a widget displaying links to a set of pages, a property of the widget could use the page selector form component to enable editors to choose the pages.

In addition to using the selectors in the administration interface as standard form components (when building property dialogs of page builder components), you can also use the content selector JavaScript API utilizing the system's modal dialog support to offer identical functionality anywhere within the code of your components.

You can examine an implementation of a sample widget using selector form components in the LearningKit project on GitHub. To set up the project, follow the instructions in the repository's README file.

Selector form components

Form components for use in the page builder

The following selectors are intended to facilitate page builder component development. These form components are not meant to be used on the live site or as part of any form builder components.

Media files selector

The media files selector form component enables users to select files from a site's media libraries using an intuitive interface. The selector returns a collection of MediaFilesSelectorItem objects, which contain the GUID of the selected media file in the FileGuid property.

Media files selector interface

The media files selector form component has the following configurable properties:

PropertyTypeDescription
LibraryNamestringConfigures the (single) media library from which you can select files in the selector. If not specified, the selector allows selecting from all media libraries on the current site for which the user has permissions.
MaxFilesLimitint

Configures the maximum number of files 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 file selection).

AllowedExtensionsstring

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. 

If not specified, the selector uses the extensions from the site settings key by default.

The following example shows the declaration of a property in a page builder component's property model class that has the MediaFilesSelector form component assigned as its editing component. A URL of the selected image is then retrieved in the corresponding component's controller.

Component model class utilizing the selector
        // Assigns a selector component to the 'Images' property
        [EditingComponent(MediaFilesSelector.IDENTIFIER)]
        // Configures the media library from which you can select files in the selector
        [EditingComponentProperty(nameof(MediaFilesSelectorProperties.LibraryName), "Graphics")]
        // Limits the maximum number of files that can be selected at once
        [EditingComponentProperty(nameof(MediaFilesSelectorProperties.MaxFilesLimit), 5)]
        // Configures the allowed file extensions for the selected files
        [EditingComponentProperty(nameof(MediaFilesSelectorProperties.AllowedExtensions), ".gif;.png;.jpg;.jpeg")]
        // Returns a list of media files selector items (objects that contain the GUIDs of selected media files)
        public IEnumerable<MediaFilesSelectorItem> Images { get; set; } = Enumerable.Empty<MediaFilesSelectorItem>();
Component controller class utilizing the selector
        private readonly IMediaFileInfoProvider mediaFileInfo;
        private readonly IComponentPropertiesRetriever componentPropertiesRetriever;
        private readonly ISiteService siteService;
 
        public MediaFilesSelectorExample(IMediaFileInfoProvider mediaFileInfo, 
                                         IComponentPropertiesRetriever componentPropertiesRetriever,
                                         ISiteService siteService)
        {
            this.mediaFileInfo = mediaFileInfo;
            this.componentPropertiesRetriever = componentPropertiesRetriever;
            this.siteService = siteService;
        }
 
        public ActionResult Index()
        {
            // Retrieves the GUID of the first selected media file from the 'Images' property
            Guid guid = componentPropertiesRetriever.Retrieve<CustomWidgetProperties>().Images.FirstOrDefault()?.FileGuid ?? Guid.Empty;
            // Retrieves the MediaFileInfo object that corresponds to the selected media file GUID
            MediaFileInfo mediaFile = mediaFileInfo.Get(guid, siteService.CurrentSite.SiteID);
 
            string url = String.Empty;
            if (mediaFile != null)
            {
                // Retrieves an URL of the selected media file
                url = MediaLibraryHelper.GetDirectUrl(mediaFile);
            }
 
            // Custom logic...
 
            return View();
        }

Configuring maximum file upload size and timeout

The media files selector also provides a media file uploader for uploading new files into media libraries as part of its functionality. By default, the uploader is limited to 200MB and times out after 120 seconds. If you wish to enable uploads of larger files or you want to set a different timeout interval, edit your MVC project's web.config file and modify the following values:

  • Modify the value of the <httpRuntime> element's maxRequestLength and executionTimeout  attributes. Enter the values in kilobytes and seconds.
  • Modify the value of the <requestLimits> element's maxAllowedContentLength attribute. Enter the value in bytes. The value of the maxAllowedContentLength attribute in kiloBytes must be greater or equal to the value of the maxRequestLength attribute.
<!-- Scopes the maximum file size configuration to only affect files uploaded using the media files selector -->
<location path="Kentico.Uploaders">
  <system.webServer>
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="MAXSIZE_IN_BYTES" />
      </requestFiltering>
    </security>
  </system.webServer>
  <system.web>
    <httpRuntime maxRequestLength="MAXSIZE_IN_KILOBYTES" executionTimeout="NUMBER_IN_SECONDS" />
  </system.web>
</location> 

Page selector

The page selector form component allows users to select pages from the content tree using a dialog window. The selector returns a collection of PageSelectorItem objects, which contain the NodeGUID property with a GUID of the selected page. If you wish to obtain a page's node alias path, use the path selector component instead.

Note: Currently, the page selector can only be used to select a single page – the returned collection of PageSelectorItem objects always contains only one object. Due to forward compatibility and to limit any possible future changes in your project, the return type is a collection.

Page selector interface

The page selector form component has the following configurable properties:

PropertyTypeDescription
RootPathstring

Limits the selection of pages to a subtree rooted at a page identified by its node alias path (e.g. "/Products/Coffee-grinders"). Only the specified page and its sub-pages can be selected. If not configured, users can select from the entire content tree.

The following example shows the declaration of a property in a page builder component's property model class that has the PageSelector form component assigned as its editing component. The selected page is then retrieved in the corresponding component's controller.

Component model class utilizing the selector
        // Assigns a selector component to the Pages property
        [EditingComponent(PageSelector.IDENTIFIER)]
        // Limits the selection of pages to a subtree rooted at the 'Products' page
        [EditingComponentProperty(nameof(PageSelectorProperties.RootPath), "/Products")]
        // Returns a list of page selector items (node GUIDs)
        public IEnumerable<PageSelectorItem> Pages { get; set; } = Enumerable.Empty<PageSelectorItem>();
Component controller class utilizing the page selector
        private readonly IPageRetriever pagesRetriever;
        private readonly IComponentPropertiesRetriever componentPropertiesRetriever;
 
        public PageSelectorExample(IPageRetriever pagesRetriever, IComponentPropertiesRetriever componentPropertiesRetriever)
        {
            this.pagesRetriever = pagesRetriever;
            this.componentPropertiesRetriever = componentPropertiesRetriever;
        }
 
        public ActionResult Index()
        {
            // Retrieves the node GUID of the selected page from the 'Pages' property
            Guid? selectedPageGuid = componentPropertiesRetriever.Retrieve<CustomWidgetProperties>().Pages.FirstOrDefault()?.NodeGuid;
            // Retrieves the page that corresponds to the selected GUID
            TreeNode page = pagesRetriever.Retrieve<TreeNode>(query => query
                                .WhereEquals("NodeGUID", selectedPageGuid)
                                .TopN(1))
                                .FirstOrDefault();
 
            // Custom logic...
 
            return View();
        }

Path selector

The path selector form component allows users to select pages from the content tree using a dialog window. The path selector returns a collection of PathSelectorItem objects, which contain the NodeAliasPath property with a node alias path of the selected page. If you wish to obtain a page's GUID, use the page selector component instead.

Note: Currently, the path selector can only be used to select a single page – the returned collection of PathSelectorItem objects always contains only one object. Due to forward compatibility and to limit any possible future changes in your project, the return type is a collection.

Path selector interface

The path selector form component has the following configurable properties:

PropertyTypeDescription
RootPathstring

Limits the selection of pages to a subtree rooted at a page identified by its node alias path (e.g. "/Products/Coffee-grinders"). Only the specified page and its sub-pages can be selected. If not configured, users can select from the entire content tree.

The following example shows the declaration of a property in a page builder component's model class that has the PathSelector form component assigned as its editing component. The selected page is then retrieved in the corresponding component's controller.

Component model class utilizing the path selector
        // Assigns a selector component to the 'PagePaths' property
        [EditingComponent(PathSelector.IDENTIFIER)]
        // Limits the selection of pages to a subtree rooted at the 'Products' page
        [EditingComponentProperty(nameof(PathSelectorProperties.RootPath), "/Products")]
        // Returns a list of path selector items (page paths)
        public IEnumerable<PathSelectorItem> PagePaths { get; set; } = Enumerable.Empty<PathSelectorItem>();
Component controller class utilizing the path selector
        private readonly IPageRetriever pagesRetriever;
        private readonly IComponentPropertiesRetriever componentPropertiesRetriever;
 
        public PathSelectorExample(IPageRetriever pagesRetriever, IComponentPropertiesRetriever componentPropertiesRetriever)
        {
            this.pagesRetriever = pagesRetriever;
            this.componentPropertiesRetriever = componentPropertiesRetriever;
        }
 
        public ActionResult Index()
        {
            // Retrieves the node alias path of the selected page from the 'PagePaths' property
            string selectedPagePath = componentPropertiesRetriever.Retrieve<CustomWidgetProperties>().PagePaths.FirstOrDefault()?.NodeAliasPath;
            // Retrieves the page that corresponds to the selected node alias path
            TreeNode page = pagesRetriever.Retrieve<TreeNode>(query => query
                                .Path(selectedPagePath)
                                .TopN(1))
                                .FirstOrDefault();
 
            // Custom logic...
 
            return View();
        }

Attachment selector

The attachment selector form component allows users to select unsorted page attachments using a dialog window. The selector returns a collection of AttachmentSelectorItem objects, which contain GUIDs of the selected attachments in their FileGuid property.

The attachment selector form component has the following configurable properties:

PropertyTypeDescription
MaxFilesLimitint

Configures the maximum number of files 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 file selection).

AllowedExtensionsstring

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.

The following example shows the declaration of a property in a page builder component's property model class that has the AttachmentSelector form component assigned as its editing component. A relative URL of the selected attachment is then retrieved in the corresponding component's controller.

Component model class utilizing the attachment selector
        // Assigns a selector component to the 'Attachments' property
        [EditingComponent(AttachmentSelector.IDENTIFIER)]
        // Limits the maximum number of attachments that can be selected at once
        [EditingComponentProperty(nameof(AttachmentSelectorProperties.MaxFilesLimit), 3)]
        // Configures the allowed file extensions for the selected attachments
        [EditingComponentProperty(nameof(AttachmentSelectorProperties.AllowedExtensions), ".gif;.png;.jpg;.jpeg")]
        // Returns a list of attachment selector items (attachment objects)
        public IEnumerable<AttachmentSelectorItem> Attachments { get; set; } = Enumerable.Empty<AttachmentSelectorItem>();
Component controller class utilizing the attachment selector
        private readonly IComponentPropertiesRetriever propertiesRetriever;
        private readonly ISiteService siteService;
        private readonly IPageAttachmentUrlRetriever attachmentUrlRetriever;
 
        public AttachmentSelectorExample(IComponentPropertiesRetriever propertiesRetriever,
                                         ISiteService siteService,
                                         IPageAttachmentUrlRetriever attachmentUrlRetriever)
        {
            this.propertiesRetriever = propertiesRetriever;
            this.siteService = siteService;
            this.attachmentUrlRetriever = attachmentUrlRetriever;
        }
 
 
        public ActionResult Index()
        {
            // Retrieves the GUID of the first selected attachment from the 'Attachments' property
            Guid guid = propertiesRetriever.Retrieve<CustomWidgetProperties>().Attachments.FirstOrDefault()?.FileGuid ?? Guid.Empty;
            // Retrieves the DocumentAttachment object that corresponds to the selected attachment GUID
            DocumentAttachment attachment = DocumentHelper.GetAttachment(guid, siteService.CurrentSite.SiteID);
 
            string url = String.Empty;
            if (attachment != null)
            {
                // Retrieves the relative URL of the selected attachment
                url = attachmentUrlRetriever.Retrieve(attachment).RelativePath;
            }
 
            // Custom logic...
 
            return View();
        }

URL selector

The URL selector form component allows users to select one content item (pagesmedia library files, or unsorted page attachments) and returns its relative URL. Alternatively, a URL to an external resource may be entered directly into the text input field.

The URL selector form component has the following configurable properties:

PropertyTypeDescriptions
Tabs

enum

Specifies what tabs (and inherently what object types) will be available for selection to content editors. To select multiple tabs, use the logical OR ('|') operator.
DefaultTab

enum

Specifies which tab will be opened first when the dialog is invoked. (e.g. ContentSelectorTabs.Page)
PageRootPathstringLimits 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.

MediaLibraryName

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

MediaAllowedExtensions

stringA semicolon-delimited string of file extensions that specify the allowed file extensions for the files to be selected on the media tab. 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.

AttachmentAllowedExtensions

stringA semicolon-delimited string of file extensions that specify the allowed file extensions for the files to be selected on the attachment tab. When no allowed extensions are specified, all extensions are displayed.
The following example shows the declaration of a property in a page builder component's property model class that has the UrlSelector form component assigned as its editing component. A relative URL of the selected content item is then stored in the component's property.
Component model class utilizing the URL selector
// Assigns a selector component to the 'ImageUrl' property
[EditingComponent(UrlSelector.IDENTIFIER)]
// Configures which tabs will be available
[EditingComponentProperty(nameof(UrlSelectorProperties.Tabs), ContentSelectorTabs.Attachment | ContentSelectorTabs.Media)]
// Configures which extensions will be avalable on the media tab
[EditingComponentProperty(nameof(UrlSelectorProperties.MediaAllowedExtensions), ".gif;.png;.jpg;.jpeg")]
// Configures which extensions will be avalable on the attachment tab
[EditingComponentProperty(nameof(UrlSelectorProperties.AttachmentAllowedExtensions), ".gif;.png;.jpg;.jpeg")]
// Configures the media library from which the media files can be selected
[EditingComponentProperty(nameof(UrlSelectorProperties.MediaLibraryName), "Graphics")]
// Returns a string containing the relative URL of the selected image file
public string ImageUrl { get; set; }

Was this page helpful?