BlazorPathHelper.Generator 0.2.0-alpha.5

BlazorPathHelper

English | 日本語

BlazorPathHelper is a library that assists in managing URL paths within Blazor projects.

Main Features

• Automatically generates URL builders and menu item lists from path definitions
• Supports menu generation for various frameworks with simple implementation

Getting Started

Installation

Install BlazorPathHelper in your Blazor project.

dotnet add package BlazorPathHelper

Preparation

Create a WebPaths.cs file.

using BlazorPathHelper;

[BlazorPath]
public partial class WebPaths
{
  [BlazorPathItem("Home")]
  public const string Index = "/";
  [BlazorPathItem("Sample1")]
  public const string Sample = "/sample";
  [BlazorPathItem("Sample1-a")]
  public const string SampleChild = "/sample/child";
  [BlazorPathItem("Sample2")]
  public const string Counter = "/counter";
  public const string CounterWithState = "/counter/{count:int}";
}

This will automatically generate the following class definition.

// <auto-generated />
// Appended to the original class
public partial class WebPaths
{
  // Helper functions useful for building URLs
  public partial class Helper
  {
    public static string Index() => "/";
    public static string Sample() => "/sample";
    public static string SampleChild() => "/sample/child";
    public static string Counter() => "/counter";
    public static string CounterWithState(int count) => string.Format("/counter/{0}", count);
  }
  
  // An array useful for dynamically creating menu items
  public static readonly BlazorMenuItem[] MenuItem = [
    new BlazorPathMenuItem(){
      Name = "Home", // Menu name. Defaults to the variable name
      Path = "/",    // Page path
      Children = []  // Submenus
      // Other properties automatically generated to assist in menu creation
    },
    new BlazorPathMenuItem(){
      Name = "Sample1",
      Path = "/sample", 
      // Parses the URL and intelligently generates submenus
      Children = [
        new BlazorPathMenuItem(){
          Name = "Sample1-a",
          Path = "/sample/child", 
          Children = []
        }
      ]
    },
    new BlazorPathMenuItem(){
      Name = "Sample2",
      Path = "/counter",
      // Pages with parameters are not displayed in the menu
      Children = []
    }
  ];
}

Finally, change the definition on the razor page from @page to @attribute + Route.

@* @page "/counter/{count:int}" *@
@attribute [Route(WebPaths.CounterWithState)]

Usage

URL Builder

// Generate URL
var url = WebPaths.Helper.CounterWithState(1); // -> "/counter/1"

// Navigate to page
// @inject NavigationManager Nav
Nav.NavigateTo(url);

// With query
Nav.NavigateTo(
  Nav.GetUriWithQueryParameter(url, "q", "test"), // -> "/counter/1?q=test"
  forceLoad: true
);

Menu Generation

Create NavMenu.razor and NavMenuItem.razor.

@* NavMenu.razor *@
<nav>
  @foreach (var menuItem in WebPaths.MenuItem)
  {
    <NavMenuItem MenuItem="menuItem"/>
  }
</nav>

@* NavMenuItem.razor *@
@using BlazorPathHelper

@* A component that recursively displays menu items *@
@* The key attribute can use MenuItem.Index *@
<div @key="@MenuItem.Index">
  <NavLink href="@MenuItem.Path" Match="@NavLinkMatch.All">
    <span class="@MenuItem.Icon" aria-hidden="true"></span>
    @MenuItem.Name
  </NavLink>

  @* Submenus *@
  @foreach(var childMenuItem in MenuItem.Children)
  {
    <NavMenuItem MenuItem="childMenuItem"/>
  }
</div>

@code {
  [Parameter, EditorRequired]
  public BlazorPathMenuItem MenuItem { get; set; } = default!;
}

Menu Customization

You can customize menu display using the BlazorPathItem attribute.

[BlazorPath]
public partial class WebPaths
{
  // To hide from the menu, specify Visible = false
  [BlazorPathItem(Visible = false)]
  public const string Index = "/";

  // Specify page name and icon (CSS class)
  [BlazorPathItem("SampleA", Icon = "fas fa-cog")]
  public const string Sample = "/sample";
  [BlazorPathItem("SampleA-1", Icon = "fas fa-star")]
  public const string SampleChild = "/sample/child";

  // To add a description, specify it as the Description
  [BlazorPathItem("SampleA-2", Description = "Description of the A-2 page")]
  public const string SampleWithDesc = "/sample/child2";

  // To recognize as a child element without URL connection, specify Group
  [BlazorPathItem("SampleA-3", Group = Sample)]
  public const string SampleChild3 = "/sample-3";

  // To display a deeply nested hierarchy that is not connected to anything as a top-level menu, specify Group = "/"
  [BlazorPathItem("SampleB", Group = Index)]
  public const string SuperInnerItem = "/hoge/fuga/piyo";

  // If specified as above, child pages will also be displayed in the menu
  [BlazorPathItem("SampleB-1")]
  public const string SuperInnerItemChild = "/hoge/fuga/piyo/child";

  // For multilingual support, use nameof to specify resource keys and use IStringLocalizer in components
  [BlazorPathItem(nameof(Resources.SampleTitle))]
  public const string SampleLocalize = "/sample-l10n";
  [BlazorPathItem(nameof(Resources.SampleTitle), nameof(Resources.SampleDesc))]
  public const string SampleLocalizeWithDesc = "/sample-l10n-plus";
}

Implementation Examples for Each Framework

Blazor Template

Since the standard template does not include icons, add the following to index.html.

<head>
    
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css">
</head>

Then, use it as follows.

// WebPaths.cs
[BlazorPath]
public partial class WebPaths
{
    [BlazorPathItem(Name="Home", Icon="bi-house-door-fill")]
    public const string Home = "/";
    [BlazorPathItem(Name="Sample1", Icon="bi-1-circle-fill")]
    public const string Sample1 = "/sample1";
    [BlazorPathItem(Name="Sample2", Icon="bi-2-circle-fill")]
    public const string Sample2 = "/sample2";
    [BlazorPathItem(Name="Sample3", Icon="bi-3-circle-fill")]
    public const string Sample3 = "/sample3";
}

@* NavMenuItem.razor *@
@using BlazorPathHelper

<div class="nav-item ps-3 py-1" @key="@MenuItem.Index">
  <NavLink class="nav-link" href="@MenuItem.Path"
    Match="@(MenuItem.Path != "/" ? NavLinkMatch.Prefix : NavLinkMatch.All)">
    <span class="me-2 fs-5 @MenuItem.Icon" aria-hidden="true"></span>
    @MenuItem.Name
  </NavLink>
  @foreach(var childMenuItem in MenuItem.Children)
  {
    <nav class="flex-column">
      <NavMenuItem MenuItem="childMenuItem"/>
    </nav>
  }
</div>

@code {
  [Parameter, EditorRequired]
  public BlazorPathMenuItem MenuItem { get; set; } = default!;
}

Implementation examples are available in Example.Plain.

FluentUI

Since FluentUI's Icon cannot be specified as is, extract the name part and specify it.

using BlazorPathHelper;
// To shorten, use using static
using static Microsoft.FluentUI.AspNetCore.Components.Icons.Regular.Size20;

[BlazorPath]
public partial class WebPaths
{
    // Specify the icon with BlazorPathItem<T>
    // ---------------------------------
    [BlazorPathItem<Home>("Home")]
    public const string Home = "/";
    [BlazorPathItem<TextHeader1>("Sample1")]
    public const string Sample1 = "/sample1";
    [BlazorPathItem<TextHeader2>("Sample2")]
    public const string Sample2 = "/sample2";
    [BlazorPathItem<TextHeader3>("Sample3")]
    public const string Sample3 = "/sample3";
}

Then, use it as follows.

@* NavMenuItem.razor *@
@using BlazorPathHelper

@if(MenuItem.Children.Length > 0)
{
  <FluentNavGroup Href="@MenuItem.Path" Title="@MenuItem.Name" Icon="@((Icon?)MenuItem.Icon)">    
    @foreach(var childMenuItem in MenuItem.Children)
    {
      <NavMenuItem MenuItem="childMenuItem"/>
    }
  </FluentNavGroup>
}
else
{
  <FluentNavLink Href="@MenuItem.Path" Icon="@((Icon?)MenuItem.Icon)" IconColor="Color.Accent">
      @MenuItem.Name
  </FluentNavLink>
}

@code {
  [Parameter, EditorRequired]
  public BlazorPathMenuItem MenuItem { get; set; } = default!;
}

Implementation examples are available in Example.FluentUI.

AntBlazor

The standard template (Pro) includes a feature to generate menus from objects, but the generation of these definitions can be simplified.

// Layout/BasicLayout.razor.cs
protected override async Task OnInitializedAsync()
{
  _menuData = ConverterMenuDataItem(WebPaths.MenuItem);
}

private MenuDataItem[] ConverterMenuDataItem(BlazorPathMenuItem[] items)
{
  return items.Select(item => new MenuDataItem {
    Path = item.Path,
    Name = item.Name,
    Key = item.Index.ToString(),
    Icon = item.Icon?.ToString(),
    Children = item.Children.Length > 0
      ? ConverterMenuDataItem(item.Children) : null
  }).ToArray();
}

Then, it's the same as others.

// WebPaths.cs
using BlazorPathHelper;

[BlazorPath]
public partial class WebPaths
{
  [BlazorPathItem("Home", Icon = "home")]
  public const string Home = "/";
  [BlazorPathItem("Sample1", Icon = "folder")]
  public const string Sample1 = "/sample1";
  [BlazorPathItem("Sample2", Icon = "folder")]
  public const string Sample2 = "/sample2";
  [BlazorPathItem("Sample3", Icon = "file")]
  public const string Sample3 = "/sample3";
}

Implementation examples are available in Example.AntBlazor.