Blazorise OffcanvasProvider component

Usage

You need to place <OffcanvasProvider> somewhere in your application razor code. It can be placed anywhere, but a good approach is to place it in App.razor, or Routes.razor like in the following example.

An IOffcanvasService will be registered by Blazorise providing you with an API to programatically instantiate offcanvas panels. Examples are provided further below.

<Router AppAssembly="typeof(App).Assembly">
    <Found>...</Found>
    <NotFound>...</NotFound>
</Router>

<OffcanvasProvider />

The IOffcanvasService

The IOffcanvasService is an important feature that lets you control <OffcanvasProvider> instantiation. You are provided with various overloads of Show() to instantiate the <Offcanvas> to your liking. This will return a OffcanvasInstance that represents the <Offcanvas> you've instantiated with all of its configuration. You may also use the provided Hide() method to close offcanvas panels.

Options

You may provide options to <OffcanvasProvider> globally by setting them on the <OffcanvasProvider> component itself.

<Router AppAssembly="typeof(App).Assembly">
    <Found>...</Found>
    <NotFound>...</NotFound>
</Router>

<OffcanvasProvider UseOffcanvasStructure Animated Placement="Placement.Start" />

Optionally you can override these when instantiating an offcanvas through the OffcanvasService usage.

<Button Color="Color.Primary" Clicked="InstantiateOffcanvas">Override Options Example</Button>

@code {
    [Inject] public IOffcanvasService OffcanvasService { get; set; }

    public Task InstantiateOffcanvas()
    {
        return OffcanvasService.Show<CustomStructureOffcanvasExample>( "Override Options Example", new OffcanvasInstanceOptions()
        {
            Animated = false,
            UseOffcanvasStructure = false,
            Placement = Placement.Top
        } );
    }
}

Closing Panels

<OffcanvasProvider> will only keep track of the offcanvas panels that have been instantiated by itself.

To close an Offcanvas:

You can use Blazorise's <CloseButton> component, which automatically knows how to close the currently opened <Offcanvas> when placed inside of it.
Use the provided IOffcanvasService and call IOffcanvasService.Hide(), this will close the last opened <Offcanvas> tracked by the <OffcanvasProvider>.
You may keep track of the OffcanvasInstance and call IOffcanvasService.Hide(offcanvasInstance), this will close the provided instance.
You may keep track of the OffcanvasInstance and call offcanvasInstance.OffcanvasRef.Hide().

Stateful Panels

<OffcanvasProvider> can keep the state of the offcanvas even after they have been closed.

To do this you will need to:

Set Stateful to true in the OffcanvasProvider or in the OffcanvasInstanceOptions. The reason why you need to explicitly opt-in for this feature is because the instances you open will be kept in memory, and you should be mindful that you need to properly manage these.
Provide a unique Id so the instance can be tracked and reopen. This can be set in OffcanvasInstanceOptions.ElementId. Optionally you may keep track of the OffcanvasInstance returned by the IOffcanvasService.Show() method to reopen the same instance.

Custom Component

Instantiates an offcanvas with a counter example taking in the counter number from the provided parameter. OffcanvasService.Show provides various overloads you can use to instantiate your custom content.

<Button Color="Color.Primary" Clicked="ShowCounter">Show Counter</Button>

@code {
    [Inject] public IOffcanvasService OffcanvasService { get; set; }

    public Task ShowCounter()
    {
        Random random = new();
        var newValue = random.NextInt64( 100 );
        return OffcanvasService.Show<CounterExample>( "My Custom Content!", x => x.Add( x => x.Value, newValue ) );
    }
}

Render Fragment

<Button Color="Color.Primary" Clicked="ShowRenderFragment">Show Custom Structure</Button>

@code {
    [Inject] public IOffcanvasService OffcanvasService { get; set; }

    private RenderFragment customFragment => __builder =>
    {
        <Paragraph>This content is provided by a custom RenderFragment</Paragraph>
    };

    public Task ShowRenderFragment()
    {
        return OffcanvasService.Show( "My Custom RenderFragment!", customFragment );
    }
}

Predefined SizeNew

Use OffcanvasInstanceOptions.Size to apply one of the predefined offcanvas sizes when opening an instance through the service.

Service calls create new offcanvas instances, so varying Placement and Size between openings is supported through the service.

<Div Margin="Margin.Is3.FromBottom">
    <Button Color="Color.Primary" Margin="Margin.Is2.FromEnd" Clicked="@(() => ShowOffcanvas( Placement.End, OffcanvasSize.Small ))">Small End</Button>
    <Button Color="Color.Primary" Margin="Margin.Is2.FromEnd" Clicked="@(() => ShowOffcanvas( Placement.End, OffcanvasSize.Large ))">Large End</Button>
    <Button Color="Color.Primary" Margin="Margin.Is2.FromEnd" Clicked="@(() => ShowOffcanvas( Placement.End, OffcanvasSize.ExtraLarge ))">Extra Large End</Button>
    <Button Color="Color.Primary" Margin="Margin.Is2.FromEnd" Clicked="@(() => ShowOffcanvas( Placement.End, OffcanvasSize.Fullscreen ))">Fullscreen End</Button>
</Div>
<Div>
    <Button Color="Color.Secondary" Margin="Margin.Is2.FromEnd" Clicked="@(() => ShowOffcanvas( Placement.Top, OffcanvasSize.Small ))">Small Top</Button>
    <Button Color="Color.Secondary" Margin="Margin.Is2.FromEnd" Clicked="@(() => ShowOffcanvas( Placement.Top, OffcanvasSize.Large ))">Large Top</Button>
    <Button Color="Color.Secondary" Margin="Margin.Is2.FromEnd" Clicked="@(() => ShowOffcanvas( Placement.Top, OffcanvasSize.ExtraLarge ))">Extra Large Top</Button>
    <Button Color="Color.Secondary" Clicked="@(() => ShowOffcanvas( Placement.Top, OffcanvasSize.Fullscreen ))">Fullscreen Top</Button>
</Div>

@code {
    [Inject] public IOffcanvasService OffcanvasService { get; set; }

    private Task ShowOffcanvas( Placement placement, OffcanvasSize size )
    {
        RenderFragment content = builder =>
        {
            builder.AddContent( 0, $"Placement {placement} with size {size}." );
        };

        return OffcanvasService.Show(
            $"{size} {placement} Offcanvas",
            content,
            new OffcanvasInstanceOptions()
            {
                Placement = placement,
                Size = size
            } );
    }
}

Custom Structure

If you want to customize the offcanvas structure, you can do so, by setting UseOffcanvasStructure to false and providing the structure inside the custom content you are instantiating. You may do this by providing your custom html or by using the internal Offcanvas components.

<OffcanvasHeader>
<OffcanvasBody>
<OffcanvasFooter>

User Name

<Field Horizontal>
    <FieldLabel ColumnSize="ColumnSize.IsFull.OnTablet.Is2.OnDesktop">User Name</FieldLabel>
    <FieldBody ColumnSize="ColumnSize.IsFull.OnTablet.Is10.OnDesktop">
        <TextInput @bind-Value="userName"></TextInput>
    </FieldBody>
</Field>

<Button Color="Color.Primary" Clicked="ShowCustomStructure">Show Custom Structure</Button>

@code {
    [Inject] public IOffcanvasService OffcanvasService { get; set; }
    private string userName = "John Doe";

    public Task ShowCustomStructure()
    {
        return OffcanvasService.Show<CustomStructureOffcanvasExample>(
            parameters => parameters.Add( x => x.UserName, userName ),
            new OffcanvasInstanceOptions() { UseOffcanvasStructure = false } );
    }
}

Interaction

Since you can pass in parameters into your component, you can take advantage of this to interact with your <Offcanvas>. A common example, might be a generic formulary where the validation and success logic are not necessarily known by this component and are provided from "outside". The following example setups a simple formulary showcasing this.

<Paragraph>
    @formularyMessage
</Paragraph>
<Button Color="Color.Primary" Clicked="ShowFormulary">Show</Button>

@code {
    [Inject] public IOffcanvasService OffcanvasService { get; set; }

    private string formularyMessage = string.Empty;

    public Task ShowFormulary()
    {
        formularyMessage = string.Empty;
        return OffcanvasService.Show<FormularyOffcanvasExample>( x =>
        {
            x.Add( x => x.OnValidate, FormularyValidate );
            x.Add( x => x.OnSuccess, FormularySuccess );
        },
        new OffcanvasInstanceOptions()
            {
                UseOffcanvasStructure = false
            } );
    }

    private Task<bool> FormularyValidate( Employee employee )
        => Task.FromResult( !string.IsNullOrWhiteSpace( employee.FirstName ) && !string.IsNullOrWhiteSpace( employee.Email ) );

    private Task FormularySuccess( Employee employee )
    {
        formularyMessage = $"Employee : {employee.FirstName} saved successfully!";
        return InvokeAsync( StateHasChanged );
    }
}

Stateful Offcanvas

<Button Color="Color.Primary" Clicked="ShowStateful">Show Stateful</Button>

@code {
    [Inject] public IOffcanvasService OffcanvasService { get; set; }

    public Task ShowStateful()
    {
        return OffcanvasService.Show<CounterExample>( "My Stateful content", new OffcanvasInstanceOptions()
        {
            Stateful = true,
            ElementId = "StatefulOffcanvas",
            Placement = Placement.Start
        } );
    }
}