Reading time: 7 min read
Enabling and configurating the editor toolbar in SitecoreAI Pages
Utilizing SitecoreAI’s Sites API for improved authoring experiences.
Rich text editor customization is finally here
If you've been playing around with Sitecore Pages lately then you'll know one of the long running grievances was the fact that the Rich Text CK Editor wasn't customizable. And I mean, very long running grievances. Those days are finally behind us. You can now fully customize the editor to meet your clients needs including adding custom stylesheet values that match their designs; if you used them. There are still some limitations, but I think the pros definitely outweigh the cons. Before we get going though, you'll want to grab a coffee, because this is not just a matter of clicking a few checkboxes sadly. We need to entirely do this via an API. And multiple ones at that. Have no fear, I've laid this out very simply, just follow along. You'll either be doing this entirely in command-line or a tool like Postman or Bruno. For everything below, I'm running these command-line but the setup is super simple.
Grab an authorization token
Before we can actually begin we need to grab a JSON Web Token (JWT) that we can then use to make all subsequent calls. Head over to your Sitecore Cloud portal and set up an Automation Client. You'll get a Client ID and a Client Secret. Keep these safe!
.png)
Head over to SitecoreAI Deploy, select Credentials, then Environment, and then under Create credentials, select Automation. You'll want to select the environment you are setting up. You could do this under Organization, but from a security perspective, I prefer setting this to Environment as then you won't accidentally update production. Copy the client ID and the client secret and keep them safe.
curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={YOUR_CLIENT_ID}' \
--data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=https://api.sitecorecloud.io'What gets returned is something like this, tho I am obviously not showing the entirely JWT that is returned.
{
"access_token": "xxxxxxxxxx",
"scope": "xmcloud.cm:admin xmcpub.queue:r xmcpub.jobs.t:r xmcpub.jobs.t:w xmcdata.items.t:r xmcdata.prvds.t:rc xmcdata.prvds.t:r xmcdata.prvds.t:w xmcdata.prvds.t:l personalize.exp:mng personalize.tmpl:r personalize.pos:mng",
"expires_in": 86400,
"token_type": "Bearer"
}The access_token is very long, so copy it and keep it handy. It will last for 24 hours and then you'll need to grab a new one but that should be plenty of time to do the changes you need.
Create an editor profile
First thing first, now that we have the JWT token, we can create an Editor Profile. You can find a set of examples here. I highly recommend starting with the full profile and then taking things away. Just makes it easy to work with initially and it gives you something you can show your clients and have them tell you what they don't need versus having them dream up things and then you having to tell them "no" a lot. Here's what the curl code looks like. You would need to replace <your_token_here>with the JWT above.
curl -i -X POST \
https://xmapps-api.sitecorecloud.io/api/ui/v1/editorprofiles \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Full Editor",
"value": "{"toolbar":{"items":["bold","italic","emphasis","underline","style","blockQuote",{"group":"formatting","label":"Formatting","icon":"text","items":["strikethrough","subscript","superscript","|","removeFormat"]},"fontColor","fontBackgroundColor","|","heading","|","alignment","bulletedList","numberedList","|","outdent","indent","|","link","internalLink","phoneLink","|",{"group":"insert","label":"Insert","withText":false,"icon":"plus","items":["sitecoreSelectMedia","insertTable","horizontalLine"]},"|","sourceEditing","|","sitecoreResetFieldValue"]},"style":{"definitions":[{"name":"Article category","element":"h3","classes":["category"]},{"name":"Info box","element":"p","classes":["info-box"]}]}}"
}'Upon submitting the API call, you will get back the editor profile GUID id. Copy it. You'll need it later. If by chance you lose it, don't fret, you can always get it back. You can give the profile any name you wish. If you want to make changes to the JSON object, I recommend copying it into an IDE or formatter so you can see how it's structured. You can see below, there are a number of options to configure.
{
"toolbar": {
"items": [
"bold",
"italic",
"emphasis",
"underline",
"style",
"blockQuote",
{
"group": "formatting",
"label": "Formatting",
"icon": "text",
"items": [
"strikethrough",
"subscript",
"superscript",
"|",
"removeFormat"
]
},
"fontColor",
"fontBackgroundColor",
"|",
"heading",
"|",
"alignment",
"bulletedList",
"numberedList",
"|",
"outdent",
"indent",
"|",
"link",
"internalLink",
"phoneLink",
"|",
{
"group": "insert",
"label": "Insert",
"withText": false,
"icon": "plus",
"items": [
"sitecoreSelectMedia",
"insertTable",
"horizontalLine"
]
},
"|",
"sourceEditing",
"|",
"sitecoreResetFieldValue"
]
},
"style": {
"definitions": [
{
"name": "p1",
"element": "p",
"classes": [
"p1"
]
}
]
}
}One of the most sought after abilities, is to customize the style definitions available to authors. You can add, what appears to be, as many elements as you want. But keep note that the space they show the values is not friendly for a lot of options. The other thing to note is there's nothing preventing authors from selecting multiple options from the list at once. You'll need to have them deselect an option before selecting another. Now that we have our Editor Profile, we need to attach it to the site. First, we will need to grab the site GUID value.
Get a list of available sites
Once again, we can use the API to get a list of sites within the environment. We will also need to utilize the JWT token from earlier. Here's the curl statement you'll want to use.
curl -i -X GET \
'https://xmapps-api.sitecorecloud.io/api/v1/sites?environmentId=<ENVIRONMENT NAME>' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'You will want to replace the <ENVIRONMENT NAME>with the name of the environment, e.g. clientqa. You'll see this from your project. It is not the GUID value, but actually the name you've given your environment. You'll get a massive JSON object in return but the most important value is what comes first.
[
{
"id": "53axxxx50-xxxx-xxxx-xxxx-b4a7xxxx8b5a",
"name": "EXAMPLE",
"description": "",
"displayName": "EXAMPLE",That id value is what you need to copy.
Updating the site's available editor profiles
In order for the Editor Profile to be usable, you need to have it attached to the site and that can only be done via updating the site using the API below. Unlike the others, you're going to be using the PATCH method. Because of this, you really only need to send the site the information you are updating.
curl -i -X PATCH \
'https://xmapps-api.sitecorecloud.io/api/v1/sites/497f6eca-6276-4993-bfeb-53cbbbba6f08?environmentId=main' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"displayName": "Skate Park Site",
"description": "New site for Brand A in English-speaking countries.",
"supportedLanguages": [
"en-US",
"en-CA"
],
"shared": true,
"errorPages": {
"errorPage": "c5a2fe31-46bd-34ae-91fb-d3c24b5a6e7f",
"notFoundPage": "a2fc5e31-6b4d-a43e-9f1b-c2d34b5a6e7f"
},
"sortOrder": 100,
"targetHostname": "skatepark.local",
"brandKitId": "e3f1c5a2-4b6d-4a3e-9f1b-2d3c4b5a6e7f",
"resetThumbnail": true,
"editorProfiles": [
"e2102e93-424a-4a99-a066-7750dbf41b28",
"530f7907-6eec-4b7a-9fcc-98aef2719232"
]
}'This above is the example Sitecore provides, but if all you're doing is updating the editorProfiles values, this is the API call you can use.
curl -i -X PATCH \
'https://xmapps-api.sitecorecloud.io/api/v1/sites/<SITE GUID>?environmentId=<ENVIRONMENT NAME>' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"editorProfiles": ["<EDITOR PROFILE GUID>"]
}'Once you've done that, your editor profile will be in place and active. You can test this by going into Pages (you may need to refresh the page) and you should see any styles you've added. What if you forgot to add your styles? No worries. With the Editor Profile attached to the site, you can simply update the Editor Profile.
Get a list of all editor profiles
If by chance you've misplaced your editor profile GUID. Don't worry, here's how you can find what editor profiles are in your system. You can quickly get them via this curl command, or setup a recurring Postman or Bruno entry for ease of use another time.
curl -i -X GET \
https://xmapps-api.sitecorecloud.io/api/ui/v1/editorprofiles \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'You'll get back an array of all Editors loaded into the system and what they are set as.
[
{
"id": "bf5f979b-xxxx-45e2-xxxx-21f5111cd900",
"name": "Full Editor",
"profile": "{"toolbar":{"items":["bold","italic","emphasis","underline","style","blockQuote",{"group":"formatting","label":"Formatting","icon":"text","items":["strikethrough","subscript","superscript","|","removeFormat"]},"fontColor","fontBackgroundColor","|","heading","|","alignment","bulletedList","numberedList","|","outdent","indent","|","link","internalLink","phoneLink","|",{"group":"insert","label":"Insert","withText":false,"icon":"plus","items":["sitecoreSelectMedia","insertTable","horizontalLine"]},"|","sourceEditing","|","sitecoreResetFieldValue"]},"style":{"definitions":[{"name":"Article category","element":"h3","classes":["category"]},{"name":"Info box","element":"p","classes":["info-box"]}]}}"
}
]Updating an editor profile
Similarly to updating a Site, you can update a profile using the PATCH method. You'll need the Editor Profile ID that you used to update the site. You can then update the name, or the profile. You will need to submit the complete updated profile in the format shown below, i.e. escaped quotes with no line feeds.
curl -i -X PATCH \
https://xmapps-api.sitecorecloud.io/api/ui/v1/editorprofiles/<EDITOR PROFILE GUID> \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Full Editor",
"profile": "{"toolbar":{"items":["bold","italic","underline","link","bulletedList","numberedList"]}}"
}'Delete an editor profile
Made a mistake? You can certainly delete an editor profile through a similar process but I would ensure that the editor profile is not attached to a site before you do.
curl -i -X DELETE \
https://xmapps-api.sitecorecloud.io/api/ui/v1/editorprofiles/<EDITOR PROFILE GUID> \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'If it works, you get a 200 OK response back.
Follow up with clients
While an editor profile might be good at the start, the client may need changes to it over time. It's important to routinely follow up with them if they are needing changes, such as new styles. Hopefully this process is simple enough now that you've seen it laid out.