Blazouter.Hybrid 1.0.5

Blazouter.Hybrid

Hybrid/MAUI-specific extensions for Blazouter - the React Router-like routing library for Blazor applications. This package provides optimized components and extensions for Blazor Hybrid applications running on .NET MAUI.

Features

• ✅ Native mobile app routing
• ✅ Cross-platform support (iOS, Android, macOS, Windows)
• ✅ MAUI integration
• ✅ All core Blazouter features
• ✅ Native platform optimizations

Installation

dotnet add package Blazouter
dotnet add package Blazouter.Hybrid

Note: This package requires the core Blazouter package and is designed for .NET MAUI projects.

Supported Platforms

• 📱 Android (API 24+)
• 🍎 iOS (15.0+)
• 💻 macOS Catalyst (15.0+)
• 🪟 Windows (10.0.17763+)

Quick Start

1. Configure Services

// MauiProgram.cs
using Blazouter.Extensions;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        builder.Services.AddMauiBlazorWebView();

        #if DEBUG
        builder.Services.AddBlazorWebViewDeveloperTools();
        #endif

        builder.Services.AddBlazouter(); // Add Blazouter services

        return builder.Build();
    }
}

2. Define Routes

@using Blazouter.Components
@using Blazouter.Models

<Router Routes="@_routes">
    <NotFound>
        <div class="not-found">
            <h1>404 - Page Not Found</h1>
        </div>
    </NotFound>
</Router>

@code {
    private List<RouteConfig> _routes = new()
    {
        new RouteConfig
        {
            Path = "/",
            Component = typeof(Pages.Home),
            Title = "Home",
            Transition = RouteTransition.Fade
        },
        new RouteConfig
        {
            Path = "/settings",
            Component = typeof(Pages.Settings),
            Title = "Settings",
            Transition = RouteTransition.Slide
        }
    };
}

3. Include CSS

Add to your main HTML file (typically index.html in wwwroot):

<link rel="stylesheet" href="_content/Blazouter/blazouter.css" />

Platform-Specific Features

Native Navigation Integration

Blazouter.Hybrid integrates seamlessly with native platform navigation:

• Back button handling on Android
• Swipe gestures on iOS
• Platform-specific animations

Optimized for Mobile

The Hybrid package includes optimizations for:

• Touch-based navigation
• Mobile performance
• Reduced memory footprint
• Native feel and responsiveness

Nested Routes for Mobile Apps

Perfect for creating tab-based or hierarchical navigation:

new RouteConfig
{
    Path = "/app",
    Component = typeof(MainLayout),
    Children = new List<RouteConfig>
    {
        new RouteConfig 
        { 
            Path = "home", 
            Component = typeof(HomePage) 
        },
        new RouteConfig 
        { 
            Path = "profile", 
            Component = typeof(ProfilePage) 
        },
        new RouteConfig 
        { 
            Path = "settings", 
            Component = typeof(SettingsPage) 
        }
    }
}

@using Blazouter.Components

<div class="main-layout">
    <nav class="bottom-nav">
        <RouterLink Href="/app/home" ActiveClass="active">Home</RouterLink>
        <RouterLink Href="/app/profile" ActiveClass="active">Profile</RouterLink>
        <RouterLink Href="/app/settings" ActiveClass="active">Settings</RouterLink>
    </nav>
    <div class="content">
        <RouterOutlet />
    </div>
</div>

Route Guards for Mobile

Implement authentication or platform-specific checks:

new RouteConfig
{
    Path = "/premium",
    Component = typeof(PremiumFeatures),
    Guards = new List<Type> { typeof(SubscriptionGuard) }
}

public class SubscriptionGuard : IRouteGuard
{
    private readonly ISubscriptionService _subscriptionService;
    
    public SubscriptionGuard(ISubscriptionService subscriptionService)
    {
        _subscriptionService = subscriptionService;
    }

    public async Task<bool> CanActivateAsync(RouteMatch match)
    {
        return await _subscriptionService.HasActiveSubscriptionAsync();
    }

    public Task<string?> GetRedirectPathAsync(RouteMatch match)
    {
        return Task.FromResult<string?>("/subscribe");
    }
}

Platform-Aware Navigation

@inject RouterNavigationService NavService

private async Task OnBackButtonPressed()
{
    // Handle Android back button
    #if ANDROID
    if (CanGoBack())
    {
        NavService.NavigateTo(-1);
    }
    else
    {
        // Exit app or show exit confirmation
    }
    #endif
}

Lazy Loading for Better Performance

Reduce app startup time by loading features on-demand:

new RouteConfig
{
    Path = "/reports",
    ComponentLoader = async () =>
    {
        // Load heavy component only when needed
        await Task.Delay(100);
        return typeof(ReportsPage);
    },
    Title = "Reports"
}

Route Transitions

Smooth animations optimized for mobile devices:

// Fade - Good for subtle transitions
new RouteConfig
{
    Path = "/home",
    Component = typeof(HomePage),
    Transition = RouteTransition.Fade
}

// Slide - Natural for hierarchical navigation
new RouteConfig
{
    Path = "/details",
    Component = typeof(DetailsPage),
    Transition = RouteTransition.Slide
}

// SlideUp - Great for modal-like screens
new RouteConfig
{
    Path = "/modal",
    Component = typeof(ModalPage),
    Transition = RouteTransition.SlideUp
}

Programmatic Navigation

@inject RouterNavigationService NavService

// Navigate to a route
private void GoToDetail(int itemId)
{
    NavService.NavigateTo($"/items/{itemId}");
}

// Go back
private void GoBack()
{
    NavService.NavigateTo(-1);
}

// Navigate with query parameters
private void SearchItems(string query)
{
    NavService.NavigateTo($"/search?q={query}");
}

Access Route Parameters

@inject RouterStateService RouterState

@code {
    private string? _itemId;
    private string? _searchQuery;

    protected override void OnInitialized()
    {
        _itemId = RouterState.GetParam("id");
        _searchQuery = RouterState.GetQueryParam("q");
    }
}

Deep Linking Support

Blazouter.Hybrid works with native deep linking:

// Configure in MauiProgram.cs
builder.Services.AddBlazouter(options =>
{
    options.EnableDeepLinking = true;
    options.DeepLinkScheme = "myapp://";
});

Then define routes that can be accessed via deep links:

new RouteConfig
{
    Path = "/product/:id",
    Component = typeof(ProductPage)
}
// Can be opened with: myapp://product/123

Performance Tips for Hybrid Apps

1. Use lazy loading for non-essential features
2. Minimize transitions on lower-end devices
3. Cache route data when appropriate
4. Implement route guards to prevent unnecessary loading
5. Optimize images and assets used in routes
6. Test on actual devices for real-world performance

Platform-Specific Considerations

Android

• Handle back button navigation
• Consider material design transitions
• Test on various screen sizes

iOS

• Respect safe areas
• Follow iOS Human Interface Guidelines
• Test swipe-back gestures

Windows

• Consider keyboard navigation
• Support window resizing
• Test with mouse and touch input

Target Frameworks

• .NET 9.0 (iOS, Android, macOS Catalyst, Windows)
• .NET 10.0 (iOS, Android, macOS Catalyst, Windows)

Example Application

See the MAUI sample application for a complete working example.

Documentation

• Main Documentation
• Core Features
• .NET MAUI Documentation

Migration from Shell Navigation

If you're migrating from .NET MAUI Shell navigation:

Before (Shell)

<Shell>
    <ShellContent Title="Home" Route="home" ContentTemplate="{DataTemplate pages:HomePage}" />
    <ShellContent Title="Settings" Route="settings" ContentTemplate="{DataTemplate pages:SettingsPage}" />
</Shell>

After (Blazouter)

private List<RouteConfig> _routes = new()
{
    new RouteConfig { Path = "/home", Component = typeof(HomePage), Title = "Home" },
    new RouteConfig { Path = "/settings", Component = typeof(SettingsPage), Title = "Settings" }
};

License

MIT License - see LICENSE for details.

Support

• GitHub Issues
• GitHub Discussions

Made with ❤️ for the Blazor community