• 
• Updated On 4.1.1

User Interface Configuration

The user interface configuration file defines the widgets shown in the user interface. It allows the user to configure the items available for interaction in Studio.

It shows different projections of the content in addition to other tools to assist in content authoring and site administration.

The UI is made up of configurable widgets and can be extended or modified by adding/removing/configuring widgets. Plugins can make use of this by adding themselves to the UI where required. See CrafterCMS Plugin Descriptor for more information on how a plugin can be wired in the user interface configuration.

Here’s a screenshot of Studio showing some of the widgets in the UI in red circles that are defined in the user interface configuration.

Here’s an annotated version of some of the widgets in the user interface shown in the image above.

<siteUI>
  <widget id="craftercms.components.ToolsPanel">...</widget>     Sidebar widget
  <widget id="craftercms.components.ICEToolsPanel">...</widget>  Experience Builder widget
  <widget id="craftercms.components.Launcher">...</widget>       Navigation Menu widget
  <widget id="craftercms.components.PreviewToolbar">...</widget> Toolbar widget
  <widget id="craftercms.components.Dashboard">...</widget>      Dashboard widget
  <widget id="craftercms.components.TinyMCE">...</widget>        TinyMCE widget
  <references>
     <reference id="craftercms.siteTools">...</reference>
     <reference id="craftercms.freemarkerCodeSnippets">...</reference>
     <reference id="craftercms.groovyCodeSnippets">...</reference>
  </references>
</siteUI>

Let’s take a look at the sidebar widget as an example. The Sidebar widget is a panel located on the left side of Studio. The Sidebar contains, the Dashboard, various path navigators and path navigator trees such as Pages, Components, etc., and the Project Tools, which are also widgets. Here’s the configuration:

<widget id="craftercms.components.ToolsPanel">
  <configuration>
    <widgets>
      <widget id="craftercms.components.ToolsPanelEmbeddedAppViewButton">
        <configuration>
          <title id="words.dashboard" defaultMessage="Dashboard"/>
          <icon id="@mui/icons-material/DashboardRounded"/>
          <widget id="craftercms.components.SiteDashboard"/>
        </configuration>
      </widget>
      <widget id="craftercms.components.PathNavigator">
        <configuration>
          <id>Pages</id>
          <label>Pages</label>
          <icon id="@mui/icons-material/DescriptionOutlined"/>
          <rootPath>/site/website</rootPath>
          <locale>en</locale>
        </configuration>
      </widget>
      <widget id="craftercms.components.PathNavigator">
        <configuration>
          <id>Components</id>
          <label>Components</label>
          <icon id="craftercms.icons.Component"/>
          <rootPath>/site/components</rootPath>
          <locale>en</locale>
        </configuration>
      </widget>
      <widget id="craftercms.components.PathNavigator">
        <configuration>
          <id>Taxonomy</id>
          <label>Taxonomy</label>
          <icon id="@mui/icons-material/LocalOfferOutlined"/>
          <rootPath>/site/taxonomy</rootPath>
          <locale>en</locale>
        </configuration>
      </widget>
      ...
      <widget id="craftercms.components.ToolsPanelEmbeddedAppViewButton">
        <permittedRoles>
          <role>admin</role>
          <role>developer</role>
        </permittedRoles>
        <configuration>
          <title id="siteTools.title" defaultMessage="Project Tools"/>
          <icon id="@mui/icons-material/ConstructionRounded"/>
          <widget id="craftercms.components.EmbeddedSiteTools"/>
        </configuration>
      </widget>
    </widgets>
  </configuration>
</widget>
...

To modify the user interface configuration, click on from the Sidebar, then click on Configuration and select User Interface Configuration from the list.

---

Sample

Here’s a sample User Interface Configuration file (click on the triangle on the left to expand/collapse):

Sample "ui.xml"

<?xml version="1.0" encoding="UTF-8" ?>
<!--
  ~ Copyright (C) 2007-2022 Crafter Software Corporation. All Rights Reserved.
  ~
  ~ This program is free software: you can redistribute it and/or modify
  ~ it under the terms of the GNU General Public License version 3 as published by
  ~ the Free Software Foundation.
  ~
  ~ This program is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
  ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  ~ GNU General Public License for more details.
  ~
  ~ You should have received a copy of the GNU General Public License
  ~ along with this program.  If not, see <http://www.gnu.org/licenses/>.
  -->
<siteUi>
    <widget
            id="craftercms.components.Preview"
            initialEditModeOn="true"
            initialHighlightMode="all"
    />
    <widget id="craftercms.components.ToolsPanel">
        <configuration>
            <widgets>
                <widget id="craftercms.components.ToolsPanelEmbeddedAppViewButton">
                    <configuration>
                        <title id="words.dashboard" defaultMessage="Dashboard"/>
                        <icon id="@mui/icons-material/DashboardRounded"/>
                        <widget id="craftercms.components.SiteDashboard"/>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <title id="previewSiteExplorerPanel.title" defaultMessage="Site Explorer"/>
                        <icon id="craftercms.icons.SiteExplorer"/>
                        <widgets>
                            <widget id="craftercms.components.PathNavigatorTree">
                                <configuration>
                                    <id>Pages</id>
                                    <label>Pages</label>
                                    <icon id="@mui/icons-material/DescriptionOutlined" />
                                    <rootPath>/site/website</rootPath>
                                    <locale>en</locale>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.PathNavigatorTree">
                                <configuration>
                                    <id>Components</id>
                                    <label>Components</label>
                                    <icon id="craftercms.icons.Component"/>
                                    <rootPath>/site/components</rootPath>
                                    <locale>en</locale>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.PathNavigatorTree">
                                <configuration>
                                    <id>Taxonomy</id>
                                    <label>Taxonomy</label>
                                    <icon id="@mui/icons-material/LocalOfferOutlined"/>
                                    <rootPath>/site/taxonomy</rootPath>
                                    <locale>en</locale>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.PathNavigatorTree">
                                <configuration>
                                    <id>StaticAssets</id>
                                    <label>Static Assets</label>
                                    <icon id="@mui/icons-material/ImageOutlined"/>
                                    <rootPath>/static-assets</rootPath>
                                    <locale>en</locale>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.PathNavigatorTree">
                                <configuration>
                                    <label>Templates</label>
                                    <icon id="@mui/icons-material/InsertDriveFileOutlined"/>
                                    <rootPath>/templates</rootPath>
                                    <locale>en</locale>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.PathNavigatorTree">
                                <configuration>
                                    <label>Scripts</label>
                                    <icon id="@mui/icons-material/CodeRounded"/>
                                    <rootPath>/scripts</rootPath>
                                    <locale>en</locale>
                                </configuration>
                            </widget>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <permittedRoles>
                        <role>admin</role>
                        <role>developer</role>
                    </permittedRoles>
                    <configuration>
                        <title id="siteTools.title" defaultMessage="Project Tools"/>
                        <icon id="@mui/icons-material/ConstructionRounded"/>
                        <widgets>
                            <widget id="craftercms.components.SiteToolsPanel"/>
                        </widgets>
                    </configuration>
                </widget>
            </widgets>
        </configuration>
    </widget>
    <widget id="craftercms.components.ICEToolsPanel">
        <configuration>
            <widgets>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewSearchPanel.title" defaultMessage="Search"/>
                        <icon id="@mui/icons-material/SearchRounded"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewSearchPanel"/>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewComponentsPanel.title" defaultMessage="Add Components"/>
                        <icon id="@mui/icons-material/ExtensionOutlined"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewComponentsPanel"/>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewBrowseComponentsPanel.title" defaultMessage="Browse Components"/>
                        <icon id="@mui/icons-material/ExtensionOutlined"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewBrowseComponentsPanel"/>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewDropTargetsPanel.title" defaultMessage="Component Drop Targets"/>
                        <icon id="@mui/icons-material/ExtensionOutlined"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewDropTargetsPanel"/>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewAssetsPanel.title" defaultMessage="Assets"/>
                        <icon id="@mui/icons-material/ImageOutlined"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewAssetsPanel"/>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewAudiencesPanel.title" defaultMessage="Audience Targeting"/>
                        <icon id="@mui/icons-material/EmojiPeopleRounded"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewAudiencesPanel">
                                <configuration>
                                    <fields>
                                        <segment>
                                            <id>segment</id>
                                            <name>Segment</name>
                                            <description>User segment.</description>
                                            <type>dropdown</type>
                                            <defaultValue>anonymous</defaultValue>
                                            <values>
                                                <value>
                                                    <label>Guy</label>
                                                    <value>guy</value>
                                                </value>
                                                <value>
                                                    <label>Gal</label>
                                                    <value>gal</value>
                                                </value>
                                                <value>
                                                    <label>Anonymous</label>
                                                    <value>anonymous</value>
                                                </value>
                                            </values>
                                            <helpText>Setting the segment will change content targeting to the audience selected.</helpText>
                                        </segment>
                                        <name>
                                            <id>name</id>
                                            <name>Name</name>
                                            <description>User's first and last name.</description>
                                            <type>input</type>
                                            <helpText>Enter user's first and last name.</helpText>
                                        </name>
                                    </fields>
                                </configuration>
                            </widget>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewPageExplorerPanel.title" defaultMessage="Page Explorer"/>
                        <icon id="craftercms.icons.PageExplorer"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewPageExplorerPanel"/>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="previewSimulatorPanel.title" defaultMessage="Device Simulator"/>
                        <icon id="@mui/icons-material/DevicesRounded"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewSimulatorPanel">
                                <configuration>
                                    <devices>
                                        <device>
                                            <title>smartPhone</title>
                                            <width>375</width>
                                            <height>667</height>
                                        </device>
                                        <device>
                                            <title>tablet</title>
                                            <width>768</width>
                                            <height>1024</height>
                                        </device>
                                    </devices>
                                </configuration>
                            </widget>
                        </widgets>
                    </configuration>
                </widget>
                <widget id="craftercms.components.ToolsPanelPageButton">
                    <configuration>
                        <target id="icePanel"/>
                        <title id="words.settings" defaultMessage="Settings"/>
                        <icon id="@mui/icons-material/SettingsOutlined"/>
                        <widgets>
                            <widget id="craftercms.components.PreviewSettingsPanel"/>
                        </widgets>
                    </configuration>
                </widget>
            </widgets>
        </configuration>
    </widget>
    <widget id="craftercms.components.Launcher">
        <configuration>
            <widgets>
                <widget id="craftercms.components.LauncherSection">
                    <configuration>
                        <title id="launcher.siteSectionTitle">
                            <defaultMessage><![CDATA[Project <muted>• {siteName}</muted>]]></defaultMessage>
                        </title>
                        <widgets>
                            <widget id="craftercms.components.LauncherLinkTile">
                                <configuration>
                                    <title id="words.dashboard" defaultMessage="Dashboard"/>
                                    <systemLinkId>siteDashboardDialog</systemLinkId>
                                    <icon id="@mui/icons-material/DashboardRounded"/>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.LauncherLinkTile">
                                <configuration>
                                    <title id="words.preview" defaultMessage="Preview"/>
                                    <systemLinkId>preview</systemLinkId>
                                    <icon id="craftercms.icons.Preview"/>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.LauncherLinkTile">
                                <permittedRoles>
                                    <role>admin</role>
                                    <role>developer</role>
                                </permittedRoles>
                                <configuration>
                                    <title id="siteTools.title" defaultMessage="Project Tools"/>
                                    <systemLinkId>siteToolsDialog</systemLinkId>
                                    <icon id="@mui/icons-material/ConstructionRounded"/>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.LauncherLinkTile">
                                <configuration>
                                    <title id="words.search" defaultMessage="Search"/>
                                    <systemLinkId>siteSearchDialog</systemLinkId>
                                    <icon id="@mui/icons-material/SearchRounded"/>
                                </configuration>
                            </widget>
                            <widget id="craftercms.components.LauncherPublishingStatusTile"/>
                        </widgets>
                    </configuration>
                </widget>
            </widgets>
        </configuration>
    </widget>
    <widget id="craftercms.components.PreviewToolbar">
        <configuration>
            <leftSection>
                <widgets>
                    <widget id="craftercms.components.SiteSwitcherSelect"/>
                    <widget id="craftercms.components.QuickCreate"/>
                </widgets>
            </leftSection>
            <middleSection>
                <widgets>
                    <widget id="craftercms.components.PreviewAddressBar"/>
                </widgets>
            </middleSection>
            <rightSection>
                <widgets>
                    <widget id="craftercms.components.EditModesSwitcher"/>
                    <widget id="craftercms.components.PublishingStatusButton">
                        <configuration>
                            <variant>icon</variant>
                        </configuration>
                    </widget>
                    <widget id="craftercms.components.WidgetDialogIconButton">
                        <configuration>
                            <title id="words.search" defaultMessage="Search"/>
                            <icon id="@mui/icons-material/SearchRounded"/>
                            <widget id="craftercms.components.Search">
                                <configuration>
                                    <embedded>true</embedded>
                                </configuration>
                            </widget>
                        </configuration>
                    </widget>
                </widgets>
            </rightSection>
        </configuration>
    </widget>
    <widget id="craftercms.components.Dashboard">
        <configuration>
            <mainSection>
                <widgets>
                    <widget id="craftercms.components.MyRecentActivityDashlet">
                        <permittedRoles>
                            <role>admin</role>
                            <role>developer</role>
                            <role>publisher</role>
                        </permittedRoles>
                    </widget>
                    <widget id="craftercms.components.UnpublishedDashlet">
                        <permittedRoles>
                            <role>admin</role>
                            <role>developer</role>
                            <role>publisher</role>
                        </permittedRoles>
                    </widget>
                    <widget id="craftercms.components.PendingApprovalDashlet">
                        <permittedRoles>
                            <role>admin</role>
                            <role>developer</role>
                            <role>publisher</role>
                        </permittedRoles>
                    </widget>
                    <widget id="craftercms.components.ScheduledDashlet">
                        <permittedRoles>
                            <role>admin</role>
                            <role>developer</role>
                            <role>publisher</role>
                        </permittedRoles>
                    </widget>
                    <widget id="craftercms.components.RecentlyPublishedDashlet">
                        <permittedRoles>
                            <role>admin</role>
                            <role>developer</role>
                            <role>publisher</role>
                        </permittedRoles>
                    </widget>
                    <widget id="craftercms.components.ExpiringDashlet">
                        <permittedRoles>
                            <role>admin</role>
                            <role>developer</role>
                            <role>publisher</role>
                        </permittedRoles>
                    </widget>
                </widgets>
            </mainSection>
        </configuration>
    </widget>
    <widget id="craftercms.components.TinyMCE">
        <configuration>
            <setups>
                <setup id="generic">
                    <!-- Configuration options: https://www.tiny.cloud/docs/configure/ -->
                    <!-- Plugins: https://www.tiny.cloud/docs/plugins/opensource/ -->
                    <tinymceOptions>
                        <![CDATA[
                            {
                                "menubar": true,
                                "theme": "silver",
                                "plugins": "preview searchreplace autolink directionality visualblocks visualchars fullscreen image link media template codesample table charmap pagebreak nonbreaking anchor insertdatetime advlist lists wordcount help acecode",
                                "extended_valid_elements": "",
                                "valid_children": "",
                                "toolbar1": "formatselect | bold italic strikethrough forecolor backcolor | link | alignleft aligncenter alignright alignjustify | numlist bullist outdent indent | removeformat",
                                "code_editor_wrap": false,
                                "toolbar_sticky": true,
                                "image_advtab": true,
                                "encoding": "xml",
                                "relative_urls": false,
                                "remove_script_host": false,
                                "convert_urls": false,
                                "remove_trailing_brs": false,
                                "media_live_embeds": true,
                                "autoresize_on_init": false,
                                "autoresize_bottom_margin": 0,
                                "menu": {
                                    "tools": { "title": "Tools", "items": "tinymcespellchecker code acecode wordcount" }
                                },
                                "automatic_uploads": true,
                                "file_picker_types":  "image media file",
                                "paste_data_images": true,
                                "templates": [],
                                "content_css": [],
                                "content_style": "body {}",
                                "contextmenu": false
                            }
                    ]]>
                    </tinymceOptions>
                </setup>
            </setups>
        </configuration>
    </widget>
    <references>
        <reference id="craftercms.siteTools">
            <tools>
                <tool>
                    <title id="dropTargetsMessages.contentTypes" defaultMessage="Content Types"/>
                    <icon id="@mui/icons-material/WidgetsOutlined"/>
                    <url>content-types</url>
                    <widget id="craftercms.components.ContentTypeManagement" />
                </tool>
                <tool>
                    <title id="GlobalMenu.EncryptionToolEntryLabel" defaultMessage="Encryption Tool"/>
                    <icon id="@mui/icons-material/LockOutlined"/>
                    <url>encrypt-tool</url>
                    <widget id="craftercms.components.SiteEncryptTool" />
                </tool>
                <tool>
                    <title id="words.configuration" defaultMessage="Configuration"/>
                    <icon id="@mui/icons-material/SettingsApplicationsOutlined"/>
                    <url>configuration</url>
                    <widget id="craftercms.components.SiteConfigurationManagement" />
                </tool>
                <tool>
                    <title id="GlobalMenu.AuditEntryLabel" defaultMessage="Audit"/>
                    <icon id="@mui/icons-material/SubjectRounded" />
                    <url>audit</url>
                    <widget id="craftercms.components.SiteAuditManagement" />
                </tool>
                <tool>
                    <title id="workflowStates.title" defaultMessage="Workflow States"/>
                    <icon id="@mui/icons-material/SettingsOutlined"/>
                    <url>item-states</url>
                    <widget id="craftercms.components.ItemStatesManagement" />
                </tool>
                <tool>
                    <title id="GlobalMenu.LogConsoleEntryLabel" defaultMessage="Log Console"/>
                    <icon id="@mui/icons-material/FormatAlignCenterRounded"/>
                    <url>log</url>
                    <widget id="craftercms.components.LogConsole">
                        <configuration>
                            <logType>preview</logType>
                        </configuration>
                    </widget>
                </tool>
                <tool>
                    <title id="words.publishing" defaultMessage="Publishing"/>
                    <icon id="@mui/icons-material/CloudUploadOutlined"/>
                    <url>publishing</url>
                    <widget id="craftercms.components.PublishingDashboard" />
                </tool>
                <tool>
                    <title id="remoteRepositories.title" defaultMessage="Remote Repositories"/>
                    <icon id="@mui/icons-material/StorageRounded"/>
                    <url>remote-repositories</url>
                    <widget id="craftercms.components.RemoteRepositoriesManagement" />
                </tool>
                <tool>
                    <title>GraphQL</title>
                    <icon id="craftercms.icons.GraphQL"/>
                    <url>graphiql</url>
                    <widget id="craftercms.components.SiteGraphiQL"/>
                </tool>
                <tool>
                    <title id="PluginManagement.title" defaultMessage="Plugin Management"/>
                    <icon id="@mui/icons-material/ExtensionOutlined"/>
                    <url>plugins</url>
                    <widget id="craftercms.components.PluginManagement" />
                </tool>
            </tools>
        </reference>
        <reference id="craftercms.freemarkerCodeSnippets">
            <contentVariable label="Content variable">
                <value><![CDATA[${contentModel.VARIABLE_NAME}]]></value>
            </contentVariable>
            <requestParameter label="Request parameter">
                <value><![CDATA[${RequestParameters["PARAM_NAME"]!"DEFAULT"}]]></value>
            </requestParameter>
            <crafterSupportMacros label="Crafter support macros">
                <value><![CDATA[<#import "/templates/system/common/crafter.ftl" as crafter />]]></value>
            </crafterSupportMacros>
            <transformPathToUrl label="Transform PATH to URL">
                <value><![CDATA[${urlTransformationService.transform('storeUrlToRenderUrl', STORE_URL)}]]></value>
            </transformPathToUrl>
            <renderComponentsList label="Render list of components">
                <value><![CDATA[<#list contentModel.VARIABLE_NAME.item as module>
	<@renderComponent component=module />
</#list>]]></value>
            </renderComponentsList>
            <iterateItemsListLoadContentItem label="Iterate over a list of items and load content item">
                <value><![CDATA[<#list contentModel.VARIABLE_NAME.item as myItem>
	<#assign myContentItem =  siteItemService.getSiteItem(myItem.key) />
	${myContentItem.variableName}
</#list>]]></value>
            </iterateItemsListLoadContentItem>
            <iterateRepeatGroup label="Iterate over repeat group">
                <value><![CDATA[<#list contentModel.VARIABLE_NAME.item as row>
	${row.VARIABLE_NAME}
</#list>]]></value>
            </iterateRepeatGroup>
            <fremarkerValueAssignment label="Freemarker value assignment">
                <value><![CDATA[<#assign imageSource = contentModel.image!"" />]]></value>
            </fremarkerValueAssignment>
            <freemarkerIf label="Freemarker value IF">
                <value><![CDATA[<#if CONDITION>
	...
</#if>]]></value>
            </freemarkerIf>
            <freemarkerLoop label="Freemarker value LOOP">
                <value><![CDATA[<#list ARRAY as value>
	${value_index}: ${value}
</#list>]]></value>
            </freemarkerLoop>
            <freemarkerFragmentInclude label="Freemarker Fragment include">
                <value><![CDATA[<#include "/templates/PATH" />]]></value>
            </freemarkerFragmentInclude>
            <freemarkerLibraryImport label="Freemarker Library import">
                <value><![CDATA[<#import "/templates/PATH" as NAMESPACE />]]></value>
            </freemarkerLibraryImport>
            <htmlPage label="HTML Page">
                <value><![CDATA[<#import "/templates/system/common/crafter.ftl" as crafter />
<!doctype html>
<html lang="en">
  <head>
    <#-- Insert your head markup here -->
    <@crafter.head />
  </head>
  <body>
    <@crafter.body_top />
    <#-- Insert your body markup  here -->
    <@crafter.body_bottom />
  </body>
</html>]]></value>
            </htmlPage>
            <specificHTMLTag label="Field (Specific HTML Tag)">
              <value><![CDATA[<@crafter.DESIRED_TAG $field="FIELD_ID">${contentModel.FIELD_ID}</@crafter.DESIRED_TAG>]]></value>
            </specificHTMLTag>
            <renderComponentCollection label="Render Component Collection">
              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=renderComponentCollection&check_keywords=yes&area=default -->
<@crafter.renderComponentCollection $field="features_o" $containerAttributes={ "class": "features-container" } $itemAttributes={ "data-custom-attribute": "true" } />]]></value>
            </renderComponentCollection>
            <renderRepeatGroup label="Render Repeat Group">
              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=renderRepeatCollection&check_keywords=yes&area=default -->
<@crafter.renderRepeatGroup
  $field="VARIABLE_NAME"
  $containerAttributes={'attr': 'value'};
  item, index
>
  <@crafter.div
    $field="sections_o.section_html"
    $index=index
  >
    ${item.itemField}
  </@crafter.div>
</@crafter.renderRepeatGroup>]]></value>
            </renderRepeatGroup>
            <navigation label="Navigation">
              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=crafter.navigation&check_keywords=yes&area=default -->
  <@crafter.navigation
    showNavElement=false
    url="NAVIGATION_URL"
    containerElementClass="container-class"
    itemWrapperClass="item-wrapper-class"
    itemClass="item-class"
    depth=2
  />]]></value>
            </navigation>
            <breadcrumb label="Breadcrumb">
              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=crafter.breadcrumb&check_keywords=yes&area=default -->
  <@crafter.breadcrumb
    url=contentModel.storeUrl
    containerElementClass="container-element-class"
    itemWrapperClass="item-wrapper-class"
    navElementAttributes={ "data-custom-attribute": "true" }
  />]]></value>
            </breadcrumb>
        </reference>
        <reference id="craftercms.groovyCodeSnippets">
            <accessContentModel label="Access Content variable">
                <value><![CDATA[contentModel.VARIABLE_NAME]]></value>
            </accessContentModel>
            <accessTemplateodel label="Access Template variable">
                <value><![CDATA[templateModel]]></value>
            </accessTemplateodel>
            <currentSiteId label="Current Site ID">
                <value><![CDATA[siteContext.siteName]]></value>
            </currentSiteId>
            <requestParameters label="Request Parameters">
                <value><![CDATA[params]]></value>
            </requestParameters>
            <cookies label="Cookies">
                <value><![CDATA[cookies]]></value>
            </cookies>
            <httpRequest label="HTTP Request">
                <value><![CDATA[request]]></value>
            </httpRequest>
            <httpResponse label="HTTP Response">
                <value><![CDATA[response]]></value>
            </httpResponse>
            <session label="Session">
                <value><![CDATA[session]]></value>
            </session>
            <transformPathToUrl label="Transform PATH to URL">
                <value><![CDATA[urlTransformationService.transform('storeUrlToRenderUrl', STORE_URL)]]></value>
            </transformPathToUrl>
            <userProfile label="User Profile">
                <value><![CDATA[profile]]></value>
            </userProfile>
            <currentAuthentication label="Current Authentication">
                <value><![CDATA[authentication]]></value>
            </currentAuthentication>
            <logInfo label="Log an INFO">
                <value><![CDATA[logger.info('MY MESSAGE')]]></value>
            </logInfo>
            <logError label="Log an ERROR">
                <value><![CDATA[logger.error('MY MESSAGE')]]></value>
            </logError>
            <searchService label="Search Service">
                <value><![CDATA[searchService]]></value>
            </searchService>
            <siteItemService label="Site Item Service">
                <value><![CDATA[siteItemService]]></value>
            </siteItemService>
            <profileService label="Profile Service">
                <value><![CDATA[profileService]]></value>
            </profileService>
            <getSpringBean label="Get Spring Bean">
                <value><![CDATA[applicationContext.get("SPRING_BEAN_NAME")]]></value>
            </getSpringBean>
        </reference>
    </references>
</siteUi>

---

Widget Permissions

Limiting who can access a widget via roles is through permittedRoles in the user interface configuration. Simply add the following to the widget you want available only to users with the permitted role(s)

<permittedRoles>
  <role>ALLOWED_ROLE</role>
  ...
</permittedRoles>

where ALLOWED ROLE is a role defined in Studio that is allowed to access the widget. See Roles and Permissions for a list of default roles in Crafter Studio

Let’s take a look at an example in the configuration where access to the Project Tools widget is limited to users with the roles admin and developer.

<widget id="craftercms.components.ToolsPanelPageButton">
  <permittedRoles>
    <role>admin</role>
    <role>developer</role>
  </permittedRoles>
  <configuration>
    <title id="siteTools.title" defaultMessage="Site Tools"/>
    <icon id="@mui/icons-material/TuneRounded"/>
    <widgets>
      <widget id="craftercms.components.SiteToolsPanel"/>
    </widgets>
  </configuration>
</widget>

Here’s the sidebar when a user with role admin is logged in. Notice that Project Tools is available in the sidebar

Here’s the sidebar when a user with role author is logged in. Notice that Project Tools is not available in the sidebar

---

Sidebar Excludes

To hide items (exclude) in the Sidebar such as path navigators and path navigator trees, use

   ...
   <excludes>
     <exclude PATTERN_TO_EXCLUDE/>
     ...
   </excludes>

where:

• PATTERN_TO_EXCLUDE is a prefix of items to hide from the Sidebar

Let’s take a look at an example using a project created from the Website Editorial blueprint, to hide the folder /site/website/articles/2021/3.

Here’s the Sidebar before the 2021/3 folder is hidden

Here’s the configuration to hide the folder:

<widget id="craftercms.components.PathNavigator">
  <configuration>
    <id>Pages</id>
    <label>Pages</label>
    <icon id="@mui/icons-material/DescriptionOutlined"/>
    <rootPath>/site/website</rootPath>
    <locale>en</locale>
    <excludes>
      <exclude>/site/website/articles/2021/3</exclude>
    </excludes>
  </configuration>
</widget>

Here’s the Sidebar with the folder 2021/3 hidden:

---

Navigator Widgets Styling Options

Several styling options are available for the navigator widgets. Both the widget’s container element and the icon element can receive CSS classes and targeted base styles, collapsed styles and expanded styles. Custom css style sheets may be loaded into Studio via Plugins.

Colors, background colors, borders (css properties) etc can be added to widgets in the Sidebar when expanding/collapsing a widget via the icon and container properties.

Let’s take a look at an example of putting a red border when Taxonomy is expanded and for Templates, a red font color when expanded and a blue font color when collapsed

Here’s the default colors of widgets in the Sidebar

Here’s the configuration for putting a red border when Taxonomy is expanded and for Templates, a red font color when expanded and a blue font color when collapsed

<widget id="craftercms.components.PathNavigator">
  <configuration>
    <id>Taxonomy</id>
    <label>Taxonomy</label>
    <icon id="@mui/icons-material/LocalOfferOutlined"/>
    <container>
      <expandedStyle>
        <border>solid</border>
        <borderColor>red</borderColor>
      </expandedStyle>
    </container>
    <rootPath>/site/taxonomy</rootPath>
    <locale>en</locale>
  </configuration>
</widget>
<widget id="craftercms.components.PathNavigatorTree">
  <configuration>
    <label>Templates</label>
    <icon id="@mui/icons-material/InsertDriveFileOutlined">
      <expandedStyle>
        <color>red</color>
      </expandedStyle>
      <collapsedStyle>
        <color>blue</color>
      </collapsedStyle>
    </icon>
    <rootPath>/templates</rootPath>
    <locale>en</locale>
  </configuration>
</widget>
...

Remember that children of expandedStyle & collapsedStyle should be camelCased standard css properties.

Here’s the Sidebar with the colors and border added:

Container Options

• baseClass: a class name (string) applied to the container regardless of state

• expandedClass: a class name (string) applied to the container when expanded

• collapsedClass: a class name (string) applied to the container when collapsed

• baseStyle: a set of CSS rules applied to the container regardless of state (e.g. <baseStyles><backgroundColor>red</backgroundColor></baseStyles>)

• expandedStyle: a set of CSS rules applied to the container when expanded

• collapsedStyle: a set of CSS rules applied to the container when collapsed

Icon Options

• class: a class name (string) applied to the icon regardless of state

• style: a set of CSS rules applied to the icon regardless of state (e.g. <baseStyles><backgroundColor>red</backgroundColor></baseStyles>)

• content: inner content of the icon to use in case you’re using a font icon library that uses content to render the icon

• expandedStyle: a set of CSS rules applied to the icon when expanded

• collapsedStyle: a set of CSS rules applied to the icon when collapsed

---

SPA Sources Sidebar Cabinet

Users may want to manage (edit/view) SPA sources in their projects through Studio. To view/edit SPA sources, simply add another PathNavigatorTree or PathNavigator widget, named sources, in the Sidebar widget like below:

SPA sources - ui.xml

<siteUI>
  <widget id="craftercms.components.ToolsPanel">
    <configuration>
      <widgets>
        ...
        <widget id="craftercms.components.PathNavigatorTree">
          <configuration>
            <id>Sources</id>
            <label>Sources</label>
            <icon id="@mui/icons-material/InsertDriveFileOutlined"/>
            <rootPath>/sources/</rootPath>
            <locale>en</locale>
          </configuration>
        </widget>
        ...

Note

Adding SPA sources in top folders other than /sources is not supported. Also note that items under /sources are excluded from search.

The Video Center blueprint from the marketplace contains an example of SPA sources managed in Studio (/sources added to the sidebar).

---

PathNavigatorTree and PathNavigator Sidebar Widget

The PathNavigatorTree sidebar widget allows the display of trees with the ability to expand/collapse containers. It shows elements (children) in a level and allows the container children to be further expanded without navigating to the child, allowing many children to be open at the same time. Also, each container child allows filtering/searching via keywords allowing users to find items faster.

PathNavigatorTree widget

The PathNavigator sidebar widget shows elements (children) of a level and allows filtering/searching via keywords allowing users to find items faster. It doesn’t provide an overview like the PathNavigatorTree, but, the PathNavigator is the recommended widget if your project contains thousands of pages where a tree becomes unresponsive due to painting a massive number of items.

PathNavigator widget

Here are some options on displaying elements (children) of navigator widgets:

Limit

The number of children displayed at a time when expanding a container can be limited via the limit property like below:

PathNavigatorTree sidebar widget limit configuration

<widget id="craftercms.components.PathNavigatorTree">
  <configuration>
    <id>StaticAssets</id>
    <label>Static Assets</label>
    <icon id="@mui/icons-material/ImageOutlined"/>
    <rootPath>/static-assets</rootPath>
    <locale>en</locale>
    <limit>5</limit>
  </configuration>
</widget>

In the example above, the Static Assets path navigator tree limits the children displayed to 5 items when opening a container like in the image on the left below:

Notice also that when the user clicks on 10 more items displayed on the image on the left, an additional 5 more items will be displayed as shown on the image on the right.

Remember to do a refresh of your browser after making the limit changes and saving your configuration in order to see the changes you’ve made in action.

Sorting

The order of children displayed may be sorted via the sortStrategy and order property like below:

Sidebar Widget Sorting Configuration Example

<widget id="craftercms.components.PathNavigatorTree">
  <configuration>
    <id>Pages</id>
    <label>Pages</label>
    <icon id="@mui/icons-material/DescriptionOutlined"/>
    <rootPath>/site/website/index.xml</rootPath>
    <locale>en</locale>
    <sortStrategy>lastUpdate</sortStrategy>
    <order>DESC</order>
  </configuration>
</widget>

The following sortStrategy property options are available:

• alphabetical: sort in alphabetical order

• foldersFirst: sort in alphabetical order, listing folders first

• lastUpdate: sort using the last modified date

The following order property options are available:

• ASC: display children in ascending order

• DESC: display children in descending order

In the example configuration above, the children of the Pages folder will be sorted using the last modified date in descending order. Let’s take a look on how the example configuration above affects the order of children displayed in the Pages folder. The image on the left is a baseline screenshot of the /articles/2021/3 folder under Pages for our example. The image on the right is a screenshot of the the same folder after editing and saving changes to the Top Books For Young Women article, where we expect our edited article to be the first one listed:

---

Audience Targeting

Audience Targeting allows an author to see what the project would look like if it were being browsed by a user with a given set of attributes.

Here’s the Audience Targeting configuration out of the box for a project created using the Website Editorial blueprint:

Audience Targeting - ui.xml

<widget id="craftercms.components.ICEToolsPanel">
  <configuration>
    <widgets>
      <widget id="craftercms.components.ToolsPanelPageButton">
      ...
      <widget id="craftercms.components.ToolsPanelPageButton">
        <configuration>
          <target id="icePanel"/>
          <title id="previewAudiencesPanel.title" defaultMessage="Audience Targeting"/>
          <icon id="@mui/icons-material/EmojiPeopleRounded"/>
          <widgets>
            <widget id="craftercms.components.PreviewAudiencesPanel">
              <configuration>
                <fields>
                  <segment>
                    <id>segment</id>
                    <name>Segment</name>
                    <description>User segment.</description>
                    <type>dropdown</type>
                    <defaultValue>anonymous</defaultValue>
                    <values>
                      <value>
                        <label>Guy</label>
                        <value>guy</value>
                      </value>
                      <value>
                        <label>Gal</label>
                        <value>gal</value>
                      </value>
                      <value>
                        <label>Anonymous</label>
                        <value>anonymous</value>
                      </value>
                    </values>
                    <helpText>Setting the segment will change content targeting to the audience selected.</helpText>
                  </segment>
                  <name>
                    <id>name</id>
                    <name>Name</name>
                    <description>User's first and last name.</description>
                    <type>input</type>
                    <helpText>Enter user's first and last name.</helpText>
                  </name>
                </fields>
              </configuration>
            </widget>
            ...

Here’s how the above configuration looks like in the Experience Builder Panel in Studio:

See Targeting for more information on configuring the targeting system of Crafter Studio to help provide Crafter Engine with fake user properties that help drive the targeting system, such as configuring targeting based on roles, etc. and Audience Targeting for more information on how content authors use the audience targeting system configured.

---

RTE Configuration

There are two ways of editing content in Studio: (1) form-based editing and (2) In-context editing (ICE). Form-based editing is done by clicking on Options (three dots next to the preview address bar at the top of the page, or the three dots next to the page in the Sidebar), then selecting Edit. In-context editing is done by enabling the Edit mode by clicking on the pencil at the top right of the page (which turns green when enabled), then clicking on the section of the page you want to edit.

To configure the RTE, add/edit the widget craftercms.components.TinyMCE:

Example RTE configuration

<widget id="craftercms.components.TinyMCE">
  <configuration>
    <setups>
      <setup id="generic">
        <!-- Configuration options: https://www.tiny.cloud/docs/configure/ -->
        <!-- Plugins: https://www.tiny.cloud/docs/plugins/opensource/ -->
        <tinymceOptions>{
          "menubar": true,
          "theme": "silver",
          "plugins": "print preview searchreplace autolink directionality visualblocks visualchars fullscreen image link media template codesample table charmap hr pagebreak nonbreaking anchor toc insertdatetime advlist lists wordcount textpattern help acecode paste editform",
          "extended_valid_elements": "",
          "valid_children": "",
          "toolbar1": "formatselect | bold italic strikethrough forecolor backcolor | link | alignleft aligncenter alignright alignjustify | numlist bullist outdent indent | removeformat | editform",
          "code_editor_wrap": false,
          "toolbar_sticky": true,
          "image_advtab": true,
          "encoding": "xml",
          "relative_urls": false,
          "remove_script_host": false,
          "convert_urls": false,
          "remove_trailing_brs": false,
          "media_live_embeds": true,
          "autoresize_on_init": false,
          "autoresize_bottom_margin": 0,
          "menu": { "tools": { "title": "Tools", "items": "tinymcespellchecker code acecode wordcount" } },
          "automatic_uploads": true,
          "file_picker_types": "image media file",
          "paste_data_images": true,
          "templates": [],
          "content_css": [],
          "content_style": "body {}",
          "contextmenu": false }
        </tinymceOptions>
      </setup>
    </setups>
  </configuration>
</widget>

Our RTE is based on TinyMCE (https://www.tiny.cloud/) and can leverage all configurations and plugins designed for the TinyMCE editor.

To learn more about configuring the RTE, see here

---

Project Tools Configuration

The Project Config tools configuration section defines what modules are available for administration use when clicking on from the Sidebar.

<references>
             <reference id="craftercms.siteTools">
                     <tools>
                             <tool>
                                     <title id="dropTargetsMessages.contentTypes" defaultMessage="Content Types"/>
                                     <icon id="@mui/icons-material/WidgetsOutlined"/>
                                     <url>content-types</url>
                                     <widget id="craftercms.components.ContentTypeManagement"/>
                             </tool>
                             <tool>
                                     <title id="GlobalMenu.EncryptionToolEntryLabel"
                                            defaultMessage="Encryption Tool"/>
                                     <icon id="@mui/icons-material/LockOutlined"/>
                                     <url>encrypt-tool</url>
                                     <widget id="craftercms.components.SiteEncryptTool"/>
                             </tool>
                             <tool>
                                     <title id="words.configuration" defaultMessage="Configuration"/>
                                     <icon id="@mui/icons-material/SettingsApplicationsOutlined"/>
                                     <url>configuration</url>
                                     <widget id="craftercms.components.SiteConfigurationManagement"/>
                             </tool>
                             ...

List of available tools

Here’s a list of available tools defined in the Website_Editorial blueprint.

Tool	Description
Content Types	Allows you to create/modify content types
Encryption Tool	Allows the user to encrypt sensitive data such as access keys and passwords
Configuration	Contains all the configuration files managed through Crafter Studio
Audit	Allows you to view your project activity log
Workflow States	Contains a list of all files in the project with its corresponding state
Log Console	Allows you to tail logs depending on what logging levels are set
Publishing	Allows the user to view the publishing status, perform a bulk publish or to publish content using commit ID(s)
Git	Allows the user to perform Git operations
GraphQL	Allows the user run GraphQL queries and explore the schema documentation for a project without the need of any other tool
Plugin Management	Allows the user to install and to view currently installed, project plugins

See Navigating Project Tools for more information on the available tools in Project Tools.

---

Preview Edit Mode Defaults

Since 4.1.2

To configure defaults for Preview edit mode, set the following attributes of the craftercms.components.Preview widget:

<widget
        id="craftercms.components.Preview"
        initialEditModeOn="true"
        initialHighlightMode="all"
        xbDetectionTimeoutMs="5000"
/>