Expo for Monarch Apps: A Client-Side Guide

Estimated reading time: 6 minutes

Interactive Applications include at least one .NET Website Project.

.NET Website Projects implements the User Interface Pages of the Application.

To present a rich User Interface on a Browser, most Websites rely on Client-Side JavaScript and CSS libraries that are downloaded from the Application server, and are cached in the browser for optimal performance.

The Website Server-Side in ASNA Monarch Base Applications relies on ASNA.QSys.Expo. The Client-Side is conveniently called ASNA QSys Expo Web Content.

Client-Side Library, Web Content and Client-Side Framework are all terms used in association to Client-Side resources on a Website.

To simplify, in the next paragraphs, we will refer to ASNA QSys Expo Web Content simply as the Expo Web Content.

Delivering Expo Web Content

Web Content is frequently stored in a folder structure at the root of the Website.

Typically, .NET Websites have the following root folder structure:

+ wwwrooot
    - css               Application Specific CSS
    - js                Application Specific JavaScript  
    + lib
        + asna-expo     Expo Web Content
            + audio
            + css
            + js
        + (other optional third party libraries)

An Application response to a Page request will be generated by the Web server with a content similar to the following HTML:

<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, minimum-scale=1.0, maximum-scale=1.0" />
    <meta name="google" content="notranslate" />
    <title>Application title</title>
    <link rel="stylesheet" href="/lib/asna-expo/css/expo.css" />
    <link rel="stylesheet" href="/css/site.css" />
    </head>

    <body>
        
        <form id="MonarchForm" method="post">
            .
            .       <!-- Active Record formats -->
            .
        </form>


        <script type="module">
            import { Page } from '../lib/asna-expo/js/asna.js';

            Page.init({ formId: 'MonarchForm' });
        </script>

        
    </body>
</html>

Note how the head section requests two Cascading Style Sheets: expo.css and site.css. The first one is defined as part of Expo Web Content, the second as the Application specific CSS.

The order of appearance of the CSS requests in the Page is important.

Note how at the end of the body section, there is a script section of type “module”, with two lines:

<script type="module">
    import { Page } from '../lib/asna-expo/js/asna.js';

    Page.init({ formId: 'MonarchForm' });
</script>

ASNA Monarch Base applications use JavaScript modules to implement Client-Side logic. The Page symbol is imported from the asna.js script file and initialized as soon as the module(s) are loaded.

So far the assumption is that the Expo Web Content exists in the wwwroot folder structure.

How does the Expo Web Content get to the `wwwroot` folder structure?

ASP.NET Core supports LibMan.

LibMan is a lightweight, client-side library acquisition tool. LibMan downloads popular libraries and frameworks from the file system or from a CDN.

ASNA Monarch Base applications use jsDelivr as the CDN to populate the Website Client-Side folder structure with a copy of Expo Web Content.

libman.json file

The libman.json configuration file in the Application Website Project defines how Expo Web Content is delivered to the Website.

The following is the typical content of libman.json:

{
  "version": "1.0",
  "libraries": [
    {
      "provider": "jsdelivr",
      "library": "asnaqsys/asna-qsys-expo-web-content@2.1.4",
      "destination": "wwwroot/lib/asna-expo"
    }
  ]
}

The configuration:

Specifies "jsDelivr" as the Library provider.
Specifies the source location as: asnaqsys organization, asna-qsys-expo-web-content as the repository name and 2.1.4 as the release requested.
If the content is found, it should be copied to wwwroot/lib/asna-expo.

jsDelivr can discover the available releases in this page.

LibMan tells jsDelivr to look in npm, GitHub, and WordPress package managers to search for the library.

Microsoft Visual Studio Integration

Visual Studio provides:

Restore Client-side libraries on Build.
Output log Window for “Library Manager” related events.
Manual Clear and Restore operations.

The Visual Studio LibMan integration is enabled when the Website Project has the following nuget package installed:

Microsoft.Web.Library.Manager.Build.dll

Visual Studio provides context-menu options when the libman.json file is selected in Solution Explorer.

Menu options:

Restore Client-side Libraries - activate LibMan and request files using configured CDN.
Clean Client-side Libraries - delete output library folder structure in wwwroot.
Enable / Disable Client-side Libraries on Build - Install / Uninstall Microsoft.Web.Library.Manager.Build.dll nuget package.

How often should Client-side Libraries be Restored?

As fast as jsDelivr is, there is a price to pay in time to complete request and have your system copy the files to the destination (it may take around 3 seconds, depending on your environment).

When the Website is created by Monarch, LibMan is enabled and EVERY TIME the Website is built, the Expo Web Content will be requested.

During development, it is recommended to:

Disable Client-side Libraries on Build when:

The Application has been built at least once since creation.

Enable Client-side Libraries on Build when:

If the local copy of the Expo Web Content is suspected to be unintentionally affected (or damaged).
If the Expo Web Content wants to be upgraded/downgraded to a different version than the originally configured.

The version number in the "library" element in the libman.json file can be replaced by the Git commit hash corresponding to the Release, or by the word "latest".