From 72641682440ba1e69ab7742ab1364f9256e4eabd Mon Sep 17 00:00:00 2001 From: Nick Craver Date: Fri, 19 Jul 2019 13:47:42 -0400 Subject: [PATCH 1/8] Codeblocks: highlighting This uses the new-ish ```razor Linguist style in code fences where appropriate. Also normalizes the various languages used in codeblock fences, e.g. C#, cs, csharp all to csharp. --- docs/01-components-and-layout.md | 16 ++++----- docs/02-customize-a-pizza.md | 24 ++++++------- docs/03-show-order-status.md | 30 ++++++++-------- docs/04-refactor-state-management.md | 10 +++--- docs/05-checkout-with-validation.md | 31 ++++++++--------- docs/06-authentication-and-authorization.md | 30 ++++++++-------- docs/07-javascript-interop.md | 18 +++++----- docs/08-templated-components.md | 38 ++++++++++----------- 8 files changed, 98 insertions(+), 99 deletions(-) diff --git a/docs/01-components-and-layout.md b/docs/01-components-and-layout.md index a10db867..326d0b4c 100644 --- a/docs/01-components-and-layout.md +++ b/docs/01-components-and-layout.md @@ -23,7 +23,7 @@ When you run the app, you'll see that it currently only contains a simple home p Open *Pages/Index.razor* in the **BlazingPizza.Client** project to see the code for the home page. -``` +```razor @page "/"

Blazing Pizzas

@@ -37,7 +37,7 @@ First we'll update the home page to display the list of available pizza specials Add a `@functions` block to *Index.razor* with a list field to keep track of the available specials: -```csharp +```razor @functions { List specials; } @@ -47,7 +47,7 @@ The code in the `@functions` block is added to the generated class for the compo To get the available list of specials we need to call an API on the backend. Blazor provides a preconfigured `HttpClient` through dependency injection that is already setup with the correct base address. Use the `@inject` directive to inject an `HttpClient` into the `Index` component. -``` +```razor @page "/" @inject HttpClient HttpClient ``` @@ -56,7 +56,7 @@ The `@inject` directive essentially defines a new property on the component wher Override the `OnInitAsync` method in the `@functions` block to retrieve the list of pizza specials. This method is part of the component lifecycle and is called when the component is initialized. Use the `GetJsonAsync()` method to handle deserializing the response JSON: -```csharp +```razor @functions { List specials; @@ -71,7 +71,7 @@ The `/specials` API is defined by the `SpecialsController` in the Server project Once the component is initialized it will render its markup. Replace the markup in the `Index` component with the following to list the pizza specials: -```html +```razor
    @if (specials != null) @@ -101,7 +101,7 @@ Next we'll setup the layout for app. Layouts in Blazor are also components. They inherit from `LayoutComponentBase`, which defines a `Body` property that can be used to specify where the body of the layout should be rendered. The layout component for our pizza store app is defined in *Shared/MainLayout.razor*. -```html +```razor @inherits LayoutComponentBase
    @@ -112,13 +112,13 @@ Layouts in Blazor are also components. They inherit from `LayoutComponentBase`, To apply a layout use the `@layout` directive. Typically this is done in a `_Imports.razor` file, which then gets inherited hierarchically. See *Pages/_Imports.razor*. -``` +```razor @layout MainLayout ``` Update the `MainLayout` component to define a top bar with a branding logo and a nav link for the home page: -```html +```razor @inherits LayoutComponentBase
    diff --git a/docs/02-customize-a-pizza.md b/docs/02-customize-a-pizza.md index 72cf5f7d..f60a6a6d 100644 --- a/docs/02-customize-a-pizza.md +++ b/docs/02-customize-a-pizza.md @@ -8,7 +8,7 @@ When the user clicks a pizza special a pizza customization dialog should pop up In *Pages/Index.razor* add the following `@onclick` handler to the list item for each pizza special: -```html +```razor @foreach (var special in specials) {
  • @@ -54,7 +54,7 @@ void ShowConfigurePizzaDialog(PizzaSpecial special) Update the `@onclick` handler to call the `ShowConfigurePizzaDialog` method instead of `Console.WriteLine`. -```html +```razor
  • ``` @@ -99,7 +99,7 @@ Add the following basic markup for the `ConfigurePizzaDialog`: Update *Pages/Index.razor* to show the `ConfigurePizzaDialog` when a pizza special has been selected. The `ConfigurePizzaDialog` is styled to overlay the current page, so it doesn't really matter where you put this code block. -```html +```razor @if (showingConfigureDialog) { @@ -116,7 +116,7 @@ Unfortunately at this point there's no functionality in place to close the dialo The user should be able to specify the size of their pizza. Add markup to the body of `ConfigurePizzaDialog` for a slider that lets the user specify the pizza size. This should replace the existing `
    ` element. -```html +```razor
    @@ -136,7 +136,7 @@ We want to make it so the value of the `Pizza.Size` will reflect the value of th If you wanted to implement two-way binding manually, you could do so by combining value and @onchange, as in the following code (which you don't actually need to put in your application, because there's an easier solution): -```html +```razor ``` @@ -158,7 +158,7 @@ But if we use `@bind` with no further changes, the behavior isn't exactly what w We'd prefer to see updates as the slider is moved. Data binding in Blazor allows for this by letting you specify what event triggers a change using the syntax `@bind:`. So, to bind using the `oninput` event instead do this: -```html +```razor ``` @@ -170,7 +170,7 @@ The pizza size should now update as you move the slider. The user should also be able to select additional toppings on `ConfigurePizzaDialog`. Add a list property for storing the available toppings. Initialize the list of available toppings by making an HTTP GET request to the `/toppings` API. -```csharp +```razor @inject HttpClient HttpClient
    @@ -191,7 +191,7 @@ The user should also be able to select additional toppings on `ConfigurePizzaDia Add the following markup in the dialog body for displaying a drop down list with the list of available toppings followed by the set of selected toppings. Put this inside the ``, below the existing `
    `." -```html +```razor
    @if (toppings == null) @@ -271,7 +271,7 @@ Add two parameters to the `ConfigurePizzaDialog` component: `OnCancel` and `OnCo Add `@onclick` event handlers to the `ConfigurePizzaDialog` that trigger the `OnCancel` and `OnConfirm` events. -```html +```razor
    @@ -339,7 +339,7 @@ Next we need to display the configured pizzas in the current order, calculate th Create a new `ConfiguredPizzaItem` component for displaying a configured pizza. It takes two parameters: the configured pizza, and an event for when the pizza was removed. -```html +```razor
    x
    @(Pizza.Size)" @Pizza.Special.Name
    @@ -362,7 +362,7 @@ Create a new `ConfiguredPizzaItem` component for displaying a configured pizza. Add the following markup to the `Index` component just below the main `div` to add a right side pane for displaying the configured pizzas in the current order. -```html +```razor
    @if (order.Pizzas.Any()) { diff --git a/docs/03-show-order-status.md b/docs/03-show-order-status.md index 75b78df8..f9de971a 100644 --- a/docs/03-show-order-status.md +++ b/docs/03-show-order-status.md @@ -41,7 +41,7 @@ If you want to, try changing the content in the `NotFoundContent` block in `App. As you can guess, we will make the link actually work by adding a component to match this route. Create a file in the `Pages` folder called `MyOrders.razor`, with the following content: -```html +```razor @page "/myorders"
    @@ -76,13 +76,13 @@ Now you'll see the links are correctly highlighted according to navigation state Switch back to the `MyOrders` component code. 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: -```html +```razor @inject HttpClient HttpClient ``` Then add a `@functions` block that makes an asynchronous request for the data we need: -```csharp +```razor @functions { List ordersWithStatus; @@ -101,7 +101,7 @@ Let's make the UI display different output in three different cases: It's simple to express this using `@if/else` blocks in Razor code. Update your component code as follows: -```html +```razor @page "/myorders" @inject HttpClient HttpClient @@ -159,7 +159,7 @@ Now we have all the data we need, we can use Razor syntax to render an HTML grid Replace the `TODO: show orders` code with the following: -```html +```razor
    @foreach (var item in ordersWithStatus) { @@ -194,7 +194,7 @@ If you click on the "Track" link buttons next to an order, the browser will atte Once again we'll add a component to handle this. In the `Pages` directory, create a file called `OrderDetails.razor`, containing: -```html +```razor @page "/myorders/{orderId:int}"
    @@ -231,7 +231,7 @@ What's more, we'll also account for the possibility of `OrderId` being invalid. Before we can implement the polling, we'll need to add the following directives at the top of `OrderDetails.razor`, typically directly under the `@page` directive: -```html +```razor @using System.Threading @inject HttpClient HttpClient ``` @@ -240,7 +240,7 @@ You've already seen `@inject` used with `HttpClient`, so you know what that is f Now you can implement the polling. Update your `@functions` block as follows: -```cs +```razor @functions { [Parameter] int OrderId { get; set; } @@ -294,7 +294,7 @@ The code is a bit intricate, so be sure to go through it carefully and be sure t 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. Update your `
    ` as follows: -```html +```razor
    @if (invalidOrder) { @@ -336,7 +336,7 @@ The last bit of UI we want to add is the actual contents of the order. To do thi Create a new file, `OrderReview.razor` inside the `Shared` directory, and have it receive an `Order` and render its contents as follows: -```html +```razor @foreach (var pizza in Order.Pizzas) {

    @@ -369,7 +369,7 @@ Create a new file, `OrderReview.razor` inside the `Shared` directory, and have i Finally, back in `OrderDetails.razor`, replace text `TODO: show more details` with your new `OrderReview` component: -```html +```razor

    @@ -407,7 +407,7 @@ To fix this, we need to make `OrderDetails` stop the polling once it gets remove In `OrderDetails.razor`, add the following directive at the top of the file, underneath the other directives: -```html +```razor @implements IDisposable ``` @@ -419,7 +419,7 @@ error CS0535: 'OrderDetails' does not implement interface member 'IDisposable.Di Resolve this by adding the following method inside the `@functions` block: -```cs +```csharp void IDisposable.Dispose() { pollingCancellationToken?.Cancel(); @@ -438,7 +438,7 @@ It would be nice if, once the order is placed, you navigated to the details disp Switch back to your `Index` component code. Add the following directive at the top: -``` +```razor @inject IUriHelper UriHelper ``` @@ -446,7 +446,7 @@ The `IUriHelper` lets you interact with URIs and navigation state. It has method To use this, update the `PlaceOrder` code so it calls `UriHelper.NavigateTo`: -```cs +```csharp async Task PlaceOrder() { var newOrderId = await HttpClient.PostJsonAsync("orders", order); diff --git a/docs/04-refactor-state-management.md b/docs/04-refactor-state-management.md index 23bd0aa1..b2f318be 100644 --- a/docs/04-refactor-state-management.md +++ b/docs/04-refactor-state-management.md @@ -14,7 +14,7 @@ We're going to fix this bug by introducing something we've dubbed the *AppState Create a new class called `OrderState` in the Client Project root directory - and register it as a scoped service in the DI container. Much like an ASP.NET Core method, a Blazor application has a `Startup` class and a `ConfigureServices` method. Add the service in `Startup.cs`. -```C# +```csharp public void ConfigureServices(IServiceCollection services) { services.AddScoped(); @@ -27,7 +27,7 @@ note: the reason why we choose scoped over singleton is for symmetry with a serv Now that this type is registered in DI, we can `@inject` it into the Index page. -``` +```razor @page "/" @inject HttpClient HttpClient @inject OrderState OrderState @@ -44,7 +44,7 @@ Now, let's add properties and methods to this class that will represent and mani Move the `configuringPizza`, `showingConfigureDialog` and `Order` to be properties on the `OrderState` class. I like to make them `private set` so they can only be manipulated via methods on `OrderState`. -```C# +```csharp public class OrderState { public bool ShowingConfigureDialog { get; private set; } @@ -57,7 +57,7 @@ public class OrderState Now let's move some of the methods from the `Index` to `OrderState`. We won't move PlaceOrder into OrderState because that triggers a navigation, so instead we'll just add a ResetOrder method. -```C# +```sharp public void ShowConfigurePizzaDialog(PizzaSpecial special) { ConfiguringPizza = new Pizza() @@ -101,7 +101,7 @@ Remember to remove the corresponding methods from `Index.razor`. You must also r At this point it should be possible to get the `Index` component compiling again by updating references to refer to various bits attached to `OrderState`. For example, the remaining `PlaceOrder` method in `Index.razor` may look something like this: -```cs +```csharp async Task PlaceOrder() { var newOrderId = await HttpClient.PostJsonAsync("orders", OrderState.Order); diff --git a/docs/05-checkout-with-validation.md b/docs/05-checkout-with-validation.md index cd3265d2..4abd264f 100644 --- a/docs/05-checkout-with-validation.md +++ b/docs/05-checkout-with-validation.md @@ -8,7 +8,7 @@ It's time to fix this by adding a "checkout" screen that requires customers to e Start by adding a new page component, `Checkout.razor`, with a `@page` directive matching the URL `/checkout`. For the initial markup, let's display the details of the order using your `OrderReview` component: -```html +```razor
    @@ -25,7 +25,7 @@ Start by adding a new page component, `Checkout.razor`, with a `@page` directive To implement `PlaceOrder`, copy the method with that name from `Index.razor` into `Checkout.razor`: -```cs +```razor @functions { async Task PlaceOrder() { @@ -40,7 +40,7 @@ As usual, you'll need to `@inject` values for `OrderState`, `HttpClient`, and `U Next, let's bring customers here when they try to submit orders. Back in `Index.razor`, make sure you've deleted the `PlaceOrder` method, and then change the order submission button into a regular HTML link to the `/checkout` URL, i.e.: -```html +```razor Order > @@ -56,7 +56,7 @@ We've now got a good place to put some UI for entering a delivery address. As us Create a new component in the `BlazingPizza.Client` project's `Shared` folder called `AddressEditor.razor`. It's going to be a general way to edit `Address` instances, so have it receive a parameter of this type: -```cs +```razor @functions { [Parameter] Address Address { get; set; } } @@ -64,7 +64,7 @@ Create a new component in the `BlazingPizza.Client` project's `Shared` folder ca The markup here is going to be a bit tedious, so you probably want to copy and paste this. We'll need input elements for each of the properties on an `Address`: -```html +```razor
    @@ -114,7 +114,7 @@ The markup here is going to be a bit tedious, so you probably want to copy and p Finally, you can actually use your `AddressEditor` inside the `Checkout.razor` component: -```html +```razor
    ... leave this div unchanged ... @@ -144,7 +144,7 @@ As yet, customers can still leave the "delivery address" fields blank and merril As such it's usually best to start by implementing server-side validation, so you know your app is robust no matter what happens client-side. If you go and look at `OrdersController.cs` in the `BlazingPizza.Server` project, you'll see that this API endpoint is decorated with the `[ApiController]` attribute: -```cs +```csharp [Route("orders")] [ApiController] public class OrdersController : Controller @@ -158,7 +158,7 @@ public class OrdersController : Controller Open `Address.cs` from the `BlazingPizza.Shared` project, and put a `[Required]` attribute onto each of the properties except for `Id` (which is autogenerated, because it's the primary key) and `Line2`, since not all addresses need a second line. You can also place some `[MaxLength]` attributes if you wish, or any other `DataAnnotations` rules: -```cs +```csharp using System.ComponentModel.DataAnnotations; namespace BlazingPizza @@ -186,7 +186,6 @@ namespace BlazingPizza public string PostalCode { get; set; } } } - ``` Now, recompile and run your application, and you should be able to observe the validation rules being enforced on the server. If you try to submit an order with a blank delivery address, then the server will reject the request and you'll see an HTTP 400 ("Bad Request") error in the browser's *Network* tab: @@ -205,7 +204,7 @@ The way Blazor's forms and validation system works is based around something cal One of the most important built-in UI components for data entry is the `EditForm`. This renders as an HTML `` tag, but also sets up an `EditContext` to track what's going on inside the form. To use this, go to your `Checkout.razor` component, and wrap an `EditContext` around the whole of the contents of the `main` div: -```html +```razor
    @@ -223,7 +222,7 @@ You can have multiple `EditForm` components at once, but they can't overlap (bec Let's start by displaying validation messages in a very basic (and not very attractive) way. Inside the `EditForm`, right at the bottom, add the following two components: -```html +```razor ``` @@ -238,7 +237,7 @@ If you ran your application now, you could still submit a blank form (and the se Next, instead of triggering `PlaceOrder` directly from the button, you need to trigger it from the `EditForm`. Add the following `OnValidSubmit` attribute onto the `EditForm`: -```html +```razor ``` @@ -254,7 +253,7 @@ Obviously it's pretty disgusting to display all the validation messages so far a Start by removing the `` component entirely. Then, switch over to `AddressEditor.razor`, and add separate `` components next to each of the form fields. For example, -```html +```razor
    @@ -274,7 +273,7 @@ Now things look a lot better: If you want, you can improve the readability of the messages by specifying custom ones. For example, instead of displaying *The City field is required*, you could go to `Address.cs` and do this: -```cs +```csharp [Required(ErrorMessage = "How do you expect to receive the pizza if we don't even know what city you're in?"), MaxLength(50)] public string City { get; set; } ``` @@ -290,7 +289,7 @@ To improve on this, you can replace the low-level HTML input elements with Blazo Go back to `AddressEditor.razor` once again. Replace each of the `` elements with a corresponding ``. For example, -```html +```razor
    @@ -316,7 +315,7 @@ Currently, if it takes a while for the form post to reach the server, the user c To check your solution works, you might want to slow down the server by adding the following line at the top of `PlaceOrder()` inside `OrdersController.cs`: -```cs +```csharp await Task.Delay(5000); // Wait 5 seconds ``` diff --git a/docs/06-authentication-and-authorization.md b/docs/06-authentication-and-authorization.md index e8deb80d..d96d2f26 100644 --- a/docs/06-authentication-and-authorization.md +++ b/docs/06-authentication-and-authorization.md @@ -35,7 +35,7 @@ Server-side Blazor comes with a built-in `AuthenticationStateProvider` that hook To start, create a new class named `ServerAuthenticationStateProvider` in the root of your `BlazingPizza.Client` project: -```cs +```csharp using System.Security.Claims; using System.Threading.Tasks; using Microsoft.AspNetCore.Components; @@ -58,7 +58,7 @@ namespace BlazingPizza.Client ... then register this as a DI service in `Startup.cs`: -```cs +```csharp public void ConfigureServices(IServiceCollection services) { services.AddScoped(); @@ -71,7 +71,7 @@ public void ConfigureServices(IServiceCollection services) To flow the authentication state information through your app, you need to add one more component. In `App.razor`, surround the `` with a ``: -```html +```razor Page not found @@ -87,7 +87,7 @@ Finally, you're ready to display something in the UI! Create a new component called `LoginDisplay` in the client project's `Shared` folder, containing: -```html +```razor