Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Page NavigationFilters

Describes how to use NavigationFilter.

NavigationFilter 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 to get to it.
  • Hide a page completely if that page is not considered enabled.
  • Prevent a page from displaying in navigation menus. Order history details is an example of a page that should not appear in a navigation menu. A link to it has to be generated for each specific order.

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

NavigationFilter examples

An example of implementing a NavigationFilter is shown below.

// 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 that you return has a few different properties that 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 that is 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. These values can then be defined in the json file that is detailed below. This allows the same filter to be applied to a number of page types with different properties that are defined per page type.

// this property exists in the IsAuthorizedNavigationFilterpublicIsAuthorizedProperties 

Properties {get;set;}

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

publicclassIsAuthorizedProperties
{
  public IEnumerable<string> AllowedRoles {get;set;}
  public IEnumerable<string> DisallowedRoles {get;set;}
  publicbool IsAllowedForRememberedUser {get;set;}
  publicbool DisplayLinkForRememberedUser {get;set;}
  publicbool 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 will be 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 name of the page in Spire, OrderHistoryPage, needs to match the name of the JSON file.

The base code OrderHistoryPage.json may be replaced in the extensions project. It needs to exist at Extensions/NavigationFilters/Filters and needs to be set up as an embedded resource.

Any JSON files for custom pages need to exist in the same location and also 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.