--- title: Working with pages in the API related: - https://docs.kentico.com/k10/managing-website-content/working-with-pages.md - https://docs.kentico.com/k10/developing-websites/defining-website-content-structure/page-types.md - https://docs.kentico.com/k10/developing-websites/developing-sites-using-asp-net-mvc/developing-mvc-applications/generating-classes-for-kentico-objects.md - https://docs.kentico.com/k10/custom-development/retrieving-database-data-using-objectquery-api.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). 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](https://docs.kentico.com/k10/custom-development/retrieving-database-data-using-objectquery-api.md). ## 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](https://docs.kentico.com/k10/custom-development/retrieving-database-data-using-objectquery-api.md). ### 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](#documentquery-reference) of the DocumentQuery API to parametrize the query to only retrieve the data you need. ```csharp // 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](#workingwithpagesintheapi-multipagetypes): ```csharp // 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 G_etDocuments(string className)_ method: ```csharp // 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](#documentquery-reference) of the DocumentQuery API to parametrize the query to only retrieve the data you need. ```csharp // 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](#workingwithpagesintheapi-multipagetypes). ```csharp // 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: ```csharp // 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. ```csharp // 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) + "
"); } ``` ## 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. > **Note:** **Updating pages under workflow** > > When using the API to update pages under [workflow](https://docs.kentico.com/k10/managing-website-content/configuring-the-environment-for-content-editors/configuring-workflows.md) or [versioning](https://docs.kentico.com/k10/managing-website-content/configuring-the-environment-for-content-editors/configuring-and-using-page-versioning.md), 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. ```csharp // Retrieves pages from the '/Services' section including the parent page. DocumentQuery pages = DocumentHelper.GetDocuments("CMS.MenuItem") .Path("/Services", PathTypeEnum.Section); ``` ```csharp // 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. ```csharp // Exclude the /Products/Software section together with the parent page when retrieving products. DocumentQuery products = DocumentHelper.GetDocuments("CMS.Product") .ExcludePath("/Products/Software", PathTypeEnum.Section); ``` ```csharp // 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. ```csharp // 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. ```csharp // Retrieves all products published on the live site. DocumentQuery products = DocumentHelper.GetDocuments("CMS.Product") .OnSite("CorporateSite") .Published(); ``` ```csharp // 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. ```csharp // Retrieves smartphones that have 'Document name' starting with 'Apple'. DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone") .OnSite("CorporateSite") .Where("DocumentName", QueryOperator.Like, "Apple%"); ``` ```csharp // 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%"); ``` ```csharp // Retrieves smartphones that have 'Document name' starting with with 'Apple'. DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone") .OnSite("CorporateSite") .WhereLike("DocumentName", "Apple%"); ``` ```csharp // Retrieves smartphones that don't have 'Document name' starting with with 'Apple'. DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone") .OnSite("CorporateSite") .WhereNotStartsWith("DocumentName", "Apple "); ``` > **Info:** There are many _Where\*_ conditions [available](https://devnet.kentico.com/docs/10_0/api/html/Methods_T_CMS_DataEngine_WhereCondition.htm). Experiment to find the one that suits your needs. - **Columns** – Specifies the columns of the page which are retrieved. ```csharp // Retrieves smartphones based on their display size. DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone") .OnSite("CorporateSite") .Columns("SmartphoneOS"); ``` > **Tip:** **Performance best practice** > > Using _Columns_ method you can restrict the amount of data loaded from the database and speed up the querying process. > **Note:** **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. ```csharp // Retrieves smartphones ordered by their display size. DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone") .OnSite("CorporateSite") .OrderBy("SmartphoneDisplaySize"); ``` ```csharp // 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. ```csharp // 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.  ```csharp // 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); ``` > **Info:** 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. ```csharp // 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. ```csharp // 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. ```csharp // 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); ``` - **InCategories** – Retrieves pages that are in specific [categories](https://docs.kentico.com/k10/managing-website-content/working-with-pages/categorizing-pages.md). To limit the filtering only to pages in enabled categories, use the _InEnabledCategories_ method. ```csharp // Retrieves smartphones that are in the 'Phablets' category DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone") .OnSite("CorporateSite") .Path("/Products/", PathTypeEnum.Children) .InCategories("Phablets"); ``` - **WithTag** – Retrieves pages based on the assigned [tags](https://docs.kentico.com/k10/managing-website-content/working-with-pages/tagging-pages.md). Note that multiple tags assigned to different tag groups can have identical names. To search for a tag across all tag groups, omit the second method parameter. ```csharp // Retrieves smartphones that have the 'Android' tag from the 'Smartphones' tag group DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone") .OnSite("CorporateSite") .Path("/Products/", PathTypeEnum.Children) .WithTag("Android", "Smartphones"); ``` - **InRelationWith** – Retrieves pages based on their [relationships](https://docs.kentico.com/k10/developing-websites/loading-and-displaying-data-on-websites/displaying-data-advanced-scenarios/displaying-related-pages-using-named-relationships.md) with other pages. ```csharp // 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); ``` ```csharp // 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"); ``` ```csharp // 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](https://docs.kentico.com/k10/managing-website-content/working-with-pages/copying-and-moving-pages-creating-linked-pages.md). ```csharp // 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. ```csharp // 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. ```csharp // 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. ```csharp // 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'. ```csharp // 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%"); ```