Pages

// Gets the current site's root "/" page, which will serve as the parent page
TreeNode parentPage = new DocumentQuery<TreeNode>()
                            .Path("/", PathTypeEnum.Single)
                            .OnSite("MySite")
                            .Culture("en-us")
                            .TopN(1)
                            .FirstOrDefault();

if (parentPage != null)
{
    // Creates a new page of the custom page type
    TreeNode newPage = TreeNode.New("Custom.Article");

    // Sets the properties of the new page
    newPage.DocumentName = "Articles";
    newPage.DocumentCulture = "en-us";

    // Inserts the new page as a child of the parent page
    newPage.Insert(parentPage);
}

// Gets a single page from the "MySite" site and in the "en-us" culture
TreeNode page = new DocumentQuery<TreeNode>()
                            .Path("/Articles/Coffee", PathTypeEnum.Single)
                            .OnSite("MySite")
                            .Culture("en-us")
                            .TopN(1)
                            .FirstOrDefault();

if (page != null)
{
    // Sets new values in the "DocumentName" and "ArticleTitle" fields of the page
    page.DocumentName = "Translated article name";
    page.SetValue("ArticleTitle", "Translated article title");

    // Inserts a new version of the page in the "de-de" culture
    // Note that the culture must be assigned to the current site
    page.InsertAsNewCultureVersion("de-de");
}

// Gets the page that will be linked
TreeNode originalPage = new DocumentQuery<TreeNode>()
                            .Path("/Archive/Articles", PathTypeEnum.Single)
                            .OnSite("MySite")
                            .Culture("en-us")
                            .TopN(1)
                            .FirstOrDefault();

// Gets the page that will be used as a parent page for the linked page
TreeNode parentPage = new DocumentQuery<TreeNode>()
                          .Path("/Articles", PathTypeEnum.Single)
                          .OnSite("MySite")
                          .Culture("en-us")
                          .TopN(1)
                          .FirstOrDefault();

if ((originalPage != null) && (parentPage != null))
{
    // Inserts a new linked page under the parent page
    originalPage.InsertAsLink(parentPage);
}

// Gets the published version of pages stored under the "/Articles/" path
// The pages are retrieved from the "MySite" site and in the "en-us" culture
IEnumerable<TreeNode> pages = new MultiDocumentQuery()
                                .Path("/Articles/", PathTypeEnum.Children)
                                .WhereStartsWith("DocumentName", "Coffee")
                                .OnSite("MySite")
                                .Culture("en-us")
                                .Published()
                                .PublishedVersion();

// Updates the "DocumentName" and "ArticleTitle" fields of each retrieved page
foreach (TreeNode page in pages)
{
    page.DocumentName = "Updated article name";
    page.SetValue("ArticleTitle", "Updated article title");

    // Updates the page in the database
    page.Update();
}

// Gets the latest version of pages stored under the "/Articles/" path whose name starts with "Coffee"
// The pages are retrieved from the "MySite" site and in the "en-us" culture
IEnumerable<TreeNode> pages = new MultiDocumentQuery()
                                  .Path("/Articles/", PathTypeEnum.Children)
                                  .WhereStartsWith("DocumentName", "Coffee")
                                  .OnSite("MySite")
                                  .Culture("en-us")
                                  .WithCoupledColumns()
                                  .LatestVersion();

// Note: When updating pages of multiple page types under workflow or versioning, always retrieve
// the pages with all columns to avoid data loss using the'WithCoupledColumns' parameterization. 
// Optionally, you can specify the page types to retrieve using the 'Types' parameterization.

// Updates the "DocumentName" and "ArticleTitle" fields of each retrieved page
foreach (TreeNode page in pages)
{
    // Allows the system to create a new version of the updated page (required even when not using content locking)
    // If using content locking, checks out the page
    page.CheckOut();

    page.DocumentName = "Updated article name";
    page.SetValue("ArticleTitle", "Updated article title");

    // Updates the page in the database
    page.Update();

    // Creates a new version of the updated page (required even when not using content locking)
    // If using content locking, checks in the page
    page.CheckIn();
}

// Gets an existing page from the "MySite" site in the "en-us" culture
TreeNode page = new DocumentQuery<TreeNode>()
                    .Path("/Articles/", PathTypeEnum.Children)
                    .OnSite("MySite")
                    .Culture("en-us")
                    .TopN(1)
                    .FirstOrDefault();

if (page != null)
{
    // Updates the "DocumentName" and "ArticleTitle" fields of the page
    page.DocumentName = "Updated article name";
    page.SetValue("ArticleTitle", "Updated article name");

    // Gets a List of the fields that were updated
    var changedColumns = page.ChangedColumns();

    page.Update();

    // Check if search is enabled for the page and that the modified fields are included in search indexes
    if (DocumentHelper.IsSearchTaskCreationAllowed(page) && page.SearchTriggerFieldChanged(changedColumns))
    {
        // Creates search tasks for updating the content of the page in related search indexes
        SearchTaskInfoProvider.CreateTask(SearchTaskTypeEnum.Update, TreeNode.OBJECT_TYPE, SearchFieldsConstants.ID, page.GetSearchID(), page.DocumentID);
    }
}

// Gets the page that will be moved
TreeNode page = new DocumentQuery<TreeNode>()
                    .Path("/Articles/Coffee-Beverages-Explained", PathTypeEnum.Single)
                    .OnSite("MySite")
                    .Culture("en-us")
                    .TopN(1)
                    .FirstOrDefault();

// Gets the page to copy under
TreeNode targetPage = new DocumentQuery<TreeNode>()
                          .Path("/Archive", PathTypeEnum.Single)
                          .OnSite("MySite")
                          .Culture("en-us")
                          .TopN(1)
                          .FirstOrDefault();

if ((page != null) && (targetPage != null))
{
    // Copies the page to the new location, including any child pages
    DocumentHelper.CopyDocument(page, targetPage, true);
}

// Gets the page that will be moved
TreeNode page = new DocumentQuery<TreeNode>()
                    .Path("/Articles/Coffee-Beverages-Explained", PathTypeEnum.Single)
                    .OnSite("MySite")
                    .Culture("en-us")
                    .TopN(1)
                    .FirstOrDefault();

// Gets the parent page to move under
TreeNode targetPage = new DocumentQuery<TreeNode>()
                          .Path("/Archive", PathTypeEnum.Single)
                          .OnSite("MySite")
                          .Culture("en-us")
                          .TopN(1)
                          .FirstOrDefault();

if ((page != null) && (targetPage != null))
{
    // Moves the page to the new location, including any child pages
    DocumentHelper.MoveDocument(page, targetPage, keepPermissions: true);
}

// Gets the parent page
TreeNode page = new DocumentQuery<TreeNode>()
                    .Path("/Parent", PathTypeEnum.Single)
                    .OnSite("MySite")
                    .Culture("en-us")
                    .TopN(1)
                    .FirstOrDefault();

if (page != null)
{
    // Initializes a provider used for manipulation of nodes in the content tree
    TreeProvider tree = new TreeProvider(MembershipContext.AuthenticatedUser);

    // Moves the page up in the content tree
    tree.MoveNodeUp(page.DocumentID);

    // Moves the page down in the content tree
    tree.MoveNodeDown(page.DocumentID);
    
    // Creates a corresponding staging task for the page move event. Useful only in environments utilizing staging.
    DocumentSynchronizationHelper.LogDocumentChangeOrder(SiteContext.CurrentSiteName, page.NodeAliasPath, tree);
}

// Gets the parent page to sort under
TreeNode page = new DocumentQuery<TreeNode>()
                    .Path("/Parent", PathTypeEnum.Single)
                    .OnSite("MySite")
                    .Culture("en-us")
                    .TopN(1)
                    .FirstOrDefault();

if (page != null)
{
    // Initializes a provider used for bulk manipulation of nodes in the content tree
    TreeProvider tree = new TreeProvider(MembershipContext.AuthenticatedUser);

    bool orderIsAscending = true;

    // Sorts all child pages under the specified parent page alphabetically in ascending order
    tree.SortNodesAlphabetically(page.NodeID, SiteContext.CurrentSiteID, orderIsAscending);

    // Sorts all child pages under the specified parent page in an ascending order based on the last modification date
    tree.SortNodesByDate(page.NodeID, SiteContext.CurrentSiteID, orderIsAscending);
}

// Gets the culture version that will be deleted
TreeNode page = new DocumentQuery<TreeNode>()
                    .Path("/Example", PathTypeEnum.Single)
                    .OnSite("MySite")
                    .Culture("en-us")
                    .TopN(1)
                    .FirstOrDefault();

if (page != null)
{
    // Deletes the page and moves it to the recycle bin (only the specified culture version)
    page.Delete();

    // Creates search tasks that remove the deleted page from the content of related search indexes
    if (SearchIndexInfoProvider.SearchEnabled)
    {
        SearchTaskInfoProvider.CreateTask(SearchTaskTypeEnum.Delete, TreeNode.OBJECT_TYPE, SearchFieldsConstants.ID, page.GetSearchID(), page.DocumentID);
    }
}

// Gets the page that will be deleted
TreeNode page = new DocumentQuery<TreeNode>()
                    .Path("/Example", PathTypeEnum.Single)
                    .OnSite("MySite")
                    .Culture("en-us")
                    .TopN(1)
                    .FirstOrDefault();

if (page != null)
{
    // Indicates whether to delete all culture versions of the page or only the current one
    bool deleteAllCultureVersions = true;
    // Indicates whether the page will be deleted permanently with no restoration possible
    bool deletePermanently = true;

    // Permanently deletes all culture versions of the page and its version history
    page.Delete(deleteAllCultureVersions, deletePermanently);

    // Creates search tasks that remove the deleted page from the content of related search indexes
    if (SearchIndexInfoProvider.SearchEnabled)
    {
        SearchTaskInfoProvider.CreateTask(SearchTaskTypeEnum.Delete, TreeNode.OBJECT_TYPE, SearchFieldsConstants.ID, page.GetSearchID(), page.DocumentID);
    }
}

// Gets the "/Articles/On-Roasts" page from the recycle bin for the current site
VersionHistoryInfo pageVersion = VersionHistoryInfo.Provider.Get()
                                           .WhereEquals("VersionNodeAliasPath", "/Articles/On-Roasts")
                                           .WhereEquals("NodeSiteID", SiteContext.CurrentSiteID)
                                           .TopN(1)
                                           .FirstOrDefault();

// Checks that the deleted page exists in the recycle bin
if (pageVersion != null)
{
    // Creates a new version manager instance and restores the deleted page from the recycle bin
    VersionManager manager = VersionManager.GetInstance(new TreeProvider(MembershipContext.AuthenticatedUser));
    manager.RestoreDocument(pageVersion.VersionHistoryID);
}

/* The IPageRetriever is a service class that wraps the standard DocumentQuery API. 
 * The service is intended to be used for page retrieval in Xperience web applications (projects using the 
 * Kentico.Xperience.AspNet.Mvc5 or Kentico.Xperience.AspNetCore.WebApp NuGet packages).
 * The service ensures the following default parameterization for each query:
 *  -- Determines whether to retrieve the latest or published versions of pages based on the context. 
 *       -- Latest version is retrieved under preview mode (e.g., when viewing a page in the Pages application)
 *       -- Published version in all other cases
 *        
 *  -- Parameterizes the query to retrieve pages from the current site (determined by the correspondence to the
 *   presentation URL configured in the Sites application in the administration interface).
 *   
 *  -- Retrieves pages only in the culture matching the culture of the current thread (Thread.CurrentThread.CurrentCulture.Name).
 *  
 *  -- Takes into account the 'Combine with default culture' setting for pages that do not exist in the specific culture. 
 *   The setting determines whether to retrieve a page in a site's default culture if the currently requested 
 *   version of the page does not exist.
 *   
 * You can further parameterize the queries (and override their default parameterization) using regular DocumentQuery syntax.
 *
 * See the following code for examples: 
 */

// Initializes an instance of a service used for page retrieval
IPageRetriever pageRetriever = Service.Resolve<IPageRetriever>();

// Retrieves a single page from the current site and using the culture of the current thread
TreeNode page = pageRetriever.Retrieve<TreeNode>(query => query
                    .Path("/Articles/Article", PathTypeEnum.Single)
                    .TopN(1))
                    .FirstOrDefault();


// Retrieves multiple pages of the same type from the current site and using the culture of the current thread
IEnumerable<TreeNode> pages = pageRetriever.Retrieve("Custom.Article", query => query
                    .Path("/Articles", PathTypeEnum.Section));


// Retrieves multiple pages of different types from the current site and using the culture of the current thread
IEnumerable<TreeNode> pagesMultiple = pageRetriever.RetrieveMultiple(query => query
                    .Path("/Articles", PathTypeEnum.Section)
                     // Ensures fields of the specific page types get added to the result
                    .WithCoupledColumns());


// Additionally, you can immediately cache the retrieved pages by providing a caching delegate together with the query
TreeNode pageCached = pageRetriever.Retrieve<TreeNode>(
                        query => query
                            .Path("/Articles/Article", PathTypeEnum.Single)
                            .TopN(1),
                        cache => cache
                             // Constructs a cache key from sufficiently unique values.
                             // Substitute the string placeholders with actual parameters.
                             // Note: This is only an example of a possible cache key format. The purpose of a cache is key is to 
                             // ensure caching with adequate granularity. When deciding on the format of cache keys,
                             // always consider the specific requirements and use cases of your site.
                            .Key($"ClassName|MethodName|NodeAliasPath|count")
                             // Includes path dependency to flush cache when a new child page is created
                             // under the specified path.
                            .Dependencies((_, builder) => builder.PagePath("NodeAliasPath", PathTypeEnum.Children)))
                        .FirstOrDefault();