03-show-order-status.md

Exercise 3: Show order status

Your customers can order pizzas, but so far they have no way to see the status of their orders. In this exercise you'll implement a "My orders" page that lists multiple orders, plus an "Order details" view showing the contents and status of an individual order.

Task 1: Adding a navigation link

Open MainLayout.razor under the Shared folder in the BlazingPizza.Client project. As an experiment, let's try adding a new link element without using a NavLink component. Add a plain HTML <a> tag linked to myorders below the NavLink element:

<a href="myorders" class="nav-tab">
    <img src="img/bike.svg" />
    <div>My Orders</div>
</a>

Notice how the URL we're linking to does not start with a /. If you linked to /myorders, it would appear to work the same, but if you ever wanted to deploy the app to a non-root URL the link would break. The <base href="/"> tag in index.html specifies the prefix for all non-slash-prefixed URLs in the app, regardless of which component renders them.

If you run the app now, you'll see the link, styled as expected:

This shows it's not strictly necessary to use <NavLink>. We'll see the reason to use it momentarily.

Task 2: Adding a "My Orders" page

If you click My Orders, you'll end up on a page that says Sorry, there's nothing at this address.. Obviously this is because you haven't yet added anything that matches the URL myorders. But if you're watching really carefully, you might notice that on this occasion it's not just doing client-side (SPA-style) navigation, but instead is doing a full-page reload.

What's really happening is this:

• You click on the link to myorders

• Blazor, running on the client, tries to match this to a client-side component based on @page directive attributes.

• However, since no match is found, Blazor falls back on full-page load navigation in case the URL is meant to be handled by server-side code.

• However, the server doesn't have anything that matches this either, so it falls back on rendering the client-side Blazor app.

• This time, Blazor sees that nothing matches on either client or server, so it falls back on rendering the NotFound block from your App.razor file.

As you can guess, we will make the link actually work by adding a component to match this route. To do this, right-click the Pages folder in Solution Explorer and click Add then Razor Component. Set the file's name to MyOrders.razor and click Add.

Add the following content:

@page "/myorders"

<div class="main">
    My orders will go here
</div>

Now when you run the app and click My Orders, you'll be brought to this page:

Also notice that this time, no full-page load occurs when you navigate, because the URL is matched entirely within the client-side SPA. As such, navigation is instantaneous.

Task 3: Adding a page title

In your browser, the title of the new page is listed as Blazing Pizza and it would be nice to update the title to reflect that in the My Orders page. Do this by adding the following to the MyOrders.razor page below the @page "/myorders" line:

<PageTitle>Blazing Pizza - My Orders</PageTitle>

This works because inside the Program.cs file is an entry that adds a HeadOutlet component to the HTML presenting the BlazingPizza app. Blazor uses this HeadOutlet to write content into the header of the HTML page.

Task 4: Highlighting navigation position

Look closely at the top bar. Notice that when you're on the My orders page in the running app, the My Orders link isn't highlighted. How can we highlight links when the user is on them? By using a NavLink component instead of a plain <a> tag. The only special thing a NavLink component does is toggle its own active CSS class depending on whether its href matches the current navigation state.

Replace the <a> tag you added earlier in MainLayout.razor with the following (which is identical apart from the tag name):

<NavLink href="myorders" class="nav-tab">
    <img src="img/bike.svg" />
    <div>My Orders</div>
</NavLink>

Now you'll see that the link is correctly highlighted according to the navigation state:

Task 5: Displaying the list of orders

Switch back to the MyOrders.razor file. Once again we're going to inject an HttpClient so that we can query the backend for data. Add the following under the @page directive line:

@inject HttpClient HttpClient

Then add a @code block below the div element that makes an asynchronous request for the data we need:

@code {
    IEnumerable<OrderWithStatus> ordersWithStatus;

    protected override async Task OnParametersSetAsync()
    {
        ordersWithStatus = await HttpClient.GetFromJsonAsync<List<OrderWithStatus>>("orders");
    }
}

Let's make the UI display different output in three different cases:

• While we're waiting for the data to load

• If the user has never placed any orders

• If the user has placed one or more orders

It's simple to express this using @if/else blocks in Razor code. Replace the div element in MyOrders.razor with the following.

<div class="main">
    @if (ordersWithStatus == null)
    {
        <text>Loading...</text>
    }
    else if (!ordersWithStatus.Any())
    {
        <h2>No orders placed</h2>
        <a class="btn btn-success" href="">Order some pizza</a>
    }
    else
    {
        <text>TODO: show orders</text>
    }
</div>

Perhaps some parts of this code aren't obvious, so let's point out a few things.

What's a <text> element?

<text> is not an HTML element at all. Nor is it a component. Once the MyOrders component is compiled, the <text> tag won't exist in the result at all.

<text> is a special signal to the Razor compiler that you want to treat its contents as a markup string and not as C# source code. It's only used on rare occasions where the syntax would otherwise be ambiguous.

What's with href=""?

If <a href=""> (with an empty string for href) surprises you, remember that the browser will prefix the <base href="/"> value to all non-slash-prefixed URLs. So, an empty string is the correct way to link to the client app's root URL.

How does this render?

The asynchronous flow we've implemented above means the component will render twice: once before the data has loaded (displaying "Loading.."), and then once afterwards (displaying one of the other two outputs).

Why are we using OnParametersSetAsync?

Asynchronous work when applying parameters and property values must occur during the OnParametersSetAsync lifecycle event. We will be adding a parameter in a later session.

How can I reset the database?

If you want to reset your database to see the "no orders" case, simply delete pizza.db from the BlazingPizza.Server project and reload the page in your browser.

Rendering a grid of orders

Now we have all the data we need, we can use Razor syntax to render an HTML grid.

Replace the <text>TODO: show orders</text> line with the following:

<div class="list-group orders-list">
    @foreach (var item in ordersWithStatus)
    {
        <div class="list-group-item">
            <div class="col">
                <h5>@item.Order.CreatedTime.ToLongDateString()</h5>
                Items:
                <strong>@item.Order.Pizzas.Count()</strong>;
                Total price:
                <strong>£@item.Order.GetFormattedTotalPrice()</strong>
            </div>
            <div class="col">
                Status: <strong>@item.StatusText</strong>
            </div>
            <div class="col flex-grow-0">
                <a href="myorders/@item.Order.OrderId" class="btn btn-success">
                    Track &gt;
                </a>
            </div>
        </div>
    }
</div>

It looks like a lot of code, but there's nothing special here. It simply uses a @foreach to iterate over the ordersWithStatus and outputs a <div> for each one. The net result is as follows:

Task 6: Adding an Order Details display

If you click on the "Track" link buttons next to an order, the browser will attempt to navigate to myorders/<id> (e.g., http://example.com/myorders/37). Currently this will result in a "Sorry, there's nothing at this address." message because no component matches this route.

Once again we'll add a component to handle this. In the Pages folder, create a razor file called OrderDetails.razor, and replace the contents with the following:

@page "/myorders/{orderId:int}"

<div class="main">
    TODO: Show details for order @OrderId
</div>

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

This code illustrates how components can receive parameters from the router by declaring them as tokens in the @page directive. If you want to receive a string, the syntax is simply {parameterName}, which matches a [Parameter] name case-insensitively. If you want to receive a numeric value, the syntax is {parameterName:int}, as in the example above. The :int is an example of a route constraint. Other route constraints, such as bool, datetime and guid, are also supported.

If you're wondering how routing actually works, let's go through it step-by-step.

• When the app first starts up, code in Program.cs tells the framework to render App as the root component.

• The App component (in App.razor) contains a <Router>. Router is a built-in component that interacts with the browser's client-side navigation APIs. It registers a navigation event handler that gets notification whenever the user clicks on a link.

• Whenever the user clicks on a link, code in Router checks whether the destination URL is within the same SPA (i.e., whether it's under the <base href> value, and it matches some component's declared routes). If it's not, traditional full-page navigation occurs as usual. But if the URL is within the SPA, Router will handle it.

• Router handles it by looking for a component with a compatible @page URL pattern. Each {parameter} token needs to have a value, and the value has to be compatible with any constraints such as :int.

  • If there is a matching component, that's what the Router will render. This is how all the pages in your application have been rendering all along.

  • If there's no matching component, the router tries a full-page load in case it matches something on the server.

  • If the server chooses to re-render the client-side Blazor app (which is also what happens if a visitor is initially arriving at this URL and the server thinks it may be a client-side route), then Blazor concludes that nothing matches on either server or client, so it displays whatever NotFound content is configured.

Task 7: Polling for order details

The OrderDetails logic will be quite different from MyOrders. Instead of fetching the data just once when the component is instantiated, we'll poll the server every few seconds for updated data. This will make it possible to show the order status in (nearly) real-time, and later, to display the delivery driver's location on a moving map.

What's more, we'll also account for the possibility of OrderId being invalid. This might happen if:

• No such order exists
• Or later, when we've implemented authentication, if the order is for a different user and you're not allowed to see it

Before we can implement the polling, we'll need to add the following directives at the top of OrderDetails.razor, directly under the @page directive:

@using System.Threading
@inject HttpClient HttpClient

You've already seen @inject used with HttpClient, so you know what that is for. Plus, you'll recognize @using from the equivalent in regular .cs files, so this shouldn't be much of a mystery either. Unfortunately, Visual Studio does not yet add @using directives automatically in Razor files, so you do have to write them in yourself when needed.

Now you can implement the polling. Replace the @code block in the OrderDetails.razor file with the following:

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

    OrderWithStatus orderWithStatus;
    bool invalidOrder;
    CancellationTokenSource pollingCancellationToken;

    protected override void OnParametersSet()
    {
        // If we were already polling for a different order, stop doing so
        pollingCancellationToken?.Cancel();

        // Start a new poll loop
        PollForUpdates();
    }

    private async void PollForUpdates()
    {
        pollingCancellationToken = new CancellationTokenSource();
        while (!pollingCancellationToken.IsCancellationRequested)
        {
            try
            {
                invalidOrder = false;
                orderWithStatus = await HttpClient.GetFromJsonAsync<OrderWithStatus>($"orders/{OrderId}");
                StateHasChanged();

                if (orderWithStatus.IsDelivered)
                {
                    pollingCancellationToken.Cancel();
                }
                else
                {
                    await Task.Delay(4000);
                }
            }
            catch (Exception ex)
            {
                invalidOrder = true;
                pollingCancellationToken.Cancel();
                Console.Error.WriteLine(ex);
                StateHasChanged();
            }
        }
    }
}

The code is a bit intricate, so be sure to go through it carefully to understand each aspect of it before proceeding. Here are some notes:

• This uses OnParametersSet instead of OnInitialized or OnInitializedAsync. OnParametersSet is another component lifecycle method, and it fires when the component is first instantiated and any time its parameters change value. If the user clicks a link directly from myorders/2 to myorders/3, the framework will retain the OrderDetails instance and simply update its OrderId parameter in place.

  • As it happens, we haven't provided any links from one "my orders" screen to another, so the scenario never occurs in this application, but it's still the right lifecycle method to use in case we change the navigation rules in the future.

• We're using an async void method to represent the polling. This method runs for arbitrarily long, even while other methods run. async void methods have no way to report exceptions upstream to callers (because typically the callers have already finished), so it's important to use try/catch and do something meaningful with any exceptions that may occur.

• We're using CancellationTokenSource as a way of signalling when the polling should stop. Currently it stops if there's an exception, or once the order is delivered.

• We need to call StateHasChanged to tell Blazor that the component's data has (possibly) changed. The framework will then re-render the component. There's no way that the framework could know when to re-render your component otherwise, because it doesn't know about your polling logic.

Rendering the order details

OK, so we're getting the order details, and we're even polling and updating that data every few seconds. But we're still not rendering it in the UI. Let's fix that. Replace the div element in OrderDetails.razor with the following.

<div class="main">
    @if (invalidOrder)
    {
        <h2>Nope</h2>
        <p>Sorry, this order could not be loaded.</p>
    }
    else if (orderWithStatus == null)
    {
        <text>Loading...</text>
    }
    else
    {
        <div class="track-order">
            <div class="track-order-title">
                <h2>
                    Order placed @orderWithStatus.Order.CreatedTime.ToLongDateString()
                </h2>
                <p class="ml-auto mb-0">
                    Status: <strong>@orderWithStatus.StatusText</strong>
                </p>
            </div>
            <div class="track-order-body">
                TODO: show more details
            </div>
        </div>
    }
</div>

This accounts for the three main states of the component:

• If the OrderId value is invalid (i.e., the server reported an error when we tried to retrieve the data)

• If we haven't yet loaded the data

• If we have got some data to show

The last bit of UI we want to add is the actual contents of the order. To do this, we'll create another reusable component.

Create a new razor file called OrderReview.razor inside the Shared directory, and have it receive an Order and render its contents by replacing the file's contents with the following:

@foreach (var pizza in Order.Pizzas)
{
    <p>
        <strong>
            @(pizza.Size)"
            @pizza.Special.Name
            (£@pizza.GetFormattedTotalPrice())
        </strong>
    </p>

    <ul>
        @foreach (var topping in pizza.Toppings)
        {
            <li>+ @topping.Topping.Name</li>
        }
    </ul>
}

<p>
    <strong>
        Total price:
        £@Order.GetFormattedTotalPrice()
    </strong>
</p>

@code {
    [Parameter] public Order Order { get; set; }
}

Finally, back in OrderDetails.razor, replace the <div class="track-order-body"> element with the following:

<div class="track-order-body">
    <div class="track-order-details">
        <OrderReview Order="orderWithStatus.Order" />
    </div>
</div>

(Don't forget to add the extra div with CSS class track-order-details, as this is necessary for correct styling.)

Run the app and click Track on the My Orders page, and you will see that you have a functional order details display!

Task 8: See it update in realtime

The backend server will update the order status to simulate an actual dispatch and delivery process. To see this in action, try placing a new order, then immediately view its details.

Initially, the order status will be Preparing, then after 10-15 seconds the order status will change to Out for delivery, then 60 seconds later it will change to Delivered. Because OrderDetails polls for updates, the UI will update without the user having to refresh the page.

Task 9: Remember to Dispose!

If you deployed your app to production right now, bad things would happen. The OrderDetails logic starts a polling process, but doesn't end it. If the user navigated through hundreds of different orders (thereby creating hundreds of different OrderDetails instances), then there would be hundreds of polling processes left running concurrently, even though all except the last were pointless because no UI was displaying their results.

You can actually observe this chaos yourself as follows:

1. Navigate to "my orders"

2. Click "Track" on any order to get to its details

3. Click "Back" to return to "my orders"

4. Repeat steps 2 and 3 a lot of times (e.g., 20 times)

5. Now, open your browser's debugging tools and look in the network tab. You should see 20 or more HTTP requests being issued every few seconds, because there are 20 or more concurrent polling processes.

This is wasteful of client-side memory and CPU time, network bandwidth, and server resources.

To fix this, we need to make OrderDetails stop the polling once it gets removed from the display. This is simply a matter of using the IDisposable interface.

In OrderDetails.razor, add the following directive at the top of the file, underneath the other directives:

@implements IDisposable

Now if you try to compile the application, the compiler will complain: error CS0535: 'OrderDetails' does not implement interface member 'IDisposable.Dispose()'

Resolve this by adding the following method inside the @code block:

void IDisposable.Dispose()
{
    pollingCancellationToken?.Cancel();
}

The framework calls Dispose automatically when any given component instance is torn down and removed from the UI.

Once you've put in this fix, you can try again to start lots of concurrent polling processes, and you'll see they no longer keep running after the component is gone. Now, the only component that continues to poll is the one that remains on the screen.

Task 10: Automatically navigating to order details

Right now, once users place an order, the Index component simply resets its state and their order appears to vanish without a trace. This is not very reassuring for users. We know the order is in the database, but users don't know that.

It would be nice if, once the order is placed, the app automatically navigated to the "order details" display for that order. This is quite easy to do.

Switch back to your Index.razor file. Add the following directive at the top:

@inject NavigationManager NavigationManager

The NavigationManager lets you interact with URIs and navigation state. It has methods to get the current URL, to navigate to a different one, and more.

To use this, replace the PlaceOrder method at the bottom of Index.razor with the following so it calls NavigationManager.NavigateTo:

async Task PlaceOrder()
{
    var response = await HttpClient.PostAsJsonAsync("orders", order);
    var newOrderId = await response.Content.ReadFromJsonAsync<int>();
    order = new Order();
    NavigationManager.NavigateTo($"myorders/{newOrderId}");
}

Now as soon as the server accepts the order, the browser will switch to the "order details" display and begin polling for updates.