• Document Up to Date
  • Updated On 4.0.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.

Configurations - User Interface Configuration Widgets

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

 1<siteUI>
 2  <widget id="craftercms.components.ToolsPanel">...</widget>     Sidebar widget
 3  <widget id="craftercms.components.ICEToolsPanel">...</widget>  Experience Builder widget
 4  <widget id="craftercms.components.Launcher">...</widget>       Navigation Menu widget
 5  <widget id="craftercms.components.PreviewToolbar">...</widget> Toolbar widget
 6  <widget id="craftercms.components.Dashboard">...</widget>      Dashboard widget
 7  <widget id="craftercms.components.TinyMCE">...</widget>        TinyMCE widget
 8  <references>
 9     <reference id="craftercms.siteTools">...</reference>
10     <reference id="craftercms.freemarkerCodeSnippets">...</reference>
11     <reference id="craftercms.groovyCodeSnippets">...</reference>
12  </references>
13</siteUI>

 1<widget id="craftercms.components.ToolsPanel">
 2  <configuration>
 3    <widgets>
 4      <widget id="craftercms.components.ToolsPanelEmbeddedAppViewButton">
 5        <configuration>
 6          <title id="words.dashboard" defaultMessage="Dashboard"/>
 7          <icon id="@mui/icons-material/DashboardRounded"/>
 8          <widget id="craftercms.components.Dashboard"/>
 9        </configuration>
10      </widget>
11      <widget id="craftercms.components.PathNavigator">
12        <configuration>
13          <id>Pages</id>
14          <label>Pages</label>
15          <icon id="@mui/icons-material/DescriptionOutlined"/>
16          <rootPath>/site/website</rootPath>
17          <locale>en</locale>
18        </configuration>
19      </widget>
20      <widget id="craftercms.components.PathNavigator">
21        <configuration>
22          <id>Components</id>
23          <label>Components</label>
24          <icon id="craftercms.icons.Component"/>
25          <rootPath>/site/components</rootPath>
26          <locale>en</locale>
27        </configuration>
28      </widget>
29      <widget id="craftercms.components.PathNavigator">
30        <configuration>
31          <id>Taxonomy</id>
32          <label>Taxonomy</label>
33          <icon id="@mui/icons-material/LocalOfferOutlined"/>
34          <rootPath>/site/taxonomy</rootPath>
35          <locale>en</locale>
36        </configuration>
37      </widget>
38      ...
39      <widget id="craftercms.components.ToolsPanelEmbeddedAppViewButton">
40        <permittedRoles>
41          <role>admin</role>
42          <role>developer</role>
43        </permittedRoles>
44        <configuration>
45          <title id="siteTools.title" defaultMessage="Site Tools"/>
46          <icon id="@mui/icons-material/ConstructionRounded"/>
47          <widget id="craftercms.components.EmbeddedSiteTools"/>
48        </configuration>
49      </widget>
50    </widgets>
51  </configuration>
52</widget>
53...

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

Configurations - Open User Interface Configuration

Sample

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

Sample "ui.xml"
  1<?xml version="1.0" encoding="UTF-8" ?>
  2<!--
  3  ~ Copyright (C) 2007-2022 Crafter Software Corporation. All Rights Reserved.
  4  ~
  5  ~ This program is free software: you can redistribute it and/or modify
  6  ~ it under the terms of the GNU General Public License version 3 as published by
  7  ~ the Free Software Foundation.
  8  ~
  9  ~ This program is distributed in the hope that it will be useful,
 10  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
 11  ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 12  ~ GNU General Public License for more details.
 13  ~
 14  ~ You should have received a copy of the GNU General Public License
 15  ~ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 16  -->
 17<siteUi>
 18    <widget id="craftercms.components.ToolsPanel">
 19        <configuration>
 20            <widgets>
 21                <widget id="craftercms.components.ToolsPanelEmbeddedAppViewButton">
 22                    <configuration>
 23                        <title id="words.dashboard" defaultMessage="Dashboard"/>
 24                        <icon id="@mui/icons-material/DashboardRounded"/>
 25                        <widget id="craftercms.components.Dashboard"/>
 26                    </configuration>
 27                </widget>
 28                <widget id="craftercms.components.ToolsPanelPageButton">
 29                    <configuration>
 30                        <title id="previewSiteExplorerPanel.title" defaultMessage="Site Explorer"/>
 31                        <icon id="craftercms.icons.SiteExplorer"/>
 32                        <widgets>
 33                            <widget id="craftercms.components.PathNavigator">
 34                                <configuration>
 35                                    <id>Pages</id>
 36                                    <label>Pages</label>
 37                                    <icon id="@mui/icons-material/DescriptionOutlined" />
 38                                    <rootPath>/site/website</rootPath>
 39                                    <locale>en</locale>
 40                                </configuration>
 41                            </widget>
 42                            <widget id="craftercms.components.PathNavigator">
 43                                <configuration>
 44                                    <id>Components</id>
 45                                    <label>Components</label>
 46                                    <icon id="craftercms.icons.Component"/>
 47                                    <rootPath>/site/components</rootPath>
 48                                    <locale>en</locale>
 49                                </configuration>
 50                            </widget>
 51                            <widget id="craftercms.components.PathNavigator">
 52                                <configuration>
 53                                    <id>Taxonomy</id>
 54                                    <label>Taxonomy</label>
 55                                    <icon id="@mui/icons-material/LocalOfferOutlined"/>
 56                                    <rootPath>/site/taxonomy</rootPath>
 57                                    <locale>en</locale>
 58                                </configuration>
 59                            </widget>
 60                            <widget id="craftercms.components.PathNavigator">
 61                                <configuration>
 62                                    <id>StaticAssets</id>
 63                                    <label>Static Assets</label>
 64                                    <icon id="@mui/icons-material/ImageOutlined"/>
 65                                    <rootPath>/static-assets</rootPath>
 66                                    <locale>en</locale>
 67                                </configuration>
 68                            </widget>
 69                            <widget id="craftercms.components.PathNavigatorTree">
 70                                <configuration>
 71                                    <label>Templates</label>
 72                                    <icon id="@mui/icons-material/InsertDriveFileOutlined"/>
 73                                    <rootPath>/templates</rootPath>
 74                                    <locale>en</locale>
 75                                </configuration>
 76                            </widget>
 77                            <widget id="craftercms.components.PathNavigatorTree">
 78                                <configuration>
 79                                    <label>Scripts</label>
 80                                    <icon id="@mui/icons-material/CodeRounded"/>
 81                                    <rootPath>/scripts</rootPath>
 82                                    <locale>en</locale>
 83                                </configuration>
 84                            </widget>
 85                        </widgets>
 86                    </configuration>
 87                </widget>
 88                <widget id="craftercms.components.ToolsPanelPageButton">
 89                    <permittedRoles>
 90                        <role>admin</role>
 91                        <role>developer</role>
 92                    </permittedRoles>
 93                    <configuration>
 94                        <title id="siteTools.title" defaultMessage="Project Tools"/>
 95                        <icon id="@mui/icons-material/ConstructionRounded"/>
 96                        <widgets>
 97                            <widget id="craftercms.components.SiteToolsPanel"/>
 98                        </widgets>
 99                    </configuration>
100                </widget>
101            </widgets>
102        </configuration>
103    </widget>
104    <widget id="craftercms.components.ICEToolsPanel">
105        <configuration>
106            <widgets>
107                <widget id="craftercms.components.ToolsPanelPageButton">
108                    <configuration>
109                        <target id="icePanel"/>
110                        <title id="previewSearchPanel.title" defaultMessage="Search"/>
111                        <icon id="@mui/icons-material/SearchRounded"/>
112                        <widgets>
113                            <widget id="craftercms.components.PreviewSearchPanel"/>
114                        </widgets>
115                    </configuration>
116                </widget>
117                <widget id="craftercms.components.ToolsPanelPageButton">
118                    <configuration>
119                        <target id="icePanel"/>
120                        <title id="previewComponentsPanel.title" defaultMessage="Add Components"/>
121                        <icon id="@mui/icons-material/ExtensionOutlined"/>
122                        <widgets>
123                            <widget id="craftercms.components.PreviewComponentsPanel"/>
124                        </widgets>
125                    </configuration>
126                </widget>
127                <widget id="craftercms.components.ToolsPanelPageButton">
128                    <configuration>
129                        <target id="icePanel"/>
130                        <title id="previewBrowseComponentsPanel.title" defaultMessage="Browse Components"/>
131                        <icon id="@mui/icons-material/ExtensionOutlined"/>
132                        <widgets>
133                            <widget id="craftercms.components.PreviewBrowseComponentsPanel"/>
134                        </widgets>
135                    </configuration>
136                </widget>
137                <widget id="craftercms.components.ToolsPanelPageButton">
138                    <configuration>
139                        <target id="icePanel"/>
140                        <title id="previewDropTargetsPanel.title" defaultMessage="Component Drop Targets"/>
141                        <icon id="@mui/icons-material/ExtensionOutlined"/>
142                        <widgets>
143                            <widget id="craftercms.components.PreviewDropTargetsPanel"/>
144                        </widgets>
145                    </configuration>
146                </widget>
147                <widget id="craftercms.components.ToolsPanelPageButton">
148                    <configuration>
149                        <target id="icePanel"/>
150                        <title id="previewAssetsPanel.title" defaultMessage="Assets"/>
151                        <icon id="@mui/icons-material/ImageOutlined"/>
152                        <widgets>
153                            <widget id="craftercms.components.PreviewAssetsPanel"/>
154                        </widgets>
155                    </configuration>
156                </widget>
157                <widget id="craftercms.components.ToolsPanelPageButton">
158                    <configuration>
159                        <target id="icePanel"/>
160                        <title id="previewAudiencesPanel.title" defaultMessage="Audience Targeting"/>
161                        <icon id="@mui/icons-material/EmojiPeopleRounded"/>
162                        <widgets>
163                            <widget id="craftercms.components.PreviewAudiencesPanel">
164                                <configuration>
165                                    <fields>
166                                        <segment>
167                                            <id>segment</id>
168                                            <name>Segment</name>
169                                            <description>User segment.</description>
170                                            <type>dropdown</type>
171                                            <defaultValue>anonymous</defaultValue>
172                                            <values>
173                                                <value>
174                                                    <label>Guy</label>
175                                                    <value>guy</value>
176                                                </value>
177                                                <value>
178                                                    <label>Gal</label>
179                                                    <value>gal</value>
180                                                </value>
181                                                <value>
182                                                    <label>Anonymous</label>
183                                                    <value>anonymous</value>
184                                                </value>
185                                            </values>
186                                            <helpText>Setting the segment will change content targeting to the audience selected.</helpText>
187                                        </segment>
188                                        <name>
189                                            <id>name</id>
190                                            <name>Name</name>
191                                            <description>User's first and last name.</description>
192                                            <type>input</type>
193                                            <helpText>Enter user's first and last name.</helpText>
194                                        </name>
195                                    </fields>
196                                </configuration>
197                            </widget>
198                        </widgets>
199                    </configuration>
200                </widget>
201                <widget id="craftercms.components.ToolsPanelPageButton">
202                    <configuration>
203                        <target id="icePanel"/>
204                        <title id="previewPageExplorerPanel.title" defaultMessage="Page Explorer"/>
205                        <icon id="craftercms.icons.PageExplorer"/>
206                        <widgets>
207                            <widget id="craftercms.components.PreviewPageExplorerPanel"/>
208                        </widgets>
209                    </configuration>
210                </widget>
211                <widget id="craftercms.components.ToolsPanelPageButton">
212                    <configuration>
213                        <target id="icePanel"/>
214                        <title id="previewSimulatorPanel.title" defaultMessage="Device Simulator"/>
215                        <icon id="@mui/icons-material/DevicesRounded"/>
216                        <widgets>
217                            <widget id="craftercms.components.PreviewSimulatorPanel">
218                                <configuration>
219                                    <devices>
220                                        <device>
221                                            <title>smartPhone</title>
222                                            <width>375</width>
223                                            <height>667</height>
224                                        </device>
225                                        <device>
226                                            <title>tablet</title>
227                                            <width>768</width>
228                                            <height>1024</height>
229                                        </device>
230                                    </devices>
231                                </configuration>
232                            </widget>
233                        </widgets>
234                    </configuration>
235                </widget>
236                <widget id="craftercms.components.ToolsPanelPageButton">
237                    <configuration>
238                        <target id="icePanel"/>
239                        <title id="words.settings" defaultMessage="Settings"/>
240                        <icon id="@mui/icons-material/SettingsOutlined"/>
241                        <widgets>
242                            <widget id="craftercms.components.PreviewSettingsPanel"/>
243                        </widgets>
244                    </configuration>
245                </widget>
246            </widgets>
247        </configuration>
248    </widget>
249    <widget id="craftercms.components.Launcher">
250        <configuration>
251            <widgets>
252                <widget id="craftercms.components.LauncherSection">
253                    <configuration>
254                        <title id="launcher.siteSectionTitle">
255                            <defaultMessage><![CDATA[Site <muted>• {siteName}</muted>]]></defaultMessage>
256                        </title>
257                        <widgets>
258                            <widget id="craftercms.components.LauncherLinkTile">
259                                <configuration>
260                                    <title id="words.dashboard" defaultMessage="Dashboard"/>
261                                    <systemLinkId>siteDashboardDialog</systemLinkId>
262                                    <icon id="@mui/icons-material/DashboardRounded"/>
263                                </configuration>
264                            </widget>
265                            <widget id="craftercms.components.LauncherLinkTile">
266                                <configuration>
267                                    <title id="words.preview" defaultMessage="Preview"/>
268                                    <systemLinkId>preview</systemLinkId>
269                                    <icon id="craftercms.icons.Preview"/>
270                                </configuration>
271                            </widget>
272                            <widget id="craftercms.components.LauncherLinkTile">
273                                <permittedRoles>
274                                    <role>admin</role>
275                                    <role>developer</role>
276                                </permittedRoles>
277                                <configuration>
278                                    <title id="siteTools.title" defaultMessage="Project Tools"/>
279                                    <systemLinkId>siteToolsDialog</systemLinkId>
280                                    <icon id="@mui/icons-material/ConstructionRounded"/>
281                                </configuration>
282                            </widget>
283                            <widget id="craftercms.components.LauncherLinkTile">
284                                <configuration>
285                                    <title id="words.search" defaultMessage="Search"/>
286                                    <systemLinkId>siteSearchDialog</systemLinkId>
287                                    <icon id="@mui/icons-material/SearchRounded"/>
288                                </configuration>
289                            </widget>
290                            <widget id="craftercms.components.LauncherPublishingStatusTile"/>
291                        </widgets>
292                    </configuration>
293                </widget>
294            </widgets>
295        </configuration>
296    </widget>
297    <widget id="craftercms.components.PreviewToolbar">
298        <configuration>
299            <leftSection>
300                <widgets>
301                    <widget id="craftercms.components.SiteSwitcherSelect"/>
302                    <widget id="craftercms.components.QuickCreate"/>
303                </widgets>
304            </leftSection>
305            <middleSection>
306                <widgets>
307                    <widget id="craftercms.components.PreviewAddressBar"/>
308                </widgets>
309            </middleSection>
310            <rightSection>
311                <widgets>
312                    <widget id="craftercms.components.EditModesSwitcher"/>
313                    <widget id="craftercms.components.PublishingStatusButton">
314                        <configuration>
315                            <variant>icon</variant>
316                        </configuration>
317                    </widget>
318                    <widget id="craftercms.components.WidgetDialogIconButton">
319                        <configuration>
320                            <title id="words.search" defaultMessage="Search"/>
321                            <icon id="@mui/icons-material/SearchRounded"/>
322                            <widget id="craftercms.components.Search">
323                                <configuration>
324                                    <embedded>true</embedded>
325                                </configuration>
326                            </widget>
327                        </configuration>
328                    </widget>
329                </widgets>
330            </rightSection>
331        </configuration>
332    </widget>
333    <widget id="craftercms.components.Dashboard">
334        <configuration>
335            <widgets>
336                <widget id="craftercms.components.LegacyInReviewDashlet">
337                    <permittedRoles>
338                        <role>admin</role>
339                        <role>developer</role>
340                        <role>publisher</role>
341                    </permittedRoles>
342                </widget>
343                <widget id="craftercms.components.LegacyUnpublishedDashlet">
344                    <permittedRoles>
345                        <role>admin</role>
346                        <role>developer</role>
347                        <role>publisher</role>
348                    </permittedRoles>
349                </widget>
350                <widget id="craftercms.components.ApprovedScheduledDashlet">
351                    <permittedRoles>
352                        <role>admin</role>
353                        <role>developer</role>
354                        <role>publisher</role>
355                    </permittedRoles>
356                </widget>
357                <widget id="craftercms.components.RecentlyPublishedDashlet">
358                    <permittedRoles>
359                        <role>admin</role>
360                        <role>developer</role>
361                        <role>publisher</role>
362                    </permittedRoles>
363                </widget>
364                <widget id="craftercms.components.RecentActivityDashlet"/>
365                <widget id="craftercms.components.IconGuideDashlet"/>
366            </widgets>
367        </configuration>
368    </widget>
369    <widget id="craftercms.components.TinyMCE">
370        <configuration>
371            <setups>
372                <setup id="generic">
373                    <!-- Configuration options: https://www.tiny.cloud/docs/configure/ -->
374                    <!-- Plugins: https://www.tiny.cloud/docs/plugins/opensource/ -->
375                    <tinymceOptions>
376                        <![CDATA[
377                            {
378                                "menubar": true,
379                                "theme": "silver",
380                                "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",
381                                "extended_valid_elements": "",
382                                "valid_children": "",
383                                "toolbar1": "formatselect | bold italic strikethrough forecolor backcolor | link | alignleft aligncenter alignright alignjustify | numlist bullist outdent indent | removeformat",
384                                "code_editor_wrap": false,
385                                "toolbar_sticky": true,
386                                "image_advtab": true,
387                                "encoding": "xml",
388                                "relative_urls": false,
389                                "remove_script_host": false,
390                                "convert_urls": false,
391                                "remove_trailing_brs": false,
392                                "media_live_embeds": true,
393                                "autoresize_on_init": false,
394                                "autoresize_bottom_margin": 0,
395                                "menu": {
396                                    "tools": { "title": "Tools", "items": "tinymcespellchecker code acecode wordcount" }
397                                },
398                                "automatic_uploads": true,
399                                "file_picker_types":  "image media file",
400                                "paste_data_images": true,
401                                "templates": [],
402                                "content_css": [],
403                                "content_style": "body {}",
404                                "contextmenu": false
405                            }
406                    ]]>
407                    </tinymceOptions>
408                </setup>
409            </setups>
410        </configuration>
411    </widget>
412    <references>
413        <reference id="craftercms.siteTools">
414            <tools>
415                <tool>
416                    <title id="dropTargetsMessages.contentTypes" defaultMessage="Content Types"/>
417                    <icon id="@mui/icons-material/WidgetsOutlined"/>
418                    <url>content-types</url>
419                    <widget id="craftercms.components.ContentTypeManagement" />
420                </tool>
421                <tool>
422                    <title id="GlobalMenu.EncryptionToolEntryLabel" defaultMessage="Encryption Tool"/>
423                    <icon id="@mui/icons-material/LockOutlined"/>
424                    <url>encrypt-tool</url>
425                    <widget id="craftercms.components.SiteEncryptTool" />
426                </tool>
427                <tool>
428                    <title id="words.configuration" defaultMessage="Configuration"/>
429                    <icon id="@mui/icons-material/SettingsApplicationsOutlined"/>
430                    <url>configuration</url>
431                    <widget id="craftercms.components.SiteConfigurationManagement" />
432                </tool>
433                <tool>
434                    <title id="GlobalMenu.AuditEntryLabel" defaultMessage="Audit"/>
435                    <icon id="@mui/icons-material/SubjectRounded" />
436                    <url>audit</url>
437                    <widget id="craftercms.components.SiteAuditManagement" />
438                </tool>
439                <tool>
440                    <title id="workflowStates.title" defaultMessage="Workflow States"/>
441                    <icon id="@mui/icons-material/SettingsOutlined"/>
442                    <url>item-states</url>
443                    <widget id="craftercms.components.ItemStatesManagement" />
444                </tool>
445                <tool>
446                    <title id="GlobalMenu.LogConsoleEntryLabel" defaultMessage="Log Console"/>
447                    <icon id="@mui/icons-material/FormatAlignCenterRounded"/>
448                    <url>log</url>
449                    <widget id="craftercms.components.LogConsole">
450                        <configuration>
451                            <logType>preview</logType>
452                        </configuration>
453                    </widget>
454                </tool>
455                <tool>
456                    <title id="words.publishing" defaultMessage="Publishing"/>
457                    <icon id="@mui/icons-material/CloudUploadOutlined"/>
458                    <url>publishing</url>
459                    <widget id="craftercms.components.PublishingDashboard" />
460                </tool>
461                <tool>
462                    <title id="remoteRepositories.title" defaultMessage="Remote Repositories"/>
463                    <icon id="@mui/icons-material/StorageRounded"/>
464                    <url>remote-repositories</url>
465                    <widget id="craftercms.components.RemoteRepositoriesManagement" />
466                </tool>
467                <tool>
468                    <title>GraphQL</title>
469                    <icon id="craftercms.icons.GraphQL"/>
470                    <url>graphiql</url>
471                    <widget id="craftercms.components.SiteGraphiQL"/>
472                </tool>
473                <tool>
474                    <title id="PluginManagement.title" defaultMessage="Plugin Management"/>
475                    <icon id="@mui/icons-material/ExtensionOutlined"/>
476                    <url>plugins</url>
477                    <widget id="craftercms.components.PluginManagement" />
478                </tool>
479            </tools>
480        </reference>
481        <reference id="craftercms.freemarkerCodeSnippets">
482            <contentVariable label="Content variable">
483                <value><![CDATA[${contentModel.VARIABLE_NAME}]]></value>
484            </contentVariable>
485            <requestParameter label="Request parameter">
486                <value><![CDATA[${RequestParameters["PARAM_NAME"]!"DEFAULT"}]]></value>
487            </requestParameter>
488            <crafterSupportMacros label="Crafter support macros">
489                <value><![CDATA[<#import "/templates/system/common/crafter.ftl" as crafter />]]></value>
490            </crafterSupportMacros>
491            <transformPathToUrl label="Transform PATH to URL">
492                <value><![CDATA[${urlTransformationService.transform('storeUrlToRenderUrl', STORE_URL)}]]></value>
493            </transformPathToUrl>
494            <renderComponentsList label="Render list of components">
495                <value><![CDATA[<#list contentModel.VARIABLE_NAME.item as module>
496	<@renderComponent component=module />
497</#list>]]></value>
498            </renderComponentsList>
499            <iterateItemsListLoadContentItem label="Iterate over a list of items and load content item">
500                <value><![CDATA[<#list contentModel.VARIABLE_NAME.item as myItem>
501	<#assign myContentItem =  siteItemService.getSiteItem(myItem.key) />
502	${myContentItem.variableName}
503</#list>]]></value>
504            </iterateItemsListLoadContentItem>
505            <iterateRepeatGroup label="Iterate over repeat group">
506                <value><![CDATA[<#list contentModel.VARIABLE_NAME.item as row>
507	${row.VARIABLE_NAME}
508</#list>]]></value>
509            </iterateRepeatGroup>
510            <fremarkerValueAssignment label="Freemarker value assignment">
511                <value><![CDATA[<#assign imageSource = contentModel.image!"" />]]></value>
512            </fremarkerValueAssignment>
513            <freemarkerIf label="Freemarker value IF">
514                <value><![CDATA[<#if CONDITION>
515	...
516</#if>]]></value>
517            </freemarkerIf>
518            <freemarkerLoop label="Freemarker value LOOP">
519                <value><![CDATA[<#list ARRAY as value>
520	${value_index}: ${value}
521</#list>]]></value>
522            </freemarkerLoop>
523            <freemarkerFragmentInclude label="Freemarker Fragment include">
524                <value><![CDATA[<#include "/templates/PATH" />]]></value>
525            </freemarkerFragmentInclude>
526            <freemarkerLibraryImport label="Freemarker Library import">
527                <value><![CDATA[<#import "/templates/PATH" as NAMESPACE />]]></value>
528            </freemarkerLibraryImport>
529            <htmlPage label="HTML Page">
530                <value><![CDATA[<#import "/templates/system/common/crafter.ftl" as crafter />
531<!doctype html>
532<html lang="en">
533  <head>
534    <#-- Insert your head markup here -->
535    <@crafter.head />
536  </head>
537  <body>
538    <@crafter.body_top />
539    <#-- Insert your body markup  here -->
540    <@crafter.body_bottom />
541  </body>
542</html>]]></value>
543            </htmlPage>
544            <specificHTMLTag label="Field (Specific HTML Tag)">
545              <value><![CDATA[<@crafter.DESIRED_TAG $field="FIELD_ID">${contentModel.FIELD_ID}</@crafter.DESIRED_TAG>]]></value>
546            </specificHTMLTag>
547            <renderComponentCollection label="Render Component Collection">
548              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=renderComponentCollection&check_keywords=yes&area=default -->
549<@crafter.renderComponentCollection $field="features_o" $containerAttributes={ "class": "features-container" } $itemAttributes={ "data-custom-attribute": "true" } />]]></value>
550            </renderComponentCollection>
551            <renderRepeatGroup label="Render Repeat Group">
552              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=renderRepeatCollection&check_keywords=yes&area=default -->
553<@crafter.renderRepeatGroup
554  $field="VARIABLE_NAME"
555  $containerAttributes={'attr': 'value'};
556  item, index
557>
558  <@crafter.div
559    $field="sections_o.section_html"
560    $index=index
561  >
562    ${item.itemField}
563  </@crafter.div>
564</@crafter.renderRepeatGroup>]]></value>
565            </renderRepeatGroup>
566            <navigation label="Navigation">
567              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=crafter.navigation&check_keywords=yes&area=default -->
568  <@crafter.navigation
569    showNavElement=false
570    url="NAVIGATION_URL"
571    containerElementClass="container-class"
572    itemWrapperClass="item-wrapper-class"
573    itemClass="item-class"
574    depth=2
575  />]]></value>
576            </navigation>
577            <breadcrumb label="Breadcrumb">
578              <value><![CDATA[<#-- Macro docs @ https://docs.craftercms.org/en/4.0/search.html?q=crafter.breadcrumb&check_keywords=yes&area=default -->
579  <@crafter.breadcrumb
580    url=contentModel.storeUrl
581    containerElementClass="container-element-class"
582    itemWrapperClass="item-wrapper-class"
583    navElementAttributes={ "data-custom-attribute": "true" }
584  />]]></value>
585            </breadcrumb>
586        </reference>
587        <reference id="craftercms.groovyCodeSnippets">
588            <accessContentModel label="Access Content variable">
589                <value><![CDATA[contentModel.VARIABLE_NAME]]></value>
590            </accessContentModel>
591            <accessTemplateodel label="Access Template variable">
592                <value><![CDATA[templateModel]]></value>
593            </accessTemplateodel>
594            <currentSiteId label="Current Site ID">
595                <value><![CDATA[siteContext.siteName]]></value>
596            </currentSiteId>
597            <requestParameters label="Request Parameters">
598                <value><![CDATA[params]]></value>
599            </requestParameters>
600            <cookies label="Cookies">
601                <value><![CDATA[cookies]]></value>
602            </cookies>
603            <httpRequest label="HTTP Request">
604                <value><![CDATA[request]]></value>
605            </httpRequest>
606            <httpResponse label="HTTP Response">
607                <value><![CDATA[response]]></value>
608            </httpResponse>
609            <session label="Session">
610                <value><![CDATA[session]]></value>
611            </session>
612            <transformPathToUrl label="Transform PATH to URL">
613                <value><![CDATA[urlTransformationService.transform('storeUrlToRenderUrl', STORE_URL)]]></value>
614            </transformPathToUrl>
615            <userProfile label="User Profile">
616                <value><![CDATA[profile]]></value>
617            </userProfile>
618            <currentAuthentication label="Current Authentication">
619                <value><![CDATA[authentication]]></value>
620            </currentAuthentication>
621            <logInfo label="Log an INFO">
622                <value><![CDATA[logger.info('MY MESSAGE')]]></value>
623            </logInfo>
624            <logError label="Log an ERROR">
625                <value><![CDATA[logger.error('MY MESSAGE')]]></value>
626            </logError>
627            <searchService label="Search Service">
628                <value><![CDATA[searchService]]></value>
629            </searchService>
630            <siteItemService label="Site Item Service">
631                <value><![CDATA[siteItemService]]></value>
632            </siteItemService>
633            <profileService label="Profile Service">
634                <value><![CDATA[profileService]]></value>
635            </profileService>
636            <getSpringBean label="Get Spring Bean">
637                <value><![CDATA[applicationContext.get("SPRING_BEAN_NAME")]]></value>
638            </getSpringBean>
639        </reference>
640    </references>
641</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)

1<permittedRoles>
2  <role>ALLOWED_ROLE</role>
3  ...
4</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.

 1<widget id="craftercms.components.ToolsPanelPageButton">
 2  <permittedRoles>
 3    <role>admin</role>
 4    <role>developer</role>
 5  </permittedRoles>
 6  <configuration>
 7    <title id="siteTools.title" defaultMessage="Site Tools"/>
 8    <icon id="@material-ui/icons/TuneRounded"/>
 9    <widgets>
10      <widget id="craftercms.components.SiteToolsPanel"/>
11    </widgets>
12  </configuration>
13</widget>

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

Configurations - User Interface Configuration Permitted Roles Admin

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

Configurations - User Interface Configuration Permitted Roles Admin

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 PathNavigator widget, named sources, in the Sidebar widget like below:

SPA sources - ui.xml
 1<siteUI>
 2  <widget id="craftercms.components.ToolsPanel">
 3    <configuration>
 4      <widgets>
 5        ...
 6        <widget id="craftercms.components.PathNavigator">
 7          <configuration>
 8            <id>Sources</id>
 9            <label>Sources</label>
10            <icon id="@mui/icons-material/InsertDriveFileOutlined"/>
11            <rootPath>/sources/</rootPath>
12            <locale>en</locale>
13          </configuration>
14        </widget>
15        ...

Note

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

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

Configurations - User Interface Configuration Sources Widget in Sidebar

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.

../../_images/page-targeting-open.webp

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

Audience Targeting - ui.xml
 1<widget id="craftercms.components.ICEToolsPanel">
 2  <configuration>
 3    <widgets>
 4      <widget id="craftercms.components.ToolsPanelPageButton">
 5      ...
 6      <widget id="craftercms.components.ToolsPanelPageButton">
 7        <configuration>
 8          <target id="icePanel"/>
 9          <title id="previewAudiencesPanel.title" defaultMessage="Audience Targeting"/>
10          <icon id="@mui/icons-material/EmojiPeopleRounded"/>
11          <widgets>
12            <widget id="craftercms.components.PreviewAudiencesPanel">
13              <configuration>
14                <fields>
15                  <segment>
16                    <id>segment</id>
17                    <name>Segment</name>
18                    <description>User segment.</description>
19                    <type>dropdown</type>
20                    <defaultValue>anonymous</defaultValue>
21                    <values>
22                      <value>
23                        <label>Guy</label>
24                        <value>guy</value>
25                      </value>
26                      <value>
27                        <label>Gal</label>
28                        <value>gal</value>
29                      </value>
30                      <value>
31                        <label>Anonymous</label>
32                        <value>anonymous</value>
33                      </value>
34                    </values>
35                    <helpText>Setting the segment will change content targeting to the audience selected.</helpText>
36                  </segment>
37                  <name>
38                    <id>name</id>
39                    <name>Name</name>
40                    <description>User's first and last name.</description>
41                    <type>input</type>
42                    <helpText>Enter user's first and last name.</helpText>
43                  </name>
44                </fields>
45              </configuration>
46            </widget>
47            ...

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

../../_images/page-targeting-curr-attributes.webp

See Content 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
 1<widget id="craftercms.components.TinyMCE">
 2  <configuration>
 3    <setups>
 4      <setup id="generic">
 5        <!-- Configuration options: https://www.tiny.cloud/docs/configure/ -->
 6        <!-- Plugins: https://www.tiny.cloud/docs/plugins/opensource/ -->
 7        <tinymceOptions>{
 8          "menubar": true,
 9          "theme": "silver",
10          "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",
11          "extended_valid_elements": "",
12          "valid_children": "",
13          "toolbar1": "formatselect | bold italic strikethrough forecolor backcolor | link | alignleft aligncenter alignright alignjustify | numlist bullist outdent indent | removeformat | editform",
14          "code_editor_wrap": false,
15          "toolbar_sticky": true,
16          "image_advtab": true,
17          "encoding": "xml",
18          "relative_urls": false,
19          "remove_script_host": false,
20          "convert_urls": false,
21          "remove_trailing_brs": false,
22          "media_live_embeds": true,
23          "autoresize_on_init": false,
24          "autoresize_bottom_margin": 0,
25          "menu": { "tools": { "title": "Tools", "items": "tinymcespellchecker code acecode wordcount" } },
26          "automatic_uploads": true,
27          "file_picker_types": "image media file",
28          "paste_data_images": true,
29          "templates": [],
30          "content_css": [],
31          "content_style": "body {}",
32          "contextmenu": false }
33        </tinymceOptions>
34      </setup>
35    </setups>
36  </configuration>
37</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 projectTools from the Sidebar.

 1<references>
 2             <reference id="craftercms.siteTools">
 3                     <tools>
 4                             <tool>
 5                                     <title id="dropTargetsMessages.contentTypes" defaultMessage="Content Types"/>
 6                                     <icon id="@mui/icons-material/WidgetsOutlined"/>
 7                                     <url>content-types</url>
 8                                     <widget id="craftercms.components.ContentTypeManagement"/>
 9                             </tool>
10                             <tool>
11                                     <title id="GlobalMenu.EncryptionToolEntryLabel"
12                                            defaultMessage="Encryption Tool"/>
13                                     <icon id="@mui/icons-material/LockOutlined"/>
14                                     <url>encrypt-tool</url>
15                                     <widget id="craftercms.components.SiteEncryptTool"/>
16                             </tool>
17                             <tool>
18                                     <title id="words.configuration" defaultMessage="Configuration"/>
19                                     <icon id="@mui/icons-material/SettingsApplicationsOutlined"/>
20                                     <url>configuration</url>
21                                     <widget id="craftercms.components.SiteConfigurationManagement"/>
22                             </tool>
23                             ...

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.