Updated On 4.1.2

Project (Site) Administration

This section details activities related to project administration in CrafterCMS. The content is oriented towards CrafterCMS administration primarily through Crafter Studio.

Most configuration files can be accessed through Crafter Studio through the Sidebar -> -> Configuration. but can also be modified by accessing the configuration files directly. Please note that it is recommended that changes to configuration files be done through the Crafter Studio UI.

What is a Project/Site?

A project or a site is a collection of related pages/components and assets.

For the project repository, the project structure looks like this:

{REPOSITORY_ROOT}/sites/PROJECTNAME/sandbox/
    config
        engine
        studio
            administration
            content-types
            data-sources
            dependency
            workflow
    scripts
        classes
        components
        pages
        rest
    site
        components
        taxonomy
        website
    static-assets
        css
        fonts
        images
        js
    templates
        system
        web

Credentials may be required in some project configurations. For more information on how to manage/encode your secrets such as AWS credentials, please see Managing Secrets.

Authoring 

In this section we discuss various aspects of managing content, UI, security, etc. in an authoring environment.

Configuration 

To access the configuration settings in Crafter Studio, click on in the Sidebar,

then click on Configuration. After clicking on Configuration, you will see a list where you can select which configuration file you’d like to view/modify. Below is one of the configuration files available to be viewed/modified.

The following items are noted in the image above:

This is the list that contains all the configurations that can be viewed/modified for your project.

This is a short description of the current selected configuration file from the dropdown list.

These are the available actions that can be selected for the current selected configuration file.

This allows the user to encrypt access keys, passwords and other sensitive information required by the current selected configuration file. For more information on how to encrypt sensitive information in a configuration file through Studio, see Automatic Encryption of Secrets in Configuration Files

This allows the user to view the selected configuration’s history

Here are the settings that can be configured through Crafter Studio:

Studio Configuration Files
Configuration File	Description	More Information
Project Configuration (`config/studio/site-config.xml`)	Defines the general project configuration	Project Configuration Content Monitoring
Notification Configuration (`config/studio/workflow/notification-config.xml`)	Defines a list of UI messages to use in notifications	Configure Simple Workflow Notifications and Dialog Messages
Permissions Mapping (`config/studio/permission-mappings-config.xml`)	Defines user access permissions to the project	Permission Mappings Configuration
Role Mappings (`config/studio/role-mappings-config.xml`)	Maps users and groups to roles within the project	Role Mappings Configuration
Content Type Editor Config (`config/studio/administration/site-config-tools.xml`)	Defines controls, data sources, and content types for content authoring	Content Type Editor Configuration
Configurations (`config/studio/administration/config-list.xml`)	Configure this list of configuration files	Configuring the Configuration List
Dependency Resolver Configuration (`config/studio/dependency/resolver-config.xml`)	Configures the dependency resolver	Dependency Resolver Configuration
AWS Profiles (`config/studio/aws/aws.xml`)	Configures the project’s AWS profiles	AWS Profiles Configuration
Box Profiles (`config/studio/box/box.xml`)	Configures the project’s Box profiles	Box Profiles Configuration
WebDAV Profiles (`config/studio/webdav/webdav.xml`)	Configures the project’s WebDAV profiles	WebDAV Profiles Configuration
Asset Processing Configuration (`config/studio/asset-processing/asset-processing-config.xml`)	Configures the project’s asset processing	How to configure asset processing Asset Processing Configuration
Blob Stores (`config/studio/blob-stores-config.xml`)	Configures the project’s blob stores	Managing assets in external storage via blob stores
Project Policy Configuration (`config/studio/site-policy-config.xml`)	Configures the project policy	Project Policy Configuration
User Interface Configuration (`config/studio/ui.xml`)	Configures the user interface	User Interface Configuration
Proxy Config (`config/engine/proxy-config.xml`)	Configures the proxy servers for preview	using-the-proxy-configuration

Crafter Studio supports creating multiple environments with different configuration files for each environment. To setup an environment follow the guide Multi-environment Support.

CrafterCMS supports managing assets in external storage through workflow and publishing mechanics. For more information, see Blob Stores.

Security 

There are various ways for securing access to your CrafterCMS project content in an authoring environment.

Role Mapping

A role represents a set of activities allowed. Role mapping allows users to only see items that they have been granted access to based on the permissions granted to the role they have been assigned to.

See Role Mappings for more information.

Permission Mapping

Permission mapping allows you to assign permissions to folders and objects in a project/site giving specific roles rights to the object.

See Permission Mappings for more information.

Authentication with JWT

JWT authentication allows access to Studio APIs.

See JWT Authentication for more information on creating and using a token.

Additional Authentication Mechanisms

There are other ways for configuring security for your authoring install such as authenticating via headers, SAML, etc.

See Studio Security for more information.

UI 

Dashboards

The dashboards show an overview of the workflow in the project. See here for a description and here for more information on configuring the dashboard.

Localization

Localization is the process of adapting the application/software to a specific culture of end users, such as units of measurements, language, etc., to make the application look and feel natural to the end users.

Project Time Zone

The default dates and times used for displays in Studio is UTC. To customize how dates & times get displayed on Studio UI for a project, edit the following in the project configuration file, by clicking on from the Sidebar, then click on Configuration and finally selecting Project Configuration from the list:

<locale>
  <!--
  BCP 47 language tag (e.g. en-US) or unicode extension (e.g. "en-US-u-ca-buddhist").
  Leave empty for using the user's browser locale (i.e. dates/times will be displayed in each users's system locale).
  Specifying a locale code will apply those localization settings to *all* users regardless of their system settings
  or location. For example, if "en-US", is specified, all users will see dates as month/day/year instead of day/month/year
  regardless of their system (i.e. OS) locale preference.
  -->
  <localeCode/>
  <!--
  Use `dateTimeFormatOptions` to customize how dates & times get displayed on Studio UI.
  For full list of options and docs, visit: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat
  -->
  <dateTimeFormatOptions>
  <!--
  Specifying a time zone (i.e. `timeZone` element) will express dates/times across the UI in the time zone you specify
  here. Leaving it unspecified, will display dates/times to each user in their own system time zone.
  -->
    <!--<timeZone>EST5EDT</timeZone>-->
    <day>numeric</day>
    <month>numeric</month>
    <year>numeric</year>
    <hour>numeric</hour>
    <minute>numeric</minute>
    <!--
    Set `hour12` to "false" to show times in 24 hour format.
    -->
    <hour12>true</hour12>
  </dateTimeFormatOptions>
</locale>

Content 

Large Assets and External Stores

Git is wonderful for managing and tracking textual content, but it’s not ideal for storing binary files or large assets. There are multiple options for storing these large assets using either Studio’s blob stores or various other external stores

Blob Store

The blob store is a Git-like repository for binary files. See here for more information

AWS S3

AWS S3 is a great option for very large externally managed artifacts. See here for more information

Box

Box is a good option when you need to store media and documents that are quite large. See here for more information

WebDAV

Using WebDAV is another good option for collaborating on assets hosted on another server. See WebDAV Profiles Configuration to learn how to configure WebDAV and review the developer documentation WebDAV Asset Access to learn how to access WebDAV assets.

Rich media processing

Images

CrafterCMS supports automatic image processing that allows you to upload just one image that gets converted to the different sizes or formats required by your project for various display sizes. See here for more information

Video (transcoding)

Crafter Studio allows users to upload and transcode videos using AWS MediaConvert in order for users to be able to show the video in different display sizes. See here for more information

Rich Text Editor (RTE)

The RTE (Rich Text Editor) provides an in-context editing experience from within a form (and through preview via the XB) that allows authors to arrange and style content without needing to know HTML For more information on configuring the RTE, see here

Localization

As mentioned above, localization is the process of adapting the application/software to a specific culture of end users.

Content Targeting Guide

Crafter Engine provides the ability to render content adapted to specific users, depending on different aspects like geographical location, language, preferences, etc. Content that is targeted to users is known in CrafterCMS as targeted content.

Language-Based Localized Content

The most common form of targeted content is language-based localization, which is enabled just by specifying some configuration in the Engine’s Project Config.

The Engine project configuration file can be accessed by clicking on from the Sidebar, then click on Configuration and finally selecting Engine Project Configuration from the list:

 <?xml version="1.0" encoding="UTF-8"?>
 <site>
   <targeting>
     <enabled>true</enabled>
     <rootFolders>/site/website</rootFolders>
     <fallbackTargetId>en</fallbackTargetId>
     <mergeFolders>true</mergeFolders>
     <redirectToTargetedUrl>true</redirectToTargetedUrl>
   </targeting>
 </site>

By default, Crafter Engine thinks that targeted content is organized in folders, directly underneath rootFolders. So following the configuration posted above:

Targeting is enabled through the property targeting.enabled.
Each folder underneath /site/website (targeting.rootFolders) will hold the content for a different locale, like en, es, fr, jp, etc.
If for example, Engine will render /site/website/index.xml and the locale for the current user is es_CR, then Engine will try to resolve first to /site/website/es_CR/index.xml, /site/website/es/index.xml, and finally, since en is the targeting.fallbackTargetId, /site/website/en/index.xml. If there was no targeting.fallbackTargetId, then the last candidate page for rendering would be /site/website/index.xml.
The targeting.mergeFolders property will make Engine create merged content trees, which is useful for navigation. For example, assume that for the top navigation of a page the first level of pages under /site/website/{locale} will be displayed, and the locale for the current user again is es_CR. Under es_CR just the “Contact Us” page exists, but under en there are more: “Products”, “About Us” and “Contact Us”. By setting mergeFolders as true, the final pages that are displayed in the navigation would be /site/website/en/products, /site/website/en/about-us and /site/website/es_CR/contact-us.
Normally, if a user goes to my-editorial.com/contact-us, and the current locale is es_CR, then page to be rendered would be resolved to /site/website/es_CR/contact-us, but the browser navigation bar would still show my-editorial.com/contact-us. If targeting.redirectToTargetedUrl is set to true, then instead the user is redirected first to my-editoriaal.com/es_CR/contact-us.

It’s important to point out that if a page exists several times under the same “family” of locales, like en (fallback), es and es_CR, and the merge strategy for the page is targetedContent, the content is inherited following the path of the most general locale to the most specific one, so /site/website/es_CR/contact-us, would inherit and overwrite the content of /site/website/es/contact-us and /site/website/en/contact-us.

Configuration for Custom Targeted Content

As stated before, the most popular case for targeted content is language-based localization, but it isn’t the only one. Sometimes you need to target content according to the user’s region, country, age, gender, etc. For these cases, a little bit more of coding and configuration is needed:

Implement the org.craftercms.engine.targeting.TargetIdManager and put it under your project’s Classes > groovy folder, with any folders that should be part of the Java package in-between (e.g. Classes > groovy > services > targeting > RegionAndCountryTargetIdManager):
- getCurrentTargetId() should return the target ID for the current user, and if the current user doesn’t have a target ID, the default one. E.g. Assume that we’re targeting content by region and country. The getCurrentTargetId() should then return the region_country ID of the current user (na, na_us, lan, lan_cr, etc), and if the current user doesn’t have associated a region/country, the default na is returned.
- getFallbackTargetId() should return the target ID used as “last resort” when resolving the URL of the page to render to the user. Continuing with the region_country example, let’s say the user requested for the /about page, his current target ID is lan_cr, and the fallback target ID is na. Engine will then look for the page in /site/website/lan_cr/about/index.xml, /site/website/lan/about/index.xml and finally /site/website/na/about/index.xml. If the fallback target ID was null, then instead of /site/website/lan_cr/about/index.xml, Engine would look in /site/website/about/index.xml.
- getAvailableTargetIds() returns a list with all the supported target IDs. In case of the region_country solution, the list would contain all the possible region/country combinations, like na, na_us, na_ca, lan, lan_cr, etc.
Add the TargetIdManager implementation as a Spring bean in your project’s application-context.xml (Config > spring > application-context.xml) with the name crafter.targetIdManager:
```
<bean id="crafter.targetIdManager" class="services.targeting.RegionAndCountryTargetIdManager"/>
```

Targeted Content By File Prefix

By default, Engine expects targeted content to be organized by folders. The most common case is to have pages under /site/website to be grouped under locale folders. So pages for en would be put under /site/website/en, pages for es under /site/website/es, and so on.

But sometimes it’s more useful to have content for different targets to be under the same location. And for those cases, Engine can resolve targeted content by file prefix, like index_en.xml, index_en_US.xml, index_fr.xml, etc. To enable this, add the following bean to your project’s application-context.xml (Config > spring > application-context.xml), which will override the targeted content by folder strategy:

<bean id="crafter.targetedUrlStrategy"
  class="org.craftercms.engine.targeting.impl.TargetedUrlByFileStrategy"
  parent="crafter.targetedUrlStrategyBase"/>

Preview 

Preview allows users to see, edit and test the project in a safe authoring sandbox prior to publishing changes.

Proxy Configuration

CrafterCMS supports a proxy system to proxy GraphQL, Engine, NodeJS or other application delivery systems. A proxy server, or proxy for short, is an application or system that acts as a middleman between requests from clients for resources such as a file or web page for example, and the server that provides those resources. Whenever a request is made by a client, the request gets sent to the proxy that then evaluates the request and then performs the required transactions. Proxies forwards web requests, act as a firewall and web filter, provide shared network connections, and cache data to speed up common requests. It helps to simplify/control the complexity of the request, and can provide additional benefits such as load balancing, privacy or security.

See here for an example of setting up the proxy for a React application

Publishing 

The publishing tool available from the sidebar under allows the user to view the publishing status, and various ways of publishing content. See here for more information

Notifications 

To configure HTML notifications that can be sent at each point in the workflow, see here

Staging 

An intermediate publishing target, named staging, is supported by CrafterCMS which allows testing of your project. See here for more information on how to setup a staging target for your project.

Multi-environment Support 

It is often required to have different configurations for different environments. For example, you may want to have developers access different integration services, keys, and configuration than QA, UAT or Prod environments.

CrafterCMS supports environment specific configuration that helps with this, read more about it in the article Multi-environment Support.

Delivery 

In this section, we discuss managing your project, security, etc. in a delivery environment.

URL Rewrites and Vanity URLs 

URL rewriting turns hard to remember, long and complicated URLs into easier to remember, user-friendly and search engine friendly URLs. Simple URL rewrite rules per project can be done through Crafter Engine.

CrafterCMS comes with the Tuckey URLRewrite filter, a Java Web Filter with functionality like Apache’s mod_rewrite, that lets you setup rewrite rules for your project.

To add a URL rewrite rule, in Studio, open the Sidebar then click on . Click on Configuration then select Engine URL Rewrite Configuration (XML Style).

Here’s an example URL rewrite rule for a project created using the Website Editorial blueprint where requests to /articles/2020/12/top-books-for-young-women will be redirected to /articles/2021/1/men-styles-for-winter

<?xml version="1.0" encoding="utf-8"?>
<urlrewrite>
  <rule>
    <from>/articles/2020/12/top-books-for-young-women</from>
    <to type="redirect">/articles/2021/1/men-styles-for-winter</to>
  </rule>
</urlrewrite>

After saving the configuration, remember to publish the configuration file just saved (urlrewrite.xml file). To publish the configuration file, from the Sidebar, click on Dashboard. In the My Recent Activity dashlet, check the box next to the urlrewrite.xml file, and click Publish from the context nav to publish.

Configurations - Publish URL Rewrite Config File from Dashboard

For more information on the UrlRewriteFilter, see http://tuckey.org/urlrewrite/

Security 

There are various ways for securing access to restricted content in your CrafterCMS project in a delivery environment. See here for more information.

Composable 

Blueprints 

CrafterCMS supports the ability to extend the functionality of the platform through the use of plugins and blueprints. Projects can be created out of blueprints which can be built-in, pulled from the Marketplace, or custom built. Learn more about blueprints in the article Blueprints.

Plugins 

Plugins are extensions that can be installed into a project to add functionality. These can extend the functionality of Crafter Studio for added authoring capabilities, or extend the functionality of the project delivery itself by providing features to your project/site. Learn more about plugins in the article Plugins.

Project Tools 

contains project administration tools such as Configurations, Plugin Management, Encryption Tool, etc. The following contains more information on administration tools

Project Tools
- Navigating Project Tools

Project (Site) Administration

Role Mapping

Permission Mapping

Authentication with JWT

Additional Authentication Mechanisms

Sidebar

Top Toolbar

Dashboards

Localization

Project Time Zone

Large Assets and External Stores

Blob Store

AWS S3

Box

WebDAV

Rich media processing

Images

Video (transcoding)

Rich Text Editor (RTE)

Localization

Content Targeting Guide

Language-Based Localized Content

Configuration for Custom Targeted Content

Targeted Content By File Prefix

Proxy Configuration