Forem: Sean G. Wright

Kentico Xperience Design Patterns: Page Type Restrictions

Sean G. Wright — Mon, 03 Apr 2023 11:48:14 +0000

In previous posts we looked at how we can model content with Page Types and Content Hierarchies.

In this post we'll continue our content tree architecture exploration 🗺️ by learning about Page Type restrictions.

This is Part 3 of 4 in a series on Content Tree Architecture in Kentico Xperience 13. You can read Part 1, Part 2, or Part 4.

📚 What Will We Learn?

Limitations are Liberating
Allowed Page Types
Video Library Example
Recommendations
- Always Limit Allowed Page Types
- Clean Up Allowed Page Types
- Disable Linked Pages
Conclusion

Limitations are Liberating

Since we'll be discussing "restrictions" in this post, we should first touch on a mantra of of mine that explains why I find Page Type Restrictions so valuable 💰 in a Content Tree Architecture.

Variety might be the spice 🌶️ of life, but too much can lead to the tyranny of choice.

Image Credit

We want to have choices 😀, but to make the best decisions, in a reasonable amount of time, we need to have the right options to choose from - not every option 🧠.

This idea is directly applicable to the work that marketers and content managers do with a DXP like Kentico Xperience. It gives them many tools and features to accomplish their goals, which is why they love the platform 🤩.

However, if a product has many features and all of them are always available, it can be hard to identify which features are available intentionally and which are incidental to a flexible and powerful product 🤔. We (developers) want the teams we are supporting (marketers, content managers, administrators) to fall into the pit of success 🤗 - curating experiences by limiting choices really helps with this 👍🏾.

Allowed Page Types

What's the point of setting up a consistent, scalable content architecture if we can't help marketers and content managers keep it well organized over the long term 🤷🏻?

One of the best tools to enforcing good organizational practices and guiding those responsible for the site into "the pit of success" is Allowed Page Types.

We can limit where pages of a specific type can be created in the Content Tree, from the perspective of the parent and the child 🧐.

Video Library Example

In the screenshot below, we can see the "Allowed parent page types" for the Video Library Page Type - it can only be created under the Root page ✅.

We can also see that Video Library pages can only have 2 types of child pages - the Call To Action Container and Videos Container.

The Video Container Page Type also has restrictions - it can only be created under a Video Library and can only have Video Year children:

The Video Year and Month follow the same pattern - the Year can only be created under the Video Container with only Months as children and the Month can only be created under the Year with Videos as children 😉:

Finally, we get to the Video Page Type and see it is the end of the content hierarchy. It can only be created under Video Months and cannot have any children:

What this means in practice is the following:

Videos are only found as children of a Year/Month hierarchy in a "Video content" container inside a Video Library.
Administrators of the site don't need to think 😩 about which type of page they can create under Video Containers, Video Years, Video Months, or Videos. Xperience automatically selects the only valid option 🙏🏽, if there is one.
Anyone responsible for managing content in the site can quickly learn 🤓 exactly where to go to find that content, even if there are multiple Video Libraries.
As the number of Videos grows, we don't have to fight against the organization of other types of content (like CTAs) because they have their own organization with container Page Types 😅.

Recommendations

Always Limit Allowed Page Types

We should always limit the Allowed Parent/Child Page Types as much as possible. If we find that a Page Type needs to have many different parent and child pages, it might mean that page is serving too many roles 👈 in the content strategy and we should try to create separate (but maybe similar) Page Types to serve those roles.

There are exceptions to this, like a "Basic Page" that has no structured content and acts as a landing page in multiple areas of a site. But even these types of pages should have their Allowed Page Types limited ✔️.

A strictly organized content hierarchy can always be relaxed over time if the requirements of the site change, but it is very difficult to "put the genie 🧞‍♂️ back in the bottle" and create a sensible organization out of a content tree that's been poorly maintained 🏚️ for years.

It's worth also noting that just because a Page Type only allows a single type of child Page Type we can't also assume that child Page Type can only be placed under that parent 😦.

The Page Type restrictions need to be setup on both ends to be really affective. The parent should have a limited number of child types and the child should have a limited number (often 1) of parent types.

This can be easy to forget, so we should double check 📝 before we deploy our Page Types to a production environment.

Clean Up Allowed Page Types

Additionally, if the requirements of the site allow for a single Video Library (ex: we don't need a Video Library per product line) we can create the Video Library page at the root of the site and then remove the Root page type from its Allowed Parent page types 🤔.

This has the benefit of ensuring only 1 Video Library will ever exist and reduces the options anyone has when creating a new page at the root of the site. "Landing Page" might appear in that list, but "Video Library" never will 😎.

We should give administrators the tools they need to not only do their job, but do it well 👏🏻, by helping them focus on the work that is impactful - not making decisions about things they don't want to do anyway 👍🏾.

In the screenshot below we can see that I've removed the Allowed parent and child Page Types for the Video Library page:

Now, if we try to create a new page under the Video Library in the Content Tree, we can see the application limits us and provides a helpful message explaining why we cannot create any pages here:

As we'll see later, this is helpful in creating and organizing "Content Libraries" in Kentico Xperience 13 🧐.

Disable Linked Pages

Kentico Xperience 13 has a Linked Pages feature that enables creating a copy of a page to another location in the Content Tree without copying any of its content 🤨.

I have used this feature in some very specific situations, but in general I avoid it. Duplicating pages can cause confusion related to where content of this Page Type should be created and there are many other ways to share and reuse content on a site. Linked pages also have some limitations 🫤 that we should be aware of if we decide to use them.

Disabling Linked Pages globally in the Content Tree is pretty simple. We first need to navigate to the Page Type Scopes application and then create a new Scope:

Our new Scope should cover the root of the site / and Apply to the whole section, which means all children for the entire Content Tree. We don't want to use this scope to limit which Page Types we want to use (we can do that with other Scopes), so we select Allow all page types. We will leave Allow creation a linked page unchecked, which will disable Linked Pages for the Content Tree:

If we want to opt-in to Linked Pages somewhere else in the Content Tree, we can create a new Scope for that section of the tree and enable Allow creating a linked page.

The net effect of all this setup is that page creation rules follow the guidance of our Allowed Page Type configuration and our content can be found in predictable locations 🙏🏼.

Conclusion

While the Allowed Page Types feature in Xperience might be simple, it's an important and powerful 💪🏽 tool that helps us keep content organized. Well organized content ensures we'll know where to create new content and we'll be able to govern the content we've already created.

Allowed Page Type configuration is usually dependent on our sitemap, content models, and content architecture. We want to use it to limit choices for marketers and content managers so they only have to choose between options that make sense 😊.

Setting up our initial Allowed Page Types should be followed by removing some allowed types after our page structure has been created in the Content Tree - further reducing options and confusion.

Finally, we might want to consider disabling Linked Pages everywhere except in the specific locations where it is needed.

Remember 🧐, a highly organized Content Tree can be made more flexible if needed, but it's very difficult to enforce structure on one that has been disorganized 🤕 for a long time.

References

Photo by Jordan Madrid on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Design Patterns: Content Hierarchies

Sean G. Wright — Fri, 03 Mar 2023 15:55:10 +0000

In a previous post we looked at how we can model 🗿 content with Page Types and learned about the value of content governance 🧑🏽‍🏫.

In this post we'll continue our Content Tree Architecture exploration by learning about Content Hierarchies.

This is Part 2 of 4 in a series on Content Tree Architecture in Kentico Xperience 13. You can read Part 1, Part 3, or Part 4.

📚 What Will We Learn?

Parent-Child Relationships
Groups and Containers
Hierarchy and URLs
Recommendations
- Planning
- Naming
- URLs
- More Page Types, not Fewer
Conclusion

Parent-Child Relationships

Content models, when combined with sitemaps, reveal a natural hierarchy of content 🤔.

As two examples, a Video Library landing page likely has child Video pages and a Product Line page usually has child Product pages.

This list-detail pattern is very common in content hierarchies but it's not the only one 😯.

A site might have an Office Location page for each regional office. The Office Location pages could then have a child page for each employee at that office. The Office Location page might not show all the employees working at that location, but it can make sense to organize the employees as children of the Office Location anyway.

With this parent-child relationship in mind, we might be inspired to go and create parent and child Page Types for every content model for our site. There's nothing wrong with this approach, but there is also a better alternative 😎.

Groups and Containers

As we already noted, a Video Library landing page is very likely to have child Video pages somewhere in its descendant page hierarchy. These could be direct descendants as seen in this screenshot of the Xperience Content Tree:

As our content structure and site matures, an issue we will encounter with the direct parent-child structure is there's no good place to add other types of structured content 😔.

What if we want to create some structured Call To Action pages that are placed on the Video Library page with the Page Builder? Where would those go in this example 🤷🏻? We could add them as direct children of the Video Library next to the Videos, but then as the number of Video pages grows, the Call To Action pages will get lost in the list 😧.

Imagine another scenario where we have 5 Video pages being created every business day. By the end of the year there could be nearly 1,300 Video Pages in the Video Library - finding a specific Video could be difficult 😫, especially if we're using the Page Selector to select a Video page to feature somewhere else on the site in the Page Builder.

This rate of content growth would also result in more child pages than Xperience recommends for the Content Tree - "each item (page) in the content tree have at most 1000 direct child pages."

A better approach, which takes a little more setup, is to create organizational Page Types and insert those under the Video Library page - all child content would then be contained in the organizational Page Types 🤔:

Above we can see there are several new pages in the Content Tree (Page Name - Page Type):

Videos - Video Container
2022/2023 - Video Year
01/02 - Video Month
CTAs - Call To Action Container
Try Our Coffee For the Full Experience - Call To Action

If your are interested in trying out a prescriptive approach to creating these container pages, check out fellow MVP Mike Wills' Page Asset Folder Module library 👍🏼.

Hierarchy and URLs

In the past, we often needed to consider the impact that the Content Tree structure would have on the URLs generated for each page. Adding too much structure could lead to overly verbose URLs and the need for aliases and URL shorteners 🛠️.

Thankfully, Kentico Xperience 13's Content Tree based routing system is more nuanced and easily customizable. It's up to us, when creating Page Types, to indicate whether a Page Type influences the generated URLs.

Organizational or container Page Types can have the URL feature disabled, which means their existence isn't reflected in the Live site URL structure - they exist purely to make content governance easier for marketers 💪🏻.

From the Xperience documentation

In more advanced scenarios, this added content structure can be leveraged to add Page-level access control lists (ACLs) to what content is visible to users. This applies to both visitors to the Live site and content creators in the Admin application 🙌🏾.

From the Xperience documentation

The disconnection of Live site URLs and content structure from the Content Tree lets us tune content organization to meet content governance needs while also prioritizing visitor experiences 🤓.

Recommendations

Planning

Generally, we model content with Page Type fields but we also need to model content relationships.

A well thought out (and understood) content hierarchy will help our sites scale both in the amount of content (thousands of videos, as an example) and future content usability. What features or new types of content will we need to add that haven't even been imagined yet 🧐!?

The Xperience documentation has specific guidance for sites with a large number of pages in the Content Tree and it aligns with what has been presented in this post.

Ok, so we have some guidelines... but how do those apply to our site's content and requirements? It might not be clear what the best approach is - for developers or content managers 🤷‍♀️.

I recommend planning a few different content structures. Talk with stakeholders about this plan and then demo the Content Tree variations in the Xperience Admin so they can see 👀 an implementation of the abstract concepts.

Don't get too caught up generating all the Page Type fields or code. We don't even need the Live site running at this point, because the goal is to have a visible Content Tree and identify any areas where scalability, requirements, or complexity haven't been resolved 📝.

Naming

We should try to define a naming convention for Page Types to better represent how a Page Type is being used, because with dozens of landing, structured content, and organizational Page Types, things can get confusing 🥴 if we aren't intentional.

Not only are the names of Page Types reflected in the Administration application (primarily in the Content Tree), but also in the application code.

Our goal should be to align the names of Page Types with how stakeholders (content managers and marketers) would name them so we have a ubiquitous language 🧠 across teams. We also want to help developers be able to make safe assumptions about their use when they see them referenced in code 🤓.

Personally, I like using the conventions below, but yours don't have to be identical:

Suffixing Page Types with the URL feature enabled with Page (ex: HomePage).
Suffixing Page Types that is reusable structured content with Content (ex: NavigationContent).
Suffixing Page Types that are organizational or are less important than their children with Group (ex: CTAGroup).

You can read more about Page Type naming conventions in the Kentico Xperience 13 Style Guide.

URLs

It's worth pointing out again that the robust content organization we've been reviewing doesn't have to affect our URLs since Xperience allows us to enable or disable the URL feature for each Page Type 🙂.

Disabling it for an organizational Page Type means it won't participate in URL generation for any child pages that do have the URL feature enabled. This lets us organize content as needed while also ensuring our URLs and content structure match the project planning sitemap ✔️.

This is a feature that's new to Kentico Xperience 13 and can free content managers from the tyranny of the "Content Tree is Sitemap" mentality 😒 (we'll touch on this idea again in a later post).

Try exploring it to see how you can improve content governance without negatively affecting the live site experience for visitors.

More Page Types, not Fewer

It's extremely important to note that in the Video Library example we reviewed earlier, each of the organizational Page Types is a different Page Type. Although we could create a generic "Container" or "Folder" Page Type that can organize anything, this approach would lose 😬 one of the most important benefits of these organizational Page Types.

As we will see in a later post, the Allowed Page Types feature in Xperience is extremely powerful and can lead to amazing content governance, but it requires a broader set of Page Types to leverage fully 🤔.

In general, we shouldn't feel discouraged from creating more Page Types. We should create as many as we need to help ensure a well structured and easily governable content tree 👍🏽.

Conclusion

Modeling content is an extremely important step in implementing an effective and maintainable website. But content in Xperience isn't only the individual structured fields of a page - it's also the relationships between those pages. This relationship modeling can be achieved through the organization of content hierarchies in the Content Tree 🧐.

There's also an aspect of content governance that benefits 😇from a well structured Content Tree in a Kentico Xperience site.

Adding layers of abstraction to the Content Tree can lead to a more manageable site, long term. It can make it easier to find content and result in a more intuitive experience for content managers 🤗. Thanks to Xperience's flexible URL feature, we don't have to sacrifice live site URLs or visitor experience for these administration improvements.

These benefits don't come for free. We will need to spend time planning the Content Tree structure after identifying our content models and pages in the visual sitemap. Creating a sample Content Tree structure can help in this planning process 🗺️ by turning the abstract into something more concrete for stakeholders without too much work.

In the end, content organization is one of the tools we can invest in to help content managers and marketers with the work they do customizing a site's experiences, every day.

As always, thanks for reading 🙏!

References

Photo by Jordan Madrid on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Design Patterns: Page Type Modeling

Sean G. Wright — Wed, 08 Feb 2023 17:15:08 +0000

Designing and organizing content with Kentico Xperience 13 has foundations going back over a decade. Page Types and the Content Tree have existed, in some form or another, for a long time.

These features' longevity is a testament to their design and flexibility, but let's not remain stuck in the past 👴🏽. Instead, let's look at what opportunities they enable for better content creation and governance in Kentico Xperience 13 and beyond 🤓.

This is Part 1 of 4 in a series on Content Tree Architecture in Kentico Xperience 13. You can read Part 2, Part 3, or Part 4 (when published).

📚 What Will We Learn?

History of Page Type Modeling
Content Governance
Modeling With Page Types
Recommendations
- Which Page Types Do We Create?
- Naming Things
- Container Page Types
- Types of Fields
- Improving the Experience
Conclusion

History of Page Type Modeling

Traditionally, Kentico sites using the previous versions' Portal Engine technology were commonly built with "Page (menu item)" pages, which often represented much of the content structure of a site.

This Page Type was also often used for content tree organization. Pages that weren't ever meant to be navigated to or viewed would have URL and template features, just because it was simpler and faster to what was already there 🤷.

When the Page (menu item) seemed a bit much for content organization, there was also a built-in Folder Page Type that could be used (or abused ☠️) to contain just about anything in the Content Tree.

One of the many caveats of the Folder was that its name impacted the URL of its child pages. This meant internal content organization always had an impact on the live site 😔.

There were some common outliers like Products (SKUs) because Kentico provided the SKU structured content fields for product information. The Media Library and Blog Posts also provided some out-of-the-box structured content.

However, structured content wasn't as common as it is today because rich text was king 🤴, the web was the primary (and often only) channel, and a lot of content was authored inline in a page's design.

I don't want it to seem like no one used structured content (many teams used it heavily with great success 👍🏾). It's just that Kentico didn't necessarily encourage or discourage its use - it left it up to implementors to use whatever they wanted (often what they were handed with a newly created site).

Content Governance

Content managers and marketers have learned that while authoring in rich text is simpler for content creation, it leads to poor content governance 😫.

Using rich text for authoring content might be a great solution for a marketing campaign landing page or pillar content because it's not meant to be reused elsewhere on the site or other channels.

But, a product catalog authored in rich text is going to be a nightmare 😵 for content reuse and modification after the first week.

If we move in the direction of structured content (and keep our content separate from the design) we'll set ourselves up for success in content strategy, reuse, and governance. Page Types are the most important starting point to achieve these goals 🤩.

Content authoring and content governance are always going to be competing priorities - often making one easier will make the other more difficult. This isn't always the case, but we need to remember 🧠 there is no perfect solution for every situation.

Modeling With Page Types

Before we begin creating Page Types we want to identify all the content that will appear on the site and model it by defining each field or unit of content and also the way the information in that field can be organized or stored.

This content is often informed by visual sitemaps and a content outline 🧐. If we don't have either of these to work from, we'll find it's hard to define a goal for modeling with Page Types 😕.

A sample visual sitemap by Miro

If we look at the Kentico Xperience 13 Dancing Goat sample site and navigate to the Article Page Type definition, we can see it has several fields that model the content of articles on the site:

If we compare this to the Cafe Page Type definition we can see that there is a different set of fields defined for the Cafe Page Type because the content model for a cafe is different than for an article:

We can see in the screenshot below how these two types of Pages are organized in the Content Tree - each type is grouped under a common parent. This could be because the sitemap requires it, for organization (more on this in a later post), or both.

Page Types model aspects of the visual sitemap and content from the content outline, both defined in the planning phase for a site. Translating from these sources of information into the features available with Xperience's Page Types is an important step in designing a site that supports and grows with an organization.

Recommendations

Which Page Types Do We Create?

Figuring out what is and is not part of each Page Type is key. Creating a new set of custom Page Types for every site should be a normal part of our workflow. The majority of our content should not be a catch-all "Page (menu item)" Page Type. Instead, aim towards creating unique custom Page Types with structured content fields 😎.

From my experiences (and those of other MVPs), having 30-60 custom Page Types is normal. This number might seem very large, especially if we don't have that many content models, but as we'll see in later posts, Page Types don't just model content, they also help with content organization.

Naming Things

While we might try to use structured content as much as possible, we'll still have a basic "Page" that acts as an aggregation point in our site for structured content found elsewhere (more on this in a later post). I typically name the catch-all Page Type "Basic Content Page" because it doesn't have much structured content (a title, primary image, and some metadata).

That said, as developers, we know that naming things is difficult 😅.

Naming things that administrators interact with - even more so - and we want to use names that make sense to them. So, provide them several options to pick from that you think make sense and explain how a Page Type will be used. In 6 years when no one likes the name selected, everyone can have a laugh about it 😆.

Fortunately, some guidance around naming with Page Types has already been collected in the evolving Kentico Xperience 13 Style Guide 👍🏽.

Container Page Types

As an aside, I would recommend against creating creating Page Types without custom fields. I'm all for creating "folder" or "container" Page Types (as we'll see in later posts), but the negatives of Pages without custom fields (not being able to add custom fields ever) far outweigh the cons of having fields but not needing them just yet.

Xperience requires us to add at least 1 custom field, so if we don't have any field to add when the Page Type is created, we can create a Boolean field that isn't required or displayed in the editing form. We can name it "PlaceholderField" to make it clear it's not being used.

Administrators will never see it and we can delete it when actually have custom fields to add in the future 🤗.

Types of Fields

A decision we'll often have to make when modeling Page Types is "what is the best way to store this information?"

In general I'd recommend against storing integer IDs of objects in Xperience because these aren't stable between environments and require special handling by the site when preparing for content staging. Instead use Guid values because they can be guaranteed to be the same in every environment assuming all content gets created in the same environment before being synced to the next 💪🏼.

A decision that bit me several times over the years was using the "Boolean (yes/no)" field type when the content or data I'm trying to model isn't truly binary 🤨.

If we have a Page Type named "Article" and we want to represent if an article is "Premium" or not (can only be accessed by logged in users), we might be tempted to make this a Boolean field - ArticleIsPremium. This will give content managers a simple checkbox in the Page form. If "true" it's premium, otherwise it's standard 🙂.

However, what happens when 6 months later we need to represent if an article is "Limited"? Do we add another Boolean field - ArticleIsLimited? What happens when an article needs to be either limited, premium, or standard but not multiple 😒.

Categories might be a good choice here, but they don't allow us to limit selection to only 1 Category.

It's become clear that "premium" isn't a true/false state of an article. It's one of multiple values for a "catalog level" of an article. Boolean fields are convenient but they lock us into only ever having 2 values.

The trick is to learn to identify when content is actually binary and when it currently has 2 possible values, but isn't inherently binary 😉!

Instead of using a Boolean field, I'd recommend using a standard Text field with the Drop-down list with a List of options:

Even if you start out with only 2 options, this approach to modeling the content is far more scalable 🤓.

Improving the Experience

A Page Type might model a single type of content that has multiple variations or aspects. For example, an Article could have either a related Video or Image Gallery. Ideally, a content manager could select what type of related media an Article has and be presented with fields in the Page's Content form that are relevant to that type of media.

This is another example of the previous topic of not limiting ourselves to Boolean fields.

The Field advanced settings section of the Page Type field's form contains some very powerful 🤘🏿 functionality in the "depending fields" and "visibility condition" settings.

We can use these to deliver a better content authoring and management experience by conditionally showing or hiding fields.

For example, the Image Gallery fields for an Article only appear in the form if the "Image Gallery" option was selected as the type of media for an Article 🥳.

Conclusion

As we've seen, there's a lot of depth to the process of creating Page Types that model our content and sitemap accurately.

Content authoring and governance can sometimes be at odds with each other. Creating the right Page Types isn't just about identifying types of content. It's also knowing the organization goals of a site. Naming things and the content management experience are important and require developers to collaborate with site content managers and marketers 😎.

We can identify some tips for content modeling with Page Types, but because each site's content is different, it's a process with outcomes that are unique to each site.

Throughout this series, I'll be linking to Content Modeling Guide for Kentico Xperience 13.

It's a great resource that helps developers think more strategically 🧐 about building their sites and not focus only on the technical details.

As always, thanks for reading 🙏!

References

Photo by Jordan Madrid on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Exploring Xperience By Kentico: Introductions

Sean G. Wright — Wed, 19 Oct 2022 17:20:43 +0000

In this post we'll be exploring Xperience by Kentico. A high performant and ASP.NET Core based Digital Experience Platform (DXP).

🧭 Starting Our Journey: What's a DXP?

Most developers are familiar with the term Content Management System (CMS) and might have worked with one at some point in their career 🙂.

CMS applications allow content managers to author and manage content (typically pages or media).

Digital Experience Platforms (DXP) are similar because they include content management features. However, they also include a key focus on the experience of visitors on a site and how they interact and engage with content and media 😮. This focus is supported through digital marketing and commerce features.

Kentico has a good explanation of the difference between a CMS and DXP.

🗺 Making a Path: Setting Up Xperience By Kentico

Now that we understand what a DXP is, let's look at how we can get started with Kentico's DXP - Xperience by Kentico.

First things first, if you want to follow along you'll need to setup Xperience by Kentico locally on your machine. Fortunately it's pretty easy 👏🏽!

The setup documentation is straight forward and driven entirely by .NET tooling we've come to love - the dotnet CLI and NuGet packages.

We will need a valid license during the setup process and we can acquire one by signing up for an account in the Kentico Client Portal and generating a new evaluation license (it's really simple!).

There's a full developer tutorial which walks us through setup, configuration, content modeling, and page creation 🧠.

I've already created several demo projects and I can say with 100% confidence that this product is ready to explore and try (even if it doesn't have all the features we might need for production).

Some of the other Kentico MVPs have already started exploring and building sites on Xperience by Kentico!

🌍 Bridging Two Worlds: The Return of the Single Application

A big change in the overall architecture of Kentico Xperience applications came in Kentico 12 MVC, where the "Presentation" application (ASP.NET MVC 5) was separate from the "Administration" application (ASP.NET Web Forms).

This separation allowed the Xperience product team to evolve the features of the Page Builder quickly 🏃🏾‍♀️ without being limited by the Web Forms technology of the administration application.

This pattern continued with Kentico Xperience 13, which now supports ASP.NET Core for the "Presentation" application while the administration application still runs on the well established ASP.NET Web Forms technology.

With Xperience by Kentico we have a return to the classic single-application architecture we're (maybe 🤷🏽‍♀️) familiar with from years past. Since the administration has been rebuilt using the same ASP.NET Core technology that the presentation (live) site uses, they can be combined into a single application 🙌🏼.

In fact, the administration application is delivered as a single NuGet package 🧐 that can be added to your ASP.NET Core presentation application.

Not only is this a return to the convenient single-application model, but it's a far simpler architecture than any previous version of Kentico/Kentico Xperience 🤩.

This is great for developers because it speeds up their ability to build and test custom features, and deploy the application. This is also a win for administrators and marketers because the technology is simpler to understand and there are fewer prickly "gotchas" 🌵 with a single application.

🌞 Live Site Only Deployments

The single application deployment model is great for simplicity, but what about when we want to scale out the "live" site that visitors actually see 🤔?

Do we have to scale out the administration functionality?
If we want to limit exposure of the administration features for security do we have to deploy them to make the live site work?

While two applications did increase complexity, it also gave us an appealing answer to those two questions (hint: nope!)

Fortunately, the folks at Kentico realized that some teams would want to opt-in to deployment complexity for the benefit of flexibility and made sure to support a dual application deployment strategy in Xperience by Kentico 🤓.

From the docs:

The Xperience administration interface (installed via the Kentico.Xperience.Admin NuGet package) and all related customizations can be removed when publishing to production.

Awesome 💪🏿!

🎨 Delightful Designs

The original spirit of the designs of the Web Forms administration application came about in Kentico 8, and while the UI has been refreshed since then, the core patterns are still in use in Kentico Xperience 13.

Xperience by Kentico has taken another leap forward by completely rethinking the design of the administration interface from the ground up.

Many of the same ideas are there, so it will quickly be familiar to anyone exposed to Kentico's products from the past several years, but the interface feels less cluttered, more intuitive, and more dynamic 🍃.

Previously there were limitations on what could be accomplished with the design (and technology) path the administration application was on. Freed from those limitations, the product really shines and we get to see a strong, forward looking UX vision.

These updates aren't limited to the navigation and dialogs that have been revamped across the UI. They can also be seen in the Page Builder which has evolved in some elegant ways when compared to Kentico Xperience 13.

We can even see the beginnings of a mobile-friendly administration UI. I know many of us don't plan to author content or administer a site on our phone 🤳🏻, but you never know when you might want to check on a marketing automation workflow or add a new user to a site while you're waiting in the checkout line at the store or at your kids' sporting event.

Here's some additional screenshots of design changes in the product:

An updated Form Builder with a new Form Component dialog

Fully featured marketing automation Condition Builder for Contact Groups

Redesigned Media Libraries application

Brand new set of icons to associate to Page Types, Page Builder components and other parts of the admin UI.

🚀 Fast and Modern - React and ASP.NET Core

The administration UI is now built on React and ASP.NET Core which means it's fast 🚀!

If you'd like to watch a video to see what it's like to use Xperience by Kentico, check out this one here:

Since the administration UI is integrated into an ASP.NET Core through a NuGet package, it has very little impact on application startup time 🏁.

This is great for developers when iterating through a code > build > test cycle, and it's great for stakeholders because a faster application means faster builds and deployments which enable faster time to market 📈 with new features and experiences!

These new technologies might seem a little intimidating 🤯, especially if we're used to the no-code admin customizations of previous versions of the product.

Thankfully, the new technology can be adopted gradually (as needed) and Kentico provides helpful 🤝🏽 guidance in setting up our local development environment for Admin UI customizations.

The docs also provide some detailed examples of working with React to build custom Form Components which can be used to build any kind of administration experience we can dream up!

With the React-based libraries for customizing the Admin UI being delivered through npm, we can explore the tools and dependencies used to build them 🧐.

At the time of this writing, the product is using the latest version of React - 18.2. Nice 💪🏾!!

📰 Always Fresh - Weekly Updates

One of the most exciting changes for Xperience by Kentico, compared to all previous versions of Kentico's flagship products, is the speed of iteration!

New versions of the Xperience by Kentico are being released nearly every month (with bug fixes being released every week).

Because this breakneck pace 🏎 is a lot to keep up with, the documentation team has been maintaining a changelog for all of us, so we can easily stay up to date with all the latest developments.

Just take a look at the various versions of NuGet packages that have been released over the past 3 months to get a good idea of the tempo Kentico has taken for this product.

They are wasting no time 😅!

Before you start wondering "If I decide to create and Xperience by Kentico project, how do I keep it up to date with all these new releases?", head on over to the docs where a full set of (fairly simple) instructions already exists to get your project on the latest version.

Since Xperience by Kentico relies of standard .NET tooling and NuGet packages, keeping projects up-to-date is far simpler than using the Kentico Installation Manager in the past.

(It can even be automated and made part of our CI/CD process! 🤩)

✈ Heading Home: What's Next for Xperience by Kentico?

For most developers used to Kentico's previous products, the progress being made in Xperience by Kentico is both exciting 🥳 and intimidating 😬.

One key question stands out - how do we get our existing applications onto Xperience by Kentico? Thankfully, Kentico is already working on that and has information about migrations in their documentation.

Expect this migration guide to grow over time as new features are added to Xperience by Kentico and expect the migration toolkit repository to evolve as more use-cases are supported.

So, what about those upcoming features? What are they?

To find out, we just need to browse Xperience by Kentico's roadmap 🗺.

Given the pace at which the team is iterating and enhancing this product, taking a quick glance at plans for the near future every few weeks is probably a good idea!

Which parts of Xperience by Kentico are you most excited about?
Have you tried it out yet?
If not, what's your biggest roadblock?

Answer in the comments below...

As always, thanks for reading 🙏!

Photo by NASA on Unsplash

References

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Bits of Xperience: Displaying Rich Text After a Form Submission

Sean G. Wright — Tue, 06 Sep 2022 12:54:54 +0000

Kentico Xperience's Form Builder enables marketing professionals to quickly build and manage forms in a no-code UI for use across their website 👩🏾‍💼.

The experience for site visitors submitting a form can be customized for successful submissions 👍🏽.

Let's look at what's possible and how a few lines of customized code can extend the functionality even more 😮!

📚 What Will We Learn?

What happens after a Form is submitted
How to customize the Form management UI
How to customize Razor Class Libraries

❓ What Happens After a Form is Submitted?

Forms on a website are one of the most common ways for marketers to engage with visitors.

Let's take the Dancing Goat demo site Contact Form as an example:

When a visitor fills out this Form and submits it, what exactly happens 🤔?

If the form is not valid (based on form field validation) Xperience will re-render the form with validation error UI and messages
If the form is valid, Xperience looks for an existing form entry for the submitter (if the visitor is identified as an existing Contact) and updates it, or adds a new Form submission to the database.
If the Form's Redirect Url is populated, redirect the page to a new URL (usually to display some "thank you" content).
If Form's Display Text is populated, return Display Text and replace the Form with the Display Text.

Redirecting to a new page gives a marketer a lot of control over the visitor's experience 💪🏻, but it also requires maintaining an additional page on the site 😞.

Using the Display Text is simpler and more convenient 🤗!

Unfortunately, the Display Text field only accepts plain text. What if we want to respond to a form submission with a helpful message, links, and maybe a Call To Action with an accessible design 🤷🏼‍♂️?

It seems as though we'll need to customize what kind of content we can author here and how it's displayed on the site after a submission 🤓!

🗃 How to Customize the Form Management UI

The first thing we need to look for is a way to change the Display Text field's Text input to a Rich Text input.

This UI element can be found at CMS\CMSModules\BizForms\Tools\BizForm_Edit_General.aspx:

The key customization we need to make to this file is to register a new "Rich Text" User Control (called HtmlAreaControl) at the top of the file:

<%@ Register 
    Src="~/CMSFormControls/Basic/HtmlAreaControl.ascx"
    TagName="HtmlArea" 
    TagPrefix="cms" %>

With that registration added, we can refer to the control further down the file, replacing the <cms:LocalizableTextBox /> currently being used for Display Text input with a <cms:HtmlAreaControl />:

<cms:CMSRadioButton ... />

<div class="selector-subitem">
    <cms:LocalizableTextBox ID="txtDisplay" runat="server" MaxLength="200" />
</div>

is replaced by:

<cms:CMSRadioButton ... />

<div class="selector-subitem">
    <cms:HtmlArea ID="txtDisplay" runat="server" MaxLength="200" />
</div>

With these two changes, we can rebuild the CMS application and go back to the Form "General" tab and add Rich Text as our Display Text 🦾!

📅 How to Customize Razor Class Libraries

Even though we're now storing Rich Text as our Form's Display Text, we won't get very far if we don't change how that Display Text is rendered on the live site 😏.

Fortunately, ASP.NET Core includes a feature that allows us to override a View included in our project from a Razor Class Library by adding a View file with the exact same name and path as the file from the Razor Class Library 🧐.

The View that controls how the Form Display Text is rendered after a successful submission is in the Razor Class Library at the following path:

~/Views/Shared/Kentico/Widgets/FormWidget/_FormWidgetTextConfirmation.cshtml

We don't have a file at that path in our project, so let's create a new empty one 🙃.

Make sure you use the same path and filename, otherwise ASP.NET Core will see your View as a new one and not a replacement for the View coming from the library!

The Razor in the original View from the library looks this like:

@model string

<div class="formwidget-submit-text">@Model</div>

Which we are going to replace with the following:

@model string

<div class="formwidget-submit-text">@Html.Raw(Model)</div>

By rendering the Model with Html.Raw() we ensure our Rich Text Display Text won't be escaped when displayed on the page.

At this point we can rebuild our ASP.NET Core application and we're all set 🙌🏿!

🏁 Conclusion

With our 2 simple customizations, we can try out the Contact form to see our Rich Text message displayed on the page:

It worked 🎉!

We can use any content or design to our Display Text that can be authored in Rich Text and craft a "richer" experience (pun intended 😆) without having to go through the process of creating a completely separate page to redirect to.

As always, thanks for reading 🙏!

References

Form Builder - Xperience Docs
Form Builder field validation - Xperience Docs
Form Builder Smart Fields - Xperience Docs
Overriding Razor Class Library Views - ASP.NET Core Docs

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Design Patterns: Handling Failures - The Result Monad

Sean G. Wright — Mon, 29 Aug 2022 13:32:35 +0000

In a previous post we looked at the benefits of returning failures instead of throwing exceptions.

We came up with a Result type that could represent an failure or a success of a given operation, either containing a string error message or the value of our operation.

This custom Result type met most of our requirements, but to really unlock its power 🦾 we need to turn it into the Result monad.

Note: This is part 3 of a 3 part series on handling failures.

Part 1 and Part 2

📚 What Will We Learn?

A Refresher on Monads
Modeling Data Access
Handling Results
Map and Bind
Handling Failures

A Refresher on Monads

If you are unsure 😕 of what a monad is, I give a description with some analogies in my previous post Kentico Xperience Design Patterns: Modeling Missing Data - The Maybe Monad.

However, if you don't feel like navigating away and want a quick explanation, think of a monad as a container 🥫, in the same way that Task<T> and List<T> are containers in C# (they are also monads).

You can manipulate these containers in a standard way, independent of what's inside and each type of monad represents a unique concept 🧠. A Task<T> represents a value T that will be available at some point in the future and List<T> represents a collection of 0 or more of some type T.

It's worth noting that monads can contain other monads, because they don't care what kind of data they contain (ex: Task<List<T>> or List<Task<T>>).

Let's consider the Result<TValue, TError> monad 😮.

It is a container that represents an operation that either succeeded or failed (past tense). If it succeeded then it will have a value of type TValue and if it failed it will have an error of type TError.

The specific implementation of the Result monad that we will be using comes from the C# library CSharpFunctionalExtensions 🎉 and we will use the simplified Result<T> where the TError error type is a string and doesn't need to be specified.

Modeling Data Access

Now we can answer the question of when and where do we actually use Result<T>.

I recommend starting somewhere our application is performing an 'operation' which could succeed or fail and we're currently modeling the failure case with a throw new Exception(...); or by ignoring it altogether.

Here's an example that might look similar to some Kentico Xperience code we have written:

public async Task<IActionResult> Index()
{
    BlogPost page = pageDataContextRetriever
        .Retrieve<BlogPost>()
        .Page;

    Author author = await authorService.GetAuthor(page);

    Image bgImage = await blogService.GetDefaultBackgroundImage();

    Image heroImage = await blogService.GetHero(page);

    return new BlogPostViewModel(
        page, 
        author, 
        bgImage, 
        heroImage);
}

In the applications I work on, it's pretty common to grab bits of data from various pages, custom module classes, the media library, ect... to gather all the content needed to render a page 🤓.

However, each of these operations needs to go to the database, an external web service, or the file system to look for something. It might even have some business rules 📃 around how the data is retrieved.

If something goes wrong in the sample code above we can assume that an exception is going to thrown and centralized exception handling will catch it and display an error page.

We end up skipping the rest of the operations, even if they would have succeeded 😞. With centralized exception handling we typically never partially display a page that experienced some failures.

Let's update the code to use Result<T> and see where that gets us:

public async Task<IActionResult> Index()
{
    BlogPost page = pageDataContextRetriever
        .Retrieve<BlogPost>()
        .Page;

    Result<Author> author = await authorService.GetAuthor(page);

    Result<Image> bgImage = await blogService
        .GetDefaultBackgroundImage();

    Result<Image> heroImage = await blogService.GetHero(page);

    return new BlogPostViewModel(...); // 🤔
}

Our potential failures are no longer hidden as exceptions behind a method signature. Instead, we're requiring consumers of the authorService and blogService to deal with both the success and failure cases.

However, we now have a bunch of Result<T> instances that are useless to our BlogPostViewModel 😩, so we'll need to do something to get the data they potentially contain to our Razor views.

Handling Results

One option for rendering when using Result<T> is to update the BlogPostViewModel to use Result properties and 'unwrap' them in the View:

public record BlogPostViewModel(
  BlogPost Post,
  Result<Author> Author,
  Result<Image> HeroImage,
  Result<Image> BgImage);

In this case, we'd pass our results directly to the BlogPostViewModel constructor in our Index() method:

public async Task<IActionResult> Index()
{
    BlogPost page = // ...
    Result<Author> author = // ...
    Result<Image> bgImage = // ...
    Result<Image> heroImage = // ...

    return new BlogPostViewModel(
        page, author, heroImage, bgImage);
}

Then, in our View we can unwrap conditionally to access the values or errors that were the outcomes of each operation:

@model Sandbox.BlogPostViewModel

@if (Model.HeroImage.TryGetValue(out var img))
{
  <!-- We retrieved content successfully -->
  <div>
    <img src="img.Path" alt="img.AltText" />
  </div>
}
else if (Model.HeroImage.TryGetError(out string err))
{
  <!-- Content retrieval failed - show error to admins -->
  <page-builder-mode exclude="Live">
    <p>Could not retrieve hero image:</p>
    <p>@err</p>
  </page-builder-mode>
}

This is an interesting approach because it allows us to gracefully 💃🏽 display error information for any operations that failed, while continuing to show the correct content for those that succeed.

In this example we were able to treat all the Result<T> as independent because none of the operations were conditional on the others, but that's not always the case 😮.

Let's enhance our BlogPostViewModel to include related posts (by author) and those post's taxonomies:

public async Task<IActionResult> Index()
{
    BlogPost page = // ...
    Result<Author> author = // ...
    Result<Image> bgImage = // ...
    Result<Image> heroImage = // ...

    Result<List<BlogPost>> relatedPosts = await blogService
        .GetRelatedPostsByAuthor(page, author);

    Result<List<Taxonomy>> taxonomies = await taxonomyService
        .GetForPages(relatedPosts);

    return new BlogPostViewModel(...);
}

We're now an in awkward situation where we have to pass Result<T> to our services. Those service methods will have to do some checks to see if the results succeeded or failed and conditionally perform the operations.

The monad is 'infecting' 😷 our code, and not in a good way.

Ideally we'd only call our services if the depending operations (getting the Author and related BlogPosts) succeeded. As with most monads, we'll have a better experience by "lifting" our code up into the Result instead of bringing the Result down into our code 😉.

This is similar to how we work with Task<T>. We don't often pass values of this type as arguments to methods. Instead we await them to get their values and pass those to our methods.

We can also compare this to creating methods that operate on a single value of type T vs updating all of them to accept List<T>.

Fortunately there's an API for that. We want to use Result<T>.Bind() and Result<T>.Map():

public async Task<IActionResult> Index()
{
    BlogPost page = // ...
    Result<Image> bgImage = // ...
    Result<Image> heroImage = // ...

    // result is Result<(Author, List<BlogPost>, List<Taxonomy>)>
    var result = await authorService.GetAuthor(page)
           .Bind((Author author) => 
           {
               return blogService
                   .GetRelatedPostsByAuthor(page, author)
                   .Map((List<BlogPost> posts) => 
                   {
                       return (author, posts);
                   });
           })
           .Bind(((Author, List<BlogPost>) t) => 
           {
               return taxonomyService
                   .GetForPages(t.posts)
                   .Map((List<Taxonomy> taxonomies) => 
                   {
                       return (t.author, t.posts, taxonomies);
                   });
           });

    return new BlogPostViewModel(...);
}

So, what's going on here 😵😵?

Let's break it down piece by piece 🤗.

authorService.GetAuthor(), blogService.GetRelatedPostsByAuthor() and taxonomyService.GetForPages() return Result<T>, so we can chain off them with Result<T>'s extension methods.

The Map() and Bind() extension methods will only execute their delegate parameter if the Result is in a successful state - that is, if the previous operation didn't fail 👍🏾.

This means we only get related blog posts if we were able to get the current post's author. And, we only get the taxonomies if we were able to get related blog posts.

If any part of this dependency chain fails, all later operations are skipped and the failed Result is returned from the final extension method 🙌🏼.

Map and Bind

To help make the above code a bit more transparent, let's review the functionality of Map() and Bind():

Map() is like LINQ's Select method, which converts the contents of the Result<T> from one value to another (it could be to the same or different types).

We often use Map() when we want to transform the data returned from a method call to something else - like converting a DTO to a view model. We don't know if the method successfully completed its operation 😏, we assume it did and declare how to transform the result. Our transformation is skipped if the data retrieval failed.

Bind() is like LINQ's SelectMany, which flattens out a nested Result (ex IEnumerable<IEnumerable<T>> or Result<Result<T>>).

We'll typically use Bind() when we have dependent operations.

When one service returns a Result and we only want to call another service if the first one succeeded we will write something like:

Result<OtherData> result = service1
    .GetData()
    .Bind(data => service2.GetOtherData())

You'll notice 🧐 we have a common pattern of Bind() followed by a nested Map(). Bind() is calling the dependent operation and Map() lets us continue to gather up the data from each operation into a new C# tuple.

We can skip the braces, type annotations, and return keywords and use expressions to keep our code terse and declarative - reading like a recipe 👩🏻‍🍳:

public async Task<IActionResult> Index()
{
    BlogPost page = // ...
    Result<Image> bgImage = // ...
    Result<Image> heroImage = // ...

    // result is Result<(Author, List<BlogPost>, List<Taxonomy>)
    var result = await authorService.GetAuthor(page)
           .Bind(author => blogService
               .GetRelatedPostsByAuthor(page, author)
               .Map(posts => (author, posts)))
           .Bind(set => taxonomyService
               .GetForPages(set.posts)
               .Map(taxonomies => (set.author, set.posts, taxonomies)));

    return new BlogPostViewModel(...);
}

If this feels too unfamiliar, and we want a place to add breakpoints for debuggability, we can extract each delegate to a method and pass the method group, which can be even more readable 😁:

public async Task<IActionResult> Index()
{
    BlogPost page = // ...
    Result<Image> bgImage = // ...
    Result<Image> heroImage = // ...

    // Here is our recipe of operations
    var result = await Result.Success(page)
           .Bind(GetAuthor)
           .Bind(GetRelatedPosts)
           .Bind(GetTaxonomies);

    return new BlogPostViewModel(...);
}

private Task<Result<(BlogPost, Author)>> GetAuthor(BlogPost page)
{
    return authorService.GetAuthor(page)
        .Map(author => (page, author));
}

private Task<Result<(List<BlogPost>, Author)>> GetRelatedPosts(
    (BlogPost page, Author author) t)
{
    return blogService.GetRelatedPostsByAuthor(
            t.page, t.author)
        .Map(posts => (posts, t.author));
}

private Task<Result<(Author, List<BlogPost>, List<Taxonomy>)>> GetTaxonomies(
    (List<BlogPost> posts, Author author) t)
{
    return taxonomyService
        .GetForPages(t.posts)
        .Map(taxonomies => (t.author, t.posts, taxonomies));
}

Handling Failures

If our entire pipeline of operations are dependent and we should skip trying to render content if we can't access everything we need, we can use the Match() extension and provide delegates that define what should happen for both success and failure scenarios:

public async Task<IActionResult> Index()
{
    BlogPost page = // ...

    return await authorService.GetAuthor(page)
           .Bind(author => blogService
               .GetRelatedPostsByAuthor(page, author)
               .Map(posts => (author, posts)))
           .Bind(t => taxonomyService
               .GetForPages(t.posts)
               .Map(taxonomies => new BlogPostViewModel(t.author, t.posts, taxonomies)))
           .Match(
               viewModel => View(viewModel),
               error => View("Error", error));
}

Now we're really seeing the power of composing Result<T> 💪🏽. Each of our services can fail, but that doesn't complicate our logic that composes the data returned by each service.

Without Result<T> we could use exceptions to signal errors - hidden from method signatures and used as secret control flow 😝.

Or, we have a bunch of conditional statements 😝, checking to see what 'state' we are in (success/failure), often modeled with Nullable Reference Types.

With Result<T> we let the monad maintain the internal success/failure state and write our code as a series of steps that clearly defines what we need to proceed.

If we have operations that aren't dependent, we can gather up all the various Result<T> values, put them in our view model and handle the conditional rendering in the view 🤘🏼.

My general recommendation is to separate independent sets of operations into View Components 🤔. We treat each View Component as a boundary for errors or failures instead of populating a view model with a bunch of Result<T> values, potentially making our views overly complex.

We can create a ViewComponent extension method to help us easily convert a failed Result to an error View:

public static class ViewComponentResultExtensions
{
    public static Task<IViewComponentResult> View<T>(
        this Task<Result<T>> result, 
        ViewComponent vc)
    {
        return result.Match(
            value => vc.View(value),
            error => vc.View("ComponentFailure", error));
    }
}

We can place the failure View in a shared location ~/Views/Shared/ComponentFailure.cshtml and have it show an error message in the Page Builder and Preview modes, but hide everything on the Live site 🙂:

@model string

<page-builder-mode exclude="Live">
    <p>There was a problem loading this component.</p>
    <p>@Model</p>
</page-builder-mode>

If we're following the PTVC pattern, we can use this in a View Component as follows:

public class BlogViewComponent : ViewComponent
{
    public Task<IViewComponentResult> InvokeAsync(
        BlogPost post) =>
        authorService.GetAuthor(page)
           .Bind(author => blogService
               .GetRelatedPostsByAuthor(page, author)
               .Map(posts => (author, posts)))
           .Bind(t => taxonomyService
               .GetForPages(t.posts)
               .Map(taxonomies => new BlogPostViewModel(t.author, t.posts, taxonomies)))
           .View(this);
    }
}

We now have the added benefit of an expression bodied member as a method implementation 😲!

Conclusion

Moving from C# exceptions to the Result monad can take some getting used to. It's also a change that should be discussed with out team members and implemented where appropriate (Exceptions still have their place! 🧐).

If we do decide it's an option worth exploring, what do we gain?

Honest methods that don't hide the possibility of failures from their signatures.
A consistent set of patterns and tools for combining Results.
Local, targeted handling of failures that prevents them from failing an entire page (unlike centralized exception handling).
A recipe of operations that reads like a set of instructions on how to gather up the data we need to proceed through our app.
No repeated boilerplate if/else statements to handle various failures.

If you think your Kentico Xperience site might benefit from returning failures and using the Result monad, checkout the CSharpFunctionalExtensions library and my library-in-progress XperienceCommunity.CQRS. It codifies these patterns for data retrieval and integrates cross-cutting concerns like logging and caching.

I'd love to hear your thoughts 👋!

...

As always, thanks for reading 🙏!

References

Kentico Xperience Design Patterns: Handling Failures - Return Errors, Don't Throw Them
Monad - Wikipedia
Kentico Xperience Design Patterns: Modeling Missing Data - The Maybe Monad
CSharpFunctionalExtensions
Kentico Xperience Design Patterns: Handling Failures - Centralized Exception Handling
LINQ Select - Microsoft Docs
LINQ SelectMany - Microsoft Docs
C# Tuple - Microsoft Docs
C# Method Groups - Stack Overflow
Nullable Reference Types - Microsoft Docs
Kentico Xperience Design Patterns: MVC is Dead, Long Live PTVC
C# Expression Bodied Member - Microsoft Docs
XperienceCommunity.CQRS - GitHub

Photo by Jordan Madrid on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Design Patterns: Registering Xperience Dependencies

Sean G. Wright — Mon, 27 Jun 2022 14:03:29 +0000

Kentico Xperience has supported dependency resolution (both in ASP.NET Core and .NET 4.x) for a few versions, through the service locator pattern 🧐.

Now, with Kentico Xperience 13, it fully supports dependency injection (DI) out of the box using ASP.NET Core. We can always inject any of Xperience's built-in services into our custom types without needing to worry about how those services are constructed 🤩.

However, we still need to be conscious of Xperience's underlying architecture when doing anything beyond simple use-cases 😮.

If we don't pull back the curtain, there are things we might do to improve convenience that have significant impacts on code reusability, discoverability, and automated testing 😟.

📚 What Will We Learn?

How does Xperience manage internal dependencies?
How can we customize Xperience's internal types?
When do customizations become inflexible?
Best practices for registering custom types with Xperience.

💎 Xperience's DI Container

In Kentico Xperience's core, there is a static service locator class CMS.Core.Service. With it, we can request any service that Xperience has registered in its internal DI container.

IUserInfoProvider provider = Service.Resolve<IUserInfoProvider>();

UserInfo user = provider.Get(1);

Note: This DI container is actually backed by Microsoft.Extensions.DependencyInjection.ServiceCollection, which is the same type that backs ASP.NET Core's DI container 🤓 and it works in both .NET 4.8 and .NET 6.0.

However, it is a completely separate container from the one ASP.NET Core provides us 🤔 so we should follow Xperience's documentation for dependency registration for Xperience type customization.

We can also use this service locator to register types with Xperience's DI container. The service registration needs to be performed in a custom Xperience Module during the PreInit phase of application startup:

public class CustomUserInfoProvider : UserInfoProvider
{
    public override ObjectQuery<UserInfo> Get()
    {
        // do something special 🤷‍♂️
    }
}

// ...

public class CustomModule : Module
{
    public CustomModule : base(nameof(CustomModule)) { }

    protected override OnPreInit()
    {
        Service.Use<IUserInfoProvider, CustomUserInfoProvider>();
    }
}

Since it's using the .NET ServiceCollection underneath, we can even use it to register configuration via the options pattern (again in the Module.OnPreInit method):

// I'm making up a `CustomUserOptions` type here as an example
public class CustomUserOptions
{
    public int DefaultUserID { get; set; }
}

// ...

Service.Configure<CustomUserOptions>(o =>
{
    o.DefaultUserID = 1;
});

This means we should also be able to retrieve this configuration through Service.Resolve anywhere in our application:

var options = Service.Resolve<IOptions<CustomUserOptions>>();

int userID = options.Value.DefaultUserID;

This isn't very useful outside of an ASP.NET Core application or modern (.netcoreapp3.1 +) .NET class libraries. We should use the built-in .NET DI container for this kind of thing, so it's more just an interesting observation.

We could use Service to get access to any Xperience type we want in our ASP.NET Core app, but in user-land code (code that isn't part of a framework), using a service locator for retrieving services is an anti-pattern 😩.

Instead, use constructor dependency injection wherever possible 🙂, and hide away your use of the Service class if you must use it. This will make your code more testable and predictable.

Customizing Xperience's Internal Types

Above, we looked at an example of how to customize Xperience's built-in types (like IUserInfoProvider) using the Service.Use method.

However, there's a much more common pattern using assembly attributes for registering dependencies that you'll see in blog posts and Xperience's documentation:

// This tells Xperience to add our custom type to its services container
[assembly: RegisterCustomProvider(typeof(CustomUserInfoProvider))]

namespace Sandbox.Data
{
    public class CustomUserInfoProvider : UserInfoProvider
    {
        public override ObjectQuery<UserInfo> Get()
        {
            // do something special 🤷‍♂️
        }
    }
}

This assembly attribute registration pattern is also used for custom modules, for example when creating a custom module to handle global events:

[assembly: RegisterModule(typeof(CustomGlobalEventsModule))]

namespace Sandbox.Data
{
    public class CustomGlobalEventsModule : Module
    {
        public CustomGlobalEventsModule
            : base(nameof(CustomGlobalEventsModule)) { }

        protected override void OnInit()
        {
            base.OnInit();

            DocumentEvents.Insert.After += Document_Insert_After;
        }

        private void Document_Insert_After(
            object sender, DocumentEventArgs e)
        {
            // Add custom actions here
        }
    }
}

These assembly attributes are a lot simpler and seem to be the way to go:

Create our custom class
Add an attribute above
Our customization is registered and ready to run 😁!

Note: We'll typically only use Service.Use when we want to have an explicit ordering to service decoration, because the assembly attributes for dependency registration are non-deterministic.

Non Flexible Dependency Registration

Xperience's documentation provides plenty of examples of registering customizations in the same assembly, and often the same file, where they are defined.

This is perfect for helping developers understand concepts 👍🏾. However, as our applications grow in size and complexity, and we discover use-cases for using Xperience's APIs outside of traditional web applications, we will find we've strung ourselves up in our dependencies 😒.

In ASP.NET Core, we are used to adding NuGet packages containing types that customize our applications. We enable those customizations when we call extension methods that add types to the IServiceCollection or modify request processing of the IApplicationBuilder.

Simply adding a NuGet package or reference to a .NET project (typically) does not change the behavior of our application - this is going to be a .NET developer's expectation 😤.

The problem with assembly registration attributes like [assembly: RegisterModule()] and [assembly: RegisterCustomProvider()] is they are DI container configuration calls that always 😲 execute in a running application, even if they aren't in our main application's code.

External Applications

Imagine we create a .netstandard2.0 class library (so that we can share its code with both our CMS .NET 4.8 application and live site ASP.NET Core application) and this library contains our custom Page Type definitions and some other code we want to share between both applications.

It's also likely that this library registers several custom providers and modules using assembly attributes.

Now, if we decide we want to use this library in an external application like a console application, we cannot opt-out of those registered modules and custom providers 😔. They always come along for the ride and automatically augment our system.

At WiredViews we often use .NET 6 console applications to iterate quickly on ETL/data import or migration processes and often we want to selectively opt-in to specific custom modules or types and opt-out of others.

When the referenced code contains these assembly attributes, our hands are tied - we can't turn them off.

Testing and Troubleshooting

Other times, a developer might want to test a specific scenario locally with a custom provider that behaves slightly differently or use an updated custom module implementation.

If class libraries are distributed through NuGet packages and those libraries have assembly registration attributes, what are the answers to the following questions 🤔?

How would a developer easily set up their testing scenario?
How can they control what dependencies are registered and executed?
How do new developers even know what customizations are running in an application? Do they have to go digging through all the source code to find out 😩?

In the modern ASP.NET Core world, we're used to commenting out an extension method in our middleware pipeline or services registration to turn functionality off.

We could use app settings to replicate this behavior even when our NuGet packages contain [assembly: RegisterModule()] calls. Those modules or custom types would need to check the app settings to enable/disable the custom behavior 😯.

But, this requires developers to have one set of expectations for non-Xperience application customizations and a completely different set for Xperience customizations 😑.

There's a better way!

Flexible Dependency Registration

All we need to do to bring some consistency and flexibility to our applications is to remove our dependency registration from our class libraries and move it into our consuming applications.

This way customizations only turn 'on' when they are explicitly registered in the applications that want them 🤗.

In the ASP.NET Core world, if we are practicing good Startup.cs hygeine we might end up with a XperienceRegistrations.cs class:

[assembly: RegisterModule(CustomGlobalEventsModule)]
[assembly: RegisterCustomProvider(CustomUserInfoProvider)]

namespace Sandbox.Web.Configuration;

public static class XperienceRegistrations
{
    public static IServiceCollection AddAppXperience(
        this IServiceCollection)
    {
        // register our Xperience services with ASP.NET Core
        services.AddKentico();

        // ...

        return services;
    }
}

Notice, we opt-in to our Xperience customizations that require assembly attributes by registering them in the same locationn that all our other Xperience-specific customizations are defined.

This makes it extremely clear what is being customized in an app and allows developers to turn things on/off in a way that is very similar to all the other code they work with in ASP.NET Core 💪🏽.

We can follow this pattern in our CMS ASP.NET 4.8 application by creating a DependencyRegistrationModule in that application's project:

[assembly: RegisterModule(typeof(DependencyRegistrationModule))]

[assembly: RegisterModule(typeof(CustomGlobalEventsModule))]
[assembly: RegisterCustomProvider(typeof(CustomUserInfoProvider))]

[assembly: RegisterModule(typeof(CMSCustomGlobalEventsModule))]

namespace CMSApp.Configuration
{
    public class DependencyRegistrationModule : Module
    {
        public DependencyRegistrationModule 
            : base(nameof(DependencyRegistrationModule)) { }

        protected override OnPreInit()
        {
            // register any services we want to access through
            // Service.Resolve in custom modules or elsewhere
            Service.Use(() =>
            {
                return new CreditCardService(...);
            });
        }
    }
}

In this example, we intentionally registered CMSCustomGlobalEventsModule in the CMS but not in our ASP.NET Core application. Had we defined these assembly registration attributes in a shared class library, we wouldn't be able to do this 😏.

Managing Registration Complexity

We might look at this and think we traded one form of complexity for another. Sure, we now have full control over which services and modules are registered in each application, but we also have to remember to register them in all applications that need them 🤨. Before, all we needed to do was reference the class library and ... bam, it was done for us 🤷🏻‍♀️.

This is true, however we can recreate another pattern that ASP.NET Core libraries often use to make things easier for ourselves - gathering all dependencies up into a single place to be registered.

Since the assembly attributes are really just calls into Xperience's internals to 'register' things, we can reproduce this with a single Custom Module that makes these calls explicitly:

namespace Sandbox.Library
{
    public class LibraryRegistrationModule : Module
    {
        public LibraryRegistrationModule
            : base(nameof(LibraryRegistrationModule) { }

        protected override OnPreInit()
        {
            Service.Use<IUserInfoProvider, CustomUserInfoProvider>();
        }

        protected override OnInit()
        {
            new CustomGlobalEventsModule().OnInit();
        }
    }
}

Now, we can just include 1 assembly registration attribute to register everything in our library:

[assembly: RegisterModule(typeof(LibraryRegistrationModule))]

This is like an ASP.NET Core library's UseX() extension method on IServiceCollection. If we are ok with the defaults, we call that extension and the library handles everything for us, but we still get to explicitly opt-in.

Likewise, if we are ok with our class library's Xperience customization defaults, adding a single assembly registration attribute brings in everything 👏🏿.

They key here is that adding a reference to an assembly (either via a .NET project or NuGet reference) doesn't change the behavior of our system. We have to be clear that we want a customization and add a line of code 😎. This means we can just as easily opt-out without having to throw away the entire class library's code.

🏁 Conclusion

Kentico Xperience 13 has been able to support both the older ASP.NET Web Form CMS application and modern ASP.NET Core applications with shared libraries and APIs. This is an impressive feat of engineering.

Until we are in a fully ASP.NET Core world with Kentico Xperience (hopefully, just a few weeks away from the June 2022 publication of this blog post), we will need to juggle platform dependencies and customizations in a couple different ways.

If you are interested in the future of Kentico Xperience from a technical perspective, checkout this video below from the Kentico Xperience Connection: 2022 Conference.

The Xperience assembly attributes for dependency registration let us tap into the platform for full customization.

However, if we aren't careful, referencing a class library or NuGet package forces consumers to use our customizations because with these assembly attributes the dependencies are automatically 'on'. This makes our code less reusable and our applications less flexible.

Thinking about dependencies in a modern way and following the patterns of ASP.NET Core gives us some better approaches that make our applications more understandable and debuggable, and let's us opt-in to the Xperience customizations we want.

We should be explicit about which types and modules our applications use by registering them next our our applications other dependency injection management.

As always, thanks for reading 🙏!

References

Wikipedia: Service Locator Pattern
Wikipedia: Dependency Injection
ASP.NET Core Docs: Options Pattern
Mark Seemann Blog: Service Locator Anti-Pattern
Xperience Docs: Custom Info Provider Example
Xperience Docs: Custom Module Initialization
Xperience Docs: Global Events
Xperience Docs: Service Decoration
Xperience Docs: Custom Email Provider Example
Xperience Docs: Using Xperience APIs Externally
GitHub Xperience Community: App Settings JSON Registration Library
WiredViews: Web Design and Development Services
Kentico Xperience Design Patterns: Good Startup.cs Hygiene

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

Also check out the Kentico Xperience Developer Hub.

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Design Patterns: Protecting Hard Coded Identifiers

Sean G. Wright — Mon, 13 Jun 2022 15:32:23 +0000

When we need access to specific values or data in our applications, we might inject them through configuration (especially if they are different for each environment), or store them in a database with an identifier and access them by this identifier in our code.

The first approach is often thought of as being architecturally sound 😎 because the application doesn't need to re-built (or even re-deployed) if the data changes. We only need to update the configuration, and maybe restart the app.

The second is considered bad 😒, because an accidental or incorrect change to the database means an application needs rebuilt and redeployed.

But, what if hard coding an identifier wasn't so risky and the identifier wasn't environment specific 😮? That sounds great, but we'll need a way of guaranteeing these things!

📚 What Will We Learn?

When would we hard code identifiers in Xperience?
How do we ensure they are stable between environments?
How do we protect them from problematic modifications?

💎 Hard Coding Identifiers

Typically, when using a DXP, we will let content managers and marketers customize content for a site 😉, but sometimes it's more convenient to code content directly into an HTML template.

An example of this could be product pages on a site with thousands of products, each with a link to the Contact Us page (/contact-us) at the bottom of the layout. This scenario isn't appropriate for the Page Builder and there's not much benefit to adding a custom Page Type field to a page in the content tree for the "Contact Us" link.

What's the best way to add these links to our templates 🤷‍♀️?

Generating Page Links

Hard-coding links in templates is a scenario where we want to reference an identifier in code, because we don't want to maintain a hard-coded URL over time.

Yes, Xperience's former URLs feature helps to ensure that moving pages around in the Content Tree or changing a URL slug will never break a URL 😅. However, there's several benefits to not hard-coding URLs:

SEO: crawlers won't need to follow 301 redirects of moved pages
UX: visitors won't need to follow 301 redirects and will have faster page loads
Developers: it will be easier to maintain a site when links aren't hard-coded
- An innocent looking /special-product link could redirect to something completely unexpected 😑!
Content Management: Multi-lingual sites will have a different URL per culture, which means a hard-coded path won't work 😞.

Ok, we've decided we do want to sometimes hard-code links, but we don't want to hard-code URLs. So, instead, we'll use an identifier of the page we are linking to.

In Xperience we have a couple of options to pick from:

NodeID
DocumentID
DocumentGUID
NodeGUID

Which should we choose 🧐?

🏛 Keeping Identifiers Stable Between Environments

If we want our URLs to be correctly generated on a multi-lingual site, we'll want to use one of the Node values, since the Document ones reference a single specific culture for a page - it wouldn't be a very friendly site if we always generated URLs to the Spanish site for all the other cultures 😁.

Xperience's SQL Server database will auto-increment page integer IDs, which means creating a page in one environment could associate it with a NodeID that is being used by another page in a different environment.

If we have "Local", "Test", and "Production" environments, we don't want our code to fail to generate URLs 😬 (or generate incorrect URLs) because the identifier we reference isn't correct for that environment.

When using content staging Xperience guarantees pages synced from one environment to another will keep their same GUID values (NodeGUID and DocumentGUID) while their ID values can change.

So, given the option of NodeID and NodeGUID, we are going to select NodeGUID because it's stable between environments 🙌🏾!

🏗 Generating URLs

Now that we've decided on our stable page identifier, how are we going to generate URLs for those pages?

We could use Page Type Guid fields combined with the Page Selector Form Control, and then retrieve the URL in code:

Guid nodeGUID = productPage.Fields.CTALinkPageNodeGUID;

TreeNode? linkedPage = pageRetrieve
    .Retrieve<TreeNode>(
        query => query
            .WhereEquals(nameof(TreeNode.NodeGUID), nodeGUID),
        cache => cache.Key($"CTA|{nodeGUID}"))
    .FirstOrDefault();

if (linkedPage is null)
{
    return null;
}

PageUrl linkedPageUrl = pageUrlRetriever.Retrieve(linkedPage);

return ProductViewModel(productPage, linkedPageUrl);

This isn't too complicated, but the whole idea here was to generate the URLs without content management customization, so a Page Type field doesn't align with our goal 🙁.

Page Link Tag Helper

Instead, I'm recommending we use an ASP.NET Core Tag Helper that will enhance <a> elements in our Views:

<a href="" xp-page-link="..."></a>

This Tag Helper will use one of our identifiers to perform a very similar series of data retrieval steps to what we outlined above, and then populate the href and link text of our <a>.

But what do we pass to the xp-page-link attribute? A hardcoded Guid, while technically correct, is going to be very difficult to understand when reading the .cshtml file:

Which page does it represent 😵?
Did we accidentally typo it somewhere 😖?
What if we need to delete and then recreate the page we want to link to and have to replace the Guid everywhere ☠?

LinkablePage

Instead, let's create a class with friendly names to encapsulate our identifiers:

public class LinkablePage
{
    public static LinkablePage Home { get; } = 
        new LinkablePage(new Guid("..."));

    public static LinkablePage ContactUs { get; } = 
        new LinkablePage(new Guid("..."));

    public static LinkablePage PrivacyPolicy { get; } = 
        new LinkablePage(new Guid("..."));

    public Guid NodeGUID { get; }

    protected LinkablePage(Guid nodeGUID) => NodeGUID = nodeGUID;

    public static All LinkablePage[] { get; } = new[]
    {
        Home,
        ContactUs,
        PrivacyPolicy
    };
}

This LinkablePage class contains the full set of any pages we might want to generate URLs for, stores the NodeGUID values of each of those pages, and makes them immutable. The constructor is also protected, so no new objects can be created elsewhere in the application.

This last point is important because these values need to be known at development time, not runtime.

Here's how we'd use one with our Tag Helper:

<a href="" xp-page-link="LinkablePage.PrivacyPolicy"></a>

Because these identifiers are static properties, we could get fancy with our Razor and add a @using static at the top of the Razor file to access the LinkablePage instances directly:

@using static Sandbox.Data.LinkablePage

<a href="" xp-page-link="PrivacyPolicy"></a>

These are both readable, and easy to author 👏🏼.

Assuming the Tag Helper caches the URLs of links it generates for each of the different pages, it's performant as well 💪🏽!

The implementation for this tag helper can be found in the NuGet package for Xperience Page Link Tag Helpers. Try it out!

👮🏽‍♀️ Protecting Identifiers

Now that we've leveraged this convenient and maintainable approach for generating links to pages in the content tree, how do we guarantee that these don't suddenly stop working because pages get deleted?

Kentico Xperience has the perfect tool for us to leverage to guarantee the consistency of our data while the application is running - Global Events.

We can register an event handler for the DocumentEvents.Delete.Before event and then cancel the event if the Page being deleted matches a LinkablePage:

public class LinkablePageProtectionModule : Module
{
    public LinkablePageProtectionModule 
        : base(nameof(LinkablePageProtectionModule));

    protected override void OnInit()
    {
        base.OnInit();

        DocumentEvents.Delete.Before += Delete_Before;
    }

    private void Delete_Before(object sender, DocumentEventArgs e)
    {
        if (LinkablePage.All.Any(
            p => p.NodeGUID == e.Node.NodeGUID))
        {
            e.Cancel();

            var log = Service.Resolve<IEventLogService>();

            string message = $"Cannot delete Linkable Page [{e.Node.NodeAliasPath}], as it might be in use. Please first remove the Linkable Page in the application code and re-deploy the application.";

            log.LogError(
                nameof(LinkablePageEventHandler),
                "DELETE_PAGE",
                message);

            return;
        }
    }
}

This class's Delete_Before method will be called each time a page is deleted and it will check to make sure that page doesn't have a NodeGUID that matches one of the values we've hard coded in the application. If it does match, the deletion is canceled and we log a helpful message explaining why 😉.

The final step is to register our custom module in our application (preferably somewhere in our CMSApp project, like a DependencyRegistrations.cs file):

[assembly: RegisterModule(typeof(LinkablePageProtectionModule))]

This pattern for protecting hard coded identifiers can be used for anything in Xperience that supports content staging:

E-Commerce data (payment methods, shipping options)
Pages
Custom Module class records
Users/roles
Categories

All data our application code directly depends on through hard-coded identifiers is probably worth protecting with this approach 🤓.

🏁 Conclusion

Usually we want to leave content management up to marketers and content managers (that's the whole point of a DXP!) 👍🏿.

But sometimes it's far more convenient to manage some of the content ourselves - especially for links to pages that don't need to change frequently (or ever).

However, we still want to make sure that these links are correct and don't break between environments or while the site is running.

By storing a page's NodeGUID value in the application code, and using both content staging and a custom module to prevent accidental page deletions, we can achieve all of our goals 🤗.

We've created a readable, maintainable, scalable, performant, environment-consistent, and robust way of generating links to pages in our application 🥳.

As always, thanks for reading 🙏!

References

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Bits of Xperience: Reducing CLS when Rendering Images

Sean G. Wright — Tue, 31 May 2022 16:10:05 +0000

Kentico Xperience sites allow marketers and content managers to author content and build pages that display text, images, and anything else that HTML supports 😁.

There are multiple ways to add images to content in Xperience:

Embed in Rich Text
Custom Page Builder Component (Widget or Section)
Rendered with Razor in a Page view or Template

These images can come from multiple sources:

Media Library
Attachments
Meta files (for SKUs)
Form Submissions

No matter which rendering approach or content source combination we are using for images on our sites, we'll want to make sure we always render those images with the appropriate HTML attributes, and these days that includes the width and height attributes.

But why 🤔?

📚 What Will We Learn?

What is Cumulative Layout Shift (CLS)?
How width and height attributes prevent Layout Shift?
How do we get this information programmatically?
Why should we always retrieve image content from the database?

🌊 Cumulative Layout Shift (CLS)

Have you ever heard of Cumulative Layout Shift? It is defined (by Google) as follows:

CLS is a measure of the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifespan of a page.

A layout shift occurs any time a visible element changes its position from one rendered frame to the next. (See below for details on how individual layout shift scores are calculated.)

We've all experienced this on websites. Something on the page finally loads and a button moves, or the text we're reading shifts out of the viewport.

Not only is this extremely annoying 😖, but Google uses it as a quality indicator for websites. More CLS means a worse user experience and Google takes that into account for scoring in PageSpeed Insights, which means it impacts search ranking 😮.

So, now that it's clear we want to reduce CLS on our sites, how does this factor into displaying images with Kentico Xperience?

Reducing CLS with Images and `width` and `height` HTML Attributes

Images can be a major cause of CLS 🙁 because the browser doesn't know an image's dimensions until it's been fully downloaded. While the image is being downloaded, the browser's rendering engine doesn't know how much space to allocate for it on the page. Once it finishes downloading, the browser re-renders, moving other content around to give the image the space it needs 😒.

It should be clear now why we shouldn't be rendering images in Xperience with just a src attribute:

<img src="@Model.ImagePath">

This will all but guarantee CLS in most situations 😭.

However, browsers have been using width and height attributes to pre-allocate space for images for awhile now 🧐.

Check out this great article on the topic on Smashing: Setting Height And Width On Images Is Important Again and it's follow up How To Fix Cumulative Layout Shift (CLS) Issues

If we know the width and height values for an image and add those attributes/values when rendering it, we can help prevent CLS by letting the browser know how much space (vertically) the image will need based on the image's aspect ratio computed from these two values 👏🏾.

Getting an Image's Dimensions in Xperience

Thankfully, Xperience stores all uploaded image's dimensions in the database 🙏🏽. However, since there are multiple ways to store and display images in Xperience, we'll need multiple techniques for retrieving an image's dimensions.

Note: Xperience doesn't treat .svg files as images, which means we need to customize its behavior to capture SVG image dimensions when they are uploaded to a site.

We can use the Xperience SVG Media Dimensions library to do this for us automatically!

Image Dimensions and Media Files

The Media Library is probably the best place to store and manage images in Xperience so we'll use it as an example 👍🏿.

To select files from the Media Library for Page Type fields, you'll probably use the Media Selection Form Control:

This will display a path on the page's Content tab for this control and a preview of the image:

Retrieving an image from the media library by full path isn't a great developer experience, so fortunately @mattnield wrote a Regex several years ago that is able to retrieve the media file's FileGUID from the path 💪🏼.

With the FileGUID retrieved, we can query the image's content from the database:

HomePage? page = (await pageRetriever.RetrieveAsync<HomePage>(
   query => query.TopN(1), 
   cancellationToken: token))
   .FirstOrDefault();

if (page is null || 
    string.IsNullOrWhiteSpace(page.Fields.HeroImageMediaFilePath))
{
   return;
}

string pattern = @"[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}";

Guid mediaFileGUID = Regex.Match(
    page.Fields.HeroImageMediaFilePath, 
    pattern, 
    RegexOptions.IgnoreCase).Value;

MediaFileInfo? file = (await mediaFileInfoProvider.Get()
    .WhereEquals(
        nameof(MediaFileInfo.FileGUID), 
        mediaFileGUID)
    .GetEnumerableTypedResultAsync(cancellationToken: token))
    .FirstOrDefault();

if (file is null)
{
   return;
}

// use Media File values ...

Now that we have our full MediaFileInfo we can use all of its data to render our <img> element 🙌.

Assuming we have an ImageViewModel class defined like this:

public class ImageViewModel
{
    public ImageViewModel(
        MediaFileInfo file,
        IMediaFileUrlRetriever urlRetriever)
    {
        Path = urlRetriever.Retrieve(file).RelativePath;
        AltText = file.FileDescription;
        Title = file.FileTitle;
        Width = file.FileImageWidth;
        Height = file.FileImageHeight;
    }

    public string Path { get; }
    public string AltText { get; }
    public string Title { get; }
    public int Width { get; }
    public int Height { get; }
}

We can render our image in Razor as follows:

<img src="@Model.Path"
     alt="@Model.AltText"
     title="@Model.Title"
     width="@Model.Width"
     height="@Model.Height">

Awesome! Layout shift avoided and CLS reduced! 🎉🥳🎊

Always Retrieve the Full Image!

You might think, "This makes sense for images at the top of the page, but what about images at the bottom? They won't impact CLS, so this is a lot of extra work for little benefit."

First, if we display an image as part of a Widget, we don't know where on the page that Widget will be added and different devices' viewports might place that content in different locations on the page. We should code defensively and always retrieve these values from the database 😊.

Second, and far more importantly, we should always retrieve the full image content from the database for accessibility 😎!

All images in Xperience have Title and Description fields, which translate to the title and alt HTML attributes. If we want accessible sites (I'd argue that accessibility is one of the 7 things we can't skip when building a website), then we need to include these values on every informational image we render (background images that are for design don't have the same requirements).

This means we are going to have to retrieve the image content anyway 🤷🏽‍♀️, so it's really no extra work to get the width and height values.

🏁 Conclusion

Cumulative Layout Shift (CLS) is "a measure of the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifespan of a page". This measurement represents some of the user experience visitors will have when they visit a page and can negatively impact our page's search rank (SEO) 🙄.

The browser doesn't know how much space to allocate for images until they are fully downloaded, so images often impact CLS on sites. To help prevent Layout Shift for images we can add the image's width and height values as HTML attributes to the <img> element. This tells the browser how much space to allocate for the image based on its aspect ratio 🧠.

To add these values with a Kentico Xperience site, we'll need to retrieve the image's content from the database (as opposed to only the image's path).

To improve the accessibility of our sites, we want to include alt text on our images. This content, authored by content managers and marketers, is stored in the image content in the database 🤗.

So, while adding width and height values to an <img> might add some complexity to our code, we should be retrieving an image's content from the database anyway to ensure our sites are accessible 😉!

As always, thanks for reading 🙏!

References

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Design Patterns: Handling Failures - Return Errors, Don't Throw Them

Sean G. Wright — Mon, 14 Mar 2022 15:03:42 +0000

In a previous post we looked at how to centralize exception handling in a Kentico Xperience ASP.NET Core application by using out-of-the-box middleware. This enabled us to handle errors as a cross-cutting concern and DRY up our code 👍🏽.

However, the approach had some drawbacks. Namely, the method signatures of our code became dishonest - we had to assume that any method could throw an exception 😒.

Centralized exception handling, while not bad in itself, can encourage using exception handling as control flow, which can make code much harder to reason about when reading it. This handling also tends to occur in an area of our application where it's too "late" to gracefully respond to the failure, so the best we can do is log it an display a generic error page 😔.

Below we'll look at an alternative to throwing exceptions - returning errors from methods 😮.

Note: This is part 2 of a 3 part series on handling failures.

Part 1 and Part 3

📚 What Will We Learn?

What Do We Do With A Failure?
Prior Art: Go
Returning Errors
Better Method Signatures

What Do We Do With A Failure?

One important question to ask, before we proceed further, is "What do we do with a failure?"

In some applications the answer is simple - nothing! We will try to catch Exceptions in a central place in the application, log them to the Xperience Event Log, and let middleware render an error page (YOLO! 🤘🏾).

However, in more complex situations we might need to handle errors at the method call site so we could provide fallback operations or data to ensure as much of a Page's content is rendered as possible.

If we are using Exceptions to communicate failures, we're going to end up with try/catch logic scattered around each of these method call sites, which is why we adopted centralized error handling in the previous post 🤦🏻‍♀️.

The alternative to this try/catch spaghetti is to "return" the error to the caller, handling any exceptions or failures within the method being called 🤨.

Prior Art: Go

We can look to other languages for inspiration here, since some of them, like Go and Rust, treat exceptions as truly exceptional events and instead return errors from functions when there are logic violations and other failures 🤓.

Go treats string values as the standard error type that a function might return in case of a failure, so it's common to see a function defined as follows:

func Sqrt(f float64) (float64, error) {
    if f < 0 {
        return 0, fmt.Errorf("square root of negative number %g", f)
    }
    // implementation

    return val, nil
}

In Go, the function return type ((float64, error)) comes after the parameter list. In this case, it shows Sqrt will always return 2 values (which is sometimes called a couple or a tuple). The first item returned is "value" and the second is the "error".

Looking at the function body, we can see the values we return when the input is invalid (f < 0):

0 - the results of the square root operation
fmt.Errorf(...) which returns a string (as the type error)

The value is a "default" and the error is a helpful message 😉.

In the successful case at the end of the function we return val as the calculated value and nil representing no errors.

Any code that would call Sqrt would check if any errors had been returned before processing the result:

f, err := Sqrt(-1)

if err != nil {
    fmt.Println(err)
}

Even though Go treats string values as the standard error type, developers can create their own custom errors that contain more context. Callers of a function can then react to this contextual error information 🧐.

Every function that can result in a failure follows this pattern, which means a typical Go program has lots of if err != nil { ... } blocks in it. This might lead us to ask ourselves, "What's the benefit over exceptions if we still have to repeat guards/checks everywhere?" 😕

Well, the main benefit is that the function signatures tell the call exactly what to expect. There's no surprises here! 👏🏿

If your application can't ever produce errors, then don't worry, you won't need many error returning functions. If it can experience experience errors then they should be modeled and handled 👍🏼.

⚠ Don't confuse an application that doesn't handle errors with an application that doesn't have them. ⚠

Returning Errors

Let's look at an example scenario for a Kentico Xperience application.

In a HomeController that builds a view model for our Home Page, we need to retrieve content from the database, which we will do with a HomePageService class:

public class HomeController : Controller
{
    private readonly HomePageService service;
    private readonly IEventLogService log;

    // ...

    public async Task<ActionResult> Index(CancellationToken token)
    {
        ??? = service.GetData();

        return View(new HomeViewModel(???));
    }
}

Before we call the HomePageService, we need to figure out how to design the GetData method so that we don't have to worry about catching exceptions.

First, we'll define the method signature to return a C# Tuple, which is very similar to Go's multiple-value returns for functions that can have failures.

Tuples provide "concise syntax to group multiple data elements in a lightweight data structure".

public class HomePageService
{
    private readonly IPageRetriever pageRetriever;
    private readonly IPageUrlRetriever urlRetriever;
    private readonly IPageDataContextRetriever contextRetriever;

    // ...

    public async Task<(HomePageData? data, string? error)> GetData(CancellationToken token)
    {
        // ...
    }
}

Now for the implementation of our GetData method:

public async Task<(HomePageData? data, string? error)> GetData(CancellationToken token)
{
    if (!retriever.TryRetrieve<HomePage>(out var context))
    {
        return (null, "Could not get HomePage Page context");
    }

    var products = Enumerable.Empty<ProductPage>();

    try 
    {
        products = await pageRetriever<ProductPage>
            .RetrieveAsync(
                q => q.WhereTrue("ProductPageIsFeatured"),
                b => b.Key("HomePageFeaturedProducts"),
                cancellationToken: token);
    }
    catch (Exception ex)
    {
        return (null, $"Query for featured products failed: {ex}");
    }

    var featured = new List<FeaturedProduct>();

    foreach (var product in products)
    {
        var url = urlRetriever.Retrieve(product);

        if (url is null)
        {
            continue;
        }

        featured.Add(new FeaturedProduct(product, url));
    }

    return (new HomePageData(products, context.Page), null);       
}

The caller (HomeController.Index) can now decide what to do if there are any errors present in the returned Tuple:

public async Task<ActionResult> Index(CancellationToken token)
{
    var (data, error) = await service.GetData();

    if (error is not null or data is null)
    {
        log.LogError(
           "HomeController",
           "DATA_FAILURE",
           error);

        return ServerError(500);
    }

    return View(new HomeViewModel(data));
}

Better Method Signatures

If the C# Tuple seems a little awkward, we could instead try a C# 10 record struct:

We choose a record struct because it has all the low memory benefits of struct types and the auto-generated members of record types while also having a very simple definition 😍.

public readonly record struct Result<T>(T? Value, string? Error)
{
    public static Result<T> Value(T value) => 
        new Result<T>(value, null);
    public static Result<T> Error(string error) => 
        new Result<T>(null, error);
}

This type is pretty simple, but that's really all we want (for now) if we are trying to return errors but avoid Tuples.

We can update our HomePageService.GetData() method to the following:

public async Task<Result<HomePageData>> GetData(CancellationToken token)
{
    if (!retriever.TryRetrieve<HomePage>(out var context))
    {
        return Result<HomePageData>.Error(
            "Could not get HomePage Page context");
    }

    var products = Enumerable.Empty<ProductPage>();

    try 
    {
        products = await pageRetriever<ProductPage>
            .RetrieveAsync(
                q => q.WhereTrue("ProductPageIsFeatured"),
                b => b.Key("HomePageFeaturedProducts"),
                cancellationToken: token);
    }
    catch (Exception ex)
    {
        return Result.Error<HomePageData>(
            $"Query for featured products failed: {ex}");
    }

    var featured = new List<FeaturedProduct>();

    foreach (var product in products)
    {
        var url = urlRetriever.Retrieve(product);

        if (url is null)
        {
            continue;
        }

        featured.Add(new FeaturedProduct(product, url));
    }

    var data = new HomePageData(products, context.Page);
    return Result<HomePageData>.Value(data); 
}

We still have to make the same checks in our HomeController, but at least the method signature of our service has been cleaned up 🧹 and the creation of "values" and "errors" returns from our method is more explicit 💪.

record struct types include a Deconstruct method which adds the deconstruction syntax that Tuples have. This means our custom Result type can use the same syntax as the tuple in our HomeController.

Conclusion

We've reviewed the problems that come with handling errors in our application with only global exception handling. We end up with dishonest method signatures that we can't trust and cannot respond to errors where we need to 😑.

By following the pattern of returning errors, like the programming languages Go and Rust, we end up with a much more understandable and readable code base. We encourage modeling the potential error states of our application, giving ourselves the opportunity to handle them 😄.

While the C# tuple syntax has its uses, using it to model application errors might not be the best. So instead we can create a simple container type - Result - to make our method signatures more legible 😀. Unfortunately this still leaves us with a bunch of procedural if (error is not null ...) { ... } checks in our application 😣.

In my next post, we'll look at a way of returning failures so we can respond to them intelligently, while avoiding both complex method signatures and procedural conditional checks everywhere by using the Result monad 🤔.
...

As always, thanks for reading 🙏!

References

Photo by Jordan Madrid on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Xplorations: Using Tailwind CSS with Kentico Xperience

Sean G. Wright — Mon, 24 Jan 2022 15:15:11 +0000

In this post we'll be exploring what it looks like to use Tailwind CSS in our Kentico Xperience applications.

🧭 Starting Our Journey: Strategies for CSS

From Tailwind CSS's home page, it defines itself as:

A utility-first CSS framework packed with classes like flex, pt-4, text-center and rotate-90 that can be composed to build any design, directly in your markup.

But, before we dive into setting up and using Tailwind CSS with Kentico Xperience, let's explore why 🤔 we would use it instead of other approaches to CSS development.

🔬 The True Nature of CSS

CSS, as a language, is declarative and global. Developers that are new to CSS or more comfortable in JavaScript often dislike CSS' declarative and global nature.

However, if we look at things holistically, we can see that being global is what enables the power of the cascade, and declarative programming provides a powerful API that hides away the brain 🧠 melting 😱 complexity of browser rendering engines.

That said, CSS does need to be managed, especially in larger projects that are expected to evolve (and be maintainable) over time.

🔩 CSS Utility Classes

One of my favorite blog posts ever about CSS and HTML is Adam Wathan's post CSS Utility Classes and "Separation of Concerns" 🤩.

Adam Wathan is the creator of Tailwind CSS, and an experienced web developer, so it's probably worth checking out his perspective on CSS if only to broaden our own... 🧐

I recommend following the link above and reading the post in full. Using Tailwind CSS has, unfortunately, become a very polarizing topic, I think primarily because developers often express their opinions without expressing the context that leads to those opinions. Do yourself a favor 👍🏽 and gain a little context!

Adam reflects on the CSS/HTML "separation of concerns" in his post:

When you think about the relationship between HTML and CSS in terms of "separation of concerns", it's very black and white.

You either have separation of concerns (good!), or you don't (bad!).

This is not the right way to think about HTML and CSS.

Instead, think about dependency direction.

CSS that depends on HTML.
Naming your classes based on your content (like .author-bio) treats your HTML as a dependency of your CSS.

HTML that depends on CSS.
Naming your classes in a content-agnostic way after the repeating patterns in your UI (like .media-card) treats your CSS as a dependency of your HTML.

He then poses this comparison:

CSS Zen Garden takes the first approach, while UI frameworks like Bootstrap or Bulma take the second approach.

Neither is inherently "wrong"; it's just a decision made based on what's more important to you in a specific context.

And, asks a simple question ❔:

For the project you're working on, what would be more valuable: restyleable HTML, or reusable CSS?

The goal of having more reusable CSS at the cost of re-stylable HTML is where Tailwind CSS as a framework comes from.

If this aligns with the goals of our project, then Tailwind might be a good fit 😃, and we can continue reading to learn how to setup Tailwind CSS with a Kentico Xperience ASP.NET Core project...

🗺 Kentico Xperience + Tailwind CSS

Tailwind CSS can be used by loading its CSS from a CDN but as noted in the documentation:

The Play CDN is designed for development purposes only, and is not the best choice for production.

So, instead, we're going to focus on using Tailwind as a Node.js CLI tool.

We can follow the documentation in the previous link with a few minor annotations and additions.

Note: These steps assume you are comfortable using the command line, have Node.js installed, and have some familiarity with client-side tools and development.

First, we'll want to make sure we've changed directory to our Kentico Xperience ASP.NET Core projects at the command line because our Tailwind integration is only for the content presentation (ASP.NET Core) application:

> cd .\Sandbox.Web\
> Sandbox.Web
>

Then we install our Node.js Tailwind CSS dependency with npm:

> npm install -D tailwindcss

Once this installation completes we can initialize our Tailwind configuration:

> npx tailwindcss init

Tailwind's build process generates a CSS file with the minimal number of CSS classes and style rules possible by scanning the HTML templates of an application and only adding the utility classes used in those templates 🤓.

In our tailwind.config.js, we customize it for our ASP.NET Core specific use-case by telling Tailwind it should look for its CSS utility classes in all of our Razor files:

module.exports = {  
  content: ["./**/*.{cshtml}"],  
  theme: {
    extend: {},  
  },
  plugins: [],
};

We then create an entry-point site.css file at the root of our ASP.NET Core project where we specify the parts of Tailwind CSS we'd like to include in our project:

@tailwind base;
@tailwind components;
@tailwind utilities;

Note: You can also use this entry-point file to define custom CSS classes. However, I'd encourage you to attempt to read Tailwind's documentation on CSS reusability and try to meet your CSS requirements with the library's utility classes first.

Now, we update our package.json with some scripts to run the Tailwind command on our project:

{
  /* ... */

  "scripts": {
    "start": "tailwindcss -i ./site.css -o ./wwwroot/site.css --watch",
    "build": "tailwindcss -i ./site.css -o ./wwwroot/site.css --minify"
  }

  /* ... */
}

We tell Tailwind to output the generated CSS file into the ./wwwroot folder because it is the only directory that ASP.NET Core serves static files from by default.

It's also convenient that all files in ./wwwroot will automatically be published with the application without any additional build configuration.

There are 2 "scripts", start which we can run with npm start, at the command line, for local development, and build which we run with npm run build for production.

Last, we'll want to integrate this npm tooling into MSBuild so that when our ASP.NET Core application is built in Release mode, the production-ready CSS is also generated.

This can be very helpful if we are using CI/CD for build and deployment of our Kentico Xperience application.

We'll make the following addition to the bottom of our ASP.NET Core's .csproj file:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <!-- other settings -->

  <Target Name="NpmInstall" BeforeTargets="BuildCSS" Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <Exec Command="npm ci" />
  </Target>

  <Target Name="BuildCSS" BeforeTargets="BeforeBuild" Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <Exec Command="npm run build" />
  </Target>

</Project>

Whenever a Release build of our application is initiated, first npm ci will be run first, followed by npm run build to kick off our CSS production build command 👏🏾.

🌵 Ouch: Kentico Xperience + Tailwind CSS Pitfalls

🥊 Visual Studio vs VS Code

Tailwind CSS includes thousands of permutations of utility CSS classes, which creates a CSS API of sorts that developers have to learn to be effective with the library.

It's recommended to use an editor when authoring HTML that supports intellisense for Tailwind CSS class names in our HTML and PostCSS's special syntax when writing custom CSS rules.

Currently, VS Code (or Rider) is the best option 😎. Visual Studio has no extension support 😑.

However, Visual Studio is a best-in-class IDE for editing C# and Razor, so developers will have to choose whether they want to prioritize the authoring experience for back-end C# or their front-end Tailwind CSS 🤷‍♂️.

I think front-end tooling is an area where Visual Studio is currently very weak compared to other products, but if your projects don't have much in the way of front-end code and dependencies, this might not matter to you.

My personal preference is to use VS Code as much as I can for any front-end development. I write a lot of TypeScript, JavaScript, SCSS, and use lots of npm scripts and VS Code extensions. I even exclude front-end files from the .NET project so that I can't see them in Visual Studio 😉. This forces me to use VS Code (and all of its wonderful extensions and tooling) for this part of a project.

🛠 Dynamic CSS Class Generation

As mentioned earlier, Tailwind CSS scans our project HTML template source files for recognizable CSS classes and then includes those in the generated output CSS file.

However, Tailwind cannot recognize dynamically composed CSS classes, which means we need to consider how creative we get in our Razor files when building our HTML templates.

For example, the following won't work because Tailwind needs to statically recognize at development time what classes we are using - it can't determine what will be used at runtime 😔:

@{
   string classColor = string.Equals(color, "red")
      ? "red"
      : "blue";
}

<div class="@(classColor + "-500")">
  <!-- ... -->
</div>

We'd need to use the following to get the desired result:

@{
   string classColor = string.Equals(color, "red")
      ? "red-500"
      : "blue-500";
}

<div class="@classColor">
  <!-- ... -->
</div>

This can feel like a hoop we have to jump through to get Tailwind to work correctly, and in a way, it is. But this extra work means the final production-ready CSS file is extremely small and optimized 💪🏾.

As a final workaround, we can safelist specific classes we know are being used but Tailwind can't find when it scans our templates. This should be avoided if possible because it means we could be shipping unused CSS if we forget to keep the safelist up to date 😣.

👩🏽‍💻 Referencing CSS Classes in CSharp

Kentico Xperience's Page Builder components (Widgets, Sections, Page Template Properties) let us provide Content Managers with many customization points to build Pages that are flexible in both content and design 😎.

Unfortunately, if we aren't careful we could end up referencing Tailwind classes in places that aren't visible to Tailwind's tooling.

If we had some Page Template Properties that let a Content Manager customize the design of a page, we could back ourselves into a corner:

public class HomePageTemplateProperties : IPageTemplateProperties
{
    [EditingComponent(DropDownComponent.IDENTIFIER)]
    [EditingComponentProperty(
        nameof(DropDownProperties.DataSource), 
        "bg-green-300;Green\r\nbg-red-500;Red")]
    public string BackgroundColor { get; set; } = "";
}

These properties reference the Tailwind classes, but since this code is in a C# file and Tailwind is configured to scan .cshtml files, it won't ever detect that our site is using them and they won't be included in the generated CSS 😕.

However, even if we weren't using Tailwind CSS storing CSS classes in component Properties is a bad idea. The approach above ties your component to a very specific design, makes this component much less reusable, and makes future design updates more difficult.

Instead, we should store values that represent our design choices and leave the selection of the actual CSS class up to the Razor View. Even better, avoid the specific color values and use more semantic terms 😊:

public class HomePageTemplateProperties : IPageTemplateProperties
{
    [EditingComponent(DropDownComponent.IDENTIFIER)]
    [EditingComponentProperty(
        nameof(DropDownProperties.DataSource), 
        "primary;Primary\r\nsecondary;Secondary")]
    public string BackgroundColor { get; set; } = "";
}

Then, in our Razor View we can render the CSS class that matches the chosen option:

@{
    string backgroundColor = Model.BackgroundColor switch
    {
        "primary" => "bg-green-300",
        "secondary" => "bg-red-500",
        _ => ""
    };
}

<div class="@backgroundColor">
  <!-- ... -->
</div>

💻 CSS Classes in the Database

I imagine a lot of you have already been thinking "How do we handle CSS classes that are stored in the database?" It's easy enough to take the semantic approach we just looked at and use it for Page Type fields and CMS Settings...

But, what about Rich Text?

Yeah, Rich Text is problematic for many reasons, but it's a requirement that most sites can't avoid.

Even if we were not using a CSS framework like Tailwind, we'd run into issues maintaining our custom CSS while having to support Rich Text 😮.

It's a lot easier to do a search in an IDE for a character sequence to see if a CSS class is still being used (and how it's being used) than querying dozens of database tables and columns looking for the same information in Rich Text content.

This is probably one situation where using Tailwind's escape hatches is the best option and we can follow these tips to avoid any real headaches:

Use @apply to compose Tailwind's utility classes into custom CSS rules
Safelist and CSS classes we know will show up in Rich Text (even if they appear in our HTML templates).
Encourage Content Managers to use Rich Text to structure free-form content and only apply styling minimally (this should always be encouraged)
Customize the Rich Text editor in Xperience to create UI elements that help Content Managers use the correct CSS classes on their Rich Text if they are required

✈ Heading Home: Is Xperience + Tailwind CSS a Good Idea?

As we've seen, setting up Tailwind CSS in a Kentico Xperience ASP.NET Core project is fairly simple, so when considering whether or not we should use Tailwind for our project, it's more a question of maintenance and growth than getting started.

Tailwind CSS is a powerful tool designed for a specific scenario - web applications where reusable CSS is more important than re-styleable HTML 🧐.

If this doesn't match our project, then Tailwind might not be the best tool for helping us author and maintain CSS. If it is, then there are a lot of benefits it can bring to our development experience 🤠.

However, there are also quite a few pitfalls we saw when exploring how we might use Tailwind with Kentico Xperience's features 😬.

We saw there are solutions to these potential problems, and that these solutions aren't only useful with Tailwind CSS - they are good practices for managing design and content in any Kentico Xperience site. It just so happens that with Tailwind they become more apparent.

As always, thanks for reading 🙏!

Photo by Jordan Madrid on Unsplash

References

Tailwind CSS
CSS Cascade on MDN
Inside a super fast CSS engine: Quantum CSS
Adam Wathan on Twitter
CSS Utility Classes and "Separation of Concerns" 🌟
Using Tailwind via CDN on Tailwind Docs
Using Tailwind via CLI on Tailwind Docs
Windows Terminal on Microsoft Docs
Download Node.js
Reusing Styles with Tailwind CSS on Tailwind Docs
ASP.NET Core Fundamentals: Webroot on Microsoft Docs
Npm ci on npm Docs
Editor Setup on Tailwind Docs
VS Code Download
JetBrains Riders
Dynamic Class Names on Tailwind Docs
Safelisting Classes on Tailwind Docs
Assigning Editing Components to Properties on Kentico Xperience Docs
Content Driven Development: Or, Why the WYSIWYG Can Be a Trap (Video) from Kentico Xperience Connections 2020
Configuring the Rich Text Editor on Kentico Xperience Docs

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico Xperience Design Patterns: Handling Failures - Centralized Exception Handling

Sean G. Wright — Mon, 08 Nov 2021 14:54:04 +0000

Even perfectly crafted code can result in runtime failures for reasons that are out of our control 😫. Flaky network connections, data schemas that don't match the deployed code, or the accidental deletion of required data.

As software engineers, we are expected to design for the happy 😊 paths and the 'exceptional' unhappy ☹ ones.

Let's look at a common approach for handling these failures in ASP.NET Core applications, how it applies to Kentico Xperience sites, and where it falls short.

Note: This is part 1 of a 3 part series on handling failures.

Part 2 and Part 3

📚 What Will We Learn?

Representing failures as Exceptions
How to handle Exceptions
Exception handling as a cross-cutting concern
The problems with using Exceptions as control flow

Representing Failures as Exceptions

.NET developers are familiar with exceptions. They are part of the Base Class Library (BCL) and can be used to signal that applications have entered into an invalid state, by using the throw new Exception() syntax.

However, throwing exceptions is just half of the story. We can also catch exceptions by wrapping some code in the try/catch syntax:

try
{
   someBusinessOperation();
}
catch (Exception ex)
{
    // log and handle the exception
}

Of course, to be able to do the correct thing with a caught exception, we need to know 🧐 what type of exception it is.

We can use the built-in exceptions, like ArgumentNullException and InvalidOperationException, or even the basic Exception type to halt execution when something's gone wrong.

We can also create our own custom exception types, like the following BadRequestException:

public class BadRequestException : Exception
{
    public BadRequestException(string message) : base(message) { }
}

But why go through the effort of making a custom exception type?

Custom exceptions can more closely model our application's domain language and use-cases. The exception types in the BCL have to be use-case agnostic, by definition, because they are 'common' and usable in any .NET application 🤔.

If we were to use the base Exception type for all of our applications exceptions, it's going to be hard to determine what we should do when we catch the exception.

When we create domain specific exception types, we can use exception filters - a specific kind of C# pattern matching used with catch statements 🤓 - to make sure we execute specific code when different kinds of exceptions happen.

Imagine this scenario...

In a Kentico Xperience application, we have site-wide settings in a custom Page Type, which we'll call SiteContent. If this SiteContent Page is deleted from the Content Tree, how should our application respond 🤷🏽‍♂️?

When we try to query for the SiteContent Page, we could throw a custom MissingContent exception if it's not found.

Here's our example exception type:

public class MissingContentException : Exception
{
    public string PageType { get; }

    public MissingContentException(string pageType)
        base($"Could not find [{pageType}] Page") =>
        PageType = pageType;
}

And, here's our content querying logic:

var pages = await pageRetriever.RetrieveAsync<SiteContent>();

if (!pages.Any())
{
    throw new MissingContentException(SiteContent.CLASS_NAME);
}

// ...

The nice thing about throwing an exception is that it lets us abort our application execution immediately, preventing additional code errors or failures 💪🏾.

We also don't have to change the type signature of our methods that throw exceptions. This is convenient for blocks of code that could fail for any number of reasons. Our method return type represents the happy path, and the exceptions which the method throws represent all the failure scenarios 😏.

How to Handle Exceptions

If we throw an exception somewhere, we need to eventually catch that exception and respond accordingly:

try
{
    var siteContent = await GetSiteContentPage();
}
catch (MissingContentException ex) 
    when (ex.PageType == SiteContent.CLASS_NAME)
{
    // log and handle
}

With this approach we're representing our failed operation (querying for the SiteContent Page) with a custom exception type, and only catching and responding to the exceptions we are interested in - all other exceptions will need to be caught at some higher level in our code.

This all leads to the question - how do we want to handle exceptions we've caught? What information do we want to collect and what do we want to present to the site visitor that was unfortunate enough to trigger this failure 🤔?

In a Kentico Xperience site, the most common way of handling exceptions is going to be logging the failure to the Xperience Event Log and displaying an error page to the visitor 👍🏻.

We can usually achieve this with two middlewares - UseStatusCodePagesWithReExecute() and UseExceptionHandler().

Status Code Pages With Re-Execute

UseStatusCodePagesWithReExecute will handle results from Controllers that have 'error' HTTP status codes (eg 400, 500) and let you execute another route, passing the status code as a parameter:

public void Configure(IApplicationBuilder app)
{
    // earlier middleware

    app.UseStatusCodePagesWithReExecute(
        "/status-code-error", 
        "?code={0}");

    // later middleware
}

The site visitor won't see /status-code-error in their address bar 🤨, but the Controller action associated with that route can return some content explaining to the user what happened, based on the code query parameter. (/status-code-error can be any path as long as it's one your application can handle).

Read another explanation on these middlewares on StackOverflow.

This middleware will typically be used when we've caught an exception later in the request pipeline - like in an MVC filter or Controller action - and returned a result representing the error, like StatusCode() or NotFound():

public class HomeController : Controller
{
    public async Task<IActionResult> Index()
    {
        try 
        {
            var data = await myService.GetData();

            return View(new HomeViewModel(data));
        }
        catch (Exception ex)
        {
            eventLogService.LogException(...);

            return StatusCode(500);
        }
    }
}

Note: The UseStatusCodePagesWithReExecute middleware does not catch exceptions 😲. It helps to keep the presentation of 'error' status codes separate from the Controllers that return them.

While this lets us handle and log each exception exactly as we'd like for every Controller action, it's also a lot of repeated code when our Kentico Xperience site grows beyond a few Pages 😬.

Fortunately, there's a way handle exceptions as a cross-cutting concern... 😅

Exception Handling as a Cross-Cutting Concern

Exception Handler

The UseExceptionHandler middleware wraps the entire request pipeline in a try/catch, which means any unhandled exceptions will be caught and the developer can specify how they should be handled - like executing a request to another path in the application:

public void Configure(IApplicationBuilder app)
{
    // This is the first in / last out middleware
    app.UseExceptionHandler(new ExceptionHandlerOptions
    {
        AllowStatusCode404Response = true,
        ExceptionHandlingPath = "/error"
    });

    // later middleware
}

In this example, when an exception is caught the site will execute the /error path, which is typically a Controller action, and return its result.

We'll often use the UseExceptionHandler and UseStatusCodePagesWithReExecute middleware together. The former might return a 'Not Found' Page, keeping the HTTP status code as 404, and we wouldn't want that to be treated as an unhandled exception for the UseExceptionHandler middleware to process. AllowStatusCode404Response = true ensures the 404 response is allowed through 😮.

The Controller that handles our failure can grab the original Exception and request data out of the IExceptionHandlerPathFeature, which is where the middleware stores it before calling the Controller action:

public class ErrorController : Controller
{
    public IActionResult Index()
    {
        var exceptionFeature = HttpContext
            .Features
            .Get<IExceptionHandlerPathFeature>();

       Exception ex = exceptionFeature.Error;
       string originalPath = exceptionFeature.Path;

       eventLogService.LogException(
           "ErrorController", 
           "ASPNET_EXCEPTION",
           exception);

       var (message, statusCode) = ex switch
       {
           BadRequestException b => 
               ("The page had some problems", 400);
           NotAuthorizedException na =>
               ("You don't have permissions to view this", 403);
           _ => 
               ("We've hit a snag loading the page!", 500);
       };

       HttpContext.Response.StatusCode = statusCode;

       return View(new ErrorViewModel(originalPath, message));
    }
}

In this example, we are logging the exception in Xperience's Event Log, creating a friendly, contextual message and HTTP status code based on the type of exception that was caught, and returning a View to the user - all under the URL that caused the original problem - no redirects here 👏🏾!

We've effectively created a central cross-cutting Global Exception Handler that guarantees any exception thrown in our application will be caught, logged, handled, and presented to the visitor as a normal site Page - not an incomprehensible 'developer' error Page.

This seems great... 😁 doesn't it 😟!?

The Problems with Using Exceptions as Control Flow

The convenience of throwing (or allowing) exceptions anywhere in our application and then using a Global Exception Handler comes with a real cost and a potential cost.

It's To Late, Baby

The real cost is that by the time we're at the Exception Handler, it's too late to do anything to recover. We've consigned ourselves to a failed request and the best we can give to the site visitor is a friendly error and log the Exception.

The problem is not all exceptions are created equal 😕.

What if an exception was thrown trying to get the URL for an image in an image gallery on the Page? Do we want to throw away everything else that was correctly retrieved from the database and show an error page, just because of this single failure? Probably not.

Building a Kentico Xperience application is about choosing the best ways to manage and present content in the system, and keep visitors coming back to the site. We need to more nuanced 😎 with handling failures and treat our approach as a spectrum - some failures are ok, others are not, some require backup content, others can just result in content missing from the Page.

Unfortunately, we lose the ability to be more nuanced if we turn every failure into an exception and then rely on a single, late (in the request lifecycle) point to deal with them.

Exception handling is a cross-cutting concern (like authorization, logging, or caching), which aligns with the UseExceptionHandler middleware 👍. At the same time, cross-cutting concerns should be applied with multiple layers, not as a single blanket thrown over the application to hide the ugly parts 😏.

Abusing Control Flow

While some exceptions represent application states that should immediately halt the request, many are business logic situations we can gracefully (or at least intelligently) recover from.

There are many articles about using exceptions to control application flow ... most recommend against it.

If you choose not to consider this advice, problems will show up in your code base over time 😧.

A developer throws an exception when an array index is a negative number. Then, another developer later throws an exception when the credentials submitted by the login form are invalid. Eventually, half the methods in your app throw exceptions, either directly, or by some method they call, and all of those method signatures have become untrustworthy 😑.

What do you think this method does?

string[] GetUserRoles();

It probably returns all the roles a User is in when the current request is from an authenticated user. But what about when the user hasn't finished sign-up? Or if the request is for an unauthenticated User 🤔?

We'd hope it would return an empty array or maybe an array with a "Anonymous" Role... but there's nothing preventing it from throwing an exception! Even if it didn't, it could call other methods and they could throw exceptions!

Method return types should tell you what happens during normal use, and exceptional cases should really be exceptional. We want to trust 🤗 the code we write and the code written by others.

Using exceptions as control flow is a leaky abstraction because it forces us to know a lot more about a method than just its signature - potentially its internals, which breaks the idea of encapsulation. It also slowly reinforces our reliance on the Global Exception Handler pattern since any code in our application can throw without us knowing 🤦‍♀️!

Conclusion

In a Kentico Xperience site, we will inevitably run into situations that cause our code to fail to produce the desired result. These could be from exceptions thrown by libraries we are using, or our own code, or they could be from data not matching what we require 🤷🏽‍♂️.

In these cases we can use exceptions to quickly stop the current execution and bubble 🧼 that failure up to another part of our application that is responsible for catching them.

If we make custom exception types, we can match them to the specific scenarios our sites might encounter. And, we can react to each type of exception intelligently 🧐.

In order to not repeat our try/catch logic across the entire code base, we can centralize exception handling with the UseExceptionHandler ASP.NET Core middleware. This gives us a convenient place to convert uncaught exceptions into friendly error pages and log entries 👍🏿.

This convenience comes with some negatives. Our centralized exception handling will often not be located where we need it to if we want to compensate for some failures and let the request continue processing. It also encourages using exceptions as control flow, which results in method signatures only representing the 'happy path' and code that is harder to understand and trust 😖.

In my next post, we'll look at a way of including failures in our method signatures/return types, which keeps our code honest 😇 and allows us to better handle failures.

...

As always, thanks for reading 🙏!

References

Photo by Jordan Madrid on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like: