Working with pages in the API

✖
Copy to clipboard

The Kentico API allows you to manage pages using custom code.

Use the following classes from the CMS.DocumentEngine namespace to work with pages in the API:

  • DocumentHelper – provides static methods for managing the latest edited versions of pages.
  • TreeProvider – provides management functionality for latest published tree nodes (pages).
  • TreeNode – represents pages. Encapsulates data from the CMS_Tree and CMS_Document tables, and the coupled data tables of individual page types.

This page consists of:

For information on how you can retrieve other data from the Kentico database, see Retrieving database data using ObjectQuery API.

Retrieving pages

To retrieve data from the Kentico database, DocumentQuery API is used. DocumentQuery is an abstraction layer over the SQL database. It provides independence on specific versions of SQL syntax and protection from SQL injections. DocumentQuery is based on the ObjectQuery API.

Retrieving latest edited versions of pages

To retrieve latest edited versions of pages from the database, use the DocumentQuery DocumentHelper.GetDocuments() method. You can use additional methods of the DocumentQuery API to parametrize the query to only retrieve the data you need.




// Retrieves pages of all page types under a specified path that have a 'Document Name' starting with 'Apple'.
MultiDocumentQuery pages = DocumentHelper.GetDocuments()
                                .Path("/Products/", PathTypeEnum.Children)
                                .WhereLike("DocumentName", "Apple%")
                                .ExcludePath("/Products/Sale", PathTypeEnum.Section)
                                .OnSite("CorporateSite")
                                .Culture("en-us")

There are two ways to only retrieve pages of specific page types:

  • Specify the page types using the Type and Types methods:

    


  // Retrieves the latest edited version of the 'CMS.Smartphone' and 'CMS.Laptop' pages under a specified path that have a 'Document Name' starting with 'Apple'.
  MultiDocumentQuery products = DocumentHelper.GetDocuments()
                                  .Types("CMS.Smartphone", "CMS.Laptop")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .WhereLike("DocumentName", "Apple%")
                                  .ExcludePath("/Products/Sale", PathTypeEnum.Section)
                                  .OnSite("CorporateSite")
                                  .Culture("en-us")

  • If you only want to retrieve pages of a single page type, use the string className parameter of the GetDocuments(string className) method:

    


  // Retrieves the latest edited version of the 'CMS.Smartphone' pages under a specified path that have a 'Document Name' starting with 'Apple'.
  DocumentQuery pages = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .WhereLike("DocumentName", "Apple%")
                                  .ExcludePath("/Products/Sale", PathTypeEnum.Section)
                                  .OnSite("CorporateSite")
                                  .Culture("en-us")

Retrieving latest published versions of pages

Use the DocumentQuery TreeProvider.SelectNodes()methodto retrieve the latest published versions of pages. You can use additional methods of the DocumentQuery API to parametrize the query to only retrieve the data you need.




// Creates a new tree provider instance
TreeProvider tree = new TreeProvider(MembershipContext.AuthenticatedUser);

// Retrieves the latest published version of all pages under a specified path that have a 'Document Name' starting with 'Apple'
MultiDocumentQuery products = tree.SelectNodes()
                        .Path("/Products/", PathTypeEnum.Children)
                        .WhereLike("DocumentName", "Apple%")
                        .ExcludePath("/Products/Sale", PathTypeEnum.Section)
                        .OnSite("CorporateSite")
                        .Culture("en-us");

There are two ways to only retrieve pages of specific page types:

  • Specify the page types using the Type and Types methods.

    


  // Creates a new tree provider instance
  TreeProvider tree = new TreeProvider(MembershipContext.AuthenticatedUser);

  // Retrieves the latest published version of pages of the 'CMS.Smartphone' and 'CMS.Laptop' types a specified path that have a 'Document Name' starting with 'Apple'
  MultiDocumentQuery products = tree.SelectNodes()
                          .Types("CMS.Smartphone", "CMS.Laptop")
                          .Path("/Products/", PathTypeEnum.Children)
                          .WhereLike("DocumentName", "Apple%")
                          .ExcludePath("/Products/Sale", PathTypeEnum.Section)
                          .OnSite("CorporateSite")
                          .Culture("en-us");

  • If you only want to retrieve pages of a single page type, use the string className parameter of the SelectNodes(string className) method:

    


  // Creates a new tree instance.
  TreeProvider tree = new TreeProvider(MembershipContext.AuthenticatedUser);

  // Retrieves the latest published version of the 'CMS.Smartphone' pages under a specified path that have a 'Document Name' starting with 'Apple'.
  DocumentQuery products = tree.SelectNodes("CMS.Smartphone")
                          .Path("/Products/", PathTypeEnum.Children)
                          .WhereLike("DocumentName", "Apple%")
                          .ExcludePath("/Products/Sale", PathTypeEnum.Section)
                          .OnSite("CorporateSite")
                          .Culture("en-us");

Working with retrieved pages

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




// Retrieves smartphone pages.
DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                .Path("/Products/", PathTypeEnum.Children)
                                .OnSite("CorporateSite");

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

Updating pages

To update a page (TreeNode object):

  1. Retrieve a page using 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.

Updating pages under workflow

When using the API to update pages under workflow or versioning, always retrieve the page objects with all fields. Otherwise, the update may cause data loss. Use one of the following approaches:

  • Call the DocumentHelper.GetDocuments(string className) method with a className parameter for a specific page type.
  • Use the Types query method to identify the page types and then apply the WithCoupledColumns method.

DocumentQuery reference

The following methods of the DocumentQuery API allow you to parameterize the search query. For example, you can limit which pages are retrieved or specify which page columns are loaded to improve querying performance.

  • Path – Specifies the path from which the pages are retrieved.

    


  // Retrieves pages from the '/Services' section including the parent page.
  DocumentQuery pages = DocumentHelper.GetDocuments("CMS.MenuItem")
                                   .Path("/Services", PathTypeEnum.Section);


  
    


  // Retrieves the child pages from the '/Services' section excluding the parent page.
  DocumentQuery pages = DocumentHelper.GetDocuments("CMS.MenuItem")
                                   .Path("/Services", PathTypeEnum.Children);

  • ExcludePath – Specifies the path from which the pages are excluded from the retrieval.

    


  // Exclude the /Products/Software section together with the parent page when retrieving products.
  DocumentQuery products = DocumentHelper.GetDocuments("CMS.Product")
                                   .ExcludePath("/Products/Software", PathTypeEnum.Section);


  
    


  // Exclude the child pages from the /Products/Software section when retrieving products.
  DocumentQuery products = DocumentHelper.GetDocuments("CMS.Product")
                                   .ExcludePath("/Products/Software", PathTypeEnum.Children);

  • OnSite – Specifies the site from which the pages are retrieved.

    


  // Retrieves all products from the Corporate site.
  DocumentQuery products = DocumentHelper.GetDocuments("CMS.Product")
                                   .OnSite("CorporateSite");

  • Published – Allows to only retrieve pages which have been published on the live site.

    


  // Retrieves all products published on the live site.
  DocumentQuery products = DocumentHelper.GetDocuments("CMS.Product")
                                   .OnSite("CorporateSite")
                                   .Published();


  
    


  // Retrieves all products on the live site including archived and not yet published products.
  DocumentQuery products = DocumentHelper.GetDocuments("CMS.Product")
                                  .OnSite("CorporateSite")
                                  .Published(false);

  • Where* – Allows filtering of the pages based on their properties.

    


  // Retrieves smartphones that have 'Document name' starting with 'Apple'.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Where("DocumentName", QueryOperator.Like, "Apple%");


  
    


  // Retrieves smartphones that have a 'Document name' starting with 'Apple' or 'BlackBerry'.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .OrderBy("SmartphoneDisplaySize")
                                  .Where("DocumentName", QueryOperator.Like, "Apple%")
                                  .Or()
                                  .Where("DocumentName", QueryOperator.Like, "BlackBerry%");


  
    


  // Retrieves smartphones that have 'Document name' starting with with 'Apple'.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .WhereLike("DocumentName", "Apple%");


  
    


  // Retrieves smartphones that don't have 'Document name' starting with with 'Apple'.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .WhereNotStartsWith("DocumentName", "Apple ");

    There are many Where* conditions available. Experiment to find the one that suits your needs.

  • Columns – Specifies the columns of the page which are retrieved.

    


  // Retrieves smartphones based on their display size.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Columns("SmartphoneOS");

    Performance best practice

    Using Columns method you can restrict the amount of data loaded from the database and speed up the querying process.

    Updating pages under workflow

    When working with pages under workflow or versioning, use the Columns method only when performing read-only operations. Do not use this method with pages you want to update. The update would likely cause a data loss.

  • OrderBy* – Allows ordering of the results by a property of the given page type.

    


  // Retrieves smartphones ordered by their display size.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .OrderBy("SmartphoneDisplaySize");


  
    


  // Retrieves smartphones based on their display size in descending order.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .OrderByDescending("SmartphoneDisplaySize");

  • TopN – Specifies the number of records, which are retrieved from the database.

    


  // Retrieves the top 5 smartphone records in ascending order based on their 'Document Name'.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .OrderByAscending("DocumentName")
                                  .TopN(5);

  • Page – Allows requesting a specific page of a certain size for a set of pages. 

    


  // Retrieves the second page of size 3 of smartphone pages.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .WhereLike("DocumentName", "Apple%")
                                  .Page(1, 3);

    To make use of data paging in web parts, connect the Universal pager web part to the viewer web part.

  • Culture – Specifies a culture of pages to be retrieved on multilingual websites. More than one culture may be selected in a single method.

    


  // Retrieves pages in two specific cultures.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .Culture("en-us", "sw-se");

  • CombineWithDefaultCulture – Retrieves a page from the original culture in a case, when the page has not been translated to the requested culture.

    


  // Retrieves a default culture version of a page whenever the specified culture version ('sw-se') isn't available.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .Culture("sw-se")
                                  .CombineWithDefaultCulture();

  • NestingLevel – Specifies the relative level to be queried within a certain section.

    


  // Retrieves smartphones that are nested one level under the '/Products/' section
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .NestingLevel(2);

  • InRelationWith – Retrieves pages based on their relationships with other pages.

    


  // Simulates a page GUID.
  Guid nodeGuid = Guid.NewGuid();

  // Retrieves smartphones that are in any relationship with a specific page.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .InRelationWith(nodeGuid);


  
    


  // Simulates a page GUID.
  Guid nodeGuid = Guid.NewGuid();

  // Retrieves smartphones that are in a specific relationship with a specific page.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .InRelationWith(nodeGuid, "IsRelatedTo");


  
    


  // Simulates a page GUID.
  Guid nodeGuid = Guid.NewGuid();

  // Retrieves smartphones that are on the left side of a specific relationship.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .InRelationWith(nodeGuid, "IsRelatedTo", RelationshipSideEnum.Left);

  • FilterDuplicates – Allows filtering of the duplicates if the result of the query contains linked pages.

    


  // Retrieves smartphones without duplicate (linked) pages.
  DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                  .OnSite("CorporateSite")
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .FilterDuplicates();

  • CheckPermissions – Allows retrieving of the pages based on the context of a specific user. By default, the current user’s context is used. CMSActionContext may be used to provide a different user’s context.

    


  // Retrieves smartphones visible to the public user.
  UserInfo user = UserInfoProvider.GetUserInfo("public");
  using (new CMSActionContext(user))
  {
      DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                      .Path("/Products/", PathTypeEnum.Children)
                                      .CheckPermissions();
  }

Methods for specifying page types

  • Types – Specifies multiple page types to be retrieved.

    


  // Retrieves pages of the 'CMS.Job' and 'CMS.Office' page type.
  MultiDocumentQuery pages = DocumentHelper.GetDocuments()
                                  .Types("CMS.Job", "CMS.Office")
                                  .Path("/Company/", PathTypeEnum.Children);

  • Type – Allows you to retrieve multiple page types at once and specify local query methods in addition to global query methods for the whole query.

    


  // Retrieves smartphone and laptop pages parametrized by local methods.
  MultiDocumentQuery products = DocumentHelper.GetDocuments()
                                  .Type("CMS.Smartphone", q => q.WhereLike("SmartphoneOS", "iOS%"))
                                  .Type("CMS.Laptop", q => q.WhereLike("LaptopOperatingSystem", "vista%"))
                                  .Path("/Products/", PathTypeEnum.Children);

    The Default method ensures that the query is parametrized only based on relevant system settings. For example, ‘Combine with default culture’.

    


  // Retrieves smartphone and laptop pages parametrized by system settings.
  MultiDocumentQuery products = DocumentHelper.GetDocuments()
                                  .Type("CMS.Smartphone", q => q.Default())
                                  .Type("CMS.Laptop", q => q.Default())
                                  .Path("/Products/", PathTypeEnum.Children)
                                  .WhereLike("DocumentName", "Apple%");