Kentico Xperience sample sites and their differences

At the time of writing, we provide the following main sources of code:

• The Dancing Goat sample site
• The Learning Kit code repository
• The API examples section in our documentation
• The Medio Clinic sample site used in our training courses

The Dancing Goat sample site

The Dancing Goat sample site (DG, for short) was born in 2014. It is a company site of a fictional coffee-selling company. You can install the DG sample project and site when installing Xperience.

Goals

We created the DG site mainly to showcase the advanced features of the Kentico Enterprise Marketing Solution edition (EMS) that was introduced in these days. The site therefore contains many of the online marketing (OM) and e-commerce (EC) features that the EMS edition brought.

The site is nowadays aimed primarily at presales presentations, to demonstrate the business features of Xperience. We want the DG site to give a full picture of what's in Xperience for content editors, marketers, and shop administrators, while also offering a sneak peek for developers into possible implementation approaches. However, the primary persona here is the business user, not the developer.

What's not a goal

The DG site by virtue cannot serve as an introduction to the world of Xperience programming. The best learning path for novice developers is to take basic ASP.NET courses and then to continue with our Xperience training courses, while sometimes referencing our Xperience documentation for details.

The DG site also does not pursue the goal of teaching best practices, neither coding best practices nor project management best practices. The former can be found in the training courses, the latter in the Kentico Advantage.

However complex the DG site may seem, it does not strive to explain all Xperience APIs. The site focuses on the OM and EC features, but leaves lots to be discovered in the documentation and its API Examples section.

Implementation

Let's quickly list the significant implementation details that set the DG site apart from our other sources of code.

As mentioned before, the site makes heavy use of OM features. Namely, it has an A/B test configured, it tracks contacts, sorts them into a contact group, it sends email newsletters and email campaigns, mainly through marketing automation processes. As for EC features, the site has several groups of products from various manufacturers. It expands those products into variants using the product options feature. It also has both catalog discounts and order discounts configured, together with the free shipping order feature.

As far as code is concerned, the DG site gets directly to the point, without much ceremony. For instance, in the GrindersController class, there's a hard dependence on the ProductRepository class, without any interface that would allow the use of dependency injection. The controller also directly uses the IPageUrlRetriever service that might otherwise be encapsulated into the said repository.

The Learning Kit repository

The repository was created as an internal project in the early days of Xperience, to support the official documentation with code examples. The repository was later made public on GitHub. In 2020, we also released a sibling repository with the .NET Core version of the code.

Goals

The repositories act as a source of code examples shown throughout the Xperience documentation. The repositories contain full-fledged Visual Studio solutions that can be run when connected to an Xperience database. The code follows a main goal of giving the simplest possible introduction into the APIs and programming concepts of Xperience. The code has the broadest scope of all our sources. It covers most of the public APIs explained in the documentation. As for the level of detail, the kits go far beyond the DG site by adding in-line code comments.

What's not a goal

As with the DG site, the Learning Kit repositories don't primarily focus on providing best practices, in terms of both coding and project management. Also, the code examples abstract from real life scenarios as they focus solely on explaining the given APIs or programming concepts.

Implementation

Let's take the MediaLibraryController class as an example. The class directly uses all of the Xperience services used when working with media libraries:

• IMediaFileUrlRetriever
• IMediaLibraryInfoProvider
• IMediaFileInfoProvider
• ISiteService

In the ASP.NET MVC world, the habit is to offload all detailed work from the controller into standalone classes. However, in this case we wish our customers to quickly understand the merits of our APIs, without distracting them with additional ceremony.

The API Examples section

The section was created to contain purely code examples and it's part of our documentation.

Goals

As the documentation grew over the years, we understood the need to demonstrate examples of API usage. On the other hand, we realized that too much code examples would hurt readability of the docs. That's why the section was created. The section provides guidance on CRUD operations and other kinds of management of Xperience data, thereby giving an alternative to the manual way of working with them in the administration application. The code has lots in common with the rest of the documentation. It focuses on simplicity and clarity, without much fuss around that.

What's not a goal

Although being a part of the documentation, the philosophy of the section is not exactly the same. Unlike the documentation pages, the section does not try to explain programming concepts. It just showcases the API calls. The section also does not make any difference beween new and older APIs. As you might expect, the section also does not strive to offer any best practices or real-life scenarios.

The Medio Clinic sample site

The Medio Clinic site (MC, for short) saw the light of day in 2014, after the release of Kentico 8. In the beginning, it served for in-person online developer classes. Later, when we switched to the self-paced e-learning model, the MC site was adapted to this training format. In 2018, we rewrote the site from scratch, from the Portal Engine development model over to ASP.NET MVC 5. With the introduction of Xperience 13, we again rewrote the site. This time around, into ASP.NET Core MVC.

Goals

From day one, the MC site was targeted at training. Unlike the other sample sites and sources of code, the MC site is optimized to give trainees A-to-Z guidance "from zero to hero". The trainees only need to know the common ASP.NET MVC concepts to start.

The MC site does not stick strictly to the main feature sets of Xperience. In MC, we focus on "getting user stories done", regardless of whether they're achieved through a certain Xperience feature, framework feature, or a 3rd party library.

We only select mainstream scenarios, which then dictate the scopes of course modules. At the time of writing, we have the Xperience for developers course consisting of three modules:

• Essentials
• Builders
• Identity

(The latter two will be available for Xperience 13 during spring 2021.)

Apart from that, we have the Xperience customization for developers course that focuses on the customizations of the administration application.

Another difference of the MC site is its real-life nature. Simply put, we wish to get as close to a production environment in our courses as possible. We only sacrifice things that are non essential and would have a low educational impact.

This comes hand in hand with another feature of the MC site: coding best practices. Although the MC site is smaller in terms of the number of pages of the live site, we compensated for that by boosting the architecture of the solution to be as flexible and scalable as the format of the course allows.

Last but not least, not only the source code itself makes the difference. In the course itself, we wanted to explain the implementation in multiple levels of detail. From top-most high-level architecture decisions, over to explaining purposes of various layers, classes, class members, to explaining what particular lines of code do.

What's not a goal

First, the MC site does not try to explain the project management best practices. This is the job of Kentico Advantage. We only explain some content modeling concepts, that's it.

The MC site was also not designed with presales demos in mind. The site is to be examined by developers and technical people.

We also don't want to cover all our APIs. The documentation and its API Examples section have much broader scope. We just cherry-pick the APIs needed to achieve the best result for our user stories.

As you might expect, the MC site does not want to pursue other goals like simplicity and clarity, usually held in the documentation.

Implementation

First off, we have a scalable solution structure consisting of multiple projects, each covering a standalone set of functionality. We also use MVC areas to keep the MVC project organized.

We use 3rd party technologies everytime it makes sense to speed up the development. We therefore use AutoFac for its excellent assembly scanning feature, we style the website using Materialize CSS, and custom-tailor the styling with SASS.

Unlike in the DG site, we want to stick with ASP.NET conventions as much as possible. We therefore write to the Xperience event log through the stock ILogger<> implementation and we implement the localization of System.ComponentModel.DataAnnotation attributes using the stock IStringLocalizer interface.

Unlike what's described in our documentation, where the culture of a given request is set through a built-in Xperience route constraint, we do that through a dedicated ASP.NET middleware.

Unlike the DG site and other sources, we implemented a localized status code (error) page that retrieves the error messages from localized Xperience pages in a dedicated section in the content tree.

In the Identity module we also use a different implementation than in the Core version of the DG site. We have a dedicated area, customized user schema, customized application-level ASP.NET Identity classes furnished with their own interfaces, strongly typed role recognition, a custom user model binder, etc.

Conclusion

As you may have noticed, there is actually a large number of differences between our sample sites and other sources of code. Hopefully we managed to explain them so that you now know which of them you should turn to when you're a novice developer, solution architect, business analyst, or a marketer.