Blax 1.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Blax --version 1.0.0                
NuGet\Install-Package Blax -Version 1.0.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Blax" Version="1.0.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Blax --version 1.0.0                
#r "nuget: Blax, 1.0.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Blax as a Cake Addin
#addin nuget:?package=Blax&version=1.0.0

// Install Blax as a Cake Tool
#tool nuget:?package=Blax&version=1.0.0                

Blax State Management Library for Blazor

Introduction

Blax is a robust and flexible state management library designed specifically for Blazor applications. It provides a simple yet powerful way to manage state across components, allowing you to build reactive and maintainable UIs. With Blax, you can manage state without the boilerplate, making your Blazor apps even more awesome!

Features

  • Reactive Observables: Keep your UI in sync with the state automatically.
  • Attributes-based State: Decorate your properties with [Observable] to make them easily observable.
  • Type-safe API: Use a straightforward and type-safe API to manage state.
  • Easy to Use: A simple API that feels native to C# and Blazor.
  • Minimal Code: Minimal code to get started.

Installation

Install the package via NuGet Package Manager:

Install-Package Blax

Or via the .NET CLI:

dotnet add package Blax

Quick Start

Create a State Class

Create a class that derives from PackageProjectUrl to represent your state, and decorate any properties you want to observe with the [Observable] attribute.

using Blax;

public class MyState : PackageProjectUrl
{
    [Observable]
    public virtual int Counter { get; set; }
}

Note: Any property decorated with the [Observable] attribute must be virtual

Instantiate State in Program.cs/Startup.cs

Instantiate your state class in the Program.cs or Startup.cs and provide it to your components.

public class Program
{
    public static async Task Main(string[] args)
    {
        var builder = WebAssemblyHostBuilder.CreateDefault(args);
        builder.RootComponents.Add<App>("#app");

        // Use the CreateInstance method provided by the ObservableState class as shown below
        builder.Services.AddScoped(sp => ObservableState.CreateInstance<MyState>());

        await builder.Build().RunAsync();
    }
}

Use the State in a Razor Component

Inject the state into your component and use it directly in your methods and UI.

To ensure that components re-render when the state changes, wrap them with an Observer element.

The State attribute should be set to the state instance you wish to observe.

@inject MyState myState

<Observer State="myState"
    <button @onclick="Increment">Increment</button>
    <p>@State.Counter</p>
</Observer>

@code {
    private void Increment()
    {
        State.Counter++;
    }
}

API Reference

Observable Attribute

Use the [Observable] attribute to make a property observable:

[Observable]
public virtual int MyProperty { get; set; }

Note: Any property decorated with the [Observable] attribute must be virtual

Observable Lists and Dictionaries

Blax also includes ObservableList<T> and ObservableDictionary<TKey, TValue> for your collections.

[Observable]
public virtual ObservableList<string> MyList { get; set; }

[Observable]
public virtual ObservableDictionary<int, string> MyDict { get; set; }

Examples

Counter Example

// AppState.cs
public class AppState : ObservableState
{
    [Observable]
    public virtual int Counter { get; set; }
}

// CounterComponent.razor
@inject AppState appState

<Observer State="appState">
    <button @onclick="Increment">Increment</button>
    <p>@appState.Counter</p>
</Observer>

@code {
    private void Increment()
    {
        appState.Counter++;
    }
}

Todo List Example

AppState.cs

// AppState.cs
using Blax;

public class AppState : ObservableState
{
    [Observable]
    public virtual ObservableList<string> Todos { get; set; } = new();
}

Program.cs or Startup.cs

// Program.cs
// Add a scoped instance of our state
builder.Services.AddScoped(sp => ObservableState.CreateInstance<AppState>());

// or Startup.cs
services.AddScoped(sp => ObservableState.CreateInstance<AppState>());

Index.razor

// Index.razor
@page "/"
@using Blax
@using Example.Components
@using Example.States;

@inject AppState appState


<input @bind="newTodo" />
<button @onclick="AddTodo">Add</button>

<TodoDrawer />

@code {
    string newTodo = string.Empty;

    private void AddTodo()
    {
        if (!string.IsNullOrEmpty(newTodo))
        {
            appState.Todos.Add(newTodo);
            newTodo = string.Empty;
        }
    }
}

TodoDrawer.razor

// TodoDrawer.razor
@using Blax
@using Example.States;
@inject AppState appState

<h3>TodoDrawer</h3>

@* Note: Try removing the Observer and leave just the foreach loop. You will notice that the newly-created todos are not displayed, because the page no longer updates automatically. *@

<Observer State="appState">
    @foreach (var todo in appState.Todos)
    {
        <p>@todo</p>
    }
</Observer>

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

Blax is licensed under the MIT license. See LICENSE for details.

Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.1 147 9/29/2023
1.0.0 123 9/29/2023

Initial Release