Working with pages in the API

The Xperience API allows you to retrieve and manage page content using custom code.

Use the following API to work with pages:

• TreeNode(CMS.DocumentEngine namespace) – object that represents pages. The TreeNode class encapsulates data from the CMS_Tree and CMS_Document tables, and the coupled data tables of individual page types.
• DocumentQuery and MultiDocumentQuery (CMS.DocumentEngine namespace) – classes that represent a query for loading pages. These classes do not employ any predefined parametrization, which means that you need to parametrize everything yourself. This makes them suitable for custom scenarios, where you require higher control over the query. Both are similar in functionality:
  • DocumentQuery allows you to retrieve pages of a single page type (when an instance is created with a page type class name as the constructor parameter) or general pages of any type (when using a parameterless constructor). If used for a single specific page type, the resulting query automatically includes coupled data of the given page type (e.g., news, articles). DocumentQuery is also used internally by the IPageRetriever service and any custom providers or repositories built around it.
  • MultiDocumentQuery allows you to retrieve pages of multiple page types in a single query at the cost of effectiveness. The coupled data of page types is not retrieved unless explicitly requested using the WithCoupledColumns parametrization method.
• IPageRetriever (Kentico.Content.Web.Mvc namespace) – interface that provides a service for retrieving pages in basic live site scenarios. IPageRetriever internally utilizes DocumentQuery or MultiDocumentQuery, and then further adjusts the query using the context of the current request, which has the following effects:
  • content is always retrieved from the current site.
  • content is always retrieved in the culture of the current context.
  • the current site's Combine with default culture setting is always reflected in the retrieved content.
  • the correct version of pages is retrieved depending on whether the content is displayed on the live site or in the administration interface.

Retrieving pages on the live site

For basic retrieval of pages in the code of your live site, use the IPageRetriever service. The service is available in the Kentico.Content.Web.Mvc namespace, which is provided by the NuGet packages installed in your live site application.

1. Obtain an instance of the IPageRetriever service (for example through dependency injection).
2. Call one of the service's Retrieve methods, and parameterize it using DocumentQuery methods to only include the pages you need.

The IPageRetriever methods return a collection of TreeNode objects representing the given pages (or a specific page type class inheriting from TreeNode).

private readonly IPageRetriever pageRetriever;

// Gets an instance of the IPageRetriever service using dependency injection
public ExampleController(IPageRetriever pageRetriever)
{
    this.pageRetriever = pageRetriever;
}

public ActionResult Index()
{
    // Retrieves pages of the 'Article' page type that are in the '/Articles/May' section of the content tree
    var articles = pageRetriever.Retrieve<Article>( documentQuery => documentQuery
                    .Path("/Articles/May", PathTypeEnum.Children));

    // Retrieves pages of a custom 'Landing page' page type from the '/Landing-pages/Products' section of the content tree
    var landingPages = pageRetriever.Retrieve("Custom.LandingPage"( documentQuery => documentQuery
                    .Path"/Landing-pages/Products", PathTypeEnum.Children));

    // Retrieves pages of multiple page types from the '/Archive' section of the content tree
    var pages = pageRetriever.RetrieveMultiple( multiDocumentQuery => multiDocumentQuery
                    .Path("/Archive", PathTypeEnum.Children));
}

Retrieving pages in custom scenarios

IPageRetriever automatically performs some parameterization of the query to simplify the code for the most common scenarios and requires live site context to function. However, if writing outside of your web application or if you require full control over the query, you can directly use the DocumentQuery or MultiDocumentQuery classes to ensure that there is not any unexpected parametrization done in the background.

// Retrieves all pages that match the query
var pages = new MultiDocumentQuery()
                    .OnCurrentSite()
                    .Path("/Articles/Reviews")
                    .Culture("en-us")
                    .CombineWithDefaultCulture()
                    .PublishedVersion()
                    .WithCoupledColumns();

// Retrieves pages of the specified page type that match the query
var pages = new DocumentQuery("Custom.Smartphone")
                    .OnCurrentSite()
                    .Path("/Products")
                    .Culture("en-us")
                    .CombineWithDefaultCulture()
                    .PublishedVersion();

Retrieving pages under workflow

When retrieving pages under workflow, you may want to retrieve the latest edited version in some cases and the published version in others.

• Use the PublishedVersion parametrization method to retrieve the published version of pages under workflow (when retrieving pages to be displayed to visitors).
• Use the LatestVersion method to retrieve the latest edited version of pages under workflow (when retrieving pages for further editing or previewing of unpublished changes).

Retrieving content in the preview mode and page builder

When retrieving page content using DocumentQuery or MultiDocumentQuery in the code of your website application for the preview mode or the page builder interface, you want to get the latest version of the content. However, you still need the published version to be displayed on the live site. To achieve this, you can parametrize queries to conditionally serve a different version of content based on where the content is displayed.

using CMS.DocumentEngine;

using Kentico.Content.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc;
using Kentico.Web.Mvc;

// Checks whether the current page is displayed in preview mode or the edit mode of the page builder
bool showLatest = HttpContext.Kentico().PageBuilder().EditMode || HttpContext.Kentico().Preview().Enabled;

// Retrieves the latest edited version of pages in preview mode or the page builder, but the published version in other cases
var pages = new DocumentQuery("Custom.Smartphone")
                    .OnCurrentSite()
                    .Culture("en-us")
                    .LatestVersion(showLatest);

Working with retrieved pages

You can iterate through the retrieved collection to access the properties of individual pages. The available columns depend on how you parametrized the query when retrieving the pages.

// Retrieves smartphone pages
var smartphones = new DocumentQuery("Custom.Smartphone")
                        .OnCurrentSite()
                        .Culture("en-us")
                        .Path("/Products/", PathTypeEnum.Children)
                        .LatestVersion();

// Writes the 'DocumentName' and 'SmartphoneOS' values of each of the retrieved smartphones into an HTTP output response stream
foreach (TreeNode smartphone in smartphones)
{      
    string smartphoneOS = smartphone.GetValue<string>("SmartphoneOS", "Default OS");
    Response.Write(HTMLHelper.HTMLEncode(smartphone.DocumentName) + " - " + HTMLHelper.HTMLEncode(smartphoneOS) + "<br />");
}

Updating pages

To update a page (TreeNode object):

1. Retrieve the latest edited version of a page (using the methods described above).
2. Modify the page's data:
   • For general page fields, directly set the corresponding TreeNode properties.
   • For the fields of specific page types, call the TreeNode.SetValue("FieldName", value) method.
3. Call the TreeNode.Update() method.

For examples and additional scenarios, see the API Examples documentation.

Creating new pages

To create a page:

1. Retrieve a parent page under which you want to create the new page (using the methods described above).
2. Create a new TreeNode object by calling the TreeNode.New("PageTypeCodeName") method.
3. Set the page's data:
   • For general page fields, set the corresponding TreeNode properties.
   • For the fields of specific page types, call the TreeNode.SetValue("FieldName", value) method.
4. Save the page by calling the Insert(parentTreeNode) method of the new TreeNode object.

For examples and additional scenarios, see the API Examples documentation.