Page NavigationFilters

5 min

The NavigationFilter in Optimizely Configured Commerce lets you:

Redirect to sign in when a user tries to go to a page before they are signed in.

Hide a page from a user if they do not have the correct roles.

Hide a page completely if that page is not enabled.

Prevent a page from displaying in navigation menus, such as order history details because the link must be generated for each specific order.

NavigationFilter is implemented in the Extensions project with C# and JSON, so you can enforce these restrictions at the API level.

NavigationFilter examples

Below is an example of implementing a NavigationFilter.

// inherit from BaseNavigationFilter to get access to some helper functions
public sealed class BrandIsEnabledNavigationFilter : BaseNavigationFilter
{
    readonly CatalogGeneralSettings catalogGeneralSettings;

    public BrandIsEnabledNavigationFilter(CatalogGeneralSettings catalogGeneralSettings)
    {
        this.catalogGeneralSettings = catalogGeneralSettings;
    }

    // based on the passed in parameter you can
    // return null to indicate that no filtering should apply
    // return a NavigationFilterResult
    public override NavigationFilterResult Apply(NavigationFilterParameter parameter)
    {
        if (!this.catalogGeneralSettings.EnableBrands)
        {
            // Because brands are not enabled, this uses the base class helper method to return
            // a 404 result
            return this.NotFoundResult();
        }
        // Brand are enabled, so do not filter out this page
        return null;
    }
}

The NavigationFilterResult has a few different properties you can use to customize the result.

public class NavigationFilterResult
{
    /// <summary>Determines if a link to this page should still be including when generating navigation menus</summary>
    public bool DisplayLink { get; set; }

    /// <summary>Determines what HttpStatusCode should be returned if someone attempts to go to this page.</summary>
    public HttpStatusCode StatusCode { get; set; }

    /// <summary>Determines what url the user should be redirected to if they are not allowed to navigation to this page.</summary>
    public string RedirectTo { get; set; }
}

The NavigationFilterParameter passed into Apply provides some data that may be used by each NavigationFilter.

public class NavigationFilterParameter
{
    public ISiteContext SiteContext { get; set; }

    /// <summary>The url being used to retrieve a page. Only populated if Type == NavigationFilterType.RetrievingPage</summary>
    public string Url { get; set; }

    /// <summary>Applying NavigationFilters is done when retrieving a specific page, or when retrieving all links for the site. Results may need to vary based on the type of retrieval.</summary>
    public NavigationFilterType Type { get; set; }

    /// <summary>The page that is being retrieved. Only populated if Type == NavigationFilterType.RetrievingPage</summary>
    public IPublicPageModel Page { get; set; }
    public Lazy<string> SignInPageUrl { get; set; }
}

A NavigationFilter may define a property named Properties. You can define these values in the JSON file detailed below. This lets you apply the same filter to several page types with different properties that are defined per page type.

// this property exists in the IsAuthorizedNavigationFilter

public IsAuthorizedProperties Properties { get; set; }

// so each page type can define different values for the following class

public class IsAuthorizedProperties
{
    public IEnumerable<string> AllowedRoles { get; set; }
    public IEnumerable<string> DisallowedRoles { get; set; }
    public bool IsAllowedForRememberedUser { get; set; }
    public bool DisplayLinkForRememberedUser { get; set; }
    public bool IsAllowedForGuestUser { get; set; }
}

Filter a page using JSON

Each page type can optionally specify the filters that should be applied to it using a JSON file. If there is no JSON file for a given type, then no filters are applied to it.

The following is an example of the OrderHistoryPage.json.

{
  // First apply the filter named IsAuthorizedNavigationFilter
  "IsAuthorized": {
      // These are the values for IsAuthorizedProperties that will be set on the    IsAuthorizedNavigationFilter
      "DisallowedRoles": [ "Requisitioner" ],
      "DisplayLinkForRememberedUser": true
  },

  // If the first filter returns null, then apply DisallowForPunchoutNavigationFilter
  "DisallowForPunchOut": {}
}

📘 Note The page's name in Spire, OrderHistoryPage, must match the JSON file's name.

You can replace the base code OrderHistoryPage.json in the extensions project. It must exist at Extensions/NavigationFilters/Filters and be set up as an embedded resource.

Any JSON files for custom pages must exist in the same location and be set up as embedded resources.

Base code NavigationFilters may be replaced by naming them the same thing. A NavigationFilter named IsAuthorizedNavigationFilter in the extensions project will replace the base code IsAuthorizationNavigationFilter.