In previous posts, we mentioned that Portable Text specification can be helpful and 

The Portable Text Specification represents a novel and increasingly popular approach to handling Rich Text in structured content environments, particularly within the realm of content management systems (CMS) and beyond. It's designed to offer a more flexible and extensible way of representing Rich Text beyond the traditional HTML, specifically catering to the needs of decoupled (headless) content management systems. where content needs to be easily portable and render-able across different platforms and devices.

: Portable Text stores rich text data as structured JSON, making it highly portable and easy to manipulate programmatically.

: Content is broken down into blocks, which can be simple text blocks, embedded images, lists, or custom types defined by the developer, facilitating complex content structures beyond simple text formatting.

: Developers can extend the specification with custom block types, allowing for the integration of complex data structures like interactive elements, embedded widgets, or third-party content, directly within the text.

: Being JSON, Portable Text content can be easily rendered on any platform that can process JSON, from web browsers to native mobile apps, and even in server-side rendering scenarios.

In the previous Rich Text example we have been working with:

Narrowing in on the first two blocks, let's look how the following markup would translate to Portable Text.

The JSON object would be defined as follows for Portable Text:

 in our React Native app. When markup does not translate well from Web to a Mobile app, this is where Portable Text can be helpful.

Here is an example of using a PortableText component in React Native:

And we can write a component to handle the 

When it comes to XM Cloud, Rendering Contents Resolvers are a great option as Experience Edge caches the snapshot of the 

Layout Service output including Rendering Content Resolvers

In our first post, we mentioned how being 

 to get data can work against portability of data. Additionally, Layout Service is not a good choice if we are focused on ease of data access.

Additionally, Sitecore also recommends not customizing your XM Cloud instance. Content Resolvers are not in this bucket so this is an acceptable solution, but works against us in other ways. What about GraphQL in XM Cloud? Anything we would want to do with GraphQL is not accessible with Experience Edge. We are limited here in the meantime until extensibility goes to the Experience Edge.

Below is the diagram that shows how Layout Service snapshot is cached in Experience Edge alone with Items and Media. GraphQL sits on the Edge so any extension is not possible.

For XM/XP, the same approach can be taken with Rendering Content Resolvers, however, it would be good to consider configuring some Output Caching for the JSON Rendering component. There is also more we can do here which will follow in a future post.

We are going to work with a Helix module we have established as 

. Here we will implement our Content Resolver. We will need a library that helps us serialize markup to JSON under Portable Text Specification.

A great open-source project, NHI.PortableText, will work great for our needs.

Once the NuGet package is installed in our project, we can implement our Content Resolver.

Let's start with creating it in Sitecore. Under 

/sitecore/system/Modules/Layout Service/Rendering Contents Resolvers/

. In the Type field, we will enter the reference to our class we will create in the next step, 

Foundation.Text.ContentsResolvers.PortableTextContentsResolver, Foundation.Text

In Visual Studio, we place all Content Resolvers under the folder, 

. You will want to make sure the class is created under this folder if you want to follow the same namespace in which the class exists.

Here is the example of our Portable Text Contents Resolver:

 is the method where we handle the JSON output of the rendering. To learn how to implement a Contents Resolver in Sitecore, refer to 

Customizing the Layout Service Rendering Output

Next, we need to create the rendering that will use the Rendering Contents Resolver. Portable Text Rendering will be created as a JSON Rendering and will be configured with our new Portable Text Context Item Resolver.

Now, we can bind the Portable Text Rendering to the presentation of our Page item.

Finally, we can test our Layout Service response for the Page item to see Portable Text is being rendered with our rendering:

One drawback with handling Rich Text just with our new Portable Text Rendering is it does not support inline editing with tools like Sitecore Pages or Experience Editor. Adding this rendering does add bloat to the Layout Service when the rendering may only be used for Mobile apps. It would be helpful if extensibility could be added in XM Cloud as we can control the shape of our data getting back from Experience Edge.

The alternative option to build Portable Text into Sitecore is to build a Rich Text field that ends up storing the serialized markup into Sitecore. This could put the implementation into a grey area of whether we would cross the line in customization in XM Cloud. The big benefit of XM Cloud is no longer needing to upgrade it like XM/XP and if it breaks when Sitecore upgrades your instance then it requires managing that risk.

In a follow-up post, we will build this mechanism in GraphQL in XM/XP instances.

Breaking Free: Portable Text Specification

A bug was discovered in Experience Editor where in particular the on-premise Content Management instance made it impossible to use Experience Editor for all editors. XM Cloud will recover from the issue and allow the Experience Editor to continue to be used.

This issue can be reproduced by deleting an item in Content Editor while another tab has the item loaded in Experience Editor. If the editor returns to the tab and reloads it, then it will trigger the issue. This is not a common use case, but it can mistakenly happen if you love to leave your tabs open as an example.

This can be disruptive when there are a large number of editors using the instance and running publishes. The recovery for the on-premise instance is to restart the application.

Take for example the Page Example item being used as the About page for the site:

Return to the Content Editor and delete the item:

Reload the tab with the item loaded in Experience Editor.

The Ribbon will result in "Server Error in '/' Application"

Upon inspecting the Network traffic in Developer Tools, the following request results in a 500 status code:

 is the Sitecore item that was deleted and 

 is the Home item that Experience Editor was redirected to.

When reviewing the logs, the deleted item is noted as not found.

Further down the logs, there will be exceptions for different parts of the ribbon

In XM Cloud, Experience Editor will be broken as long as a non-existent Item Id is provided. Other items opened in Experience Editor can be completed without issue. The solution is not elegant for editors, but it does not render the Experience Editor useless.

If reproducing with an on-premise installation, be mindful that this will break the ability to use Experience Editor. Use a non-production or sandbox instance to test.

For on-premise instances, the issue breaks Experience Editor for all editors across the instance and the ability to load Experience Editor becomes impossible. The only way to recover from this issue is to recycle the application pool for the Content Management instance.

Sitecore is working on a fix for this issue for on-premise installations and should come out as a pre-release in December. To learn more about pre-releases, refer to 

https://doc.sitecore.com/xp/en/developers/104/platform-administration-and-architecture/sitecore-xp-pre-releases.html

. To reference this issue with Sitecore Support, the following reference number can be used 622162.

Experience Editor Bug with Deleted Items

As the week of October 14th begins, Sitecore enthusiasts flock from around the world to attend yet another Sitecore Symposium. Over the years, this has become a valuable resource for learning how others have been innovating on this CMS platform and getting a glimpse of the upcoming product roadmap. We also know that, over the years, Sitecore has become more than just a CMS platform.

This next year will bring some areas of particular focus as I work with clients on Sitecore: XM Cloud, Headless, Sitecore Personalize & CDP, and AI.

Here are some sessions that will hit the target in these focus areas.

Big Bangs are for Physicists, Not XM Cloud! Five Tech Tips to Streamline Your Transition to Composable Sitecore


This session by UNRVLD’s Jeremy Davis caught my eye because it addresses one of the biggest challenges organizations face when moving from legacy Sitecore systems to XM Cloud. I'm looking forward to learning about the five composable tech tips that can make this migration less daunting.

Leveraging Composable Architecture in Global E-commerce


For businesses with global e-commerce operations, this session promises valuable insights into how composable architecture can help create seamless, personalized experiences across B2C and B2B. It’s a great opportunity to explore how Sitecore can elevate e-commerce strategies.

Accelerate Sitecore XM Cloud Adoption Using Generative AI


Generative AI is becoming an essential part of modern development. I’m eager to see how Sitecore integrates AI to accelerate XM Cloud adoption, particularly with the challenges of migrating from MVC Razor and SXA to React and Next.js.


The partnership between Sitecore and Vercel seems to be yielding some exciting innovations. This session promises a deep dive into how the Vercel AI SDK is helping Sitecore create interactive AI experiences. It’s a step beyond traditional chatbot interactions, and I can't wait to see it in action.

Next-Gen Sitecore Development: Leveraging Large Language Models for Code Generation


As a developer, I'm especially keen to see how large language models (LLMs) can speed up Sitecore-specific code generation. This promises to be a game-changer for development workflows, and I’m curious about the real-world applications of LLMs in Sitecore.

Our Journey Toward Micro Frontends: Decoupling the Monolith and Leveraging XM Cloud in Cytiva E-commerce


This session offers a candid look into the realities of transitioning from a monolithic architecture to micro frontends. Cytiva’s experience with Sitecore and XM Cloud will provide valuable insights into both the successes and challenges of this process. I’m particularly excited to learn about the practical lessons they’ve gained along the way and how they navigated unexpected obstacles.

Building Resilient Integrations with XM Cloud


Integrating with XM Cloud is critical for any organization looking to future-proof its digital ecosystem. This session will delve into scalable architectural concepts using cloud-native technologies, which I’m always interested in exploring to enhance performance and resilience.

Headless SXA vs. Component Builder: The Rock-Off of the Year


This session will be an exciting showdown between two powerhouse frameworks—Headless SXA and the XM Cloud Component Builder. As someone who has experimented with both technologies, I’m looking forward to this ‘rock-off’ to see which emerges for future projects.

All sessions and many more can be found on the conference website: 

These sessions highlight the diverse ways Sitecore is evolving, from composable architectures to AI-powered tools. I’ll share more thoughts and takeaways from the Symposium in a follow-up post, so stay tuned!

Sitecore Symposium 2024 Session Picks

Rich Text or WYSIWYG editors leave the impression to editors that what they see must be how the consuming end user sees it. So much so that an editor may hack a Rich Text field to accomplish the right display of the content on a page.

 This leads to complexity that is hard to manage in content that needs to be distributed.

If a field combines the body of content with inserted call-to-actions, tables, pull quotes, and images, it becomes complex to separate it when it needs to be distributed and carry its meaning to the right channels. The Rich Text field doesn't facilitate the ability to use the meaningful parts.

"If HTML markup and styling were stripped from the rich text field, would any content retain its meaning?"

Content that is tightly coupled with presentation creates issues for it to be portable.

In her book Designing Connected Content, Carrie Hane calls it "Chunking."


She explains that chunks are the smallest form of the defined piece of content. It should aim at what technical writers call "minimum reusable units."

To keep a Rich Text field from hindering portability, there are a few recommendations to keep in mind:

A defined piece of content needs to be entered into a Rich Text field so that it makes sense on its own. Even if all markup is stripped from the field, it should still retain its meaning

Review the content model to separate things like pull quotes, images, and call-to-actions away from Rich Text fields. An example of this is adding a call-to-action within the content of the Rich Text. It may link to a podcast, an e-learning course, or a product, but it alters the meaning and abstracts away what is being linked.

Plan a content strategy around rich text fields, defining a consistent process of content creation that fits the niche yet limits the usage of markup that aligns with text portability.

Pages should be modular without becoming a dumping ground for a Rich Text field. Modular parts can be assembled in the proper presentation at their final distribution.

Finally, with the Rich Text fields you do have, consider storing that content around the Portable Text Specification. Your current CMS may not support it, so this option may be limited.

Finding a Content Strategy with Rich Text

To carry out a good strategy, it is essential to consider how content editors create content in Rich Text fields. A successful strategy would encompass:

Understand how content editors create content with Rich Text today. This should involve interviews with content editors, marketing, and other subject matter experts involved in the content creation process. Consider auditing the current usage of Rich Text fields. The goal is to understand how markup is currently used and the use cases.

Plan for how metadata can be incorporated when creating content. Consider how that may affect the distribution of content to other channels.

Develop a strategy around these fields that strips down the formatting options so the editor focuses strictly on the written word. Remove the distractions of editors spending too much time formatting content. Start the basic minimum options for Rich Text and add what is necessary. It can be things like:

You can't change font family, color, or size.

Limit formatting options to bold, italics,

Allow only sub-heads (two levels deep), block quotes, and links.

Sitecore has the ability to configure Rich Text field types with an HTML Editor Profile. It may be tempting to give the editor the full profile. However, as Sitecore moves toward being a content repository with several APIs to get at data, it would be beneficial to consider what is the proper configuration. If the editor needs to create a lot of complex content with a Rich Text field, then that is the complexity you will need to deal with downstream. It may seem that this can indicate that the content model may need to be revisited.

The HTML Editor Profiles that are provided in Sitecore are found in the Core database:

/sitecore/system/Settings/Html Editor Profiles/Rich Text Default

/sitecore/system/Settings/Html Editor Profiles/Rich Text Full

/sitecore/system/Settings/Html Editor Profiles/Rich Text IDE

/sitecore/system/Settings/Html Editor Profiles/Rich Text Medium

The Rich Text editor already is configured with a toolbar that gives us some basic defaults.

This toolbar will get us most of the way there, but a few things need to be addressed to fit our content strategy. We determined we want editors to do the following:

What needs to be done is add the ability to insert headings (two levels deep) with reserving the 

 tag for the page title. We also need to allow block-quotes and remove the ability to insert symbols. Finally, the toolbar option, Pasting from Microsoft Word, will be removed.

It presents a problem of allowing formatting beyond the ideal state. For example, the editor can write their content in Microsoft Word and use different headings like 

. If it is part of the content strategy to limit the number of headings and believe it is a distraction for the editor.

To make this change, the Rich Text Default profile can be duplicated into a Rich Text Minimal profile

Second, we will need to test along the way. I usually open another browser and log into Content Editor to test Rich Text fields from the content in the Master database. But, we will need to configure a field to use the new HTML Profile we created. To do this go to the data template for the content item that has a Rich Text field and update the Source as with 

/sitecore/system/Settings/Html Editor Profiles/Rich Text Minimal

If you want to set up this profile for every Rich Text field, the configuration can be updated by patching it follows:

Now, we can test the toolbar as we make changes.

Next, let's delete paste from Microsoft Word, which will be an option under 

If we test the Rich Text Editor back in our other browser session, we should see the Paste option for Microsoft Word has been removed:

We did find something better that would assist editors in pasting written word from another source: the ability to paste as plain text.

Once this is added, you can test it in the Rich Text Editor:

Next, let's add the ability to manage our headings and block-quotes. We can expand the Paragraphs node and add options for Heading 2, Heading 3, and Blockquote. Notice the fields for Header and Value when creating the option. The Value field will hold the element used to insert the element around the text.

Finally, we just need to add the Format Block with setting the Click field value as 

Once this is complete, the Rich Text Minimal profile is where we need it to be:

Our next task is to lock down the ability to edit markup. Planning out security for Sitecore and roles you can use to assign editors is always recommended. We will use roles to assign permissions to allow functionality for administrators or power users and limit the functionality for editors. In this scenario, you may want to set up another account that would function like a typical editor. In this case, we are using the 

The Content Editor will add a link above the Rich Text field to allow editing of the markup. This link is where we will add permissions.

Let's configure permissions for this. By going back to the Core database under our Administrator account, we need to find the item 

/sitecore/system/Field types/Simple Types/Rich Text/Menu/

Find the Security field and assign security for this item. For the example, 

 role was used to limit Read access to this item while allowing 

Next, open a browser session to log in with your test editor account and test going to a Rich Text field on a content item.

Also, the Rich Text Editor will provide a way to toggle between Design and HTML.

This option can be removed completely by deleting 

Once this is deleted (or you can set permissions to not read the item with a defined editor role), the toggles should be removed:

This configuration should carry over to Sitecore Experience Editor.The benefit of Sitecore XM was that configuring a profile for Rich Text fields was only done in one place. However, there is one problem if we take these changes to XM Cloud.

The Trouble With Sitecore Pages in XM Cloud

Sitecore Pages is a much lighter editing interface than Sitecore Experience Editor. It provides inline editing of page content.

In the Skater Park demo site in XM Cloud, the right sidebar provides many formatting options and access to the markup. While Sitecore Pages provides many benefits, it currently does not have options to tailor the Rich Text editing to our content strategy.

 tags, which breaks our consistency with heading tags and will impact SEO.

Until Sitecore can manage our Rich Text editing profiles across the platform in XM Cloud, our ability to implement our content strategy will be limited.

In conclusion, optimizing Rich Text fields in Sitecore requires a balance between functionality and control. Limiting formatting options, managing markup access, and tailoring HTML Editor Profiles allow you to streamline the editor experience and ensure content consistency across platforms. While Sitecore’s Rich Text capabilities are robust, aligning them with your content strategy is important to maintain portability and flexibility. Challenges like those found in XM Cloud highlight the need for ongoing adjustments as technology evolves. Implementing these best practices will enhance content creation and improve overall site performance and SEO.

The upcoming blog post will focus on how thinking in the context of structured content can improve content portability. Then we will focus on how we can add Portable Text Specification to Sitecore.

Daniel Jacobson, "Content Portability: Building an API is Not Enough", Programmable Web, November 11, 2009

"Designing Connected Content", Mike Atherton and Carrie Hane, Pearson, 2018, pg 134

Jeff Eaton, "Inline Editing and the Cost of Leaky Abstractions", December 11, 2012, 

https://www.lullabot.com/articles/inline-editing-and-the-cost-of-leaky-abstractions

Breaking Free: Troublesome Rich Text

As .NET developers, we always look for ways to streamline our workflows, reduce repetitive tasks, and create robust, maintainable code. At the recent developer conference, Jerry Nixon introduced us to Data API Builder (DAB), a powerful tool designed to simplify and enhance how we build and interact with data APIs. Here's a summary of the session at Denver Dev Day. He explained why DAB could be a significant addition to your toolkit!

Jerry began by addressing a common scenario: directly interacting with databases from client applications. While this approach works, it's not ideal due to increased complexity and the risk of exposing database details. Traditionally, we would create web APIs in Visual Studio, coding controllers, and set up minimal APIs or fast APIs. However, this process can be repetitive, adding unnecessary lines of code, unit tests, and complexity to your CI/CD pipeline.

Enter Data API Builder. This open-source tool, built by Microsoft, abstracts away repetitive tasks by providing a ready-to-use data API. It's cross-platform, requires no specific operating system or framework, and operates within a container. DAB generates the necessary API endpoints by simply providing a JSON file describing your database.

: DAB is excellent for proof-of-concept projects and production environments. It lets you quickly spin up data APIs, making it ideal for rapid development cycles.

: Whether you're using SQL Server, Cosmos DB, MySQL, or PostgreSQL, DAB supports various back-end databases. It also facilitates seamless migration between different database types without client-side changes.

: With DAB, you configure your API through a JSON file. This approach minimizes coding and focuses on configuration, which is easier to manage and less error-prone.

: DAB is designed with security and robustness. It supports JWT tokens, retry policies, local caching, and more. This ensures your API is secure and resilient.

: Being open source, DAB encourages contributions from the developer community. You can extend its capabilities, ensuring it evolves with your requirements.

Jerry demonstrated how straightforward it is to get started with DAB:

: Install the DAB CLI tool via .NET tools:

 command to create a base configuration file.

: Define your database connections, JWT settings, entities (tables), and permissions in the JSON file.

 command, which reads your environment variables, validates your configuration against the database schema, and sets up the API endpoints.

Imagine a scenario where you need to create an API for a SQL Server database. Instead of writing controllers, setting up routing, and handling data access, you simply configure DAB. It generates REST and GraphQL endpoints, complete with OpenAPI documentation, Banana Cake Pop IDE, and Swagger UI for easy interaction. This drastically reduces development time and ensures consistency across your APIs.

For .NET developers, Data API Builder offers a powerful way to simplify API development. By abstracting the repetitive tasks and providing a robust, configuration-based solution, DAB allows you to focus on building great applications rather than boilerplate code. It's a versatile tool that works well with various databases and integrates seamlessly into your existing workflows.

As Jerry highlighted, the future of database interaction is through APIs. Adopting tools like Data API Builder prepares you for this shift and enhances your development efficiency and code quality. Now is the perfect time to start if you haven't explored DAB yet.

For more detailed information and documentation, visit:

https://learn.microsoft.com/en-us/azure/data-api-builder/

https://github.com/JerryNixon/dab-tool-dotnet-cli

https://chillicream.com/products/bananacakepop/

Launching Your Projects to New Heights with Data API Builder

Content Management Systems (CMS) can be great repositories of your content. However, they can become web publishing tools where content becomes trapped in your presentation. When content needs to be distributed for something other than just a web page, getting data out of it becomes complex.

Take, for example, the page below. It has the following components on it and each one has been dragged and dropped onto a page editor and maybe assigned a data source:

Separating content from presentation is not something that Sitecore does not lack in providing. The separation between data templates (schema) and layout (presentation) makes it possible to separate content from display.

However, Rich Text components on a page in Sitecore might do more harm than good. In the content tree, the Body item is bound only with the Rich Text component that makes the page content. Only the presentation details on the Page Example item can tell you what makes that page.

When Sitecore Headless came out, it came with endpoints to get at content that enabled content distribution beyond a web page. The Layout Service and Graph QL endpoints were introduced to enable the building of JAM Stack solutions. While these API endpoints provide access to the content, problems began to surface when its consumption for other distributions realized that the response was dirty. "Dirty" may be a strong word for it. But let's look at some examples.

This endpoint combines content and presentation in the response when pages are requested. The Layout Service is a JSON object of a page on the site with every component and then the content that fills in that component for that page. This is the heart of the JAM stack solution. Generating pages... For example:

If you were building a Mobile App, you would probably not use the Layout Service to retrieve the data this way. The response just seems heavy and a lot to parse through. It would make sense to go straight to Graph QL. Let's take a look at Graph QL and see how it stacks up.

This endpoint would be expected to the the right fit for distributing content out of the CMS. Why wouldn't it be the right tool for consumption by other mediums? Yet, we still have a problem.

At first, the query is fairly straightforward until we get to the page content. But how do we construct our query to retrieve content?

There are only two options. First, assume the child items in the tree hierarchy determine the order in which rich text is consumed. In this example, our content is the Body item in the content tree under Page Example.

But we know this is not sustainable. How do you enforce such a thing? The editor really shouldn't have to think about where the content goes so it can be consumed properly on Graph QL.

The second option is to get the page presentation. This is done by adding 

 as a property on the query to return this data.

Below is an example of a Graph QL response:

 will stuff the Layout Service response in the Graph QL response. This does not get us any further in getting our content out of the CMS.

The problem statement is the following. It is easy to fall into the trap of data source-driven pages tightly coupled to a page's presentation definition. Sitecore Experience Accelerator (SXA) is built around this. The example presented could be easily remedied by moving the Body item as a field on the page item itself. But it is still Rich Text, which can present some more problems we didn't consider. I will go deeper into Rich Text in another post.

The next problem is we know that content models are not this simple. Once the site gets into Accordions, Tabs, or, dare I say, Carousels, we can only imagine the complexity of piecing all that content on a page.

The ideal solution here is to take time to build out a content model that fits the organization that is consuming it. Structured Content is really what is at the heart of this. We will dig into this with later posts. If the organization is good with a web publishing tool and you are a Sitecore customer, then SXA can fit right in. But, if the organization wants to be omnichannel, involve the right people to build a content model that embraces the portability of its content. A content model can be built correctly in Sitecore.

https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/query-examples-for-the-delivery-api.html

Posts

Breaking Free: Portable Text Specification

Experience Editor Bug with Deleted Items

Sitecore Symposium 2024 Session Picks

Breaking Free: Troublesome Rich Text

Launching Your Projects to New Heights with Data API Builder

Breaking Free: Overcoming Presentation Lock-in Content Management Systems