Navigation

Structr.Navigation package is intended to help organize navigation menu (nav bar) or/and breadcrumbs in web-application.

Installation

Navigation package is available on NuGet.

dotnet add package Structr.Navigation

Setup

Create menu or breadcrumb navigation item.

public class MenuItem : NavigationItem<MenuItem>
{
	public string Action { get; set; }
	public string Controller { get; set; }
	public string Area { get; set; }
	public string Icon { get; set; }
}

Navigation services uses different providers to get source navigation data. For example: JSON, XML file, Database, or something else.

You can create custom navigation provider:

public class CustomNavigationProvider<TNavigationItem> : INavigationProvider<TNavigationItem>
    where TNavigationItem : NavigationItem<TNavigationItem>, new()
{
    public IEnumerable<TNavigationItem> CreateNavigation() 
    {
        /* Do some logic here */
    }
}

And then setup navigation services:

services.AddNavigation()
    .AddProvider(new CustomNavigationProvider<MenuItem>());

Or you can use one of default implemented navigation provider from list:

JSON provider

Create JSON file with hierarchical navigation:

[
  {
    "Id": "Parent_1",
    "Title": "Parent 1",
    "Icon": "icon-1",
    "Action": "Parent_1_Action",
    "Controller": "Parent_1_Controller",
    "Children": [
      {
        "Id": "Child_1_1",
        "Title": "Child 1 1",
        "Icon": "icon-1-1",
        "Action": "Child_1_1_Action",
        "Controller": "Child_1_1_Controller"
      }
    ]
  },
  {
    "Id": "Parent_2",
    "Title": "Parent 2",
    "Icon": "icon-2",
    "Action": "Parent_2_Action",
    "Controller": "Parent_2_Controller"
  },
  {
    "Id": "Parent_3",
    "Title": "Parent 3",
    "Icon": "icon-3",
    "Action": "Parent_3_Action",
    "Controller": "Parent_3_Controller"
  }
]

Setup JSON navigation provider:

services.AddNavigation()
    .AddJson<MenuItem>("path_to_json_file");

XML provider

Create XML file with hierarchical navigation:

<?xml version="1.0" encoding="utf-8" ?>
<menu>
    <item id="Parent_1" title="Parent 1" Action="Parent_1_Action" Controller="Parent_1_Controller" icon="icon-1">
        <item id="Child_1_1" title="Child 1 1" Action="Child_1_1_Action" Controller="Child_1_1_Controller" icon="icon-1-1"/>
    </item>
    <item id="Parent_2" title="Parent 2" Action="Parent_2_Action" Controller="Parent_2_Controller" icon="icon-2"/>
    <item id="Parent_3" title="Parent 3" Action="Parent_3_Action" Controller="Parent_3_Controller" icon="icon-3"/>
</menu>

Setup XML navigation provider:

services.AddNavigation()
    .AddXml<MenuItem>("path_to_xml_file");

Options

When you setup navigation provider you can configure navigation options represents by NavigationOptions<TNavigationItem>.

NavigationOptions<TNavigationItem> properties:

Property nameProperty typeDescription

ResourceType

Type

Determines a type of resources file whether uses for localization, null by default.

ItemFilter

Func<TNavigationItem, bool>

Determines a filter function for navigation items, item => true by default.

ItemActivator

Func<TNavigationItem, bool>

Determines an activation function for navigation items, item => false by default.

EnableCaching

bool

Determines whether navigation items should be cached, true by default.

Example configure navigation services:

services.AddNavigation()
    .AddJson<MenuItem>("path_to_json_file", (serviceProvider, options) =>
    {
        options.ResourceType = typeof(MenuResource); // Also navigation item should have configured `ResourceName` property.
        options.ItemFilter =
            item => serviceProvider.GetService<IMenuFilter>().Filter(item);
        options.ItemActivator =
            item => serviceProvider.GetService<IMenuActivator>().Activate(item);
    });

Usage

Navigation services uses to organize menu or breadcrumbs. Both of navigation elements should be inherited from NavigationItem<T> that represents basic navigation item.

NavigationItem<T> properties:

Property nameProperty typeDescription

Id

string

Navigation item identifier.

Title

string

Navigation item title.

ResourceName

string

The key of navigation item in resource file.

Children

IEnumerable<TNavigationItem>

Child navigation elements.

Ancestors

IEnumerable<TNavigationItem>

Returns all parent navigation items.

Descendants

IEnumerable<TNavigationItem>

Returns all child navigation items.

Parent

TNavigationItem

Returns closest parent navigation item.

IsActive

bool

Status of navigation item. Only one navigation item can be active at the same time.

HasChildren

bool

Returns true if the navigation item has a child, otherwise returns false.

HasActiveChild

bool

Returns true if the navigation item has an active child, otherwise returns false.

HasActiveDescendant

bool

Returns true if the navigation item has an active descendant, otherwise returns false.

HasActiveAncestor

bool

Returns true if the navigation item has an active ancestor, otherwise returns false.

Last updated