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.
The media files selector form component has the following configurable properties:
Property | Type | Description | |
---|---|---|---|
LibraryName | string | Configures 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. | |
MaxFilesLimit | int | Configures the maximum number of files allowed to be selected:
If not specified, the default value is 1 (single file selection). | |
AllowedExtensions | string | 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.
// 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>();
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.
The page selector form component has the following configurable properties:
Property | Type | Description | |
---|---|---|---|
RootPath | string | 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.
// 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>();
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.
The path selector form component has the following configurable properties:
Property | Type | Description | |
---|---|---|---|
RootPath | string | 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.
// 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>();
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:
Property | Type | Description | |
---|---|---|---|
MaxFilesLimit | int | Configures the maximum number of files allowed to be selected:
If not specified, the default value is 1 (single file selection). | |
AllowedExtensions | string | 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.
// 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>();
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 (pages, media 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:
Property | Type | Descriptions |
---|---|---|
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) |
PageRootPath | string | 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. |
MediaLibraryName | 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. |
MediaAllowedExtensions | string | A 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 | string | A 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. |
// 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?