Navigation (OrchardCore.Navigation
)¶
Purpose¶
Provides the Navigation
, Pager
and PagerSlim
shapes.
Theming¶
Navigation can be themed by adding the appropriate partial view files to your theme's views folder.
A good example can be found in the TheAdmin
theme project.
That theme creates the standard, vertical navigation menu that is found on the admin dashboard of any OrchardCore application.
The TheAdmin
theme provides the following alternates to the default ones provided in the Navigation
module:
Navigation-admin.cshtml
NavigationItem-admin.cshtml
NavigationItemLink-admin.cshtml
The theme developer has full control over how and where navigation is displayed in their OrchardCore application.
Pager¶
This is a multi-purpose pagination component that renders links to specific page numbers. It can optionally render First and Last links.
Parameter | Type | Description |
---|---|---|
Page |
int |
Active page number. |
PageSize |
int |
Number of items per page. |
TotalItemCount |
double |
Total number of items (used to calculate the number of the last page). |
Quantity |
int? |
Number of pages to show, 7 if not specified. |
FirstText |
object |
Text of the "First" link, default: T["<<"] . |
PreviousText |
object |
Text of the "Previous" link, default: T["<"] . |
NextText |
object |
Text of the "Next" link, default: T[">"] . |
LastText |
object |
Text of the "Last" link, default: T[">>"] . |
GapText |
object |
Text of the "Gap" element, default: T["..."] . |
PagerId |
string |
An identifier for the pager. Used to create alternate like Pager__[PagerId] . |
ShowNext |
bool |
If true, the "Next" link is always displayed. |
Properties inherited from the List
shape:
Parameter | Type | Description |
---|---|---|
Id |
string |
The HTML id used for the pager, default: none. |
Tag |
string |
The HTML tag used for the pager, default: ul . |
ItemTag |
string |
The HTML tag used for the pages, default: li . |
FirstClass |
string |
The HTML class used for the first page, default: first . |
LastClass |
string |
The HTML tag used for last page, default: last . |
ItemClasses |
List<string> |
Classes that are assigned to the pages, default: none. |
ItemAttributes |
Dictionary<string, string> |
Attributes that are assigned to the pages. |
The PagerId
property is used to create templates for specific instances. For instance, assigning
the value MainBlog
to PagerId
and then rendering the pager will look for a template named
Pager-MainBlog.cshtml
.
A pager can be further customized by defining templates for the following shapes:
Pager_Gap
Pager_First
Pager_Previous
Pager_Next
Pager_Last
Pager_CurrentPage
Each of these shapes are ultimately morphed into Pager_Link
.
Alternates for each of these shapes are created using the PagerId
like Pager_Previous__[PagerId]
which
would in turn look for the template Pager-MainBlog.Previous.cshtml
.
PagerSlim
¶
This shape renders a pager that is comprised of two links: Previous and Next.
Parameter | Type | Description |
---|---|---|
PreviousClass |
string |
The HTML class used for the Previous link, default: none. |
NextClass |
string |
The HTML class used for the Next link, default: none. |
PreviousText |
object |
Text of the "Previous" link, default: T["<"] . |
NextText |
object |
Text of the "Next" link, default: T[">"] . |
Properties inherited from the List
shape:
Parameter | Type | Description |
---|---|---|
Id |
string |
The HTML id used for the pager, default: none. |
Tag |
string |
The HTML tag used for the pager, default: ul . |
ItemTag |
string |
The HTML tag used for the pages, default: li . |
FirstClass |
string |
The HTML class used for the first page, default: first . |
LastClass |
string |
The HTML tag used for last page, default: last . |
ItemClasses |
List<string> |
Classes that are assigned to the pages, default: none. |
ItemAttributes |
Dictionary<string, string> |
Attributes that are assigned to the pages. |
A slim pager can be further customized by defining templates for the following shapes:
Pager_Previous
Pager_Next
Examples of Liquid alternates or templates for Pager_Next
and Pager_Previous
:
{% shape_clear_alternates Model %} {% shape_type Model "Pager_Link" %} {% shape_add_classes Model "page-link" %} {{ Model | shape_render }}
Each of these shapes are ultimately morphed into Pager_Link
.
Alternates for each of these shapes are created using the PagerId
like Pager
Previous`[PagerId]
which
would in turn look for the template Pager-MainBlog.Previous.cshtml
.
Extending Navigation¶
Navigation can be extended, through code, by implementing INavigationProvider
and registering it in the extending module (or theme) Startup.cs
file.
Below is a sample implementation of an INavigationProvider
used to extend the "main" navigation section of the site.
public class MainMenu : INavigationProvider { public MainMenu(IStringLocalizer<MainMenu> localizer) { T = localizer; } public IStringLocalizer T { get; set; } public async Task BuildNavigation(string name, NavigationBuilder builder) { //Only interact with the "main" navigation menu here. if (!String.Equals(name, "main", StringComparison.OrdinalIgnoreCase)) { return; } builder .Add(T["Notifications"], T["Notifications"], layers => layers .Action("Index", "Template", new { area = "CRT.Client.OrchardModules.CommunicationTemplates", groupId = 1 }) .LocalNav() ); } }
This provider will be called as long as the site is using a theme that includes a line similar to the following, which causes the navigation menu to be rendered by your theme at the location specified:
@await DisplayAsync(await New.Navigation(MenuName: "main", RouteData: @ViewContext.RouteData))
Examples of extending the admin navigation can be found in various OrchardCore modules. Searching the repository for AdminMenu
will locate various settings. Below is a partial list:
OrchardCore.Modules/OrchardCore.Admin/AdminFilter.cs
OrchardCore.Modules/OrchardCore.Media/AdminMenu.cs
At this time, the Admin Menu is the only navigation with code dynamically adding items in the OrchardCore git repository. However, as the example above shows, the pattern can be used to control any named navigation.