03-web-ui-with-asp-net-blazor-wasm.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating Web UI with ASP.NET Blazor WASM\n",
    "\n",
    "Purpose of this section is not to make the reader proficient in ASP.NET Blazor, but rather to provide the basic information needed to start building client side rendered web apps."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The overarching goal is rather to teach ***how to learn*** to work with the Web UI frameworks. How to pick up pieces of relevant information when quick solutions are needed, and how to assemble them into some working prototype. \n",
    "\n",
    "This notebook will focus on using Blazor to create web UIs, although there are other legitimate choices available."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Blazor high level overview\n",
    "\n",
    "Blazor allows to render `html` documents using \"Razor components\".\n",
    "\n",
    "Razor components allows to do scripting using using C#. Scripting can be used for assembling the `html` based on data, making `HTTP` calls to fetch the data dynamically or writing event handlers to give page additional interactions.\n",
    "\n",
    "In this example - C# is compiled into into web assembly (WASM) and executed on the client side. There are other rendering modes like hybrid or server side that can be used with Blazor.\n",
    "\n",
    "`App.razor` acts as a root component. It is executed initially and other components can be rendered recursively if they are referenced in the root component. In the default template there is `Routes.razor` component which add routing capability to the web application. It is added by adding `<Routes />` in the root component. Other components are added the same way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create Blazor project\n",
    "\n",
    "`dotnet new blazorwasm-empty -n <project name>`. There are other Blazor templates among the `dotnet new` templates. Other Blazor templates might have different rendering methods."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Rendering static data\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First create a file `EventsData.cs` in the root namespace of the solution as shown in the example. It will provide some static data that can be used to render into `html`.\n",
    "\n",
    "```csharp\n",
    "public class EventsData\n",
    "{\n",
    "    public static List<Event> Events { get; set; }\n",
    "\n",
    "    static EventsData()\n",
    "    {\n",
    "        Events = new List<Event>();\n",
    "\n",
    "        for (int i = 1; i <= 10; i++)\n",
    "        {\n",
    "            Events.Add(new Event\n",
    "            {\n",
    "                Id = i,\n",
    "                Title = $\"Event {i}\",\n",
    "                Description = $\"Description for event {i}\",\n",
    "                Date = DateTime.Now.AddDays(i)\n",
    "            });\n",
    "        }\n",
    "    }\n",
    "}\n",
    "\n",
    "public class Event\n",
    "{\n",
    "    public int Id { get; set; }\n",
    "    public string Title { get; set; }\n",
    "    public string Description { get; set; }\n",
    "    public DateTime Date { get; set; }\n",
    "}\n",
    "```\n",
    "\n",
    "Then add a `EventList.razor` component in the `Pages/` directory.\n",
    "\n",
    "```csharp\n",
    "@page \"/events\"\n",
    "\n",
    "<div>\n",
    "    @foreach (var eventas in EventsData.Events)\n",
    "    {\n",
    "        <div>\n",
    "            <h5 class=\"card-title\">@eventas.Title</h5>\n",
    "            <p class=\"card-text\">@eventas.Description</p>\n",
    "        </div>\n",
    "    }\n",
    "</div>\n",
    "```\n",
    "\n",
    "Upon starting web app and navigating to to `/events` it should display a list of 10 events that were generated in the `EventsData` class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively code generating the events data can be placed inside the `EventsList.razor` component itself:\n",
    "\n",
    "```csharp\n",
    "@page \"/events\"\n",
    "\n",
    "<div>\n",
    "    @foreach (var eventas in events)\n",
    "    {\n",
    "        <div>\n",
    "            <h5 class=\"card-title\">@eventas.Title</h5>\n",
    "            <p class=\"card-text\">@eventas.Description</p>\n",
    "        </div>\n",
    "    }\n",
    "</div>\n",
    "\n",
    "\n",
    "@code\n",
    "{\n",
    "    private List<Event> events = new List<Event>();\n",
    "\n",
    "    protected override void OnInitialized()\n",
    "    {\n",
    "        for (int i = 0; i < 10; i++)\n",
    "        {\n",
    "            events.Add(new Event\n",
    "                {\n",
    "                    Id = i,\n",
    "                    Title = $\"Event {i}\",\n",
    "                    Description = $\"Description {i}\"\n",
    "                });\n",
    "        }\n",
    "    }\n",
    "\n",
    "    class Event\n",
    "    {\n",
    "        public int Id { get; set; }\n",
    "        public string Title { get; set; }\n",
    "        public string Description { get; set; }\n",
    "    }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Loading static assets\n",
    "\n",
    "`wwwroot` directory contains static assets. These assets are not compiled or processed in other way, but just served as downloadable assets when the web app runs. Files like `css` stylesheets, `js` scripts or images typically placed in this directory.\n",
    "\n",
    "There is default `wwwroot/css/app.css` stylesheet which contains several default styles. To add an additional stylesheet first create a file and the add line in `wwwroot/index.html` `<head>` element:\n",
    "\n",
    "```css\n",
    "// wwwroot/css/app.css\n",
    ".card-title {\n",
    "    font-size: 1.5em;\n",
    "    font-weight: bold;\n",
    "}\n",
    "```\n",
    "\n",
    "```html\n",
    "<!-- Added to wwwroot/index.html head element -->\n",
    "<link href=\"css/card.css\" rel=\"stylesheet\" />\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Images can be added similarly: upon placing image `cheems_dancing.gif` to `wwwroot/cheems_dancing.gif` it can be referenced from the Razor components with simple `html` element: `<img src=\"/cheems_dancing.gif\" alt=\"Cheems dancing\" />`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Navigating between pages\n",
    "\n",
    "In `html` navigation between components can be done via `<a>` element. In the `href` attribute of the `<a>` element the path to the page should be placed and upon clicking the children of the element browser will navigate to the page in `href` attribute.\n",
    "\n",
    "In the previous example a page was created with path `/events`. The path was specified in the `@page` annotation at the top of the file. By the adding `<a href=\"/events\">Go to events</a>` line in the `Index.razor`, it will cause a link to appear in the root page of the web application. Upon clicking the link, the browser will navigate to the `/events` page."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively navigation can be done dynamically from the C# code, using the `NavigationManager` class. \n",
    "\n",
    "`NavigationManager` must be injected into the component using the `@inject` annotation at the top of the component:\n",
    "```@inject NavigationManager Navigation```\n",
    "\n",
    "A method in the `@code` block can then be created which uses `NavigateTo` method of `NavigationManager` class to invoke the navigation:\n",
    "```cs\n",
    "@code {\n",
    "    private void NavigateToEvents()\n",
    "    {\n",
    "        Navigation.NavigateTo(\"/events\");\n",
    "    }\n",
    "}\n",
    "```\n",
    "\n",
    "Created `C#` method can then be bound to some `html` component like button:\n",
    "```html\n",
    "<button @onclick=\"NavigateToEvents\">Go to events</button>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Razor Components\n",
    "\n",
    "A component can be created that does not represent the whole page but rather an isolated part of the code. Create the file `Components/Event.razor`:\n",
    "```html\n",
    "<div>\n",
    "    <h5 class=\"card-title\">Event name</h5>\n",
    "    <p class=\"card-text\">Event description</p>\n",
    "</div>\n",
    "```\n",
    "\n",
    "Then in the page where you would like to use this component add:\n",
    "```cs\n",
    "@using <root namespace>.Components\n",
    "\n",
    "<Event />\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Components can be made more sophisticated by passing them some properties. In this way we could upgrade the `Event.razor` component so it would not use static data for name and description, but would rather display the data that was passed to it.\n",
    "\n",
    "This is achieved by using `[Parameter]` attribute. Change `Event.razor` component to the following:\n",
    "```html\n",
    "<div>\n",
    "    <h5 class=\"card-title\">@Title</h5>\n",
    "    <p class=\"card-text\">@Description</p>\n",
    "</div>\n",
    "\n",
    "@code {\n",
    "    [Parameter]\n",
    "    public string Title { get; set; }\n",
    "\n",
    "    [Parameter]\n",
    "    public string Description { get; set; }\n",
    "}\n",
    "```\n",
    "\n",
    "Now it can be called like and it will display `Some description` and `Some title` that were passed here instead of hardcoded values:\n",
    "```csharp\n",
    "<Event Description=\"Some description\" Title=\"Some title\" />\n",
    "```\n",
    "\n",
    "Variables can also be passed like this using the standard `@` notation:\n",
    "```csharp\n",
    "<Event Description=\"@Description\" Title=\"@Title\" />\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Calling an API\n",
    "\n",
    "`HttpClient` can be used to make calls to APIs. In order to be able to inject `HttpClient` it should be first registered to the dependency injection container:\n",
    "\n",
    "```csharp\n",
    "// localhost:1111 should be replaced with the address of your API instead\n",
    "builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(\"http://localhost:1111\") });\n",
    "```\n",
    "\n",
    "After this the `HttpClient` can be injected into the Component:\n",
    "```csharp\n",
    "@inject HttpClient HttpClient\n",
    "```\n",
    "\n",
    "After this the variable named `HttpClient` can be used in `@code` block to call the API."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An example how the `EventsList.razor` page component can be modified to fetch events list from an API:\n",
    "\n",
    "```csharp\n",
    "@page \"/events\"\n",
    "@using EventsWebWasm.Components\n",
    "@inject HttpClient HttpClient\n",
    "\n",
    "@foreach (var @eventas in events)\n",
    "{\n",
    "    <Event Title=\"@eventas.Title\" Description=\"@eventas.Description\" />\n",
    "}\n",
    "\n",
    "@code\n",
    "{\n",
    "    private List<Event> events = new List<Event>();\n",
    "\n",
    "    protected override async Task OnInitializedAsync()\n",
    "    {\n",
    "        events = await HttpClient.GetFromJsonAsync<List<Event>>(\"api/Events\");\n",
    "    }\n",
    "\n",
    "    class Event\n",
    "    {\n",
    "        public int Id { get; set; }\n",
    "        public string Title { get; set; }\n",
    "        public string Description { get; set; }\n",
    "    }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### CORS\n",
    "\n",
    "After calling an API from the user's browser it is most likely going to be blocked by the browser's CORS policy. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) is a security mechanism that prevents browser scripts to call APIs that do not specifically allow calls from that origin. \n",
    "\n",
    "Using ASP.NET cross-origin requests can be enabled by doing the following **in the api API project**:\n",
    "1. Register the required services in Dependency Injection container: `builder.Services.AddCors();`.\n",
    "2. Registered the required middlewares:\n",
    "```csharp\n",
    "app.UseCors(builder =>\n",
    "{\n",
    "    // This should be full URL of WASM web application including the port\n",
    "    // I.e. \"http://localhost:5199\"\n",
    "    builder.WithOrigins(\"http://<wasm application url>\");\n",
    "    builder.AllowAnyMethod();\n",
    "    builder.AllowAnyHeader();\n",
    "});\n",
    "```\n",
    "\n",
    "This in the example is a very permissive policy, but it can be narrowed down and be made more secure by using the `builder` variable (as named in the example)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Forms\n",
    "\n",
    "Up until this point we only dealt with only displaying the existing data. In practice the data will most likely have to be created by users, rather than automatically. This can be done using the forms. Forms in Blazor are based on standard html `<form>` element.\n",
    "\n",
    "Consider the following code:\n",
    "```csharp\n",
    "@page \"/eventform\"\n",
    "@inject HttpClient HttpClient\n",
    "\n",
    "<h1>Create Event</h1>\n",
    "\n",
    "<form @onsubmit=\"OnSubmit\">\n",
    "    <label for=\"title\">Title</label>\n",
    "    <input type=\"text\" id=\"title\" @bind=\"Model.Title\" />\n",
    "    <br />\n",
    "    <label for=\"description\">Description</label>\n",
    "    <input type=\"text\" id=\"description\" @bind=\"Model.Description\" />\n",
    "    <br />\n",
    "    <button type=\"submit\">Create</button>\n",
    "</form>\n",
    "\n",
    "@code {\n",
    "    private CreateEventInput? Model { get; set; } = new CreateEventInput();\n",
    "\n",
    "    private async Task OnSubmit() {\n",
    "        await HttpClient.PostAsJsonAsync(\"api/Events\", new CreateEventInput { Title = \"New Event\", Description = \"New Event Description\" });\n",
    "        Model = new();\n",
    "    }\n",
    "\n",
    "    class CreateEventInput\n",
    "    {\n",
    "        public string Title { get; set; }\n",
    "        public string Description { get; set; }\n",
    "    }\n",
    "}\n",
    "```\n",
    "\n",
    "`@inject HttpClient HttpClient` is being injected because the new created event will be sent to the API for processing. It is intended that the event later will be fetched from the API.\n",
    "\n",
    "`<form @onsubmit=\"OnSubmit\">` is used to define `html` form. Instead of standard html submit behavior, a custom submit handler is registered via `@onsubmit` attribute, which calls `OnSubmit` method from `@code` block.\n",
    "\n",
    "Inputs from the form are bound to `Model` property using the `@bind` attributes on html `input` elements."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".NET (C#)",
   "language": "C#",
   "name": ".net-csharp"
  },
  "polyglot_notebook": {
   "kernelInfo": {
    "defaultKernelName": "csharp",
    "items": [
     {
      "aliases": [],
      "languageName": "csharp",
      "name": "csharp"
     }
    ]
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}