DEV Community: Oleksandr Liakhevych

BlazorBindings.Maui v1.0

Oleksandr Liakhevych — Tue, 07 Mar 2023 22:33:16 +0000

This release is one of the biggest ones so far, and I have decided that BlazorBindings.Maui is stable enough for a 1.0 release! Take a look at Get Started page to check it out!

About this project
New controls supported
- SearchBar
- IndicatorView
- SwipeView
- TableView
- ListView
Behaviors
BlazorBindingsApplication
Root Wrapper
Error Boundaries
Entry is generic
Other changes
Breaking changes
What's next?

About this project

This project is a fork of MobileBlazorBindings - experimental project by Microsoft to allow to use Blazor syntax for native controls instead of XAML with MAUI. Here is a sample Counter component that renders native UI, which may look familiar to Blazor developers, that increments a value on each button press:

<StackLayout>
    <Label FontSize="30">You pressed @count times </Label>
    <Button Text="+1" OnClick="@HandleClick" />
</StackLayout>

@code {
    int count;

    void HandleClick()
    {
        count++;
    }
}

New controls supported

This update brings the support to five more controls. That alse means that all Maui built-in controls are supported now (however, not all the functionality is supported for some controls yet).
You can take a look at ControlGallery sample to find the examples of usage for those (and other) controls.

SearchBar

SearchBar is a user input control used to initiating a search.

<SearchBar @bind-Text="_searchQuery" @bind-Text:after="UpdateSearchResults" />
<CollectionView ItemsSource="_displayedItems" />

@code {
    string _searchQuery;
    string[] _displayedItems;

    async Task UpdateSearchResults()
    {
        _displayedItems = await /* retrieve items */;
    }
}

IndicatorView

IndicatorView is a control that displays indicators that represent the number of items, and current position, in a CarouselView.

<CarouselView IndicatorView="() => indicatorView">
    <ItemTemplate>
        ...
    </ItemTemplate>
</CarouselView>

<IndicatorView @ref="indicatorView"
               HorizontalOptions="LayoutOptions.Center"
               IndicatorColor="Colors.DarkGray"
               SelectedIndicatorColor="Colors.LightGray" />

@code {
    IndicatorView indicatorView;
}

SwipeView

SwipeView is a container control that wraps around an item of content, and provides context menu items that are revealed by a swipe gesture.

@foreach (var item in _items)
{
    <SwipeView>
        <RightItems>
            <SwipeItems>
                <SwipeItem BackgroundColor="Colors.Yellow"
                       Text="Favorite"
                       OnInvoked="() => MakeFavorite(item)" />

                <SwipeItem BackgroundColor="Colors.Red"
                       Text="Remove"
                       IsDestructive="true"
                       OnInvoked="() => Remove(item)" />
            </SwipeItems>
        </RightItems>

        <ChildContent>
            <ContentView BackgroundColor="Colors.Green" Padding="8">
                <Label>@item</Label>
            </ContentView>
        </ChildContent>
    </SwipeView>
}

TableView

TableView displays a table of scrollable items that can be grouped into sections. A TableView is typically used for displaying items where each row has a different appearance, such as presenting a table of settings.

    <TableView>
        <TableRoot>
            <TableSection Title="Cells examples">
                <TextCell Text="Click me" Detail="Tapping makes something happen." OnTapped="OnCellTapped" />
                <EntryCell Label="Enter your name:" @bind-Text="entryText" />
                <SwitchCell Text="Click to toggle:" @bind-On="switchOn" />
            </TableSection>
        </TableRoot>
    </TableView>

ListView

ListView displays a scrollable vertical list of selectable data items. While ListView manages the appearance of the list, the appearance of each item in the list is defined by a DataTemplate that uses a Cell to display items.

<ListView ItemsSource="items" SelectionMode="ListViewSelectionMode.None">
    <ItemTemplate>
        <ImageCell Text="@context.Name" Detail="@context.Type" ImageSource="@context.ImageUrl">
            <ContextActions>
                <MenuItem Text="Remove" IsDestructive="true" OnClick="() => RemoveItem(context)" />
            </ContextActions>
        </ImageCell>
    </ItemTemplate>
</ListView>

Behaviors

While Behaviors concept is a bit foreign with Blazor, it is an important part of the Maui ecosystem, therefore this update brings the support for Behaviors. While there are no Behavior components provided out of the box, you can create bindings for the behaviors that you need using component generator.
Here's the example for StatusBarBehavior from the MAUI Community Toolkit (you can take a look at the full sample here).

<ContentPage Title="CommunityToolkit.Behaviors">
    <Behaviors>
        <StatusBarBehavior StatusBarColor="Colors.Green" />
    </Behaviors>

    ...
</ContentPage>

BlazorBindingsApplication

Previously, you had to use MauiBlazorBindingsRenderer instance to add BlazorBindings component to your application. However, MauiBlazorBindingsRenderer is not recommended to be used from the application code, as it is a low level implementation detail.
This release brings an easy to use BlazorBindingsApplication type, which accept your root component type as a generic argument.

You can inherit your App type from BlazorBindingsApplication, if you need to customize the Application in any way:

public class App : BlazorBindingsApplication<AppShell>
    {
        public App(IServiceProvider services) : base(services)
        {
            // Do whatever you need (e.g. add resources).
        }
    }

Or you can use this type directly in simple cases:

builder.UseMauiApp<BlazorBindingsApplication<AppShell>>();

Root Wrapper

Generally, BlazorBindings' renderer creates separate render trees for each page - that includes MainPage and navigations (both regular and modals). However, in some cases it might be useful to have a component, which wraps any rendered subtree - e.g. to define global cascading parameters, or to update all the pages on some theme changed.

Now it is possible to do that via BlazorBindingsApplication's WrapperComponentType property.

For instance, here's an example of a wrapping component Root.razor, which adds a global cascading value, and updates the UI based on some event:

@inject AppState AppState

<CascadingValue Value="123" Name="test">
    @ChildContent
</CascadingValue>

@code {
    [Parameter] public RenderFragment ChildContent { get; set; }

    protected override void OnInitialized() 
    {
        AppState.ThemeChanged += InvokeAsync(() => StateHasChanged());
    }
}

Now, it is set as a wrapper component by overriding WrapperComponentType property:

public class App : BlazorBindingsApplication<AppShell>
{
    public App(IServiceProvider services) : base(services) { }

    public override Type WrapperComponentType => typeof(Root);
}

Error Boundaries

One of use cases for wrapper components is to allow to set a global error boundary. It allows to handle any exception, display a nice error page, and return back to the application (instead of simply crashing the application).

[!NOTE]
Error boundaries do not allow you to ignore exceptions based on some conditions, and leave the user on a current page. Error boundary content is always replaced with an error content if any exception occurs.

Here's an example of such wrapper component:

<ErrorBoundary @ref="_errorBoundary">
    <ChildContent>
        @ChildContent
    </ChildContent>

    <ErrorContent>
        <ContentPage Title="Error">
            <VerticalStackLayout Margin="8" Spacing="8">
                <Label Text="Oops!" HorizontalOptions="LayoutOptions.Center" FontSize="20" />
                <Label Text="Unexpected error has occured:" />
                <Label>@context.Message</Label>

                <Button Text="Return" OnClick="Recover" />
            </VerticalStackLayout>
        </ContentPage>
    </ErrorContent>

</ErrorBoundary>

@code {
    [Parameter] public RenderFragment ChildContent { get; set; }

    ErrorBoundary _errorBoundary;

    void Recover() {
        _errorBoundary.Recover();
    }
}

[!NOTE]
You'll need to create your ErrorBoundary type, implementing ErrorBoundaryBase. You can take a look here for an example.

Entry is generic

Entry component is generic now, which allows binding the value to non-string properties, like int or decimal.

<Label>Int entry: @_int</Label>
<Entry @bind-Text="_int" Keyboard="Keyboard.Numeric" />

@code{
    int _int;
}

[!NOTE]
While this change should not cause any troubles in most cases (since Blazor is able to infer generic argument from the @bind directive),
it still might cause compilation errors in some cases. You can add T="string" attribute value to resolve that.

Other changes

Component Generator adds XML documentation now.

Breaking changes

Due to some internal changes, components created via Component Generator have to be regenerated.
NativeControlComponentBase.ElementHandler is protected now.
Control components do not inherit ComponentBase anymore.
Default error page is removed. Application will crash in case of unhandled exceptions now.
MauiBlazorBindingsRenderer does not support rendering the component to non-Application parent.
Some methods, which are not stable yet, have [RequiresPreviewFeatures] attribute now.
Entry component is generic now (see above).

What's next?

Shell URL navigation improvements.
Supporting DataTemplateSelectors.
Supporting Maps controls, which were added in MAUI for .NET 7.
Improving the documentation.

BlazorBindings.Maui - Preview 10

Oleksandr Liakhevych — Fri, 18 Nov 2022 16:17:39 +0000

Another BlazorBindings.Maui update, which adds .NET 7 support, component generator and others improvements. Take a look at Get Started page to check it out!

About this project

<StackLayout>
    <Label FontSize="30">You pressed @count times </Label>
    <Button Text="+1" OnClick="@HandleClick" />
</StackLayout>

@code {
    int count;

    void HandleClick()
    {
        count++;
    }
}

Previous release notes

.NET 7 support

BlazorBindings.Maui is updated to use .NET 7. .NET 6 projects are not supported anymore.

Navigation improvements

Previously, the only supported way for navigation was URI-based Shell navigation. But it has its limitations:

It can be used with Shell-based applications only.
Cannot pass arbitrary parameters, only the ones based on URL path.
Hard to use with modal navigation.
Inconvenient in some cases.

In Preview 10 INavigation type is added, which allows you to perform regular navigation in addition to URI-based.

Note that you can use regular navigation for Shell-based applications as well.

For instance, let's say you have the following page component:
TargetPage.razor

<ContentPage Title="Target Page">
    <VerticalStackLayout>
        <Label>Hello, @UserName</Label>
    </VerticalStackLayout>
</ContentPage>

@code {
    [Parameter] public string UserName {get; set;} 
}

You can use the following code in your main page component to navigate to TargetPage:

@inject INavigation Navigation;

/* MainPage content */
<Button Text="Go to target page" OnClick="NavigateToTargetPage" />

@code {
    Task NavigateToTargetPage() => Navigation.PushAsync<TargetPage>(new()
    {
        [nameof(TargetPage.UserName)] = "Jayne Cobb"
    });
}

You can also perform modal navigation via PushModalAsync method:

@code {
    Task NavigateToTargetModalPage() => Navigation.PushModalAsync<TargetPage>(new()
    {
        [nameof(TargetPage.UserName)] = "Jayne Cobb"
    });
}

You can read more about navigation stack and modal navigation in MAUI here.

In addition to that, INavigation provides overloads, which accept RenderFragment argument. This allows to use a bit exotic, but easier to read syntax:

@code {
    Task NavigateViaRenderFragment() => Navigation.PushAsync(
        @<TargetPage UserName="Jayne Cobb" />);
}

This syntax is only available in .razor files, not in regular .cs files.

Shell properties

Previously, it was possible to set Shell attached properties to a certain Page via Blazor "unmatched" values (read here).

<ContentPage Title="Shell Properties"
             Shell.NavBarIsVisible="true"
             Shell.TabBarIsVisible="false"
             Shell.TitleColor="@Colors.Green">
...
</ContentPage>

However, this approach is quite limited and not user-friendly - not all properties are possible to set this way (e.g. TitleView), it misses IntelliSense or any compile-time validation, etc. Because of that, some mostly used attached properties are added to ContentPage component as regular properties:

<ContentPage Title="Shell Properties"
             NavBarIsVisible="true"
             TabBarIsVisible="false"
             TitleColor="@Colors.Green">
...
</ContentPage>

Component generator improvements

ComponentGenerator is updated to support generating DataTemplate and ElementTemplate properties (with RenderFragment type), generic properties and Brush properties. Most of the components in BlazorBindings.Maui are created using this generator, therefore it allowed to add some properties missed before.

Breaking changes

Generated components should be re-generated

Due to some internal changes, components created by component generated from previous version will probably not work. Simply re-generating them should be sufficient.

ShellNavigationManager is deprecated

Since INavigation contains all ShellNavigationManager functionality, INavigation should be used instead. ShellNavigationManager is deprecated and will be removed in the next version.

What next?

Getting closer to a stable release, it is planned to make final breaking changes, stabilize the API, improve the documentation and test coverage.
Generator improvements are planned as well, specifically to include properties documentation.
Supporting Maps controls, which were added in MAUI for .NET 7.

If you have any suggestions or ideas, you are welcome log issues!

BlazorBindings.Maui - Preview 9

Oleksandr Liakhevych — Fri, 23 Sep 2022 13:50:01 +0000

Another BlazorBindings.Maui update, which adds component generator, shadows, and other improvements. Take a look at Get Started page to check it out!

About this project

This project is a fork of MobileBlazorBindings - experimental project by Microsoft to allow to use Blazor syntax for native controls instead of XAML. Here is a sample Counter component that renders native UI, which may look familiar to Blazor developers, that increments a value on each button press:

<StackLayout>
    <Label FontSize="30">You pressed @count times </Label>
    <Button Text="+1" OnClick="@HandleClick" />
</StackLayout>

@code {
    int count;

    void HandleClick()
    {
        count++;
    }
}

Previous release notes

Component Generator

This release adds the ability to generate Blazor components for third party controls. Originally it was planned to implement it as a source generator, but, unfortunately, source generators don't play well with razor files. Therefore, generator is packed as a dotnet tool. In order to generate Blazor component for a control, you need to add an assembly attribute with control info, e.g.

[assembly: GenerateComponent(typeof(CommunityToolkit.Maui.Views.AvatarView))]

Then, you need to install and run generator tool in project folder:

dotnet tool install --global BlazorBindings.Maui.ComponentGenerator --version 0.9.2-preview

dotnet generate-maui-blazor-components

You take a look at a sample project with generated components for AlohaKit and CommunityToolkit libraries.

Keep in mind that it doesn't support some parameter types (like Shapes or Templates) so far.

Shadows

Shadows are supported with Blazor components now:

<Image Source=@("dotnet_bot.png")
       WidthRequest="250"
       HeightRequest="310">
    <Shadow>
        <Shadow Color="Colors.Black"
                Offset="new (20, 20)"
                Radius="50"
                Opacity="0.8f" />
    </Shadow>
</Image>

Gesture events

In order to add, for instance, tap event handler for some arbitrary control, you use Maui Gesture Recognizers. And that is already possible with Maui Blazor Bindings as well. However, the syntax is quite verbose, so this release adds events for the most used gestures directly to component (they are still implemented as gesture recognizers underneath):

<Frame OnTap="OnTap"
       OnDoubleTap="OnDoubleTap"
       OnPanUpdate="OnPanUpdate">

    <Label>@Item - @status</Label>
</Frame>

@code {
    [Parameter] public int Item { get; set; }

    string status = "Pending";

    void OnTap() => status = "Tapped";
    void OnDoubleTap() => status = "Double Tapped";

    async Task OnPanUpdate(PanUpdatedEventArgs args)
    {
        // ...
    }
}

Breaking changes

Significant internal changes

In Preview 9 element wrappers implementation is changed significantly in order to simplify it and to improve performance. Blazor components API is unchanged, so it won't affect most users. But if you have created any custom bindings (e.g. wrapping a third party control), they will probably not work with Preview 9. Hopefully, that woundn't be a huge issue thanks to a component generator.

TimePicker / DatePicker updates

TimePicker is updated to use recently-added TimeOnly type instead of TimeSpan, as this type is much more suitable to represent time of day. Same, DatePicker is updated to use DateOnly instead of DateTime.

What next?

Further ComponentGenerator improvements (#45).
Navigation service overhaul (#44).

If you have any suggestions or ideas, you are welcome log issues!