Kentico Xperience 13 documentation and ASP.NET Core

Most documentation about running Xperience applications under ASP.NET Core can be found in a dedicated section: Developing Xperience applications using ASP.NET Core. The rest of the documentation still applies, but some code samples and scenarios might need slight modifications for Core projects.

All major differences between the MVC 5 and Core platforms are summarized in Migrating to ASP.NET Core.

×

Displaying page content

Page content is stored in the database and edited through the administration interface using the content tree in the Pages application. To display the content on your site, you need to retrieve the data in the code of your MVC application.

The implementation and complexity of the code depends on your preferences and project requirements, ranging from simple method calls within controller actions to custom solutions utilizing repository and service patterns. You can then use the retrieved page content to populate prepared view models and display them in your views.

Retrieving page data

To retrieve content from pages, use the generated strongly typed classes provided by the system for each page type. Generated provider classes facilitate the retrieval of pages of the corresponding page type. The following example demonstrates the use of a provider class generated for a sample Article page type:

// Gets the specified articles using the generated provider
IEnumerable<Article> articles = ArticleProvider.GetArticles()
    .OnSite("MySite")
	.Culture("en-US")
	.Path("/Articles/", PathTypeEnum.Children);

// Gets the published version of a single article using the generated provider
Article article = ArticleProvider.GetArticle(nodeGuid, "en-US", "MySite");

By default, the generated code returns published versions of pages. If you need to retrieve the latest edited version of a page under workflow, use the following approach:

// Gets the latest version of a single article using the generated provider
Article article = ArticleProvider.GetArticle(nodeGuid, "en-US", "MySite")
	.LatestVersion()
	.Published(false);

To filter the retrieved pages, use the methods listed in Reference - DocumentQuery methods.

Tip: Optimize the performance of your website by caching the retrieved page data.

Selecting content based on page taxonomy

Pages on Xperience websites can be categorized and organized in several different ways. The code that you use to retrieve content from specific "categories" depends on the taxonomy approach used by the given pages:

  • Content tree structure – for pages categorized using the parent-child structure of the content tree, select the content using DocumentQuery methods such as Path and NestingLevel. You can filter out linked pages from the data by adding the FilterDuplicates method.

    // Gets the English version of articles contained directly under the '/Articles/Featured' section of the content tree
    IEnumerable<Article> articles = ArticleProvider.GetArticles()
                    .Path("/Articles/Featured/", PathTypeEnum.Children)
                    .NestingLevel(1)
                    .OnSite("MySite")
                    .Culture("en-US");
  • Categories – for pages organized by assigning categories, select the content using the InCategories DocumentQuery method:

    // Gets the English version of article pages assigned to the 'Featured' category
    IEnumerable<Article> articles = ArticleProvider.GetArticles()        
                    .InCategories("Featured")
                    .OnSite("MySite")
                    .Culture("en-US")
  • Tags – for pages marked by tags, select the content using the WithTag DocumentQuery method:

    // Gets the English version of articles marked with the 'Coffee' tag from the 'Beverages' tag group
    IEnumerable<Article> articles = ArticleProvider.GetArticles()
                    .WithTag("Coffee", "Beverages")
                    .OnSite("MySite")
                    .Culture("en-US");

Working with retrieved page data

You can access various types of data from retrieved page objects:

  • Page fields – the data that is editable on a page's Content tab.
  • General page data – properties available for all pages (via the TreeNode class). For example identifiers, values indicating the position in the content tree, etc.
  • Page URL – the URL under which the page is available on the live site. See Getting page URLs.
  • Metadata – SEO-related data like the page title and page description. See Working with page metadata.
  • Page attachments – stored in fields with the File or Attachments data type. For information about retrieving page attachments, see Displaying page attachments.
Example
// Retrieves a specific page
News news = NewsProvider.GetNews(nodeGuid, "en-US", "MySite");

// Accesses the ID of the page's parent node in the content tree
int parentNodeId = news.NodeParentID;

// Accesses the 'DocumentName' data field
string pageName = news.DocumentName;

Accessing page field data

The fields available on a page's Content tab are specific to its Page type. You can see the fields that each page type uses:

  • In Page types (application) -> edit page type -> Fields tab
  • In the corresponding <namespace>_<page_type_code_name> database table

We recommend accessing specific fields of a page type via the Fields property:

// Retrieves a specific page
News news = NewsProvider.GetNews(nodeGuid, "en-US", "MySite");

// Accesses the 'Title' field
string title = news.Fields.Title;

// Accesses the 'Text' field
string text = news.Fields.Text;

Resolving HTML tags and relative URLs

Fields which are populated by the Rich text editor form control may contain HTML tags and relative links. To ensure that the content is displayed correctly, use one of the following methods in your views:

  • The standard Html.Raw method, which disables HTML encoding for the values.
  • The Html.Kentico().ResolveUrls extension method, which disables HTML encoding for the values and additionally resolves relative URLs to their absolute format. By default, relative URLs are automatically resolved by a filter that processes the output of all pages. You can use the ResolveUrls method to minimize the output filtering requirements or if you wish to disable the filter completely (via the CMSMVCResolveRelativeUrls web.config key).
@Html.Raw(Model.<Rich text field content>)
@Html.Kentico().ResolveUrls(Model.<Rich text field content>)

Automatic URL resolving

The system provides page output filtering functionality that automatically resolves all virtual relative URLs to their absolute form. The URLs are processed on the side of the MVC application, based on the environment where the site is actually running.

This filter ensures that links added by content editors into page content work correctly, even if you do not explicitly handle URL resolving in your code.

Getting page URLs

Pages in the content tree of Xperience websites can have their live site URLs generated by the system, either through content tree-based routing or according to URL patterns set for page types. This allows content editors to create new pages or adjust the URLs of existing ones in the administration interface, without the need to update and redeploy the code of the MVC application.

You may need to get the URLs of retrieved pages in various scenarios, such as rendering navigation menus or other page links, performing redirects, etc.

To get the URL of a page in general code:

  1. Obtain an instance of the IPageUrlRetriever service (for example through dependency injection in your controller constructor).
  2. Call the service's Retrieve method, and use one of the following parameter types to specify the page:
    • TreeNode object representing the page (or a specific page type class inheriting from TreeNode).
    • string containing a node alias path value, representing the page's location in the Xperience content tree

The IPageUrlRetriever.Retrieve method returns a PageUrl object, with properties containing the given page's URL:

  • RelativePath – the virtual path of the specified page, which you can resolve to an application absolute path at runtime (for example using the UrlHelper.Content method).
  • AbsoluteURL – the page's absolute URL, including the scheme and domain name.

The URL is automatically adjusted for the current culture, i.e. any language prefixes in the URL path or the domain in the absolute URL (see Configuring URLs for multilingual websites to learn more).

Example
using System.Web.Mvc;

using CMS.DocumentEngine;

using Kentico.Content.Web.Mvc;

public class PageController : Controller
{
	private readonly IPageUrlRetriever pageUrlRetriever;

	// Controller constructor that receives an IPageUrlRetriever instance using dependency injection
	public PageController(IPageUrlRetriever pageUrlRetriever)
    {
    	this.pageUrlRetriever = pageUrlRetriever;
    }

	...
	
	// Gets the relative URL of a specified page (TreeNode object or inheriting page type class)
	string relativePageUrl = pageUrlRetriever.Retrieve(page).RelativePath;

	...
}

Page URL extension methods

In addition to the IPageUrlRetriever API, the system provides UrlHelper extension methods for getting page URLs.

  • Kentico().PageUrl(string nodeAliasPath) – returns the URL of a page identified by a node alias path value (representing the page's location in the Xperience content tree). You can provide the following optional parameters:

    • string cultureCode – the culture code of the desired language variant.

    • string siteName – the code name of the site from which to retrieve the page.

  • Example
    @using System.Web.Mvc
     
    @using Kentico.Content.Web.Mvc
    @using Kentico.Web.Mvc
    
    ...
    
    @* Renders a link to the page under the '/Home' alias path in the site's content tree *@
    @Html.HtmlLink(Url.Kentico().PageUrl("/Home"), "Home page"))


  • Kentico().CurrentPageUrl() – returns the URL of the currently displayed page. Requires the context of the current page to be available and initialized (automatic for pages on sites using content-tree based routing, requires manual initialization of the page data context for pages handled by custom routes based on page type URL patterns).

The methods return the page's application absolute URL path, as a PageUrlString object. The object automatically converts to a string within views. You can call the PageUrlString object's ToAbsolute() method to get the page's absolute URL, including the schema and domain name.

Tip

For methods that accept node alias path parameters, you can use a helper class to store the paths to frequently targeted pages as constants. For example:

public static class ContentItemIdentifiers
{
	public const string HOME = "/Home";
	public const string ARTICLES = "/Articles";
}

Canonical URLs

The API also provides the Kentico().PageCanonicalUrl() extension method, which returns page URLs suitable for Canonical link elements. Rendering canonical links is recommended to improve SEO on websites where pages are available under multiple URLs, typically when using alternative URLs or linked pages.

For detailed information, see Providing canonical URLs for pages.

Working with page metadata

The standard way of configuring SEO-related parameters for a website's pages is to add <meta> elements into the <head> section of the page HTML code. To utilize the metadata entered for pages in the administration interface, such as the page title and description, you can use the following HtmlHelper extension methods provided by the Xperience API:

  • Kentico().PageDescription
  • Kentico().PageKeywords
  • Kentico().PageTitle

The methods render the corresponding HTML <meta> elements for the currently displayed page. Before rendering the elements, all methods transform the metadata based on the settings for metadata format and prefixes (i.e. add a prefix or resolve macros in the title format).

To work, the methods must have the context of the current page available:

For the PageTitle method, you can optionally set the alternateTitle parameter, which is then used for pages where the title and context of the current page is not available (e.g. completely custom pages that are not represented in the Xperience content tree). For example, you can get the alternateTitle value from a ViewBag property used inside the view layout.

The following example of view code uses the extension methods to render metadata tags for the current page (such code can be added to the site's main layout):

@using Kentico.Content.Web.Mvc
@using Kentico.Web.Mvc

...

<html>
<head id="head">
    ...
    @Html.Kentico().PageDescription()
    @Html.Kentico().PageKeywords()
    @Html.Kentico().PageTitle(ViewBag.Title as string)
    ...
</head>

General API for retrieving page metadata

You can also access the metadata for specific pages through the properties of IPageMetadata instances. To get the IPageMetadata instance for a page, use one of the following approaches (depending on your scenario and context):

  • Call the Retrieve method of the IPageMetadataRetriever service, with the page's TreeNode object as the parameter.
  • Access the Metadata property of an IPageDataContext instance. The data context for the current page can be retrieved using the IPageDataContextRetriever service (requires manual initialization of the page data context for pages handled by custom routes based on page type URL patterns).
  • Access the Metadata property of an IPageViewModel instance – available as the model in the views of pages handled by basic content tree-based routing.

Was this page helpful?