Ficus App Shell UI Loader

The app shell UI loader is the minimal UI required for an app. It is loaded as soon as possible, and is responsible for loading the rest of the app.

Usage

The app shell UI loader loads the initial UI for the app. The initial UI is the minimal UI required for the app to be visible on either mobile or desktop. The initial UI is loaded as soon as possible, and is responsible for loading the rest of the app.

To use the app shell UI loader, add the following to your index.html:

<script type="module">
  import { createLoader, html } from 'https://cdn.skypack.dev/@ficusjs/app-shell-ui-loader'
  createLoader()
</script>

API

createLoader(options)

The createLoader(options) function loads the initial UI for the app. The initial UI is the minimal HTML and CSS required for the app to be presented to the user. The initial UI is typically rendered using placeholders before the content is fully loaded. The loader is then responsible for loading the rest of the app.

Options can be passed to the createLoader(options) function to configure the loader. The following example shows the default values for each option. When passing options, all properties are optional, so you only need to override the values you want to change.

import { createLoader, html } from 'https://cdn.skypack.dev/@ficusjs/app-shell-ui-loader'

createLoader({
  appTagName: 'fas-app',
  desktopMediaQuery: '(min-width: 1280px)',
  breakpointReactive: false,
  desktopUiTagName: 'fas-ui-desktop',
  desktopUiScriptUrl: '/app-ui-desktop/main.js',
  desktopHTML: html`
    <div>
      <fas-desktop-header></fas-desktop-header>
      <fas-desktop-nav></fas-desktop-nav>
      <main>
        <div id="router-outlet"></div>
        <fas-desktop-aside></fas-desktop-aside>
      </main>
      <fas-desktop-footer></fas-desktop-footer>
    </div>
  `,
  mobileUiTagName: 'fas-ui-mobile',
  mobileUiScriptUrl: '/app-ui-mobile/main.js',
  mobileHTML: html`
    <div>
      <fas-mobile-header></fas-mobile-header>
      <fas-mobile-nav></fas-mobile-nav>
      <main id="router-outlet"></main>
      <fas-mobile-footer></fas-mobile-footer>
    </div>
  `
})

html tagged template literal

The html tagged template literal is used to create HTML templates for the desktop and mobile UI. It must be used to create the desktopHTML and mobileHTML options.

import { createLoader, html } from 'https://cdn.skypack.dev/@ficusjs/app-shell-ui-loader'

createLoader({
  desktopHTML: html`
    <div>
      <my-desktop-header></my-desktop-header>
      <my-desktop-aside></my-desktop-aside>
      <main id="router-outlet"></main>
      <my-desktop-footer></my-desktop-footer>
    </div>
  `
})

Options

The createLoader(options) function accepts an optional object containing properties for configuring the loader.

The following options can be provided:

| Option | Type | Default | Description | |----------------------|-----------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------| | appTagName | string | fas-app | The tag name of the app tag. The app tag is the root tag that uses a media query to load a specific mobile or desktop UI. | | desktopMediaQuery | string | (min-width: 1280px) | The breakpoint at which to switch from mobile to desktop. | | breakpointReactive | boolean | false | Should the breakpoint be reactive on resize? | | desktopUiTagName | string | fas-ui-desktop | The tag name of the desktop UI component. | | desktopUiScriptUrl | string | /app-ui-desktop/main.js | The path to the desktop UI components bundle. | | desktopHTML | string | See desktop HTML | The HTML of the desktop app shell UI. | | mobileUiTagName | string | fas-ui-mobile | The tag name of the mobile UI component. | | mobileUiScriptUrl | string | /app-ui-mobile/main.js | The path to the mobile UI components bundle. | | mobileHTML | string | See mobile HTML | The HTML of the mobile app shell UI. |

Desktop HTML

The desktop HTML is the HTML that is loaded when the desktop UI is loaded. The desktop HTML is loaded when the desktop media query is matched. It is loaded within the desktopUiTagName tag.

The default desktop HTML is:

```html
<div>
  <fas-desktop-header></fas-desktop-header>
  <fas-desktop-nav></fas-desktop-nav>
  <main>
    <div id="router-outlet"></div>
    <fas-desktop-aside></fas-desktop-aside>
  </main>
  <fas-desktop-footer></fas-desktop-footer>
</div>

To provide your own desktop HTML, pass it in as the desktopHTML option using the html tagged template literal:

{
  desktopHTML: html`
    <div>
      <my-desktop-header></my-desktop-header>
      <my-desktop-aside></my-desktop-aside>
      <main id="router-outlet"></main>
      <my-desktop-footer></my-desktop-footer>
    </div>
  `
}

Mobile HTML

The mobile HTML is the HTML that is loaded when the mobile UI is loaded. The mobile HTML is loaded when the desktop media query is not matched. It is loaded within the mobileUiTagName tag.

The default mobile HTML is:

<div>
  <fas-mobile-header></fas-mobile-header>
  <fas-mobile-nav></fas-mobile-nav>
  <main id="router-outlet"></main>
  <fas-mobile-footer></fas-mobile-footer>
</div>

To provide your own mobile HTML, pass it in as the mobileHTML option using the html tagged template literal:

{
  mobileHTML: html`
    <div>
      <my-mobile-header></my-mobile-header>
      <my-mobile-aside></my-mobile-aside>
      <main id="router-outlet"></main>
      <my-mobile-footer></my-mobile-footer>
    </div>
  `
}

Styling

The app shell UI loader does not provide any styling. It is up to you to style the app shell UI. It is recommended to provide the minimal styling required to present the app shell UI to the user. The rest of the styling should be loaded by the UI components.

Production

It is recommended to inline the app shell UI loader in production along with any initial styles. This embeds the initial app shell in the HTML, and removes the need for an additional HTTP requests. It also means the app shell UI is available immediately, and the user does not see a flash of unstyled content.