Skip to main content

getDependentPages pipeline

Introduction#

The getDependentPages pipeline is a critical piece to power both the Incremental Static Site Generation and the Incremental Content Sync capability if Uniform for Sitecore. Check out this guide more more information.

There are two ways to define the pipeline:

  • global: sitecore/pipelines/group[@name="uniform"]/pipelines/getDependentPages This is how it is defined by default.
  • site-specific: sitecore/uniform/siteConfigurations/siteConfiguration[@name='mysite']/pipelines/getDependentPages which is not defined by default, you can define it when the page dependency resolution needs vary per your Site Configuration (this should be very rare)

The purpose of this pipeline is to return the list of all page-level items that are both:

  • dependent on a given content item
  • in scope for the given Site Configuration

Inner workings#

The processors of this pipeline have access to the following key objects:

  • an instance of the Evaluated Item This represents the content item that was changed during publishing process and could represent any Sitecore item - a template, a media item, a data source item.
  • an instance of Site Configuration This represents the current Site Configuration for which the pipeline execution takes place.
  • Dependent Pages This is the list of page-level items resolved by each processor. At the end of the pipeline process, all pages in the list will be post-processed (duplicates removed) and passed to the incremental static generation process.

The pipeline is executed for each Evaluated Item. It is the job of each pipeline processor to interrogate the Evaluated Item and enrich the list of the Dependent Pages based on the business logic.

Pipeline Processors#

The following default pipeline processors are in place to cover some common use cases:

1. CheckIfPage#

This pipeline processor checks if the Evaluated Item belongs to the given Site Configuration for which the operation is performed and ensuring that it is a page-level item from Uniform Map Service standpoint. If both conditions are true, this item is added to the list of Dependent Pages.

<processor type="Uniform.Pipelines.GetDependentPages.CheckIfPage, Uniform.Deployment.Incremental">  <param desc="mapNodeService" ref="uniform/services/mapNodeService" />  <abortIfFound>false</abortIfFound></processor>

2. CheckIfLocalPageDatasource#

This pipeline processor checks if the item belongs to a given Site Configuration for which operation is performed and then checks if the current item is placed under a "local page datasource folder" by inspecting the current item's ancestors to find if there is any that has template id matching the value of LocalPageDatasourceFolderTemplate element. If local page datasource folder is found, then the parent item (which is the page-level item) will be added to the list of Dependent Pages. This is a default setting for the SXA solutions and can be tweaked according to your setup.

<processor type="Uniform.Pipelines.GetDependentPages.CheckIfLocalPageDatasource, Uniform.Deployment.Incremental">  <abortIfFound>false</abortIfFound>  <LocalPageDatasourceFolderTemplate>{1C82E550-EBCD-4E5D-8ABD-D50D0809541E}</LocalPageDatasourceFolderTemplate></processor>

3. CheckLinkDatabaseReferrers#

This pipeline processor checks if there are any referrers to the evaluated item. If the referrer is a page-level item and it belongs to the current Site Configuration, it is added to the list of Dependent Pages.

<processor type="Uniform.Pipelines.GetDependentPages.CheckLinkDatabaseReferrers, Uniform.Deployment.Incremental">  <param desc="mapNodeService" ref="uniform/services/mapNodeService" />              <abortIfFound>false</abortIfFound></processor>

4. CheckParentItemLinkDatabaseReferrers#

This one is similar to the CheckLinkDatabaseReferrers processor, with the one difference - the Evaluated Item for which referrers are looked up is different. The configured Locators are responsible for providing with criteria of the ancestor item lookup. The first ancestor that matches the criteria will be evaluated for referrers using the same logic as the CheckLinkDatabaseReferrers processor. This is useful for use cases where you want to detect changes of datasource child items, which are not linked directly to the page-level items.

<processor type="Uniform.Pipelines.GetDependentPages.CheckParentItemLinkDatabaseReferrers, Uniform.Deployment.Incremental">        <param desc="mapNodeService" ref="uniform/services/mapNodeService" />        <abortIfFound>false</abortIfFound>        <Locators hint="raw:AddLocator">          <slides type="Uniform.Pipelines.GetDependentPages.EvaluatedItemLocators.AncestorByTemplateLocator, Uniform.Deployment.Incremental"                         itemtemplateid="{TEMPLATE-OF-SLIDE-DATA-ITEM}"                 parenttemplateid="{TEMPLATE-OF-SLIEDES-FOLDER-ITEM-THAT-IS-ACTUALLY-USED-AS-RENDERING'S-DATASOURCE}"  />        </Locators></processor>

5. CheckMediaNestedDependentPages#

The main purpose of this pipeline processor is to collect the dependent pages for the evaluated media item when it's used by a datasource item instead of a page item directly. Common scenario: media item => datasource item => page-level item We call getDependentPages pipeline for each datasource item to follow default behavior for datasource items.

If abortIfFound is set to true for a given processor, the processor will exit from the pipeline and prevent further processors from being fired, this is reserved for special use cases.

Disabled processors#

  1. AncestorByTemplate - this processor is disabled by default. It can be enabled to allow looking up the ancestor page-level item using ancestorTemplateId if the currently Evaluated Item's template id equals to itemTemplateId. The lookup up the content tree will be limited based on the supplied maxLevel value:

    <processor type="Uniform.Pipelines.GetDependentPages.AncestorByTemplate, Uniform.Deployment.Incremental">  <param desc="mapNodeService" ref="uniform/services/mapNodeService" />  <itemTemplateId>{TEMPLATE_OF_EVALUATED_ITEM}</itemTemplateId>  <ancestorTemplateId>{TEMPLATE_OF_EXPECTED_PARENT_ITEM}</ancestorTemplateId>    <maxLevel>{MAX_AMOUNT_OF_LEVELS_TO_CHECK}</maxLevel></processor>

Adding a custom processor#

Adding a custom pipeline processor is easy and similar to any other Sitecore extension:

  1. Add Uniform Nuget packages to your solution. Follow this guide for more info.

  2. Add a new implementation with a method Process following the signature below:

    public class CustomDependentPagesProcessor{  public void Process(Uniform.Pipelines.GetDependentPages.GetDependentPagesArgs args)  {    // the item that is currently being evaluated     var evaluatedItem = args.EvaluatedItem;    // home item of the context site    var homeItem = args.HomeItem;    // getting current Site Configuration    var siteConfiguration = args.SiteConfiguration;    // add your custom logic of detecting page-level items here...    var foundPageLevelItem = siteConfiguration.Database.GetItem(someItemId, Language.Parse(siteConfiguration.Language));    args.DependentPages.Add(foundPageLevelItem);  }}

  3. Add the configuration patch that adds the pipeline processor 

    <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:set="http://www.sitecore.net/xmlconfig/set/">  <sitecore>    <pipelines>      <group name="uniform" groupName="uniform">        <pipelines>          <getDependentPages>            <processor type="YourNamespace.CustomDependentPagesProcessor, YourAssembly" />          </getDependentPages>        </pipelines>      </group>    </pipelines>  </sitecore></configuration>

  4. Optional - pass parameters to the pipeline processor.

    • Add a new XML element with your desired name and a value:

      <processor type="YourNamespace.CustomDependentPagesProcessor, YourAssembly">    <YourParameter>some value</YourParameter></processor>

    • Add the property to your implementation with the same name (YourParameter):

        public class CustomDependentPagesProcessor  {    public virtual string YourParameter { get; set; }
    public void Process(Uniform.Pipelines.GetDependentPages.GetDependentPagesArgs args)    {      // the item that is currently being evaluated       var evaluatedItem = args.EvaluatedItem;      // home item of the context site      var homeItem = args.HomeItem;      // getting current Site Configuration      var siteConfiguration = args.SiteConfiguration;      // add your custom logic of detecting page-level items here...      var foundPageLevelItem = siteConfiguration.Database.GetItem(someItemId, Language.Parse(siteConfiguration.Language));      args.DependentPages.Add(foundPageLevelItem);    }  }

    The value passed in configuration will be available during runtime.