Adliance.AspNetCore.Buddy.GuiKit 10.2.0.14

Adliance.AspNetCore.Buddy.GuiKit

The GuiKit Buddy provides a set of UI components, tag helpers, and static assets (CSS, JS, fonts) for building consistent ASP.NET Core web applications.

Features

• Bundled and minified CSS and JavaScript assets
• Razor tag helpers for common UI components
• Application Insights integration helper

Setup

Register the services in your ASP.NET Core application:

using Adliance.AspNetCore.Buddy.GuiKit.Extensions;

// In Program.cs or Startup.ConfigureServices:
services.AddApplicationInsightsIfConfigured();

AddApplicationInsightsIfConfigured reads the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable and configures Application Insights telemetry automatically if it is present. It also registers AppInsightsJavaScript, which can be injected into Razor views to render the Application Insights JavaScript snippet.

Serve static files with app.UseGuiKitStaticFiles() instead of app.UseStaticFiles(), so browsers cache them: files requested with a version (?v=..., like the CSS and JavaScript of GuiKit's layouts) for a year, and GuiKit's fonts and images for a week. The version is the app's InformationalVersion (AppVersion.Current, which the app's own files can use as well: href="~/styles.css?v=@AppVersion.Current"), so a new build of the app (eg. with an updated GuiKit) loads them again. During development, browsers check every file for changes instead.

Layout

GuiKit ships a base layout, _AgkLayout, with GuiKit's CSS and JavaScript, FontAwesome, the Application Insights snippet and the htmx configuration for a Content Security Policy. An app's own layout builds on it:

@{
    Layout = "_AgkLayout";
}

@section Header
{
    <title>My App</title>
}

<partial name="_Navigation"/>
<main>
    @RenderBody()
</main>

Its sections are Header (additional content of <head>) and Scripts (additional scripts at the end of <body>), both optional. AgkStylesheets and AgkScripts replace GuiKit's own min.css/min.js, eg. with a theme's bundle that already contains them - the MADx layouts (_MadxCommonLayout, _MadxLoginLayout) build on _AgkLayout that way.

Tag Helpers

Add the tag helpers to your _ViewImports.cshtml:

@addTagHelper *, Adliance.AspNetCore.Buddy.GuiKit

Styling

Layout

• <section> (within <main>) lays out panels next to each other, <fieldset> does the same for form elements within a panel. Up to 4 children share a row equally (1 child takes the full width, 2 half of it, 3 a third, ...). How many columns there are at most depends on the width of the section/fieldset itself (container queries), not on the width of the screen.
• A <select> written by hand (eg. into <agk-form-element>) gets the same dropdown arrow as <agk-select> when it's wrapped into a <div class="select">; without it, it keeps the browser's own arrow.

Page transitions

Navigating between pages of the app shows a subtle transition: the nav stays in place and the content fades out and back in. It uses the browser's cross-document view transitions (no JavaScript needed); in browsers without support, and for users who reduce motion in their OS settings, pages simply switch as before. It can be tuned with --agk-page-transition-duration, or switched off with @view-transition { navigation: none; } in the app's own CSS.

Content Security Policy

GuiKit works with a strict Content Security Policy, without 'unsafe-inline' or 'unsafe-eval':

• app.UseGuiKitContentSecurityPolicy() sends a strict policy with every response (register it before static files). It only allows the app's own origin plus the request's nonce for inline scripts and styles, and Application Insights if it's configured. More sources can be allowed, or the policy tried out without blocking anything:

  app.UseGuiKitContentSecurityPolicy(options =>
  {
      options.Add("img-src", "https://images.example.com");
      options.ReportOnly = true;
  });
  

• Apps that build their own policy use HttpContext.GetGuiKitCspNonce() (in Adliance.AspNetCore.Buddy.GuiKit.Extensions), a random nonce for the current request, eg. script-src 'self' 'nonce-{nonce}'; style-src 'self' 'nonce-{nonce}'.
• Every inline <script> in a view that uses GuiKit's tag helpers automatically gets that nonce, and so do GuiKit's own inline scripts (eg. of <agk-chart>, or the Application Insights snippet).
• htmx inserts scripts and styles of the content it loads, which need the nonce as well - the MADx layouts already configure this, other layouts add <meta name="htmx-config" content='{"inlineScriptNonce":"@Context.GetGuiKitCspNonce()","inlineStyleNonce":"@Context.GetGuiKitCspNonce()"}'/>.
• GuiKit itself sets no inline styles (a chart's height, for example, is set by its JavaScript).

Theming

All styles are built from CSS variables, which are defined (and documented) in css/tokens.css. They are named --agk-{component}-{property}[-{variant}], eg. --agk-button-background-hover or --agk-input-padding-block-lg. Variables starting with --_ are private to a component and not meant to be overridden.

Override them on :root, eg.:

:root {
    --agk-color-primary: #004488;
    --agk-button-radius: 0;
}

All GuiKit styles are in cascade layers (agk.reset, agk.tokens, agk.base, agk.components, agk.layout, agk.overlays, agk.theme). CSS of an app that isn't in a layer always wins over them, regardless of its specificity - so no !important is needed to override GuiKit styles. Themes that are distributed as a package (like the MADx one) put their overrides into @layer agk.theme { ... }.

Application Insights JavaScript

To inject the Application Insights JavaScript snippet into your layout, inject AppInsightsJavaScript and render the script tag:

@inject Adliance.AspNetCore.Buddy.GuiKit.AppInsightsJavaScript AppInsightsJavaScript

@Html.Raw(AppInsightsJavaScript.Script)