DEV Community: Chris Sainty

Building a simple tooltip component for Blazor in under 10 lines of code*

Chris Sainty — Tue, 06 Oct 2020 14:32:27 +0000

It has been so long since I've managed to get some time to write a blog post. Since my last post, I've been working hard writing the first few chapters for my book, Blazor in Action – which should be out on MEAP (Manning Early Access Program) very very soon. My wife and I also had our first child at the start of September which has been an amazing and interesting new challenge to take on. I'm loving every minute so far but I'm sooo thankful for my coffee machine!!

Anyway, back to the subject in hand, in this post I'm going to be showing you how you can build a really simple, reusable, tooltip component for your Blazor applications. I've used a bit of artistic license with the title of this post, while it's less than 10 lines of Razor, that doesn't include the CSS. But as the CSS will be minified at some point I don't think it should count.... Anyway, moving on.

If you're just interested in the result, then you can check out the GitHub repo which has the final working version of the code in this post. I also want to point out that I've used the .NET5 preview bits to build this so you will need those installed to run the sample.

Creating the Tooltip component

The first thing we're going to do is create a new component called Tooltip.razor and add the following code:

<div class="tooltip-wrapper">
    <span>@Text</span>
    @ChildContent
</div>

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

The component has two parameters, ChildContent and Text. When we use the component, it's going to wrap the markup where we want the tooltip to display. The wrapped markup will be captured by the ChildContent parameter and displayed inside the main div of our tooltip. The other parameter Text, is what we will use to set the text that the tooltip will display.

That's all there is in terms of Razor code! Not bad, 9 lines including a space. The real magic to making this all work is in the CSS. I'm using the new .NET5 RC1 bits and with that I can take advantage of Blazor's new CSS isolation feature.

Adding the CSS

To use CSS isolation in Blazor we need to create a CSS file with the same name as the component the styles are used by. In our case the component is called, Tooltip.razor. So our stylesheet needs to be called Tooltip.razor.css. Once this is done we can add the following styles:

.tooltip-wrapper {
    position: relative;
    display: inline-block;
    border-bottom: 1px dotted black;
    cursor: help;
}

span {
    visibility: hidden;
    position: absolute;
    width: 120px;
    bottom: 100%;
    left: 50%;
    margin-left: -60px;
    background-color: #363636;
    color: #fff;
    text-align: center;
    padding: 5px 0;
    border-radius: 6px;
    z-index: 1;
}

span::after {
    content: "";
    position: absolute;
    top: 100%;
    left: 50%;
    margin-left: -5px;
    border-width: 5px;
    border-style: solid;
    border-color: #555 transparent transparent transparent;
}

.tooltip-wrapper:hover span {
    visibility: visible;
}

The first class, .tooltip-wrapper is applied to the container div of the component. It makes the div render as inline-block so the document flow isn't disrupted. It also sets it's position as relative. This means we can then absolute position the child span (tooltip text) where we need, relative to the parent div. The final two rules add some styling to show the user there is a tooltip available.

The next set of styles apply to the span element, this contains the tooltip text that will be shown. By default, the span is hidden and it's absolutely positioned relative to the parent div. With the styles shown above, the tooltip will be shown above the content which is contained between the start and end tags of the Tooltip component.

The next style is what is called a pseudo element. This is going to add an element to the DOM. What this style does is create a small arrow at the bottom of the tooltip text pointing to the content that the tooltip is wrapping.

The final style will show the span containing the tooltip text whenever the user hovers over the parent div with their cursor.

That's all there is to it!

Using the Tooltip

In order to use the tooltip, just wrap it around the content you want the user to be able to hover over to show the tooltip text, and add whatever message you want to be displayed. If all goes well it should look something like this...

Summary

Just to recap, in this post I showed you how you can create a simple reusable tooltip component for your Blazor application. The whole component was only 9 lines of Razor code, require no JavaScript, and about 36 lines of CSS. We also had a chance to use the new CSS isolation feature which will be shipping in .NET 5 which is right around the corner.

This was a much shorter post than I normally write but it's just nice to actually write a blog post again! I hope to be announcing the MEAP for Blazor in Action any day now so as soon as that is available I will have a blog post up about it and how you can get your hands on it.

Creating a Custom Validation Message Component for Blazor Forms

Chris Sainty — Tue, 30 Jun 2020 08:14:07 +0000

As some of you may know, I'm a big fan of Tailwind CSS. If you've not heard of Tailwind before then please checkout my previous posts about it which can be found here and here. The reason I mention this is because when I was using it on a recent Blazor project, I hit a bit of a snag. I wanted to style my validation messages using Tailwinds utility classes, but I couldn't add them to the component. This is because the ValidationMessage component adds a hard-coded class which can't be added to or overriden.

builder.OpenElement(0, "div");
builder.AddMultipleAttributes(1, AdditionalAttributes);
builder.AddAttribute(2, "class", "validation-message");
builder.AddContent(3, message);
builder.CloseElement();

The full source can be viewed here, but as you can see in the snippet above, while the component supports passing additional attributes, the component will always override any class attribute that is supplied.

I could've added a wrapper div around each usage of ValidationMessage and added my classes there, but that felt like a clunky solution. I've also seen several people in the community asking about customising the output of the ValidationSummary component. So I thought this would be a good opportunity to come up with a better way.

In this post, I'm going to show how you can create a ValidationMessage component with customisable UI. I'll start by showing a more simplistic approach and then show a more robust and reusable solution.

How does ValidationMessage work?

Before we get into the solutions, I wanted to quickly cover how the standard ValidationMessage works.

The default component is pretty compact weighing in at about 100 lines of code. It accepts a cascaded EditContext and adds an event handler for the OnValidationStateChanged event. All this handler does is call StateHasChanged whenever the event fires.

It also creates a FieldIdentifier based on whichever model property has been specified via the For parameter. This is then used when calling the GetValidationMessages method on the EditContext. This method will return all of the current validation error messages for the given FieldIdentifier. Any messages returned are then rendered.

In summary, the componet does three things:

Listens for changes to the validation state
Retrieves any validation messages for the model property specified
Displays the messages on screen

Now we understand what the original component does, let's move on to the solutions.

Creating a simple replacement

The first option, which was pretty quick to build, was largly a modified version of the original component.

The default component caters for a lot of potential scenarios, things like dynamically changing EditContext's or updates to the For parameter. Therefore there's a lot of code which is checking and caching values to support this and be as efficient as possible.

However, my use case was very straightforward, just a standard form which wouldn't have anything dynamically changing. This mean't that I could do away with a good amount of code. The result is the following.

@using System.Linq.Expressions

@typeparam TValue
@implements IDisposable

@foreach (var message in EditContext.GetValidationMessages(_fieldIdentifier))
{
    <div class="@Class">
        @message
    </div>
}

@code {
    [CascadingParameter] private EditContext EditContext { get; set; }

    [Parameter] public Expression<Func<TValue>> For { get; set; }
    [Parameter] public string Class { get; set; }

    private FieldIdentifier _fieldIdentifier;

    protected override void OnInitialized()
    {
        _fieldIdentifier = FieldIdentifier.Create(For);
        EditContext.OnValidationStateChanged += HandleValidationStateChanged;
    }

    private void HandleValidationStateChanged(object o, ValidationStateChangedEventArgs args) => StateHasChanged();

    public void Dispose()
    {
        EditContext.OnValidationStateChanged -= HandleValidationStateChanged;
    }
}

I implemented the same fundamental behavor as the original component, I created a FieldIdentifier based on the model property defined via the For parameter. Registered a handler for the OnValidationStateChanged event on EdiContext. I also unregistered it to avoid any memory leaks by implementing IDisposable.

In my markup, I then output any validation messages as per the original component, but with one simple difference. I removed the hard-coded CSS applied and added a Class parameter. Now I could provide any classes I wanted to apply on a case by case basis. Here's an example of usage.

<CustomValidationMessage For="@(() => _model.FirstName)"
                         Class="mt-2 sm:ml-4 font-semibold text-red-600" />

This implementation resolved the original issue, I could now use my Tailwind CSS classes to style my validation messages without any issues. Job done, right?

For my immediate problem, yes. But it got me thinking about some of those comments from the community I mentioned in the introduction. In those comments, developers were asking about changing the HTML that was rendered, not just adding custom CSS classes. This solution doesn't help with that problem. This lead me to create my second solution.

ValidationMessageBase for ultimate customisation

I really love the approach the Blazor team took with building the input components for forms. Providing us with InputBase<T> is great as we can focus on building custom UI, which is what needs to be changed in 99% of cases, while the boilerplate of integrating with the form and validation system is taken care of.

Wouldn't it be great if there was something like that for validation messages as well...?

Creating ValidationMessageBase

By creating a base class for validation messages, as per the design of the input components, it would give developers the freedom to tweak the UI output to their exact needs. Here's the code.

public class ValidationMessageBase<TValue> : ComponentBase, IDisposable
{
    private FieldIdentifier _fieldIdentifier;

    [CascadingParameter] private EditContext EditContext { get; set; }
    [Parameter] public Expression<Func<TValue>> For { get; set; }
    [Parameter] public string Class { get; set; }

    protected IEnumerable<string> ValidationMessages => EditContext.GetValidationMessages(_fieldIdentifier);

    protected override void OnInitialized()
    {
        _fieldIdentifier = FieldIdentifier.Create(For);
        EditContext.OnValidationStateChanged += HandleValidationStateChanged;
    }

    private void HandleValidationStateChanged(object o, ValidationStateChangedEventArgs args) => StateHasChanged();

    public void Dispose()
    {
        EditContext.OnValidationStateChanged -= HandleValidationStateChanged;
    }
}

This is essentially the logic from the code block in the first solution, except I've added a property which returns the current validation messages instead of calling the GetValidationMessages method directly on the EditContext. This is purely to make the developer experience a little nicer when implementing markup for the validation messages.

With this base class I can implement the same markup as I had for the first solutions really easily.

@typeparam TValue
@inherits ValidationMessageBase<TValue>

@foreach (var message in ValidationMessages)
{
    <div class="@Class">
        @message
    </div>
}

And if I want to implement something different in a future project all I need to do is create a new derived component.

@typeparam TValue
@inherits ValidationMessageBase<TValue>

@if (ValidationMessages.Any())
{
    <ul class="validation-errors">
        @foreach (var message in ValidationMessages)
        {
            <li class="validation-error-message">
                @message
            </li>
        }
    </ul>
}

Summary

In this post, I've show a limitation with the default ValidationMessage component which comes with Blazor, specifically, the inability to customise the markup it produces. I've shown two potential solutions.

The first is a modified version of the original component. The hard-coded styling was removed and replaced with a Class parameter allowing CSS classes to be specified per usage.

The second solution was based on the design of Blazors input components. A base class was used to abstract away the boilerplate code, allowing developers to focus on creating the specific markup they require, for ultimate flexability.

Avoiding AccessTokenNotAvailableException when using the Blazor WebAssembly Hosted template with individual user accounts

Chris Sainty — Tue, 09 Jun 2020 08:00:00 +0000

Blazor WebAssembly has shipped with a host of new options for authentication. We now have the ability to create Blazor Wasm apps which can authenticate against Active Directory, Azure AD, Azure AD B2C, Identity Server, in fact any OIDC provider should work with Blazor. But, there is a little gotcha which has tripped a few people up when building applications which mix protected and unprotected endpoints using the Blazor WebAssembly ASP.NET Core Hosted template with Individual user accounts enabled.

The default configuration in the template uses an HTTP client with a custom message handler called BaseAddressAuthorizationMessageHandler. This handler attempts to attach an access token to any outgoing requests and if it can't find one, it throws an exception.

This makes sense if you're only calling protected endpoints, but if your application allows the user to call unprotected endpoints without logging in then you might see a AccessTokenNotAvailableException in the browser console.

In this post, I'm going to show you how to configure an additional HttpClient instance which can be used by unauthenticated users to call unprotected endpoints, avoiding an AccessTokenNotAvailableException.

Default Configuration

When you create a new Blazor WebAssembly application using ASP.NET Core Identity, you'll find the following configuration in the Program.Main method.

builder.Services.AddHttpClient("BlazorApp.ServerAPI", client => client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress))
                .AddHttpMessageHandler<BaseAddressAuthorizationMessageHandler>();

This sets up the HttpClient for the application using a custom handler, BaseAddressAuthorizationMessageHandler. This handler is really useful as it saves us having to worry about adding access tokens to our API requests manually. However, as I explained in the introduction, this is also a potential issue.

If we delve into the source code, we can see that the BaseAddressAuthorizationMessageHandler inherits from another class called AuthorizationMessageHandler, this is the class where we find the potential gotcha.

var tokenResult = _tokenOptions != null ?
                        await _provider.RequestAccessToken(_tokenOptions) :
                        await _provider.RequestAccessToken();

if (tokenResult.TryGetToken(out var token))
{
    _lastToken = token;
    _cachedHeader = new AuthenticationHeaderValue("Bearer", _lastToken.Value);
}
else
{
    throw new AccessTokenNotAvailableException(_navigation, tokenResult, _tokenOptions?.Scopes);
}

The piece of code above is looking for a token so it can add it to the authentication header of the outgoing request. And as you can see, if one isn't found then an exception is thrown, AccessTokenNotAvailableExcpetion.

The default template configuration actually gives us a hint of this potential issue on the FetchData component.

protected override async Task OnInitializedAsync()
{
    try
    {
        forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");
    }
    catch (AccessTokenNotAvailableException exception)
    {
        exception.Redirect();
    }
}

There is a try..catch setup to specifically check for this exception and redirect the user to login.

Now we can see where the problem comes from, what's the solution?

Configuring a second HttpClient for unauthenticated requests

The answer is to add a second HTTP Client instance which doesn't use this message handler. We can then use this instance when we want to make unprotected requests, and use the original one for everything else.

The easiest way we can achieve this is by adding the following line to our Program.Main.

builder.Services.AddHttpClient("BlazorApp.PublicServerAPI", client => client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress));

This will add another named HTTP Client instance to our application but, as you can see, there is no special message handler added this time.

Once this is done, we can get an instance of this client by injecting IHttpClientFactory into our component or service and using the Create method with the name of the client.

@inject IHttpClientFactory HttpClientFactory

...

@code {
    private async Task GetSomethingFromAPI()
    {
        var client = HttpClientFactory.Create("BlazorApp.PublicServerAPI");
        var result = client.GetFromJsonAsync<Something>("/api/something");
    }
}

Another option, which in my opinion is a bit nicer as I'm not a fan of magic strings, is to create a typed client. This means we can request an instance by type rather than use the magic string solution.

To do this we first need to add a new class, we'll call it PublicClient and add the following code.

public class PublicClient
{
    public HttpClient Client { get; }

    public PublicClient(HttpClient httpClient)
    {
        Client = httpClient;
    }
}

This code is quite straightforward, we're just accepting a instance of HttpClient through DI and saving it off to the Client property.

Then in Program.Main we add the following code.

builder.Services.AddHttpClient<PublicClient>(client => client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress));

This is going to inject an HttpClient instance, configured with the base address we've specified, into our PublicClient class. It will also add our PublicClient class into the DI container so we can request an instance of it with the preconfigured HttpClient.

We can then use it like this.

@inject PublicClient PublicClient

...

@code {
    private async Task GetSomethingFromAPI()
    {
        var result = PublicClient.Client.GetFromJsonAsync<Something>("/api/something");
    }
}

I think this is a much cleaner way to do things, it's saved us a line of code in our component and it's more obvious at a glance the type of client we are using. Using this approach also allows us to abstract the underlying HttpClient entirely, if we wish. We can write methods on the PublicClient so we never expose the HttpClient to calling code.

public class PublicClient
{
    private HttpClient _client

    public PublicClient(HttpClient httpClient)
    {
        _client = httpClient;
    }

    public async Task<SomeThing> GetSomething()
    {
        var result = await _client.GetFromJsonAsync<SomeThing>("/api/something");
        return result;
    }
}

@inject PublicClient PublicClient

...

@code {
    private async Task GetSomethingFromAPI()
    {
        var result = PublicClient.GetSomething();
    }
}

This code is now really succinct, we've also centralised all our API calling code which should make any future maintenance simpler.

Summary

In this post we've explored a potential issue with unauthenticated users calling unprotected endpoints using the default HttpClient that comes with the Blazor WebAssembly auth templates. We've investigated Blazors source to understand where this comes from and then we've applied a solution which was to add a second HttpClient instance.

Once we had this working we also looked at a different implementation of the solution which made our code a bit simpler and easier to understand, as well as potentially making API calling code easier to maintain in the long run.

Auto Saving Form Data in Blazor

Chris Sainty — Tue, 05 May 2020 08:00:00 +0000

I got tagged in a thread on Twitter last week by Mr Rockford Lhotka. I've embedded the thread below so you can read it for yourself, but essentially he was voicing his frustration at losing data when an error/timeout/server error/etc occur in web applications.

I hate the web. I've hated the web forever. Type in a thoughtful bit of content, click save, get some server/gateway timeout, lose your content. You'd think we've have this solved, but no. 1995-present this is a problem. f-cking web.

— Rockford Lhotka (@RockyLhotka) April 29, 2020

Now, this type of situation very much depends on the application and how it's been developed, but, none the less, I agree. There is nothing worse than spending ages filling in a form and then for something to blow up and lose everything you've entered.

He and Dan Wahlin were discussing the idea of a form auto saving data so it could be recovered if something went wrong with the application. I got tagged by Rockford suggesting it would be a great addition to Blazored – Challenge accepted! 😃

Speaking of which - a good thing for @chris_sainty to add to his blazord project? 😁😁😁

— Rockford Lhotka (@RockyLhotka) April 29, 2020

In this post, I'm going to show you a solution I've come up with for auto saving and rehydrating form data in Blazor. I'm going to start by outlining the goals and boundaries I set for this project. Then I'm going to tell you about some options I decided not to go with and why I didn't pursue them. Then I'll get into the meat of things and step through the solution I developed. I'll show how I satisfied each goal set out at the start. Then I'll finish by showing you how using the solution compares to the existing EditForm experience.

I want to be clear this is by no means a bullet proof, cover all bases solution. It's more an MVP to be built on. I'm hoping to release this as a new package under Blazored after a bit more development and refinement. If you want to help out with that then I've included a link to the new repo at the end of the post.

Defining the Goals

To give myself some focus and boundaries I made a list of four things that needed to be achieved in order for this to be considered useful.

Save data to local storage when it's entered into each form controls
Rehydrate data from local storage when the user returns to the page
Clear saved data from local storage when it's successfully submitted by the form
Try to keep things as close to the current experience with EditForm as possible for developers

There were also some things that I wanted to rule out for now.

Only persist to local storage
Don't worry about complex forms with nested complex objects

Now I had a defined scope for the work, I could start playing around with some ideas and see what I could come up with.

The Cutting Room Floor

As you would expect, I went though many failed ideas before I settled on a solution I was happy with. I thought it might be interesting to briefly highlight what they were and why I didn't pursue them.

First attempt

I started with the idea of creating a new component which could be nested inside an EditForm, similar to the DataAnnotationValidator. I quickly got something in-place which used the cascaded EditContext, provided by EditForm, to hook into the OnFieldChanged event. From here I could intercept model updates and persist the model to local storage.

The problem came when trying to rehydrate the form. Due to where my component sat in the component tree, the UI wasn't updating to show the values in the textboxes. I needed a StateHasChanged call higher in the tree and I just couldn't get that to work in a nice way.

I also would need to know when the form had been submitted so I could achieve number 3 on my goals list, clearing the saved values on a successful form post. There was no way I could reliably do that using the EditContext alone.

Second attempt

After some hacking about I came to the conclusion that the best option was going to be a new form component, replacing EditForm. I wanted to save duplicating all of the code from EditForm and just inherit from it. I could then add some additional functionality to save and load the form values.

Unfortunately, that was a short lived hope. I needed access to some members which were private. I got round that with some reflection foo, but the show stopper was needing to add some additional logic in the HandleSubmitAsync method, there was no way to hack this.

Conclusion

In the end, I concluded that I would need to duplicate the EditForm component and use it as a starting point for my new form component. It wasn't the end of the world, after my experimenting I was happy with the fact I had to change the behaviour of the original component enough that just extending it wasn't going to work.

With this decision made I then moved on to what became the solution I ended up with.

Building the AutoSaveEditForm Component

The starting point for the new component was the existing EditForm component produced by the Blazor team. If you want to see this in its unaltered state you can find it here. Let's go through each of the changes I made and why.

Integrating with Local Storage

The first thing I did was to add the functionality to persist and retrieve the form to and from local storage. This required injecting IJSRuntime into the component and then adding the following two methods.

private async void SaveToLocalStorage(object sender, FieldChangedEventArgs args)
{
    var model = Model ?? _fixedEditContext.Model;
    var serializedData = JsonSerializer.Serialize(model);
    await _jsRuntime.InvokeVoidAsync("localStorage.setItem", Id, serializedData);
}

private async Task<object> LoadFromLocalStorage()
{
    var serialisedData = await _jsRuntime.InvokeAsync<string>("localStorage.getItem", Id);
    if (serialisedData == null) return null;
    var modelType = EditContext?.Model.GetType() ?? Model.GetType();

    return JsonSerializer.Deserialize(serialisedData, modelType);
}

Both of these methods do exactly what they say on the tin. SaveToLocalStorage persists the current form model and LoadFromLocalStorage retrieves the form model.

In order to identify a particular form, I added an Id parameter to the component which you can see used in the code above. It's worth pointing out that this is definitely something which will need to be improved before the component could be used in a real app – this method won't be enough to guarantee uniqueness across an application.

Hooking into Field Changes

With the local storage interfaces in place I moved on to saving the form when fields were updated. This required making some changes to the existing OnParametersSet method. There's an if statement at the end of the original method which looks like this.

if (_fixedEditContext == null || EditContext != null || Model != _fixedEditContext.Model)
{
    _fixedEditContext = EditContext ?? new EditContext(Model);
}

I updated it to this.

if (_fixedEditContext == null || EditContext != null || Model != _fixedEditContext.Model)
{
    _fixedEditContext = EditContext ?? new EditContext(Model);
    _fixedEditContext.OnFieldChanged += SaveToLocalStorage;
}

I added an extra line which registers a handler for the EditContexts OnFieldChanged event. Now, whenever a field on the form model is updated the SaveToLocalStorage method will be called and the form will be persisted to local storage.

With the above changes I'd satisfied number 1 on my goals list:

~~Save data to local storage when it's entered into each form controls~~
Rehydrate data from local storage when the user returns to the page
Clear saved data from local storage when it's successfully submitted by the form
Try to keep things as close to the current experience with EditForm as possible for developers

Rehydrating the Form Model

I played around with a lot of ideas for this and ended up settling on the use of reflection. This was because I needed to update the specific instance of the model passed in, anything else I tried ultimately ended up overwriting that instance with a new one.

I came up with the following method which is used to copy the values from the form model retrieved from local storage, to the active form model.

public void Copy(object savedFormModel, object currentFormModel)
{
    var savedFormModelProperties = savedFormModel.GetType().GetProperties();
    var currentFormModelProperties = currentFormModel.GetType().GetProperties();

    foreach (var savedFormModelProperty in savedFormModelProperties)
    {
        foreach (var currentFormModelProperty in currentFormModelProperties)
        {
            if (savedFormModelProperty.Name == currentFormModelProperty.Name && savedFormModelProperty.PropertyType == currentFormModelProperty.PropertyType)
            {
                var childValue = currentFormModelProperty.GetValue(currentFormModel);
                var parentValue = savedFormModelProperty.GetValue(savedFormModel);

                if (childValue == null && parentValue == null) continue;

                currentFormModelProperty.SetValue(currentFormModel, parentValue);

                var fieldIdentifier = new FieldIdentifier(currentFormModel, currentFormModelProperty.Name);
                _fixedEditContext.NotifyFieldChanged(fieldIdentifier);

                break;
            }
        }
    }
}

In a nutshell, this code is looping over each property on the saved form model and then finding that same property on the current form model and transferring the value.

A key thing to note is the call to _fixedEditContext.NotifyFieldChanged(fieldIdentifier);. This lets the current edit context know that the value has been updated and triggers all the right events, a key one being any validation for that field.

With that method in placed I overrode the OnAfterRender lifecycle method and added the following code.

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        var savedModel = await LoadFromLocalStorage();

        if (Model is object && savedModel is object)
        {
            Copy(savedModel, Model);
            StateHasChanged();
        }
        else if (savedModel is object)
        {
            Copy(savedModel, _fixedEditContext.Model);
            StateHasChanged();
        }
    }
}

When the component first renders, this code will check local storage for an existing saved form model. If one is found then it will use the Copy method we just looked at to copy values from the saved form model to the current one. Once this has been done it will call StateHasChanged, this is important as it will refresh the UI and show the newly copied values in the form controls.

This was number 2 ticked off the list of goals, form values were now being reloaded from local storage when a user revisited a page.

~~Save data to local storage when it's entered into each form controls~~
~~Rehydrate data from local storage when the user returns to the page~~
Clear saved data from local storage when it's successfully submitted by the form
Try to keep things as close to the current experience with EditForm as possible for developers

Clearing saved form data on a successful submit

This one took me a bit of time to get working and for a very specific reason. If I wanted to honour number 4 on my goals list, keep things close to the current developer experience, I wanted to allow developers to still use the same form events OnSubmit, OnValidSubmit and OnInvalidSubmit.

The original method which handles the submit events is called HandleSubmitAsync and looks like this.

private async Task HandleSubmitAsync()
{
    if (OnSubmit.HasDelegate)
    {
        await OnSubmit.InvokeAsync(_fixedEditContext);
    }
    else
    {
        if (isValid && OnValidSubmit.HasDelegate)
        {
            await OnValidSubmit.InvokeAsync(_fixedEditContext);
        }

        if (!isValid && OnInvalidSubmit.HasDelegate)
        {
            await OnInvalidSubmit.InvokeAsync(_fixedEditContext);
        }
    }
}

Keeping OnInvalidSubmit doesn't require any action in terms of the saved form model. For OnValidSubmit I only had to make the following change to clear local storage after the OnValidSubmit event has been invoked.

if (isValid && OnValidSubmit.HasDelegate)
{
    await OnValidSubmit.InvokeAsync(_fixedEditContext);

    // Clear saved form model from local storage
    await _jsRuntime.InvokeVoidAsync("localStorage.removeItem", Id);
}

The headache came when trying to keep the OnSubmit event. This event requires the developer to handle the validation of the form manually and then submit it. With the existing design, there is no way for me to know if the form had been submitted and that the saved form model could be removed.

After some back and fourth I came up with the following design which does require some extra steps from the consumer but I think is worth the trade off.

The original OnSubmit event is typed as an EventCallback<EditContext> as follows.

[Parameter] public EventCallback<EditContext> OnSubmit { get; set; }

I updated the definition of the OnSubmit parameter to this.

[Parameter] public Func<EditContext, Task<bool>> OnSubmit { get; set; }

I'm now requiring the developer to register a method which returns a bool to let me know if the form was submitted successfully or not. Making this change did break a check performed in OnParametersSet.

if (OnSubmit.HasDelegate && (OnValidSubmit.HasDelegate || OnInvalidSubmit.HasDelegate))

This just required a simple update.

if (OnSubmit is object && (OnValidSubmit.HasDelegate || OnInvalidSubmit.HasDelegate))

Once that was fixed I could then update the code in HandleSubmitAsync to this.

if (OnSubmit is object)
{
    var submitSuccess = await OnSubmit.Invoke(_fixedEditContext);
    if (submitSuccess)
    {
        await _jsRuntime.InvokeVoidAsync("localStorage.removeItem", Id);
    }
}

I could now await the bool value from the consumer code and if it's true the saved form model is removed form local storage. The complete updated HandleSubmitAsync method looks like this.

private async Task HandleSubmitAsync()
{
    if (OnSubmit is object)
    {
        var submitSuccess = await OnSubmit.Invoke();
        if (submitSuccess)
        {
            await _jsRuntime.InvokeVoidAsync("localStorage.removeItem", Id);
        }
    }
    else
    {
        if (isValid && OnValidSubmit.HasDelegate)
        {
            await OnValidSubmit.InvokeAsync(_fixedEditContext);
            await _jsRuntime.InvokeVoidAsync("localStorage.removeItem", Id);
        }

        if (!isValid && OnInvalidSubmit.HasDelegate)
        {
            await OnInvalidSubmit.InvokeAsync(_fixedEditContext);
        }
    }
}

At this point I was happy to tick off number 3 on my goals list.

~~Save data to local storage when it's entered into each form controls~~
~~Rehydrate data from local storage when the user returns to the page~~
~~Clear saved data from local storage when it's successfully submitted by the form~~
Try to keep things as close to the current experience with EditForm as possible for developers

The only remaining goal was number 4, and the only way to tick that off is to check a few things from the consuming developers point of view and see how it compares to the original EditForm component.

Using the AutoSaveEditForm Component

Let's look at a simple example of form usage first. We'll use a model which contains two fields, FirstName and LastName. To make sure validation is working we'll also make the LastName required.

public class MyFormModel
{
    public string FirstName { get; set; }

    [Required]
    public string LastName { get; set; }
}

First we'll look at using EditForm and its OnValidSubmit event. The code is as follows.

<EditForm Model="myFormModel" OnValidSubmit="HandleValidSubmit">
    <DataAnnotationsValidator />

    <InputText @bind-Value="myFormModel.FirstName" />
    <InputText @bind-Value="myFormModel.LastName" />

    <button type="submit">Submit</button>
</EditForm>

@code {
    private MyFormModel myFormModel = new MyFormModel();

    private void HandleValidSubmit()
    {
        Console.WriteLine($"Form Submitted For: {myFormModel.FirstName} {myFormModel.LastName}");
        myFormModel = new MyFormModel();
    }
}

So how does this compare with AutoSaveEditForm?

<AutoSaveEditForm Id="form-one" Model="myFormModel" OnValidSubmit="HandleValidSubmit">
    <DataAnnotationsValidator />

    <InputText @bind-Value="myFormModel.FirstName" />
    <InputText @bind-Value="myFormModel.LastName" />

    <button type="submit">Submit</button>
</AutoSaveEditForm>

@code {
    private MyFormModel myFormModel = new MyFormModel();

    private void HandleValidSubmit()
    {
        Console.WriteLine($"Form Submitted For: {myFormModel.FirstName} {myFormModel.LastName}");
        myFormModel = new MyFormModel();
    }
}

The only changes needed were the name of the component and the addition of the Id parameter. That's pretty cool, really minimal changes for existing developers. But what about a slightly more complex example?

Let's look at the scenario where the developer is using the OnSubmit event and manually validating. This is what the code looks like with the EditForm component.

<EditForm Model="myFormModel" OnSubmit="HandleSubmit">
    <DataAnnotationsValidator />

    <InputText @bind-Value="myFormModel.FirstName" />
    <InputText @bind-Value="myFormModel.LastName" />

    <button type="submit">Submit</button>
</EditForm>

@code {
    private MyFormModel myFormModel = new MyFormModel();

    private void HandleSubmit(EditContext editContext)
    {
        var isValid = editContext.Validate();

        if (isValid)
        {
            Console.WriteLine($"Form Submitted For: {myFormModel.FirstName} {myFormModel.LastName}");
            myFormModel = new MyFormModel();
        }
        else
        {
            Console.WriteLine($"Form Invalid");
        }
    }
}

Here's the code with auto save.

<AutoSaveEditForm Id="form-one" Model="myFormModel" OnSubmit="HandleSubmit">
    <DataAnnotationsValidator />

    <InputText @bind-Value="myFormModel.FirstName" />
    <InputText @bind-Value="myFormModel.LastName" />

    <button type="submit">Submit</button>
</AutoSaveEditForm>

@code {
    private MyFormModel myFormModel = new MyFormModel();

    private async Task<bool> HandleSubmit(EditContext editContext)
    {
        var isValid = editContext.Validate();

        if (isValid)
        {
            Console.WriteLine($"Form Submitted For: {myFormModel.FirstName} {myFormModel.LastName}");
            myFormModel = new MyFormModel();

            return true;
        }
        else
        {
            Console.WriteLine($"Form Invalid");
            StateHasChanged();
            return false;
        }
    }
}

I think you'll agree, that's not bad and sticks pretty close to the original developer experience.

While I appreciate these are simple examples, I'm happy to take that as a win and tick off number 4 on the goals list.

~~Save data to local storage when it's entered into each form controls~~
~~Rehydrate data from local storage when the user returns to the page~~
~~Clear saved data from local storage when it's successfully submitted by the form~~
~~Try to keep things as close to the current experience with EditForm as possible for developers~~

I've created a gif to show what this looks like from the users perspective when using the component in an application.

I just want to reiterate again, this is not a fool-proof and complete solution. It's just a starting point. I do think it's really awesome that all this has been possible using just C# code. As you may have noticed, I've not had to write any JavaScript to achieve this.

Blazored AutoSaveEditForm

As I mentioned at the start, this is the starting point for a new component I'm adding to Blazored – you can find the repo here. It contains the complete code from this post and any suggestions are welcome, just open an issue. Also if anyone wants to help out with getting the component to a state where it's ready for public use, please let me know.

Summary

If you've made it this far, well done! For those looking for the complete source code I haven't published this yet as what you've just read about is the starting point for a new component which is going to be added to Blazored very soon.

In this post I've walked you though my design for a new form component which will persist form values to local storage until the form is submitted successfully. I started by showing why I was attempting this and the goals and boundaries for this work.

Then I talked about some of the brain storming I did and some other options I decided not to go with for the end design. Before taking you through the design for the end component which is based on the original EditForm component produced by the Blazor team.

Copy to Clipboard in Blazor

Chris Sainty — Wed, 29 Apr 2020 08:38:48 +0000

Recently I was creating a new repo on GitHub, a pretty common action for most of us now-a-days. When I noticed a feature which I use everytime but had never given much thought to, the copy to clipboard button.

This is a really useful feature, as I said a second ago, I literally use it everytime. Another great example of this can be found on the Bootstrap site. Each code example has a copy button in the top right corner allowing developers to copy the sample code straight to their clipboard.

I thought this would be a cool little feature to be able to use in Blazor applications so thought I would do a bit of investigation and see how it could be replicated.

In this post I’m going to show you how to create a simple copy to clipboard feature for Blazor apps. We're going to start by looking at the available APIs we can use for this functionality. From there we are going to create two solutions, one for short amounts of text, replicating the GitHub example above. The other for larger amounts of text, replicating the functionality from the Bootstrap docs.

Choosing the API

The first thing to understand is that we can't create the feature using C# code alone, we're going to have to use some JavaScript interop to achieve our goal. There are two API options available to us, Document.execCommand and Clipboard.

Document.execCommand

Historically, clipboard operations have been achieved using execCommand. A quick google of "copy to clipboard in JavaScript" will bring up numerous examples using this API. execCommand is also well supported across the different browsers, a quick check on caniuse.com shows lots of green (95.63%).

However, there is a rather large issue with this API. It's been marked obsolete.

The good news is there's a new API which supersedes it called the Clipboard API.

Clipboard API

The new Clipboard API has the ability to read and write to the clipboard both syncronously and asyncronously, as well as integrating with the Permissions API to ensure the user has given permission to do so.

The API breaks down into 2 interfaces, Clipboard and ClipboardEvent. The ClipboardEvent interface gives us access to information about the modification of the clipboard by events such as cut, copy and paste. It's good to know this is here but the more intestesting stuff is in the Clipboard interface.

The Clipboard interface provides us the functions to interact with the clipboard in our applications and contains the following 4 functions (from the MDN docs):

read()Requests arbitrary data (such as images) from the clipboard, returning a Promise. When the data has been retrieved, the promise is resolved with a DataTransfer object that provides the data.
readText()Requests text from the system clipboard; returns a Promise which is resolved with a DOMString containing the clipboard's text once it's available.
write()Writes arbitrary data to the system clipboard. This asynchronous operation signals that it's finished by resolving the returned Promise.
writeText()Writes text to the system clipboard, returning a Promise which is resolved once the text is fully copied into the clipboard.

The adoption of this new API isn't anywhere near as widespread as the old execCommand. The function we're interested in is writeText has 71.11% adoption according to caniuse.

However, the browsers that don't support this also don't support Blazor so that makes thing simple. Based on all the information I decided to go with the new clipboard API for this functionality.

Solution 1: Replicating GitHubs copy to clipboard

In this first solution we're going to replicate the funcationality from GitHub. This is ideal for any small, single line amounts of text you want to allow users to copy to their clipboards.

First create a component call CopyToClipboard with the following code.

Note: I'm doing this using the standard Blazor project template which has Bootstrap included. So for styling, I'm just using classes from that and some inline styles where needed.

@inject IJSRuntime

<div class="form-inline">
    <input class="form-control" readonly type="text" value="@Text" />
    <button type="button" class="btn btn-primary" @onclick="CopyTextToClipboard">Copy</button>
</div>

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

    private async Task CopyTextToClipboard()
    {
        await JSRuntime.InvokeVoidAsync("clipboardCopy.copyText", Text);
    }
}

The component takes in the text which can be copied by the user via the Text parameter. When the user click on the button the CopyTextToClipboard is invoked which calls the following JavaScript.

window.clipboardCopy = {
    copyText: function(text) {
        navigator.clipboard.writeText(text).then(function () {
            alert("Copied to clipboard!");
        })
        .catch(function (error) {
            alert(error);
        });
    }
};

The above function calls writeText to write the text provided from the CopyToClipboard component to the users clipboard.

We can use the component like this.

<CopyToClipboard Text="Copy this text" />

Which will produce the following output.

Solution 2: Replicating Bootstraps copy to clipboard

This time we're going to replicate the functionality from Bootstrap docs. This is great for copying larger amounts of text. Here is the updated code for the CopyToClipboard component.

<div class="position-relative" style="background-color: #f5f5f5">
    <pre>
    <code @ref="_codeElement">
            @ChildContent
        </code>
    </pre>
    <div style="position:absolute; top: 10px; right: 10px;">
        <button type="button" class="btn btn-primary" @onclick="CopyTextToClipboard">Copy</button>
    </div>
</div>

@code {

    private ElementReference _codeElement;

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

    private async Task CopyTextToClipboard()
    {
        await JSRuntime.InvokeVoidAsync("clipboardCopy.copyText", _codeElement);
    }
}

This time we're taking in child content defined by the components consumer and rendering it inside a code tag. We're capturing a reference to that element using Blazors @ref directive and passing that to JS when the copy button is clicked.

window.clipboardCopy = {
    copyText: function (codeElement) {
        navigator.clipboard.writeText(codeElement.textContent).then(function () {
            alert("Copied to clipboard!");
        })
        .catch(function (error) {
            alert(error);
        });
    }
}

The JavaScript code is largly the same as before. The only difference is we're receiving an HTML element instead of a text string. When we call writeText we're now passing in the text inside the code element using the textContent property.

We can use component like this.

<CopyToClipboard>
    @("<div class=\"clipboard-copy\">")
        @("<button type=\"button\" class=\"btn btn-primary\">Copy</button>")
    @("</div>")
</CopyToClipboard>

Which will produce the following output.

Summary

In this post I've show a couple of solutions for copying text to the users clipboard in Blazor. We started off by understanding the two API's available in JavaScript for interacting with the clipboard, execCommand and the Clipboard API. We concluded that using the new Clipboard API was a better choice due to the execCommand API being marked obsolete.

We then looked at two solutions for implementing copy to clipboard functionality. The first allowed short string to be copied to the users clipboard via a simple component with a button which invoked a call into JavaScript. The second method showed how to copy larger volumes of text by passing an ElementReference to JavaScript and accessing its textContent property to retrieve the text before copying it to the clipboard.

Mobile Blazor Bindings - Navigation and Xamarin Essentials

Chris Sainty — Tue, 21 Apr 2020 08:00:00 +0000

Mobile Blazor Bindings for Web Developers Series

Part 1 - Mobile Blazor Bindings - Getting Started

Part 2 - Mobile Blazor Bindings - Layout and Styling

Part 3 - Mobile Blazor Bindings - State and Data

Part 4 - Mobile Blazor Bindings - Navigation and Xamarin Essentials (this post)

We've come to the final post in this series on Mobile Blazor Bindings (MBB). In part 3, we learned about different ways to manage the state of our MBB applications. From simple state held in components to a central state container. We then looked at data, and how we could persist data locally using the SQLite database, as well as back to an API using HttpClient. Finally, we applied what we'd learned to our Budget Tracker app.

In this post, we're going to talk about navigation in MBB. We're also going to take a look at Xamarin Essentials, a collection of cross platform operating system and platform APIs we can use from C# to do some cool stuff in our MBB applications.

Navigation

Coming from the web, we're used to being able to navigate between pages in our apps using URLs. For example, www.mysite.com/about would take us to the about page. And generally speaking, users are free to navigate between pages in any order they choose.

Mobile apps tend to use a stack based navigation system where every time the user navigates to a new page it's added to the top of a stack. They can then move around the app in a linear fashion by tapping on new pages to go forwards and using the devices back button or a swipe gesture to move backwards.

There are different page types, such as MasterDetailPageand TabbedPage, which give the feeling of a more free movement. But essentially you are just moving around within a defined set of sub pages.

At the time of writing, there is no formal way to navigate between pages in MBB – This infrastructure isn't in place yet. However, there is a sample application in the MBB repo called Xaminals. This does demonstrate a way of navigating using multiple pages using something called Shell navigation.

Shell navigation is a URI-based navigation system for Xamarin applications. This is great for us developers coming from a web background as it naturally fits with the paradigms we're used to working with. It also uses concepts like routes which fit well with Blazors web based hosting models.

However, I did some experimenting with this technique but I just couldn't get things to do what I wanted. The biggest hurdle which I couldn't overcome was setting a starting page for the application. Also as Shell navigation isn't an official way to navigate, you can't get parameters populated from the "route" as you would in web based Blazor apps. However, you could overcome this by pulling any required state from a central state container like we talked about in part 3.

I think for me, navigation is just a little to alpha right now so I'm going to wait and see what comes down the line. Luckily, our Budget Tracker app doesn't need multiple pages so it won't impact us in any way.

Xamarin Essentials

So far, we've talked a lot about the fundamentals required to start building native mobile apps with MBB. But what about doing some more advanced/cool things like Geolocation or making the device vibrate. That's where Xamarin Essentials comes in.

Xamarin Essentials offers a set of operating system and platform APIs which we can use from C#. Those of you who've been following this series will know that we've briefly mentioned Xamarin Essentials in part 3 where we talked about using the Connectivity feature to decide whether to save data locally or to an API. But that was just the tip of the iceberg, here's the full list of features available from Xamarin Essentials right now.

Accelerometer – Retrieve acceleration data of the device in three dimensional space.
App Information – Find out information about the application.
App Theme – Detect the current theme requested for the application.
Barometer – Monitor the barometer for pressure changes.
Battery – Easily detect battery level, source, and state.
Clipboard – Quickly and easily set or read text on the clipboard.
Color Converters – Helper methods for System.Drawing.Color.
Compass – Monitor compass for changes.
Connectivity – Check connectivity state and detect changes.
Detect Shake – Detect a shake movement of the device.
Device Display Information – Get the device's screen metrics and orientation.
Device Information – Find out about the device with ease.
Email – Easily send email messages.
File System Helpers – Easily save files to app data.
Flashlight – A simple way to turn the flashlight on/off.
Geocoding – Geocode and reverse geocode addresses and coordinates.
Geolocation – Retrieve the device's GPS location.
Gyroscope – Track rotation around the device's three primary axes.
Launcher – Enables an application to open a URI by the system.
Magnetometer – Detect device's orientation relative to Earth's magnetic field.
MainThread – Run code on the application's main thread.
Maps – Open the maps application to a specific location.
Open Browser – Quickly and easily open a browser to a specific website.
Orientation Sensor – Retrieve the orientation of the device in three dimensional space.
Permissions – Check and request permissions from users.
Phone Dialer – Open the phone dialer.
Platform Extensions – Helper methods for converting Rect, Size, and Point.
Preferences – Quickly and easily add persistent preferences.
Secure Storage – Securely store data.
Share – Send text and website uris to other apps.
SMS – Create an SMS message for sending.
Text-to-Speech – Vocalize text on the device.
Unit Converters – Helper methods to convert units.
Version Tracking – Track the applications version and build numbers.
Vibrate – Make the device vibrate.
Web Authenticator - Start web authentication flows and listen for a callback.

I think you'll agree there is a lot of cool stuff there to explore. I'm not going to talk about each item here, I'll leave it to you to explore the particular features you're interested in. I've included a link with each feature to it's docs page to get you started.

Adding Dark Mode to Budget Tracker

To finished things off we're going to use one of the features from Xamarin Essentials to add a dark mode options to Budget Tracker. I mean, let's face it, it's not a real app unless it has a dark mode! 😆

We're going to use the App Theme feature which will allow us to ask for the current theme set on the OS. This will return one of three options to us, Dark, Light or Unspecified. Based on this, we can load a different style sheet for either light or dark mode. It's worth pointing out that this feature only works on the newer versions of Android and iOS, here are the specifics:

Android 10+ (API level 29+) - Older versions return Light
iOS 13+ - Older versions return Unspecified

Creating a Dark Theme

To start we'll rename the existing stylesheet to BudgetTrackerLight.css and then make a copy of it and call that BudgetTrackerDark.css. In here we'll update the various styles with the new dark colour scheme.

entry {
    font-size: 30;
    color: #F7FAFC;
    background-color: #718096;
}

frame {
    border-radius: 10;
    background-color: #4A5568;
}

label {
    color: #CBD5E0;
    -xf-horizontal-text-alignment: center;
}

button {
    background-color: #718096;
    color: #E2E8F0;
}

.textSmall {
    font-size: 12;
}

.homeContainer {
    padding: 10;
    background-color: #1A202C;
}

.balanceContainer {
    margin: 0 0 10 0;
    -xf-spacing: 0;
}

    .balanceContainer > .currentBalance {
        font-size: 30;
        color: #F7FAFC;
        -xf-vertical-text-alignment: center;
        -xf-horizontal-text-alignment: center;
    }

.budgetContainer {
    -xf-spacing: 0;
}

    .budgetContainer > .currentBudget {
        font-size: 20;
        color: #48BB78;
        -xf-vertical-text-alignment: center;
        -xf-horizontal-text-alignment: center;
    }

.expensesContainer {
    -xf-spacing: 0;
}

    .expensesContainer > .currentExpenses {
        font-size: 20;
        color: #E53E3E;
        -xf-vertical-text-alignment: center;
        -xf-horizontal-text-alignment: center;
    }

.currencySymbol {
    color: #718096;
    font-size: 30;
    -xf-vertical-text-alignment: center;
}

.createExpenseContainer {
    margin: 20 0 0 0;
    -xf-orientation: horizontal;
}

    .createExpenseContainer > entry {
        font-size: initial;
        background-color: #718096;
        color: #F7FAFC;
        -xf-placeholder-color: #CBD5E0;
    }

.expenseListItem {
    margin: 10 0 0 0;
    -xf-orientation: horizontal;
}

    .expenseListItem > label {
        font-size: 20;
        color: #F7FAFC;
    }

.noExpenses {
    font-size: 16;
    color: #A0AEC0;
    padding: 10;
    -xf-horizontal-text-alignment: center;
}

Now we have the styles sorted out we just need to add a bit of logic to the HomePage component to load the right stylesheet based on the device's theme.

Loading the correct stylesheet

We're going to add a new field to the HomePage component which will store the theme. Then in the OnInitializedAsync method we're going to set the field using the AppInfo.RequestedTheme which is provided by Xamarin Essentials.

private AppTheme theme;

protected override async Task OnInitializedAsync()
{
    theme = AppInfo.RequestedTheme;

    // ... other code omitted
}

Now we have that in place it's just a case of using it to load the correct stylesheet. At the top of the component where we declare the stylesheet we're going to replace it with the following code.

@if (theme == AppTheme.Light)
{
    <StyleSheet Resource="BudgetTrackerLight.css" Assembly="GetType().Assembly" />
}
else if (theme == AppTheme.Dark)
{
    <StyleSheet Resource="BudgetTrackerDark.css" Assembly="GetType().Assembly" />
}
else
{
    <StyleSheet Resource="BudgetTrackerLight.css" Assembly="GetType().Assembly" />
}

I appreciate this isn't the most sophisticated code in the world, but for our simple app it will work nicely. We can now run the app and see how things have turned out.

We now have a nice dark mode for our Budget Tracker app which will adjust based on the users preference set on the device. And it was all pretty painless to setup thanks to the features provided by Xamarin Essentials!

You can find the full source code on GitHub.

Summary

In this post, we've talked about navigation in Mobile Blazor Bindings, covering the current limitations in the framework. We then talked about Xamarin Essentials and what that offers us. We finished up by applying the App Theme feature from Xamarin Essentials to the Budget Tracker app so that we could show a dark mode if the user had that set as their display preference.

I hope you've enjoyed this series on Mobile Blazor Bindings and I've piqued your interest in the technology. As I've said many times through this series, this is an experiment and there is no official commitment to deliver this. So please only use it for fun right now. But if you're interested in seeing this become a real product, let the team know either via GitHub or on Twitter.

Mobile Blazor Bindings - State Management and Data

Chris Sainty — Tue, 14 Apr 2020 08:00:00 +0000

Mobile Blazor Bindings for Web Developers Series

Part 1 - Mobile Blazor Bindings - Getting Started

Part 2 - Mobile Blazor Bindings - Layout and Styling

Part 3 - Mobile Blazor Bindings - State Management and Data (this post)

Last time, we looked at layout and styling options for Mobile Blazor Bindings (MBB). We learned about the various page types and layout components available to us, as well as how we could style our components using either parameter styling or the more familiar CSS approach. We finished up by applying what we learned to our Budget Tracker app, adding various layout components and styling to make the app look a bit more appealing.

In this post, we're going to explore state management and data in MBB. We'll look at some option to manage the state of our applications ranging from simple to more complex. Then we'll talk about data, specifically, how to persist it. We'll cover how to deal with local persistence as well as persisting back to a server. Just as before, we'll finish up by applying what we've learned to our Budget Tracker app.

State Management

Just as with web applications, we need to be able to manage the state of our mobile apps. Even in a simple app like Budget Tracker, we have various bits of state to keep track of. The current budget, the current balance and the expenses that have been entered. Let's explore a couple of options we could use.

Storing state in components

The simplest thing we can do when it comes to state is to manage it within a component. The Budget Tracker at the end of the last post stores and manages its state this way – all state is kept on the HomePage component.

@code {

    private decimal _budget;
    private List<Expense> _expenses = new List<Expense>();

    private decimal _currentBalance => _budget - _expenses.Sum(x => x.Amount);
    private decimal _expensesTotal => _expenses.Sum(x => x.Amount);

}

The other components in the app update these values using Blazors EventCallback approach.

This method works really well in simple scenarios such as the Budget Tracker app where there is only a single page component. But, depending on the app, in multi page apps this stops being a good option and we would need to look at something a bit more advanced.

AppState class

The next level up would be implementing an AppState class. We can record all the bits of state we need to keep track of across our application in this one place. This class is registered with the DI container as a Singleton, giving all components we inject it into access to the same data.

Say for example we had an ecommerce application. We could use an AppState class to keep track of the contents of the shopping basket. It might look something like this.

public class AppState
{
    private readonly List<Item> _basket = new List<Item>();
    public IReadOnlyList<Item> Basket => _basket.AsReadOnly();

    public event Action OnChange;

    public void AddItem(Item newItem)
    {
        _basket.Add(newItem);
        NotifyStateChanged();
    }

    public void RemoveItem(Item item)
    {
        _basket.Remove(item);
        NotifyStateChanged();
    }

    private void NotifyStateChanged() => OnChange?.Invoke();
}

You'll notice that the Basket property is read only, this is important as we wouldn't want it being changed randomly. We want changes to go through the public methods, AddItem and RemoveItem, so we can ensure the OnChange event is raised. All the components in our app that care about the state of the basket can subscribe to this event and be notified when updates happen.

@inject AppState AppState
@implements IDisposable

<StackLayout>
    <Label Text="@($"{AppState.Basket.Count} Items in Basket")" />
</StackLayout>

@code {

    protected override void OnInitialized()
    {
        AppState.OnChange += StateHasChanged;
    }

    public void Dispose() => AppState.OnChange -= StateHasChanged;
}

In the code above, whenever an item is added or removed from the basket the OnChange event will trigger the component to re-render by calling StateHasChanged. We're also using implementing IDisposable so we can safely unsubscribe from the OnChange event when the component is destroyed.

This method works really well and is pretty simple to implement and get going with. However, you may find it doesn't work well in large applications. The more state that's tracked the bigger the class gets as we add more methods to update the various values. Eventually, it will become quite difficult to navigate and maintain.

At this point it would be worth looking at breaking the state down into smaller chunks, alternatively, you could also look at doing a Redux or MobX implementation for you MBB app. There some example out there of implementing Redux in a Xamarin Forms app which should be fairly easy to port to MBB. I think the Fluxor library from Peter Morris would also work, although I've not tested it myself.

Data

Let's talk about what we can do with our data. In mobile apps we have three scenarios we potentially need to cater for. Online, offline and a mix of both.

Online - Saving data to an API

Saving data back to an API in MBB isn't much different to what we would do in a web based Blazor app, which is handy.

There isn't an HttpClient configured out of the box, so we need to install the Microsoft.Extensions.Http NuGet package. Once installed we add the following line to register the various services with the DI container.

.ConfigureServices((hostContext, services) =>
{
    // Register app-specific services
    services.AddHttpClient();
})

We can also install the same HttpClient helper methods we're used to from Blazor by adding the System.Net.Http.Json package. This is currently a pre-release package, if you're not familiar with it you can read more about it in this blog post. We now have access to GetFromJsonAsync, PostAsJsonAsync and PutAsJsonAsync.

We can now inject an IHttpClientFactory into any component and use the CreateClient method to get an instance of the HttpClient to make our API calls with. From here things are the same as they would be in a web based Blazor app.

Offline - Storing data on the device

The most common option for storing data locally on the device is SQLite. It's a small, fast, self-contained, high-reliability, full-featured, SQL database engine – it's also free and open source.

Using SQLite is really easy. Once the sqlite-net-pcl NuGet package is installed, we need to define entity classes, similar to how we would with Entity Framework. These represent the shape of the data we're going to persist. For example, if we were saving cars, a Car entity could be defined like this.

public class Car
{
    [PrimaryKey, AutoIncrement]
    public int Id { get; set; }
    public string Make { get; set; }
    public string Model { get; set; }
    public int Doors { get; set; }
}

This is a simple POCO (Plain Old CLR Object/Plain Old C# Object) class the only bit of magic that's been added is the PrimaryKey and AutoIncrement attributes. These mark the primary key for the table and ensure it has an auto-incrementing value.

Then we need to define a database class. this performs a few jobs. It ensures that the database is created along with any tables, it's also where we define any methods for saving or retrieving data. You can think of it as a mix between an Entity Framework DB context and a repository.

public class Database
{
    readonly SQLiteAsyncConnection _database;

    public Database(string dbPath)
    {
        _database = new SQLiteAsyncConnection(dbPath);
        _database.CreateTableAsync<Car>().Wait();
    }

    public Task<List<Car>> GetCarsAsync()
    {
        return _database.Table<Car>().ToListAsync();
    }

    public Task<int> SaveCarAsync(Car newCar)
    {
        return _database.InsertAsync(newCar);
    }
}

The final job is to add an instance of the Database class into the DI container so we can using it by injecting it into our components.

public App()
{
    var database = new Database(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "cars.db3"));

    var host = MobileBlazorBindingsHost.CreateDefaultBuilder()
        .ConfigureServices((hostContext, services) =>
        {
            // Register app-specific services
            services.AddSingleton<Database>(database);
        })
        .Build();

        // other code omitted
}

That's all there is to it, data can now be saved locally on the device and will persist between app restarts.

Both - Catering for offline scenarios

The final option we'll look at is a mix of online and offline. This is probably the majority of mobile apps. And really this is about knowing if we're online or offline. If we're online we can make an API and if we're offline we can save data to a local database until the network is back and then push it up to the API. Now, we could just make API calls and see if they time out, then if they do, save locally. But this doesn't seem very elegant. Luckily for us there is a much simpler way thanks to Xamarin Essentials.

We'll talk more about Xamarin Essentials another time but it's a great library which gives us access to loads of OS and platform APIs from C#, one of which is the Connectivity class. This gives us a simple API we can call to determine the network status of the device.

var current = Connectivity.NetworkAccess;

if (current == NetworkAccess.Internet)
{
    // Connection to internet is available
}

We can even subscribe to an event which will tell us when the network status changes.

public ConnectivityTest()
{
    // Register for connectivity changes, be sure to unsubscribe when finished
    Connectivity.ConnectivityChanged += HandleConnectivityChanged;
}

void HandleConnectivityChanged(object sender, ConnectivityChangedEventArgs e)
{
    // Do something based on new network status
}

This gives us everything we need to be able to cater for scenarios where the app may not have a network connection.

Adding State Management & Data to Budget Tracker

Let's put everything together and apply it to Budget Tracker. Now, as I mentioned earlier, Budget Tracker can work perfectly fine with storing all its state on the HomePage component. But using an AppState class would clean up some of the code keeping everything in sync. Another advantage would come when persisting data. We aren't going to add an API to this project, that seems a bit overkill. But it would be great to be able to save data locally using SQLite. If we added an AppState class we could do this much easier as everything is in one place.

Adding an AppState Class

We'll start by defining an AppState class, in the root of the project, which contains all of the state which was originally kept in the HomePage component.

public class AppState
{
    private readonly List<Expense> _expenses = new List<Expense>();

    public decimal Budget { get; private set; }
    public IReadOnlyList<Expense> Expenses => _expenses.AsReadOnly();
    public decimal CurrentBalance => Budget - _expenses.Sum(x => x.Amount);
    public decimal ExpensesTotal => _expenses.Sum(x => x.Amount);

    public event Action OnChange;

    public void SetBudget(decimal newBudget)
    {
        Budget = newBudget;
        NotifyStateChanged();
    }

    public void AddExpense(Expense newExpense)
    {
        _expenses.Add(newExpense);
        NotifyStateChanged();
    }

    private void NotifyStateChanged() => OnChange?.Invoke();
}

We're also going to register it as a singleton in the DI container in App.cs

var host = MobileBlazorBindingsHost.CreateDefaultBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        // Register app-specific services
        services.AddSingleton<AppState>();
    })
    .Build();

With those bits in place it's just a case of updating the various components to pull their state directly from the AppState class. Here's what the updated HomePage component looks like.

@inject AppState AppState
@implements IDisposable

<StyleSheet Resource="BudgetTracker.css" Assembly="GetType().Assembly" />

<StackLayout class="homeContainer">

    <Frame>
        <StackLayout>
            @if (AppState.Budget > 0)
            {
                <BudgetSummary />
            }
            else
            {
                <SetBudget />
            }
        </StackLayout>
    </Frame>

    @if (AppState.Budget > 0)
    {
        <Frame>
            <ScrollView>
                <StackLayout>
                    <Label Text="EXPENSES" />
                    <ExpenseList />
                    <CreateExpense />
                </StackLayout>
            </ScrollView>
        </Frame>
    }

</StackLayout>

@code {

    protected override void OnInitialized() => AppState.OnChange += StateHasChanged;

    public void Dispose() => AppState.OnChange -= StateHasChanged;
}

You can view all of the changes to the app over on the GitHub repo.

Storing Data via SQLite

Great! We now have the state of the app in a central place. Next we're going to add in SQLite so we can save the values we enter between app reboots. First we need to define our database class.

public class BudgetTrackerDb
{
    private readonly SQLiteAsyncConnection _database;

    public BudgetTrackerDb(string dbPath)
    {
        _database = new SQLiteAsyncConnection(dbPath);
        _database.CreateTableAsync<Budget>().Wait();
        _database.CreateTableAsync<Expense>().Wait();
    }

    public async Task<int> SaveBudgetAsync(Budget newBudget)
    {
        var result = await _database.InsertAsync(newBudget);

        return result;
    }

    public async Task<decimal> GetBudgetAsync()
    {
        // This is nasty but as we're only going to have one budget for now so we'll let it slide
        var result = await _database.Table<Budget>().FirstOrDefaultAsync(x => x.Amount > 0);

        return result?.Amount ?? 0;
    }
    public async Task<int> SaveExpenseAsync(Expense newExpense)
    {
        var result = await _database.InsertAsync(newExpense);

        return result;
    }

    public Task<List<Expense>> GetExpensesAsync()
    {
        return _database.Table<Expense>().ToListAsync();
    }

}

Our DB has two tables, one to store the budget and one to store the expenses. This setup would also allow us to expand the functionality of the app at a later data and support multiple budgets. We've also defined a few methods to save and retrieve data from the database.

With the database class in place, next we're going to update our AppState class.

public class AppState
{
    private readonly BudgetTrackerDb _budgetTrackerDb;

    public AppState()
    {
        _budgetTrackerDb = new BudgetTrackerDb(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "BudgetTrackerDb.db3"));
    }

    public event Func<Task> OnChange;

    public async Task SetBudget(decimal newBudget)
    {
        _ = await _budgetTrackerDb.SaveBudgetAsync(new Budget { Amount = newBudget });
        await NotifyStateChanged();
    }

    public async Task<decimal> GetBudget() => await _budgetTrackerDb.GetBudgetAsync();

    public async Task AddExpense(Expense newExpense)
    {
        _ = await _budgetTrackerDb.SaveExpenseAsync(newExpense);
        await NotifyStateChanged();
    }

    public async Task<IReadOnlyList<Expense>> GetExpenses() => await _budgetTrackerDb.GetExpensesAsync();

    public async Task<decimal> GetCurrentBalance()
    {
        var budget = await GetBudget();
        var expenses = await GetExpenses();

        return budget - expenses.Sum(x => x.Amount);
    }

    public async Task<decimal> GetTotalExpenses()
    {
        var expenses = await GetExpenses();

        return expenses.Sum(x => x.Amount);
    }

    private async Task NotifyStateChanged() => await OnChange?.Invoke();
}

Essentially what we've done here is written methods which retrieve the data from our database rather than just storing the values in memory. An advantage of doing this is if our app needed to support online and offline functionality. We could easily add in a check to see if the app is connected or not, if it isn't then we could save locally to the SQLite database. But if it was then we could use a HttpClient to send and retrieve data from an API. But the rest of our app wouldn't need to care, it could all be handled inside the AppState class.

The final job now is to make some updates to the various components to work with the new methods. Here is the final HomePage component.

@inject AppState AppState
@implements IDisposable

<StyleSheet Resource="BudgetTracker.css" Assembly="GetType().Assembly" />

<StackLayout class="homeContainer">

    <Frame>
        <StackLayout>
            @if (budgetSet)
            {
                <BudgetSummary />
            }
            else
            {
                <SetBudget />
            }
        </StackLayout>
    </Frame>

    @if (budgetSet)
    {
        <Frame>
            <ScrollView>
                <StackLayout>
                    <Label Text="EXPENSES" />
                    <ExpenseList />
                    <CreateExpense />
                </StackLayout>
            </ScrollView>
        </Frame>
    }

</StackLayout>

@code {

    private bool budgetSet;

    protected override async Task OnInitializedAsync()
    {
        await UpdateState();
        AppState.OnChange += UpdateState;
    }

    public void Dispose() => AppState.OnChange -= UpdateState;

    private async Task UpdateState()
    {
        var budget = await AppState.GetBudget();
        budgetSet = budget > 0;

        StateHasChanged();
    }
}

That's it, we're done. You can see the full updated source code on the GitHub repo.

Summary

In this post we've looked at some options around managing state and storing data in a Mobile Blazor Bindings application.

Starting with state, we looked at the most simple options first, state in components. We then moved on to a more advanced method using a central class called AppState to store all state in the application.

Next we looked at data and how we can store it locally on the device using SQLite, a popular, open source, portable SQL database. We talked about how we could configure MBB to make API calls using the HttpClient so we could persist data back to the server. We also covered how we could use the Xamarin Essentials Connectivity class to determine if the app is connected in order to decide if data should be saved locally or an API call should be attempted.

Finally, we applied some of our learnings to the Budget Tracker application. We added an AppState class to hold all of the app state centrally. We also added in SQLite to store our budget and any expenses we'd added.

Mobile Blazor Bindings - Layout and Styling

Chris Sainty — Tue, 07 Apr 2020 08:00:00 +0000

Mobile Blazor Bindings for Web Developers Series

This is the second post in the series: Mobile Blazor Bindings for Web Developers.

Part 1 - Mobile Blazor Bindings - Getting Started

Part 2 - Mobile Blazor Bindings - Layout and Styling (this post)

In my part 1, I covered what Mobile Blazor Bindings (MBB) is, how to get your dev environment setup and create and run your first app. Over the next few posts we're going to exploring various topics to deepen our knowledge and help us build more feature rich, native mobile apps with MBB.

In this post, we're going to look at layout and styling. In the web world, we're used to creating layouts and structure in our apps using elements such as divs, spans and tables. These are then usually enhanced using CSS features such as flexbox, CSS grid or general CSS rules. When it comes to styling, everything we do uses CSS, we don't have any alternatives. So, how do we do this stuff in MBB? That's what we're going to find out.

Introducing Budget Tracker

Before we get started, to give us a bit of focus over the coming posts, we're going to be working with a simple budget tracker app I've created. This will allow us to apply the various features we learn to a real app.

I'm not going to go into loads of detail about the app as our goal here is to learn about Mobile Blazor Bindings, not budget tracking. I'll give a quick summary just so we understand the layout of the project.

The app is very simple and can currently perform 3 tasks:

Set a budget for the month
Record expenses
Track the remaining balance

This is what the project structure looks like.

I'm a big fan of feature folders to organise projects, you can see them in use here. There's a top level feature called Home which has a single page component called HomePage – I tend to postfix any page components with Page so they are easily distinguishable from regular components. Then there are two sub-features, BudgetManagement and ExpenseManagement. The contain regular components which are loaded into the HomePage based on certain logic.

The project is available on GitHub so you can check it out and play with it at your leisure. As I said, we'll be evolving it over the next few posts so it may change from the above structure over time.

Let's crack on and starting looking at layout options for our app.

Layout Options

When compared to the web, our options for layouts in MBB are far more structured. As I mentioned in the intro, when creating web apps we tend to use a lot of div elements with CSS to add structure to our pages. But the div element is just a divider, something that marks a section of an HTML document. Other than being a block element (display: block;), it has no predefined abilities. This can be useful as it makes it flexible, however, we have to define what we want a particular div to do every time.

With MBB this is not the case, we have access to a set of predefined structural components allowing us to rapidly create interesting and efficient UI. There are two categories of component for this, page components and layout components.

Page Components

Different page types is not something we're used to in the web world. We have a single page type, a HTML document, and that's it. It's certainly possible to create the kinds of page configurations offered by MBB in HTML, but it involves us having to do all the configuration manually and can take a lot of time.

With MBB, at the time of writing, there are three ready to use page components out of the box (checkout thelatest list here).

ContentPage The most commonly used type of page. This is a simple component which can display a single piece of child content. For example, a StackLayout or Grid.
MasterDetailPage This page displays a master view, often set to display a menu. And a detail view, set to display the selected menu item. This is a great starting point for multi-page apps.
TabbedPage Allows the developers to define a set of tabs which, when clicked, load their content in to the main view.

There are also two lower level components which can be used to create your own custom page types.

Page Page is essentially a base class used for creating more functional derived types, all of the other page components here derive from this class. You could use this as a starting point for creating your own custom page type.
TemplatedPage Derives from the Page component above. This component displays full-screen content with a control template and is the base class for the ContentPage component.

Layout Components

In MBB, we can use dedicated layout components. At the time of writing there are five layout components available (you can checkout the current list in the docs). They are:

ContentView This is a simple structural component which can display a single child. The child can be any view component or layout component.
Frame Frame derives from ContentView and, by default, displays its child content with a border and shadow making it stand out on the screen.
Grid Unsurprisingly, this component allows its child content to be displayed in a grid of rows and columns. This is equivalent to an HTML table element.
ScrollView This component allows its content to be scrollable, very useful when displaying long lists or large amounts of text.
StackLayout Child components are displayed in a vertical stack, by default. This can be swapped to horizontal by setting the Orientation parameter. This is the most common layout component I've used so far – the div of the MBB world if you will.

Styling

Now we know about the various options available to use for structuring our pages, what about styling them? MBB offers us two options here, what I'm going to call parameter styles, and CSS styles.

Parameter Styles

Parameter based styling is very similar to what Xamarin Forms refers to as XAML styles. When styling apps using this method we set all style related settings on the component using its exposed parameters.

This is probably easier to understand with an example. Let's say we wanted to style a Label with a font size of 30 and have it's text coloured blue. This is how we would do that using parameter styles.

<Label Text="EXPENSES"
       FontSize="30"
       TextColor="Color.Blue" />

We can also set other types of style information for components which is specific to the underlying Xamarin Forms platform. For example, a StackLayout stacks it's child content vertically by default. We can change this to horizontal by using the Orientation parameter.

<StackLayout Orientation="StackOrientation.Horizontal">
    <!-- ... other code omitted ... -->
</StackLayout>

This method of styling is pretty quick to get going with and it makes it very clear what styles are applied to which components. But one big downside is that we have to set styles everywhere, we can't just predefine a style for all Labels globally, we have to set each one individually.

Let's look at the other options now which is much more familiar to us web devs, CSS.

CSS Styles

Please Note: CSS styles don't appear to work correctly in the current offical release (v0.2.42-preview). In order to use them, I've had to clone the repo and build my own NuGet packages to get the latest changes. Hopefully a new release will be out shortly and this step won't be needed.

Styling components using CSS is probably the obvious go-to option if you're coming from a web background, and it works pretty much how you would expect it to in MBB. We can create style classes and apply them to individual components or we can use CSS selectors to target all Labels in an app.

We create a stylesheet as normal to contain our styles and we reference it in each page of our app using a special component called StyleSheet which looks like this.

<StyleSheet Resource="BudgetTracker.css" Assembly="GetType().Assembly" />

Don't put the StyleSheet component inside any layout components otherwise things won't work and you'll probably get a load of weird exceptions – trust me I lost a few hours to this 😭.

Another thing to be aware of is that right now stylesheets need to be at the root of your project, they don't appear to work when moved into folders. There is a issue tracking this on the GitHub repo.

Using the examples we looked at with parameter styles, what do they look like using CSS. For our first example, we could create a normal style class in our stylesheet with the following rules.

.largeBlueLabel {
    font-size: 30;
    colour: blue;
}

Then apply it to the relevant component using the class parameter.

<Label Text="EXPENSES"
       class="largeBlueLabel" />

Pretty simple right?! But what about handling the Xamarin Forms specific styling such as the orientation example? Well we can do that with CSS as well!

The CSS in MBB is a special flavour which includes a load of specific selectors and properties. Which means we can manipulate setting such as orientation via CSS as well.

.horizontal {
    -xf-orientation: horizontal;
}

<StackLayout class="horizontal">
    <!-- ... other code omitted ... -->
</StackLayout>

In these examples the changes aren't huge but imagine if we'd set several style parameters on a component, the markup starts to look noisy really quick. Using CSS also allows us to remove the issue we identified with parameter styling where we need to set the same styles over and over again. With CSS we can define the class once and just apply it to whatever components we choose.

Now we have all of this new knowledge about how to layout and style Mobile Blazor Bindings apps, let's put some of it into action but applying it to the budget tracker app.

Adding Layout & Styling to Budget Tracker

We don't really need more than one page in our app, at least for now. We'll keep the default page type, which is a ContentPage, and we'll focus on applying layout components and styling.

Just for reference, if you check the App.cs you can see where the HomePage component is set as the child of the ContentPage.

MainPage = new ContentPage();
host.AddComponent<HomePage>(parent: MainPage);

Let's start applying some of these layout components to our app. Currently the app has no layout components at all. This is the code for the HomePage component.

@if (_budget > 0)
{
    <BudgetSummary Budget="_budget"
                   TotalExpenses="_expensesTotal"
                   CurrentBalance="_currentBalance" />
}
else
{
    <SetBudget OnBudgetSet="@((newBudget) => _budget = newBudget)" />
}

@if (_budget > 0)
{
    <Label Text="EXPENSES" />
    <ExpenseList Expenses="_expenses" />
    <CreateExpense OnExpenseAdded="@((newExpense) => _expenses.Add(newExpense))" />
}

@code {

    private decimal _budget;
    private List<Expense> _expenses = new List<Expense>();

    private decimal _currentBalance => _budget - _expenses.Sum(x => x.Amount);
    private decimal _expensesTotal => _expenses.Sum(x => x.Amount);

}

What does this look like when we run it?

Umm... not the best, I think you'll agree. As our budget is currently 0 the SetBudget component is being displayed, which looks like this.

<Label Text="SET YOUR BUDGET" />
<Label Text="£" />
<Entry @bind-Text="Budget"
       OnCompleted="@(() => OnBudgetSet.InvokeAsync(_budget))" />

But where are all the other UI elements? All we are seeing is the Entry component – equivalent to an HTML input control – This is because the HomePage component is being displayed in a ContentPage which, as we learned earlier, can only display one child. It seems the last component wins, in this case the Entry component.

At the very least we need a single top level component to contain all our content. Let's add a StackLayout to our HomePage and see what happens.

<StackLayout>
    @if (_budget > 0)
    {
        <BudgetSummary Budget="_budget"
                       TotalExpenses="_expensesTotal"
                       CurrentBalance="_currentBalance" />
    }
    else
    {
        <SetBudget OnBudgetSet="@((newBudget) => _budget = newBudget)" />
    }

    @if (_budget > 0)
    {
        <Label Text="EXPENSES" />
        <ExpenseList Expenses="_expenses" />
        <CreateExpense OnExpenseAdded="@((newExpense) => _expenses.Add(newExpense))" />
    }
</StackLayout>

That's looking a bit better, we can see all 3 UI elements, the 2 Labels and the Entry. As we found out earlier, child components in a StackLayout are stacked vertically by default, but it would be much nicer if the £ symbol and the Entry were on the same line. We can add another StackLayout around the Label and the Entry and set it to display horizontally, which should achieve what we're after.

<Label Text="SET YOUR BUDGET" />
<StackLayout Orientation="StackOrientation.Horizontal">
    <Label Text="£" />
    <Entry @bind-Text="Budget"
           OnCompleted="@(() => OnBudgetSet.InvokeAsync(_budget))" />
</StackLayout>

We now have the layout that we wanted but it's looks pretty naff. Let's apply some styling to try and improve things a bit.

First off we'll apply some parameter styles as its a pretty quick way to try things out.

<Label Text="SET YOUR BUDGET" />
<StackLayout Orientation="StackOrientation.Horizontal">
    <Label Text="£"
           TextColor="@(Color.FromHex("718096"))"
           FontSize="30"
           VerticalTextAlignment="TextAlignment.Center" />
    <Entry FontSize="30"
           TextColor="@(Color.FromHex("2D3748"))"
           HorizontalOptions="LayoutOptions.FillAndExpand"
           @bind-Text="Budget"
           OnCompleted="@(() => OnBudgetSet.InvokeAsync(_budget))" />
</StackLayout>

That's now looking loads better but as I mentioned earlier, there is a lot of markup added just for a few style tweaks. Let's swap this over to CSS styles and see what it looks like.

We first need to create a stylesheet in the root of the project, we'll call it BudgetTracker.css and then add a reference to it in the HomePage component.

<StyleSheet Resource="BudgetTracker.css" Assembly="GetType().Assembly" />

<StackLayout>
    <!-- ... other code omitted ... -->
</StackLayout>

We can then add the following styles to our stylesheet and adjust the markup to use these new styles.

entry {
    font-size: 30;
    color: #2D3748;
}

.currencySymbol {
    color: #718096;
    font-size: 30;
    -xf-vertical-text-alignment: center;
}

<Label Text="SET YOUR BUDGET" />
<StackLayout Orientation="StackOrientation.Horizontal">
    <Label Text="£"
           class="currencySymbol" />
    <Entry HorizontalOptions="LayoutOptions.FillAndExpand"
           @bind-Text="Budget"
           OnCompleted="@(() => OnBudgetSet.InvokeAsync(_budget))" />
</StackLayout>

The final change we will make is to add in a Frame component to make our set budget section stand out. We'll start by adding a new CSS class with some styling, then adjust the markup.

.setBudgetContainer {
    border-radius: 10;
    background-color: #ffffff;
    margin: 10;
}

<Frame class="setBudgetContainer">
    <StackLayout>
        <Label Text="SET YOUR BUDGET" />
        <StackLayout Orientation="StackOrientation.Horizontal">
            <Label Text="£"
                   class="currencySymbol" />
            <Entry ClearButtonVisibility="ClearButtonVisibility.WhileEditing"
                   HorizontalOptions="LayoutOptions.FillAndExpand"
                   @bind-Text="Budget"
                   OnCompleted="@(() => OnBudgetSet.InvokeAsync(_budget))" />
        </StackLayout>
    </StackLayout>
</Frame>

Like other layout components we talked about earlier, the Frame component can only have a single child, so we need to add an additional StackLayout to wrap the existing Label and StackLayout – told you StackLayouts are the div of the MBB world! 😂. With the above changes our app now looks like this.

Our app now looks loads better, obviously we still need to apply layout and styling to the rest of it, but I think this blog post is long enough already! So, if you've made it this far then well done and thank you. I'll carry on with styling the app and you can check it out on GitHub.

Summary

In this post I've introduced the layout and styling options available to us in Mobile Blazor Bindings. I briefly introduced the Budget Tracker app we'll be developing over the course of this series.

Then I talked about the layout options available in MBB, this included all the current page components and layout components. We learned about what each one offers us before moving on to talk about styling. In terms of styling we found out we had two options, parameter styling or CSS. We looked at examples of how to use each one and talked about some potential downsides of parameter styling and how CSS styles could solves those problems.

Finally, we took what we learned and applied to the Budget Tracker app. We added some layout components to improve the look of the page and then added some styles. We first tried parameter styling and then quickly moved to CSS styles.

Getting Started with Mobile Blazor Bindings

Chris Sainty — Wed, 01 Apr 2020 08:00:00 +0000

This is the first, in what will probably be a series of blog posts, I've been looking forward to writing for a while – I'm going to be exploring the new experimental Mobile Blazor Bindings project.

In this post, I'm going to be giving an introduction to the Mobile Blazor Bindings (MBB) project, what it is, why you might be interesting in trying it, what is and isn't available and we'll finish with creating our first app.

What is Mobile Blazor Bindings?

It's a new experimental project led by Eilon Lipton, a principal software engineer at Microsoft. The unique selling point of the project is it enables developers to author native, cross platform mobile apps using Blazors programming model.

What this means is instead of writing a mix of C# and HTML to create components, as we would in the web hosting models for Blazor, we write C# and native mobile controls. To give you an idea of what this looks like, below is a counter component written for a Blazor WebAssembly application, then below that is that same component but written for MBB.

<!-- Blazor WebAssembly -->

<p>Current count: @currentCount</p>
<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    int currentCount = 0;

    void IncrementCount()
    {
        currentCount++;
    }
}

<!-- Mobile Blazor Bindings -->

<Label Text="@($"Current count: {currentCount}")" />
<Button Text="Click me" OnClick="@IncrementCount" />

@code
{
    int currentCount = 0;

    void IncrementCount()
    {
        currentCount++;
    }
}

As you can see the programming model is identical, it's just the types of controls which are used that is different. This makes MBB a great stepping stone for web developers looking to get into cross platform native mobile app development, using their existing skills.

The components we use to author apps with MBB are essentially wrappers around Xamarin Forms controls. At the time of writing, the following components are available.

Page components

ContentPage
MasterDetailPage
Page
TabbedPage
TemplatedPage

Layout components

ContentView
Frame
Grid
ScrollView
StackLayout

View components

ActivityIndicator
BoxView
Button
CheckBox
Image
ImageButton
Entry
Label
ProgressBar
Slider
Stepper
Switch

Specialized components

Application
BaseMenuItem
FormattedString
GestureElement
MenuItem
Shell (including ShellContent, ShellGroupItem, ShellItem, FlyoutItem, TabBar, ShellSection, Tab)
Span

You can checkout the official docs to get the most up-to-date information on the current components available.

After reading the above, a few questions may be going round in your head, what about Xamarin? Do they know about this? Is Xamarin being replaced? These are all good questions so let's cover those next.

What about Xamarin? Is it being replaced?

The first thing to point out is that MBB is just an experiment, there is no commitment to developing and delivering this as a product. When the first version of MBB was announced, the blog post contained the following statement.

We have heard from a set of developers that come from a web programming background that having web specific patterns to build mobile applications would be ideal for them. The goal of these bindings is to see if developers would like to have the option of writing markup and doing data binding for native mobile applications using the Blazor-style programming model with Razor syntax and features.

The key part to pull out is "if developers would like to have the option". MBB, if was taken forward, would offer an alternative to writing native mobile apps using XAML.

I think this is a great idea and I'm keen to see where it goes, the big thing keeping me away from native mobile development is XAML, I just don't like it. That's not to say there is anything wrong with it, I know a lot of developers really enjoy working with it. I also know a lot of developers also feel the same way about HTML.

I think giving developers the choice to write apps using the languages they enjoy, and have skills in, is a fantastic thing. The likes of Uno Platform are offering the same choice the other way, allowing developers familiar with XAML the option to write web applications using that instead of HTML. Everyone wins!

Getting Setup

Now we've gotten a better understanding of what MBB is and why we might want to try it out. Let's move on and get setup so we can start playing with it.

Installing Workloads

You can try out MBB using either Visual Studio or Visual Studio for Mac, but you will need to install the following workloads:

Mobile development with .NET
ASP.NET and web development

Once you have installed the above workloads, if you don't already have it, you will also need to download and install the latest version of the .NET SDK.

Installing the MBB Template

There is a project template we need to use to create new MBB applications, this can be installed using the dotnet CLI using the following command (you may want to check for a newer version of the templates before installing).

dotnet new -i Microsoft.MobileBlazorBindings.Templates::0.2.42-preview

Once you have the template installed, you should be able to see it when running the dotnet new command.

Enabling Windows Hypervisor Platform

This was something I bumped into when I first tried to run the Android emulator from Visual Studio. I then had to go and enable it which then required a restart of my PC. So I want to save you a bit of time and let you know about it now.

Windows Hypervisor Platform will greatly improve the performance of the Android emulator when working with MBB, or any Xamarin application for that matter. If you follow this link, full instructions are given on how to enable WHP on your machine.

Creating an MBB app

Once you've completed the above steps you should be ready to create your first Mobile Blazor Bindings application!

Currently there is no integration with the new project dialogue in Visual Studio so we will need to create the app from the command line using the dotnet CLI. To create a new MBB app use the following command (I've called my app HelloMBB but call yours whatever you want):

dotnet new mobileblazorbindings -o HelloMBB

You can now open Visual Studio and load up the solution. You should see 3 projects in the Solution Explorer, HelloMBB, HelloMBB.Android and HelloMBB.iOS.

The Android and iOS projects are essentially shells for the particular platform which our MBB app is going to load into. All of the application logic is kept in the HelloMBB project.

This is the same approach you can use to run a Blazor web app using either the Server or WebAssembly hosting model. Putting all common components into a RazorClassLibrary and removing everything but the infrastructure code from the Server and WebAssembly projects. You can find an example of that approach on my GitHub if you've not seen it before.

If you want to run the iOS project you're going to need a Mac in order to compile the project. This is due to Apples licencing and there isn't a way around it. I do have a Mac but I'm current working on a Windows machine so, for now, I'm going to set the Android project as the startup project and then hit F5 to run the application.

Creating an Android Device

If you've not done any Xamarin work before, after a few seconds, you will see this screen.

This is because we don't currently have an Android device setup for the emulator to use. I'm not very familiar with Android devices so I've created the default device selected, Pixel 2 (+ Store). This seems to work really well, at least on my machine* 😋.

Once you create your device, it will be downloaded and then you will be able to use it. This can take a good few minutes to complete.

Running the App

You will probably ended up back at Visual Studio, at least I did, but now the Start Debugging button should contain the name of the new device you've created. Hit F5 again and after a few moments you should see your new MBB app.

Making Changes

Let's make a simple change, well add in a button which updates the text to display "Hello, MBB!" instead of the default "Hello, World!". Currently, there is no hot reload available for MBB so we are going to have to stop debugging to make our changes.

Once you've stopped debugging, open up the HelloWorld.razor file, it should look like this.

<ContentView>
    <StackLayout Margin="new Thickness(20)">

        <Label Text="Hello, World!"
               FontSize="40" />

        <Counter />

    </StackLayout>
</ContentView>

We're going to update the code to match the code below.

<ContentView>
    <StackLayout Margin="new Thickness(20)">

        <Label Text="@LabelText"
               FontSize="40" />

        <Button Text="Update Message" OnClick="@(() => LabelText = "Hello, MBB!")" />

        <Counter />

    </StackLayout>
</ContentView>

@code {

    public string LabelText { get; set; } = "Hello, World!";

}

Instead of the Label text being hardcoded, it's now using the WelcomeMessage property. When we click the Button we're updating the value of WelcomeMessage to be "Hello, MBB!".

Press F5 to run the updated app, when you click on Update Message you should see the new message displayed.

Congratulations, you've just created, modified and run your first Mobile Blazor Bindings application!

Summary

In this post I have introduced Mobile Blazor Bindings. We started off by covering what MBB is, why we might choose to try it out and what components are available. We also talked about MBB in relation to Xamarin and how it complements the existing Xamarin platform.

We then moved on to setting up a machine to use MBB, covering the workloads required by Visual Studio and Visual Studio for Mac. How to install the template for MBB and improve the performance of the Android device emulator by enabling Windows Hypervisor Platform.

Finally, we created a new MBB app and ran it on an Android device emulator. We then made a simple change to the app, adding in a button which updated the default message displayed.

I hope I've piqued you interest in Mobile Blazor Bindings. Next time I'm going to delve deeper by building out a more complex app.

Working with Query Strings in Blazor

Chris Sainty — Wed, 25 Mar 2020 12:51:20 +0000

In this post I'm going to be taking a look at query strings and specifically how we can work with them in Blazor, because at this point in time, Blazor doesn't give us any tools out of the box. In fact, Blazor pretty much ignores them.

We're going to start off by covering what query strings are and why we'd want to use them over route parameters. Then we'll get into some code and I'll show you a couple of options which should make working with them in your Blazor applications much easier.

Example Code: A sample project to accompany this blog post can be found on GitHub

What are query strings?

Query strings are essentially an instance or collection of key value pairs encoded into a URL. Below is an example of what a query string looks like.

mysite.com/about?name=Chris&favouritecolor=orange

The start of a query string is separated from the rest of the URL by a ?. Then comes the key value pairs, each key and value is separated by a =. If there's more than one pair a & is used to separate them.

In the example above, the query string contains two pairs, name with a value of Chris and favouritecolour with a value of orange.

One of the original use cases for query strings was to hold form data. When a form was submitted the field names and their values were encoded into the URL as query string values.

Why use them over route parameters?

A good question, for me, query strings provide a more flexibility over route parameters when it comes to optional values. Having optional parameters in a route can be a real pain if not impossible, in my experience at least. A good example of this is when using filters on a list page.

Let's pretend we have a page listing cars (/carsearch) and we offer the user the ability to filter that list by make, model, and colour. If we wanted to use route parameters we'd have to use multiple route templates.

@page "/carsearch"
@page "/carsearch/{make}"
@page "/carsearch/{make}/{model}"
@page "/carsearch/{make}/{model}/{colour}"

The problem is what happens if the user only selected make and colour? The route would look like this /carsearch/ford/blue. Now we have a problem, the router is going to find a match with the 3rd template we've defined, @page "/carsearch/{make}/{model}". So we'd be trying to find all cars with a make of ford and a model of blue, oh dear.

Now, we could work round this but using defaults for the various filters but it would be much simplier to use query strings instead.

Query strings don't care about order of values, or even if a value is present or not, we don't even need to define them in a route template. Which means we can go back to using a single route template for our car search page.

@page "/carsearch"

And when the user wants to filter we can just add the selected criteria to the URL using query strings.

/carsearch?make=ford&colour=blue

The only problem now is how do we actually get hold of and use the values in our query string?

Introducing WebUtilites

There is a library called Microsoft.AspNetCore.WebUtilities which contains a fantastic helpers for dealing with query strings. It will chop up a query string for us and allow us to retrieve values in a straightforward way, meaning we don't have to get into loads of string manipulation.

We're going to update the Counter page in the default template to look for a query string which sets the initial count for the counter. So given the url /counter?initialCount=10, we'd expect the counter to start at 10. Here's how we can achieve that.

@page "/counter"
@inject NavigationManager NavManager

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    int currentCount = 0;

    protected override void OnInitialized()
    {
        var uri = NavManager.ToAbsoluteUri(NavManager.Uri);
        if (QueryHelpers.ParseQuery(uri.Query).TryGetValue("initialCount", out var _initialCount))
        {
            currentCount = Convert.ToInt32(_initialCount);
        }
    }

    void IncrementCount()
    {
        currentCount++;
    }
}

We can inject the NavigationManager which gives us access to the current URI. Once we have that, we can pass the query string (uri.Query) to the WebUtilities helper and ask for the value of initialCount. The last thing we need to do is convert the value of initialCount to an int as all values are returned as strings by the helper.

That wasn't actually too bad and if we just needed to do this on one page then we're now sorted. However, if we needed to use query strings in multiple places in our app this becomes a lot of boilerplate to have kicking around. So let's make this better.

Moving to an Extension Method

We can encapsulate all this functionality into a extension method on the NavigationManager class. This should make working with query strings all over our app trivial going forward. Here's the code.

public static class NavigationManagerExtensions
{
    public static bool TryGetQueryString<T>(this NavigationManager navManager, string key, out T value)
    {
        var uri = navManager.ToAbsoluteUri(navManager.Uri);

        if (QueryHelpers.ParseQuery(uri.Query).TryGetValue(key, out var valueFromQueryString))
        {
            if (typeof(T) == typeof(int) && int.TryParse(valueFromQueryString, out var valueAsInt))
            {
                value = (T)(object)valueAsInt;
                return true;
            }

            if (typeof(T) == typeof(string))
            {
                value = (T)(object)valueFromQueryString.ToString();
                return true;
            }

            if (typeof(T) == typeof(decimal) && decimal.TryParse(valueFromQueryString, out var valueAsDecimal))
            {
                value = (T)(object)valueAsDecimal;
                return true;
            }
        }

        value = default;
        return false;
    }
}

A lot of the code above is the same as we just saw, except I've used some generics to allow the caller to specify the type they want the requested value to be converted to. I've then added a some checks to covert values to string int or decimal you could add whatever other ones you wish.

If we refactor our counter page to use our new extension method this is what we end up with.

@page "/counter"
@inject NavigationManager NavManager

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    int currentCount = 0;

    protected override void OnInitialized()
    {
        NavManager.TryGetQueryString<int>("initialCount", out currentCount);
    }

    void IncrementCount()
    {
        currentCount++;
    }
}

That now looks much cleaner and we've got all our query string code in one place which is great for maintainability.

Dealing with updates to query string values

One last scenario I want to cover is how to react to updates in query string values. Lets add a few links to our counter page which set the counter to different initial values, say 10, 20 and 30.

The problem we have no is that when we click any of these links Blazor isn't going to call the OnInitialized life cycle method again as we are already on the correct componet for the route. So how can we react to the new query string value? It turns out the NavigationManager.LocationChanged event still fires, so we can setup a handler for that event which will retrieve the new values.

@page "/counter"
@inject NavigationManager NavManager

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

<hr />

<a href="/Counter?initialCount=10">Start counter at 10.</a> |
<a href="/Counter?initialCount=20">Start counter at 20.</a> |
<a href="/Counter?initialCount=30">Start counter at 30.</a>

@code {
    int currentCount = 0;

    protected override void OnInitialized()
    {
        GetQueryStringValues();
        NavManager.LocationChanged += (o, e) => 
        {
            GetQueryStringValues();
            StateHasChanged();
        };
    }

    void GetQueryStringValues()
    {
        NavManager.TryGetQueryString<int>("initialCount", out currentCount);
    }

    void IncrementCount()
    {
        currentCount++;
    }
}

I think that wraps things up. We can now easily access query string values from any of our components both on initial load and when the URL is updated.

Summary

In this post I talked about working with query strings in Blazor. I started off by describing what query strings are and why you would choose to use them over route parameters.

I then suggested some options on how to achieve this in Blazor. I started off with a simple solution based on the Microsoft.AspNetCore.WebUtilities library. I then developed that into an extension method for the NavigationManager class to avoid code duplication and ease use and maintainability.

Integrating Tailwind CSS with Blazor using Gulp - Part 2

Chris Sainty — Tue, 03 Mar 2020 09:46:25 +0000

Last time, I introduced Tailwind CSS and showed how you can get it up and running with Blazor. This time I'm going to go a little deeper and show how you can customise and configure Tailwind for your application, optimise the final CSS, as well as how to integrate it all into a CI pipeline.

Customising Tailwind

I mentioned in part 1, it's possible to custom Tailwind to your specific needs. The default settings include, a set of colour palettes, fonts, padding and margin spacing, plus many more. And you can customise all of them via the tailwind.config.js file.

The file is split into three different sections, theme, variants and plugins. The theme section allows us to customise things like fonts, colour palettes, border widths, essentially anything related to the visual style of your site. The variants section allows you to configure the responsive and pseudo-class variants which are generated. These control the generation of classes which style things like hover and focus events. Finally, the plugins section allows you to add third party plugins which can generate even more CSS classes for your app. For a full breakdown of every option you can checkout the fantastic official docs.

To see this in action we're going to add a custom colour on top of the default colour palettes. In the root of your app, create a new file called tailwind.config.js, if you don't have one already, and paste in the following code.

module.exports = {
  theme: {
    extend: {
      colors: {
        blazoredorange: '#ff6600'
      }
    }
  }
};

The key here is the use of the extend object, this tells Tailwind we want to ADD to the existing colours. If we had written the config like this instead.

module.exports = {
  theme: {
    colors: {
      blazoredorange: '#ff6600'
    }
  }
};

Then we would be telling Tailwind to replace the existing colour palettes. It's worth noting that everything in Tailwinds configuration is optional, so you only need to include the things you want to override or extend.

This file is automatically picked up by Tailwind during the build process so once you've finished adding your custom configuration, just rerun the gulp css task to generate your new custom CSS. With the above configuration change we now get access to the following extra classes.

text-blazoredorange
border-blazoredorange
bg-blazoredorange

Optimising Your CSS

One downside of Tailwind is that there are a lot of classes generated by default and you're potentially not using a lot of them in your application. This means that the size of your CSS file can be a bit large, relatively speaking. So what can we do about this?

Removing unused CSS with PurgeCSS

There is a great plugin which solves this exact problem called PurgeCSS. It scans through your files and tries to determine what CSS classes you are using and then removes all the ones you don't. If we look back at the configuration we had for our Gulp file from part 1, it looks like this.

const gulp = require('gulp');

gulp.task('css', () => {
  const postcss = require('gulp-postcss');

  return gulp.src('./Styles/site.css')
    .pipe(postcss([
      require('precss'),
      require('tailwindcss'),
      require('autoprefixer')
    ]))
    .pipe(gulp.dest('./wwwroot/css/'));
});

If we look at the size of the CSS file produced from this configuration, it's pretty large, 1073kb.

This is fine while we are working locally, in fact it's needed so we can have access to all those utility classes while we're developing. But once we've finished there will be a lot of unused classes that are now just taking up space. Let's update our config to use PurgeCSS and see what kind of saving we can make.

First we need to install PurgeCSS using npm and the following command

npm install --save-dev gulp-purgecss

Once that has completed we can update our gulpfile.js to use PurgeCSS.

const gulp = require('gulp');

gulp.task('css', () => {
  const postcss = require('gulp-postcss');
    const purgecss = require('gulp-purgecss');

  return gulp.src('./Styles/site.css')
    .pipe(postcss([
      require('precss'),
      require('tailwindcss'),
      require('autoprefixer')
    ]))
    .pipe(purgecss({ content: [' **/*.html', '** /*.razor'] }))
    .pipe(gulp.dest('./wwwroot/css/'));
});

As part of the configuration for PurgeCSS I've passed in the types of files I want it to scan in order to look for CSS classes. I've specified it should look for any files ending in .html or .razor within my application. We can then run our Gulp task using the command gulp css, as before, to regenerate our CSS.

Wow! That's a pretty impressive size reduction! 1073kb down to 12kb. At this point it's worth checking your application to make sure everything still looks as it should, but so far I haven't found any issues.

We could stop there but I think there are more savings to be had. After all, we've not even minimised the file. Let's do that next and see how we get on.

Minimising CSS

In order to minimise our CSS we need to install another plugin or two. First, we'll install CleanCSS which is going to do the minimising for us.

 npm install gulp-clean-css --save-dev

Optionally, you can also install Sourcemaps which will generate sourcemap files so you can debug your CSS once it's been minified. This isn't essential and I'll leave it up to you to decide if you want to include it or not.

npm install gulp-sourcemaps --save-dev

With those plugins installed we can return to our gulpfile and add some more configuration.

const gulp = require('gulp');

gulp.task('css', () => {
  const postcss = require('gulp-postcss');
  const purgecss = require('gulp-purgecss');
  const sourcemaps = require('gulp-sourcemaps');
  const cleanCSS = require('gulp-clean-css');

  return gulp.src('./Styles/site.css')
    .pipe(sourcemaps.init())
    .pipe(postcss([
      require('precss'),
      require('tailwindcss'),
      require('autoprefixer')
    ]))
    .pipe(purgecss({ content: [' **/*.html', '** /*.razor'] }))
    .pipe(cleanCSS({ level: 2 }))
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest('./wwwroot/css/'));
});

The changes here are calling into CleanCSS once we have purged any unused classes. Then generating the sourcemap for the minified CSS file. If you don't want to create a sourcemap file then just leave those lines out of the config.

Once you're done rerun your gulp task gulp css, and let's see what the savings are.

4KB! Now that is a pretty small file, I think you'll agree. I'm pretty happy with our work, we've taken the original file weighing in at 1073KB and we've managed to reduce it to only 4KB. This is great but we do have one problem.

With the current configuration we only have one gulp task which produces our CSS and now it's producing a version which doesn't include all the utility classes we might need for future development. It would be much better to create two gulp tasks, one to use during development and one to use when we want to ship to production.

const gulp = require('gulp');
const postcss = require('gulp-postcss');
const sourcemaps = require('gulp-sourcemaps');
const cleanCSS = require('gulp-clean-css');
const purgecss = require('gulp-purgecss');

gulp.task('css:dev', () => {
  return gulp.src('./Styles/site.css')
    .pipe(sourcemaps.init())
    .pipe(postcss([
      require('precss'),
      require('tailwindcss'),
      require('autoprefixer')
    ]))
    .pipe(gulp.dest('./wwwroot/css/'));
});

gulp.task('css:prod', () => {
  return gulp.src('./Styles/site.css')
    .pipe(sourcemaps.init())
    .pipe(postcss([
      require('precss'),
      require('tailwindcss'),
      require('autoprefixer')
    ]))
    .pipe(purgecss({ content: [' **/*.html', '** /*.razor'] }))
    .pipe(cleanCSS({ level: 2 }))
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest('./wwwroot/css/'));
});

Here is the final configuration, we now have two gulp tasks, css:dev and css:prod.

By running the css:dev task we can get the full CSS file with all of Tailwinds utility classes and any customisations we've made. The great thing is we only need to run this once to generate the initial CSS locally and then only again if we change any customisations.

The css:prod task is going to give us the super optimised version of our CSS to use in production. But we wouldn't want to run this locally, at least in an ideal world, it would be much better to use this in a CI pipeline when we deploy our application. So to finish things up, let look at how we can integrate all our work so far into a CI pipeline using Azure DevOps.

Using with TailwindCSS in a CI pipeline

As our CSS file is compiled, we should check it into source control, we should have it be dynamically generated by our build process for each release. In order to do this we will need to install the tools we've been using locally via npm and then run our Gulp task to produce the production CSS.

Unsurprisingly, there are already tasks available on Azure DevOps to do this. There is an npm task which will install all our npm packages and a Gulp task we can use to build our CSS.

trigger:
- master

pool:
  vmImage: 'windows-latest'

variables:
  buildConfiguration: 'Release'

steps:
- task: UseDotNet@2
  displayName: 'Installing .NET Core SDK...'
  inputs:
    packageType: sdk
    version: 3.1.102
    installationPath: $(Agent.ToolsDirectory)/dotnet

- task: Npm@1
  displayName: 'Running NPM Install...'
  inputs:
    command: 'install'
    workingDir: 'MySite'

- task: gulp@1
  displayName: 'Running Gulp tasks'
  inputs:
    gulpFile: 'MySite/gulpfile.js' 
    targets: css:prod

- script: dotnet build --configuration $(buildConfiguration) MySite/MySite.csproj
  displayName: 'Building $(buildConfiguration)...'

The first task installs the latest .NET Core SDK. Then the npm install command is run via the npm task. Use the workingDir setting to point to where your package.json file lives in your project structure. Then the gulp css:prod task is run before building the app.

You can then publish your app where ever you wish and if you need some guidance on how to do that with Azure DevOps, I have a couple of posts which should help you out, here and here.

Summary

That bring us to an end. We now have Tailwind CSS integrated into our Blazor app allowing us to take advantage of its awesome utility based approach to styling UI.

We have learned how to customise Tailwind using its extensive configuration options. We then saw how we can optimise the CSS we produced using PurgeCSS and CleanCSS to create the smallest file possible for a production scenario. Then we finished up by integrating Tailwind into a CI pipeline using Azure DevOps.

Integrating Tailwind CSS with Blazor using Gulp - Part 1

Chris Sainty — Tue, 18 Feb 2020 09:00:00 +0000

I've been a fan of Tailwind CSS for quite some time now. It was created by Adam Wathan and has been developed by Jonathan Reinink, David Hemphill, and Steve Schoger. I actually discovered Tailwind due to following Steve and his excellent tweets on UI tips and tricks. In fact, if you are a developer with an interest in UI design, I couldn't recommend Steve's eBook, RefactoringUI, enough.

Tailwind is a utility-first CSS framework, which means that instead of providing you with a set of premade UI components, which lead to every website looking the same, you are provided with a massive array of low-level utility classes that allow you to rapidly create custom designs with ease. Let me give you an example to illustrate.

Let's look at styling a button with bootstrap first. We can define our button and apply the btn and btn-primary CSS classes as per the code below.

<button class="btn btn-primary">Primary</button>

This will render a button that looks like this.

Next, we'll style a button using Tailwind.

<button class="px-3 py-2 rounded-md bg-blue-600 text-white">Primary</button>

Which will render a button that looks like this.

As you can see straight away, there are no tailored CSS classes in this version. The button is built up using multiple classes which each provide a single element of the styling. The px and py classes provide padding, rounded-md rounds the corners of the button, bg-blue-600 colours the background and text-white defines the text colour. You can checkout the full array of options on the Tailwind docs.

You're probably thinking, but Chris, that's a lot more styles I have to apply to get the same result. I agree, but what you're getting in return is flexibility and the option to not have your site look like the thousands of others that use the same CSS framework. I appreciate this isn't something that interests everyone and there is nothing wrong with using frameworks like bootstrap, I have for years and it's awesome. But when you're trying to do something a little different Tailwind is your friend.

Another huge benefit of using Tailwind is that you pretty much never have to write any CSS classes yourself. As everything is composable using utility classes, you can create any look, any style from what's provided by the framework. Need your site to be responsive? No problem, Tailwind has utilities for that. Need cool transitions? Tailwind has you covered there, too.

Tailwinds approach sits really well with component based UIs, such as Blazor. Building on the example above we could create a PrimaryButton component which looks like this.

<!-- PrimaryButton.razor -->

<button class="px-3 py-2 rounded-md bg-blue-600 text-white"
        @onclick="HandleClick">@Text</button>

@code {
    [Parameter] public Action HandleClick { get; set; } 
    [Parameter] public string Text { get; set; } 
}

We've now nicely encapsulated the styles for our primary button in a component. And if we need to update the styles later down the road, we can come to a single place to make the changes.

It doesn't stop there either. Tailwind can also be customised. This is because Tailwind is more than just a CSS framework, it's written in PostCSS and can be configured to your needs. We're going to be covering how to do this in part 2.

Integrating Tailwind with Blazor

Hopefully, if you've gotten this far, I've convinced you to try Tailwind—or you're already a fan and just want to know how to use it with your Blazor app.

In order to get the most out of Tailwind, we're going to be using some tools you may or may not be familiar with from the JavaScript ecosystem, NPM and Gulp. If you're not familiar with these tools, I've added a link to each of them so you can have a read up on what they do.

Installing NodeJS to get NPM

If you haven't already got NodeJS installed then you will need to do that first. This is because installing node installs NPM (Node Package Manager). Head over to the Node site and grab the latest LTS version (12.16.0 at the time of writing). Run the installer, you should be able to accept all the defaults, just make sure that npm package manager is selected.

Once the installer is finished, open a terminal and type npm -v. If you see a version number printed out then you're good to go.

Adding Gulp and Tailwind via NPM

The next thing we need to do is install the Gulp CLI globally, this will allow us to work with Gulp on the command line. At your terminal type npm install gulp-cli -g. Once the install has completed we can turn our attention to our Blazor project.

In the root of your Blazor app, add a new file called package.json and then add the following code.

{
  "devDependencies": {
    "gulp": "^4.0.2",
    "gulp-postcss": "^8.0.0",
    "precss": "^4.0.0",
    "tailwindcss": "^1.2.0",
    "autoprefixer": "^9.7.4"
  }
}

This tells NPM what packages to install for our project. We'll see how these are used a little later in when we configure Gulp.

The next step is to setup our CSS file as per the Tailwinds docs. The way I do this is by creating a folder in the root of my app called Styles and in there add a file called site.css (you can name this file whatever you want). The reason this file is sitting outside of the wwwroot folder is because it is it going to be processed to produce the final CSS file which will be outputted to the wwwroot folder. Then add the following code.

@tailwind base;
@tailwind components;
@tailwind utilities;

#blazor-error-ui {
    background: lightyellow;
    bottom: 0;
    box-shadow: 0 -1px 2px rgba(0, 0, 0, 0.2);
    display: none;
    left: 0;
    padding: 0.6rem 1.25rem 0.7rem 1.25rem;
    position: fixed;
    width: 100%;
    z-index: 1000;
}

    #blazor-error-ui .dismiss {
        cursor: pointer;
        position: absolute;
        right: 0.75rem;
        top: 0.5rem;
    }

The three lines at the top are all we need to add to get all of those awesome Tailwind utilities. When the file is processed, those three lines will be replaced with all the generated classes from Tailwind. You can also add any custom styles you want present in the final CSS file as well. I've made sure to keep the styling for the Blazor error messages which come in the default project template.

The last part is to add another file to the root of the project called gulpfile.js. This is where we are going to configure Gulp to build Tailwind for us. Add the following code, remember to update the filename if you didn't use site.css.

const gulp = require('gulp');

gulp.task('css', () => {
  const postcss = require('gulp-postcss');

  return gulp.src('./Styles/site.css')
    .pipe(postcss([
      require('precss'),
      require('tailwindcss'),
      require('autoprefixer')
    ]))
    .pipe(gulp.dest('./wwwroot/css/'));
});

We're defining a single Gulp task called css. It takes the site.css we defined above as an input and then runs it though a plugin called postcss. Essentially, this plugin builds all of those Tailwind utility classes. Once it's finished, the processed CSS is output into the wwwroot/css folder.

With all of the above in place, open a terminal and navigate to the root of the Blazor app, the same folder where the package.json and gulpfile.js reside. Once there, run the following commands.

npm install
gulp css

The first command will install all the packages in the package.json file we created earlier. Once that's finished, the second command executes the css task we defined in our gulpfile.js. If all has gone well you should see a new file, site.css in your wwwroot/css folder. All that's left to do is to reference the file in your apps index.html or _Host.cshtml.

Congratulations! You can now go and start building your UI using the utility of Tailwind.

Summary

In this post, I've shown how to integrate the awesome, utility-first CSS framework, Tailwind CSS into your Blazor project. We started by looking at what makes Tailwind different to other CSS frameworks such as Bootstrap and reasons why we'd want to use it. We then looked at how we can integrate it with a Blazor application using NPM and Gulp.

I hope you enjoyed this post and if you didn't know about Tailwind before, that I've made you curious about it. Next time, we're going to go a little deeper down the rabbit hole. We'll look at how we can customise Tailwind using it's configuration system. As well as how we can optimise our outputted CSS by removing unused classes. To finish off we'll go through how to integrate Tailwind into a CI pipeline with Azure DevOps.

I'm using Tailwind to build a new documentation site for the Blazored UI packages. So if you want to see this in a real world application then feel free to check it out on GitHub.