# MetaStatic Tutorial

### Building a Web Site Using the SB Admin Meta Tag Library

# Introduction

The MetatStatic Repository includes a Tag Library that provides a partial implementation of the Open Source [SB Admin](https://github.com/StartBootstrap/startbootstrap-sb-admin) User Interface.  What's included is sufficient to demonstrate:

- how a technical developer can build out such a Meta Tag Library
- how a Web Site maintainer can build and maintain a site using such a Tag Library

In this tutorial we'll explain in detail both aspects so that by the end of the tutorial you can begin to use MetaStatic for your own specific purposes.

# Getting Started

MetaStatic is written in JavaScript and therefore requires either Node.js or Bun.js to run.

In this tutorial I'm going to use Bun as it's a lot faster to run and much simpler to set up and maintain than Node.js, but if you're a Node.js developer it should be straightforward to translate the instructions to make them work with Node.js.

This tutorial also assumes that you'll be using a Linux machine.  Bun.js is also available for Windows and MacOS and once installed, all the commands should work identically apart from file path syntax differences.

So let's get started!

## Create a Work Directory

Create a directory for this tutorial and switch to it.

For example:

```code
mkdir mstutorial
cd mstutorial
```

## Install Bun.js

If you're using Linux or MacOS, the recommended way to install Bun.js is as follows:

```code
curl -fsSL https://bun.sh/install | bash
```

If you're using Windows, [refer to the Bun.js documentation](https://bun.sh/docs/installation).


## Clone the MetaStatic Repository

```code
git clone https://github.com/robtweed/metastatic
```

## Switch to the Repository's */examples* directory

cd cd metastatic/examples


## Start the Included Bun.js Web Server

We've included a basic but handy Web Server.  It's written in Bun.js and uses its extremely fast *Bun.serve* HTTP server.  This Web Server will allow you to quickly view the Web Site file(s) you generate in this tutorial directly from the location in which MetaStatic will create them.  

Note that this Web Server is **NOT** meant for production use!  

You'll see the Bun Web Server in the directory that you've previously switched to:

```code
bunws.js
```

and you can [view its source code here](./examples/bunws.js).

Note also that the file(s) generated by MetaStatic can be served up by any Web Server, so once you're happy with them, simply upload them to your Web Server.  You will, of course, need to ensure that any URL paths for images etc that you might use are correctly structured for your production Web Server.

To start the Web Server, just issue the following command from the */examples* directory:

```code
bun bunws.js
```

This will start the Web Server and it will listen on port 3000.  If you're already using that port for something else, Bun will report an error and fail to start.  If so, you can specify a different port, eg:

```code
bun bunws.js 8080
```

Note: the first time you invoke this command, Bun should automatically install all of the Web Server's dependencies.  If it doesn't, and if it reports an error, eg:

```code
error: Cannot find package "mg-bun-router" from "/home/ubuntu/metastatic-tutorial/bun/metastatic/examples/bunws.js"
```

Then try manually installing the missing package:

```code
bun install mg-bun-router
```

You should then be able to start the Web Server.


## Test the Web Server

The Bun Web Server is automatically configured to fetch static files from the */examples/sites* folders.  You can test it with the *demo* site which includes a pre-built *index.html* file.  In another process, type:

```code
curl http://localhost:3000/demo/index.html
```

or point a browser at this same URL.

if you followed the instructions correctly, you should see the file's contents or see them rendered in your browser.

If so, you're ready to begin exploring MetaStatic!

----

# The SB Admin Tag Library

## Background

You'll find the SB Admin Tag Library in your */examples/metaTagLibraries/sbadmin* directory.

You can also see the [source files here](./examples/metaTagLibraries/sbadmin).

The SB Admin User Interface (UI) is designed around a set of panels:

- a top bar, for titles etc
- a left-hand panel for menu options
- a footer panel for site information, copyright notices etc
- a main content panel

This UI is based on the popular Open Source responsive Bootstrap v5 CSS framework.  The built-in responsive behaviour is very nice: for example, you'll find that the menu panel will automatically collapse on small devices such as phones, and content will automatically stack vertically in small devices.

As such, the SB Admin UI is very powerful and versatile and can be used for many, if not most Web Sites to provide a modern UI for your content.

Of course, with MetaStatic you aren't limited to using this UI: any alternative UI can be implemented as a set of MetaStatic's Meta Tags and then used to construct your Web Site.  Their design is entirely up to you!

The *namespace* we've used for the SB Admin Tag Library is *sbadmin*, so you'll notice that all the individual Tag definition files are prefixed with this, eg:

- sbadmin-root
- sbadmin-header
- sbadmin-sidebar-menu

Each Meta Tag is defined in its own file which has a file extension of *.mst*, eg:

- sbadmin-root.mst
- sbadmin-header.mst
- sbadmin-sidebar-menu.mst

A Web Developer/Maintainer will use these as tags, eg:

- <sbadmin-root>
- <sbadmin-header>
- <sbadmin-sidebar-menu>


## The Root Meta Tag

Every MetaStatic Tag Library will have a top-level tag within which all other Tags are nested.  What it's called is up to you.  In our case we've named this tag *sbadmin-root*.

You'll find it in your system at */examples/metaTagLibraries/sbadmin/sbadmin-root.mst*.

You can also inspect its [source code here](./examples/metaTagLibraries/sbadmin/sbadmin-root.mst).

We'll come back to explain its contents and how/why it works in detail later.

For now, suffice to say that this Meta Tag:

- creates the correct HTML <head> tag contents for your Web Site:
  - loading the required Bootstrap-compatible CSS resources;
  - loading the Bootstrap JavaScript resources
  - loading the free Font Awesome icon resources
  - adding some specific customisable styles that override the standard *StartBootstrap* ones
- defines and creates the basic UI layout in the <body> tag


## Creating Our Web Site

Let's get started and create a "bare bones" SB Admin Web Site.

Change to the */examples/sites/tutorial* directory that you'll find on your system.

In order to create a Web Site, you create a file with a file extension of *.meta*.  The file name is otherwise up to you, but by convention, a single page Web Site will normally have a name of *index*.

You'll find we've already created an instance of the *index.meta* file for you to get you started.  It's very simple and just contains the *sbadmin-root* tag:

```html
<sbadmin-root />
```

Let's try building a Web Site from it and see what happens.


## Running the MetaStatic Builder

You're best to run the MetaStatic Builder from within your */examples* directory:

- change to the correct directory, eg:

```code
cd ~/mstutorial/metastatic/examples
```

Then run the Builder:

```code
bun build.mjs tutorial
```

Specifying *tutorial* as a command line parameter will tell the builder to find your definition *.meta* file in your */sites/tutorial* directory.  By default it will look for and use a file named *index.meta*.  You could specify it explicitly by adding it as a second command line parameter:

```code
bun build.mjs tutorial index.meta
```

The first time you run this, Bun will probably return an error, telling you that it couldn't find the *metastatic* module.  You can fix this by typing:

```code
bun install metastatic
```

Now you should be able to re-run the Builder:

```code
bun build.mjs tutorial
```

You should see the generated HTML returned in the terminal, but that same HTML should now be in a file named *index.html* in your */examples/sites/tutorial* directory.  

Try fetching it in a browser (making use of the Bun Web Server we started earlier):

```code
http://localhost:3000/tutorial/index.html
```

You should see an empty version of the SB Admin UI!

![Initial SB Admin UI](./images/sbadmin-1.png)


Clearly this isn't very useful as yet, but it's worth taking a look at what's been generated and why.

If you inspect the contents of the generated *index.html* file, you'll see that it includes everything that was needed to render this UI. [Here's a copy of what it should contain](./examples/sites/tutorial/example1.html).

Notice how the &lt;title> tag has used a default title attribute value from the &lt;sbadmin-root> tag:

```html
    <title>MetaStatic</title>
```

If you want to specify your own &lt;title> text, edit the *index.meta* tag as shown:

```html
<sbadmin-root title="My MetaStatic Demo" />
```

and re-run the builder:

```code
bun build.mjs tutorial
```

You'll see that the *index.html* file has been overwritten and contains the new version of the generated markup, and if you take a look at the &lt;title> tag, it should now contain our own modified text:

```html
    <title>My MetaStatic Demo</title>
```

It might not look like it yet, but this *sbadmin-root* tag has already generated all the basic scaffolding needed to create your own customised version of the SB Admin UI, with empty versions of:

- a top bar, for titles etc
- a left-hand panel for menu options
- a footer panel for site information, copyright notices etc
- a main content panel

So in a while we'll look at how you use and populate each of the four panel areas it's created for you.  But first, let's take a deep dive into that *sbadmin-root* Meta Tag definition, as it demonstrates almost all of the key features of MetaStatic.


## Key Features of the *sbadmin-root* Meta Tag

We're going to take an in-depth look at the *sbadmin-root* Meta Tag.  You'll find it in your system in the */examples/metaTagLibraries/sbadmin directory: it's the file named *sbadmin-root.mst*.

Alternatively view the [source code for it here](./examples/metaTagLibraries/sbadmin/sbadmin-root.mst).

The first thing to notice is that it contains two &lt;template> tags and a &lt;script> tag.

### First Template

Let's start with the very first line which is the first &lt;template> tag:

```html
<template 
 slot="*head"
 :title="^title|MetaStatic"
 :cssurl="^cssurl|https://startbootstrap.github.io/startbootstrap-sb-admin/css/styles.css"
 :faurl="^faurl|https://use.fontawesome.com/releases/v6.3.0/js/all.js"
 :bsurl="^brurl|https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"
 :topbarcolor="^topbarcolor|#bdddf6"
 :topbartextcolor="^topbartextcolor"
 :topbaropacity="^topbaropacity|0.9"
 :menubgcolor="^menubgcolor|#fff"
 :menutextcolor="^menutextcolor|#212832"
 :contentbgcolor="^contentbgcolor|#f2f6fc"
 :contenttextcolor="^contenttextcolor|#69707a"
 :footerbgcolor="^footerbgcolor|rgb(242, 246, 252)"
 :footertextcolor="^footertextcolor|#69707a"
 :topbargradient="^topbargradient"
 :menuwidth="^menuwidth|225px"
>
```

There's clearly a lot going on here!  But let's break it down and you'll find it's all actually remarkably simple.

Let's go through the attributes one by one:

#### slot

This attribute tells MetaStatic's Builder where to insert the markup that's within the &lt;template> tag.  The value in this case is *\*head*.  That asterisk (\*) prefix denotes that this refers to one of two reserved slot names that denote:

- *\*head*: The document's &lt;head> tag
- *\*body*: The document's &lt;body> tag

It also highlights an important aspect of MetaStatic's Builder: its starting point is an empty HTML page or document:

```html
<html>
  <head></head>
  <body></body>
</html>
```

So the first or "root" Meta Tag that you specify in your *index.meta* Web Site description will start the process of populating that empty document, and in this case, the first &lt;template> tag is defining what we want to go into our document's &lt;head> section.

Meta Tag *template*s will normally specify a slot into which their contents will be inserted by MetaStatic's Builder.  We'll see how they are defined and used later.

#### :title

We've seen how this is used: it populates the &lt;title> tag within the &lt;head> section.  But how did that actually work?

You'll see that in the &lt;template> tag, the name of the attribute is prefixed by a colon character (:).  This tells MetaStatic's Builder to create a substitution variable named *:title*.

Note: substitution variable names **MUST** be all in lower case.


The value of this *:title* attribute is specified as *^title|MetaStatic*.  

That caret character (^) prefix tells MetaStatic's Builder to use the actual value in the &lt;sbadmin-root> tag that was used in the *index.meta* file: in this case *MetaStatic Demo*, ie as a result of this:

```html
<sbadmin-root title="MetaStatic Demo" />
```

The vertical bar character (|) followed by the text *MetaStatic* defines a default value that should be used if no *title* attribute was defined, eg if we'd used this in the *index.meta* file:

```html
<sbadmin-root />
```

If we take a look at the &lt;title> tag in the *template*, you'll see that the textContent of the &lt;title> tag should be substituted by whatever is the value of the *:title* variable:

```html
  <title>:title</title>
```

The variable *:title* could, in fact, be used as many times as needed within the *template*'s contents.  In the case of this *template*, however, we're only using it once - within the &lt;title> tag.

#### :cssurl

This allows you to optionally specify an alternative URL for the main CSS stylesheet.  If you look at its value in the template:

```code
:cssurl="^cssurl|https://startbootstrap.github.io/startbootstrap-sb-admin/css/styles.css"
```

you'll see that once again it has two parts separated by a vertical bar character (|).  The first part tells tells MetaStatic's Builder to use the actual value in the &lt;sbadmin-root> tag that was used in the *index.meta* file - if it can find one.  We haven't specified a value however: all we specified was:

```html
<sbadmin-root title="MetaStatic Demo" />
```

So the second part after the vertical bar character defines a default value to use if the actual tag didn't define a value.  So in this case, the *:cssurl* value will be *https://startbootstrap.github.io/startbootstrap-sb-admin/css/styles.css*.

If we take a look further down inside the template markup we'll find this:

```html
  <link rel="stylesheet" href=":cssurl">
```

and in our generated *index.html* file this was substituted with that default value:

```html
    <link rel="stylesheet" href="https://startbootstrap.github.io/startbootstrap-sb-admin/css/styles.css">
```

The ability to define optional attributes with default values is a very powerful and useful feature, yet very simple to use, both by a developer of a Meta Tag and a user of that Meta Tag.

Why might you want to use it in this case?  One reason might be if you wanted to use a local copy of the CSS file rather than one fetched from a CDN.  Alternatively you may want to use your own customised version.

#### :faurl

This defines the URL to use for the Free Font Awesome icon library.  Just like the *:cssurl* attribute, it defines a default URL in the template (*https://use.fontawesome.com/releases/v6.3.0/js/all.js*) that you can optionally override.

It's used in this line within the template:

```html
  <script async src=":faurl" crossorigin="anonymous"></script>
```

#### :bsurl

This defines the URL to use for the Bootstrap v5 JavaScript library.  Just like the *:cssurl* attribute, it defines a default URL in the template (*https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js*) that you can optionally override.

It's used in this line within the template:

```html
  <script async src=":bsurl"></script>
```

#### :topbarcolor

This allows you to optionally modify the background colour of the top bar.  A default value of *#bdddf6* is applied if no value is specified, and is used to substitute these lines within the custom &lt;style> tag within the head section:

```css
.bg-mgw {
  opacity: :topbaropacity;
  background-color: :topbarcolor;
  background-image: :topbargradient;
  color: :topbartextcolor;
}
```

#### :topbartextcolor

This allows you to optionally modify the colour of any text you define within the top bar.  No default is specified.  As a result, if you don't explicitly specify this attribute, the underlying default style provided by the SB Admin UI will be inherited instead: a light grey colour.


#### :topbaropacity

This allows you to optionally modify the opacity of the top bar.  A default value of *0.9* is applied if no value is specified, and is used to substitute these lines within the custom &lt;style> tag within the head section:

```css
.bg-mgw {
  opacity: :topbaropacity;
  background-color: :topbarcolor;
  background-image: :topbargradient;
  color: :topbartextcolor;
}
```

#### :topbargradient

This allows you to optionally specify a vertical colour gradient for the top bar.  By default, no gradient is defined, in which case the substituted value will be an empty string, ie:

```css
.bg-mgw {
  opacity: :topbaropacity;
  background-color: :topbarcolor;
  background-image: :topbargradient;
}
```

is substituted with:

```css
      .bg-mgw {
        opacity: 0.9;
        background-color: #bdddf6;
        background-image: ;
      }
```

so no gradient will be applied.

Here's an example of a gradient value:

```code
:topbargradient="linear-gradient(to top, #707595 0%, #0e1025 100%)"
```

Note that if you specify a *background-image* value, any *background-color* property is ignored: the *background-image* takes precedence.

#### Other Similar Attributes

All the other substitution variable attributes within the &lt;template> tag are hopefully now self explanatory: they all use the same kind of logic and syntax as described above:

- :menubgcolor="^menubgcolor|#fff" 
- :menutextcolor="^menutextcolor|#212832"
- :contentbgcolor="^contentbgcolor|#f2f6fc" 
- :contenttextcolor="^contenttextcolor|#69707a" 
- :footerbgcolor="^footerbgcolor|rgb(242, 246, 252)" 
- :footertextcolor="^footertextcolor|#69707a" 

These optional attributes are all used to substitute CSS property values within the &lt;style> tag at build time with either a value supplied by the Web Designer or a default value.

#### :menuwidth

This attribute defaults to a value of 225 and defines the width of the left-hand menu panel (measured in pixels).

If you require menu options with longer than normal text descriptions, you may need to increase this value.  Alternatively it may be worth lowering the value if you can to reduce the menu width.

----

### Second Template

The *sbadmin-root* Meta Tag's second template is much simpler and defines the specifically-styled markup that constitutes the basic SB Admin UI scaffolding.  This markup belongs within the generate Web Page's &lt;body> tag, so the *&lt;template>* tag specifies its *slot* to be *\*body*:

```html
<template slot="*body">
  <span onload="loadByHash()">
    <slot name="topbar" />
  </span>

  <div id="layoutSidenav">
  ...etc

</template>
``` 

The key thing to notice within this Template are the four *slots* that it defines:

- topbar:

```html
  <span>
    <slot name="topbar" />
  </span>
```

- sidebar:

```html
      <nav class="sb-sidenav shadow-right accordion sb-sidenav-light navbar-nav-scroll" id="sidenavAccordion">
        <slot name="sidebar" />
      </nav>
```
- content:

```html
      <main>
        <div class="container-fluid px-4">
          <slot name="content" />
        </div>
      </main>
```

- footer:

```html
      <footer class="py-4 bg-light mt-auto">
        <div class="container-fluid px-4">
          <slot name="footer" />
        </div>
      </footer>
```

These provide the insertion points for any content/markup you want to add to these parts of the SB Admin UI.

Typically what you will use for such insertion is other *sbadmin* Meta Tags that are designed for use within each particular slot.  You'll see how to use them later on in this tutorial.

### Script Tag

Meta Tags can optionally contain one or two script tags.  There are two types you can specify:

- a standard HTML &lt;script> tag that defines JavaScript that is needed for event handlers etc within the Meta Tag's content.  

  The contents of such a &lt;script> tag is added to a &lt;script> tag that MetaStatic's Builder will have already added at the end of the &lt;body> section.

  MetaStatic's Builder keeps a note of all such inserted Meta Tag &lt;script> tags, and if any more instances of the Meta Tag are processed, their &lt;script> tags are ignored.  In other words, MetaStatic will ensure that there is only ever one instance of the JavaScript code for each Meta Tag you use in your Web Site.

- a &lt;script> tag with a *type* attribute whose value is *build*, which is what the *sbadmin-root* Meta Tag includes:

```html
<script type="build">
document.body.classList.add('sb-nav-fixed');
let index = '{}';
if (MetaStatic.indexContent) {
  index = JSON.stringify(MetaStatic.wordToFileIndex);
}
scriptEl.textContent += `
  function getWordIndex() {
    return ${index};
  }
`;
</script>
```

  Such scripts allow you to optionally define custom code that you want MetaStatic's Builder to execute at the end of its standard processing of the Meta Tag.  In this case we're adding a class to the generate'd Web Page's &lt;body> tag: something MetaStatic's Builder's own logic doesn't automatically make possible.

It's also adding optional word search indexing, but that's something we're not going to use in this tutorial.

  You'll therefore see in the generated Web Page HTML:

```html
  <body class="sb-nav-fixed">
```

  If you want to provide your own custom *build* script in a Meta Tag, the main thing you need to know is that the generated Web Page DOM is held in the *document* object.  MetaStatic's Builder makes use of the
[jsdom](https://www.npmjs.com/package/jsdom) package which emulates the in-browser DOM APIs, so you can manipulate the generated Web Page's DOM using the standard DOM API methods and properties.

Build scripts also have access to the MetaStatic class instance, and the partially-processed Meta Tag DOM(s) (via the *Templates* array). As a result, advanced MetaStatic developers can extend and customise the functionality of MetaStatic.

----

## Populating The SB Admin Slots

OK, let's get back to using the *sbadmin* Meta Tags.

Currently we've just created a Web Page that displays the SB Admin UI's basic appearance with its four panels, but without any content.

Let's do something very crude and simple and put some text into each one.  To do this, we'll just add four &lt;div> tags, one for each of the named slots provided by the *sbadmin-root* Meta Tag.

So, open up the *./sites/tutorial/index.meta* file in a text editor and change it to:

```html
<sbadmin-root title="MetaStatic Demo">
  <div slot="topbar">Top Bar Content Goes Here</div>
  <div slot="sidebar">Menu Content Goes Here</div>
  <div slot="content">Main Content Goes Here</div>
  <div slot="footer">Footer Content Goes Here</div>
</sbadmin-root>
```

Note how we've specified the slot to use for each &lt;div> tag by using a *slot* attribute.  The slot names must, of course, correspond to those used in the *sbadmin-root* Meta Tag.

Now simply re-run MetaStatic's Builder.  Remember to do this from within your *./examples* directory

```code
cd ~/mstutorial/metastatic/examples    # if necessary, then:
bun build.mjs tutorial
```

You'll find that the *index.html* file in the *./examples/sites/tutorial* directory has been over-written.

Try loading it into a browser (make sure you still have the Bun Web Server running!) using the same URL as before, eg:

```code
http://localhost:3000/tutorial/index.html
```

You should now see the text we specified occupying each of the respective SB Admin UI panels.

![SB Admin UI with text](./images/sbadmin-2.png)

You'll notice that the text we specified for the *topbar* slot isn't actually visible, and also notice that the text for the *sidebar* and *content* slots are in what appear to be strange positions.

This is because the top bar banner requires its own styling which is carried out by another Meta Tag in the *sbadmin* tag library: *sdadmin-header*.  It will insert itself into the *topbar* slot and makes available its own slot named *header*.

So let's edit our *index.meta* file to make use of that:

```html
<sbadmin-root title="MetaStatic Demo">
  <sbadmin-header>
    <div slot="header">Top Bar Content Goes Here</div>
  </sbadmin-header>
  <div slot="sidebar">Menu Content Goes Here</div>
  <div slot="content">Main Content Goes Here</div>
  <div slot="footer">Footer Content Goes Here</div>
</sbadmin-root>
```

Re-run the Builder as before and reload the page in your browser.  You should now see the top banner and the menu and content text will be properly aligned:

![SB Admin UI with banner](./images/sbadmin-3.png)

The *footer* text isn't using the correct styling either: we should use another Meta Tag - *sbadmin-footer* to provide that.  The *sbadmin-footer* Meta Tag attaches itself to the *footer* slot and makes its own slot available: *footercontent*.

So let's edit the *index.meta* file to use this too:

```html
<sbadmin-root title="MetaStatic Demo">
  <sbadmin-header>
    <div slot="header">Top Bar Content Goes Here</div>
  </sbadmin-header>
  <div slot="sidebar">Menu Content Goes Here</div>
  <div slot="content">Main Content Goes Here</div>
  <sbadmin-footer>
    <div slot="footercontent">Footer Content Goes Here</div>
  </sbadmin-footer>
</sbadmin-root>
```

Re-run the Builder as before and reload the page in your browser. The page will look almost identical, but the footer text will now be a bit smaller.

Next, while we're at it, let's try changing the top bar styling.  For example, re-edit the *index.meta* file as shown here:

```html
<sbadmin-root title="MetaStatic Demo" topbarcolor="blue" topbartextcolor="white">
  <sbadmin-header>
    <div slot="header">Top Bar Content Goes Here</div>
  </sbadmin-header>
  <div slot="sidebar">Menu Content Goes Here</div>
  <div slot="content">Main Content Goes Here</div>
  <sbadmin-footer>
    <div slot="footercontent">Footer Content Goes Here</div>
  </sbadmin-footer>
</sbadmin-root>
```

Re-run MetaStatic's Builder and refresh the newly built version of the *index.html* in your browser.  The top bar should now be blue and the text white.

![SB Admin UI with styled top bar](./images/sbadmin-3a.png)

You can try playing about with the other optional *sbadmin-root* attributes described in the previous section above to re-style the other panels.

----
## Creating a Header

Normally you'll want the header to include:

- some text as a title; and/or
- an image or logo

You'll also want a visual widget to control the menu, which, by convention, is depicted as three short horizontal stacked bars, often termed a "hamburger".

The *sbadmin* Meta Tag Library includes Meta Tags for these:

- *sbadmin-brand*
- *sbadmin-sidebar-toggle*

These have been designed to use the *sbadmin-header* Meta Tag's *header* slot.

Let's try them out.  Edit your *index.meta* tag as follows:

```html
<sbadmin-root title="MetaStatic Demo">
  <sbadmin-header>
    <sbadmin-sidebar-toggle />
    <sbadmin-brand text="MetaStatic Demo" src="images/logo.png" height="55" position="right" opacity="0.2" />
  </sbadmin-header>
</sbadmin-root>
```

Before we re-run the Builder, let's just take a closer look at these two Meta Tags:

### *&lt;sbadmin-brand>*

The *sbadmin-brand* Meta Tag allows you to specify text and/or an image.  In our example above, we're displaying both.  

The *height*, *position* and *opacity* attributes allow you to size, position and blend the image/logo within the top bar.  The *position* attribute value can be *left*, *right* or *center*.

It's a good idea to use a color tool to determine your logo file's RGB value(s) and style the top bar's background colour or background gradient to match (see the *sbadmin-root* attributes described earlier).  As it happens, the *sbadmin* Meta Tags are pre-styled with colours that match the example image/logo that are included in this repository, so you'll see how such colour matching can work.


### *&lt;sbadmin-sidebar-toggle>*

You'll notice in our example above that we've specified the *sbadmin-sidebar-toggle* Meta Tag is specified without any attributes.  By default it will be coloured black.  Depending on the colour of your top bar, you may prefer to have it coloured white, in which case you simply add the attribute:

- color="light"

If you look at the source code for the 
[*sbadmin-sidebar-toggle* Meta Tag](./examples/metaTagLibraries/sbadmin/sbadmin-sidebar-toggle.mst), you'll notice that it contains a script tag:

```html
<script>
function toggle(e) {
  e.preventDefault();
  document.body.classList.toggle('sb-sidenav-toggled');
}
</script>
```

This will be added to the generated page's &lt;script> tag by MetaStatic's Builder.

You'll see in the Meta Tag's *template* how this is triggered:

```html
    <button class="btn btn-link btn-sm order-1 order-lg-0 me-4 me-lg-0" id="sidebarToggle" href="#!" onclick="toggle(event)">
```

### Rebuild and Reload the *index.html* File

OK let's try out our changes.  Save your edited version of the *index.meta* tag and re-run the Builder:

```code
bun build.mjs tutorial
```

Refresh it in your browser and you should now see:

![SB Admin UI with top bar](./images/sbadmin-4.png)

Try clicking the "hamburger" widget: the menu panel should slide in and out of view on each successive click.

Also try either reducing the width of the browser, or try viewing the page in your mobile phone's browser.  As a result of the Responsive design of the SB Admin styling, it should now look like this:

<p align="center">
  <img src="./images/sbadmin-5.jpg" alt="SB Admin UI in mobile browser" width="300">
</p>

Notice how the menu panel has now automatically disappeared, but it will slide across into view when you click the "hamburger".

Notice also that the title text appears on top of the image.  That has been achieved by reducing the opacity of the image to 0.2: the image would otherwise obscure the text.

----
## Adding a Footer

Now let's add a footer.  

You've already seen that there's a *sbadmin-footer* Meta Tag that provides a styled insertion point.  There are two other Meta Tags included in the *sbadmin* Tag Library:

- *sbadmin-copyright*: this can be used to add a copyright notice at the bottom of the page
- *sbadmin-footer-text*: this can be used for any other text.

You can have multiple combinations of these Meta Tags within a parent *sbadmin-footer* Tag.  The text will be equally spaced across the available width of the footer panel.

So, let's edit the *index.meta* tag and we'll first add a copyright notice in the footer:

```html
<sbadmin-root title="MetaStatic Demo">
  <sbadmin-header>
    <sbadmin-sidebar-toggle />
    <sbadmin-brand text="MetaStatic Demo" src="images/logo.png" height="55" position="right" opacity="0.2" />
  </sbadmin-header>
  <sbadmin-footer>
    <sbadmin-copyright text="2024 MGateway Ltd" />
  </sbadmin-footer>
</sbadmin-root>
```

If you re-run the Builder and reload the generated *index.html* file in your browser, you'll now see a Copyright notice in the footer.  By default it uses a very small 8pt font size.  To increase the font size, specify it using the *size* attribute, eg:

```html
<sbadmin-copyright text="2024 MGateway Ltd" size="10pt" />
```

Now try also adding some footer text:

```html
<sbadmin-root title="MetaStatic Demo">
  <sbadmin-header>
    <sbadmin-sidebar-toggle />
    <sbadmin-brand text="MetaStatic Demo" src="images/logo.png" height="55" position="right" opacity="0.2" />
  </sbadmin-header>
  <sbadmin-footer>
    <sbadmin-copyright text="2024 MGateway Ltd" />
    <sbadmin-footer-text text="Registered in England" />
  </sbadmin-footer>
</sbadmin-root>
```

Re-run the Builder and reload the *index.html* page in your browser.  The footer should now look something like this:

![SB Admin UI with footer](./images/sbadmin-6.png)

----

## Adding Menus and Associated Content

Now we get to the really interesting part which is adding menus with options which, when clicked, change the content displayed in the *content* panel of the SB Admin UI.

With appropriately defined Meta Tags, menus become very easy to define and manage.

### The *&lt;sbadmin-sidebar-menu>* Tag

The first thing to add is an *&lt;sbadmin-sidebar-menu>* Meta Tag.  This is designed to use the *sidebar* slot.

The *sbadmin-sidebar-menu* Meta Tag doesn't do a great deal, but it establishes the correct styled scaffolding for all the other menu-related Meta Tags to work:

```html
<template slot="sidebar">
  <div class="sb-sidenav-menu">
    <div class="nav">
      <slot name="menu" />
    </div>
  </div>
</template>
```

All the other menu-related Meta Tags attach to its *menu* slot.

### Menu Headings

So the first Meta Tag we'll use isn't a menu item *per se*, but allows you to create some header text for a group of menu items: *&lt;sbadmin-sidebar-heading>*.

Edit your *index.meta* file as follows:

```html
<sbadmin-root title="MetaStatic Demo">
  <sbadmin-header>
    <sbadmin-sidebar-toggle />
    <sbadmin-brand text="MetaStatic Demo" src="images/logo.png" height="55" position="right" opacity="0.2" />
  </sbadmin-header>
  
  <sbadmin-sidebar-menu>
    <sbadmin-sidebar-heading text="Select a Menu Option" />
  </sbadmin-sidebar-menu>

  <sbadmin-footer>
    <sbadmin-copyright text="2024 MGateway Ltd" />
    <sbadmin-footer-text text="Registered in England" />
  </sbadmin-footer>
</sbadmin-root>
```

Re-run the Builder and refresh the *index.html* page in your browser.  You should now see the heading in the menu panel:

![SB Admin UI with menu heading](./images/sbadmin-7.png)

### Menu Items

Now let's add a proper menu item.  Each menu item has some associated text that will appear in the menu, and can also have an optional icon before the text.

Each menu item is associated with text content that will appear in the *content* panel whenever the menu item is clicked.  This will all happen automatically.

To add a menu item, we use the *&lt;sbadmin-sidebar-menu-item*> tag.  This has two attributes:

- text: defines the text to appear in the menu
- iconname: (optional) defines the name of the Font Awesome icon to use

  You can 
  [view the available free icons and their names here](https://fontawesome.com/search?m=free&o=r).

You specify the text content that is associated with this menu using one or more child Meta Tags.

There are special *sbadmin* Meta Tags available for displaying and styling the text within the *content* panel that we'll describe later, but let's start out with just a simple &lt;div> tag for our text, to demonstrate the basic principles.  To use a &lt;div> tag we'll need to specify that it should use a slot named *contentpage* which has been created automatically by one of the *sbadmin-sidebar-menu-item* Meta Tag templates.

You can [view the source for the *sbadmin-sidebar-menu-item* Meta Tag here](./examples/metaTagLibraries/sbadmin/sbadmin-sidebar-menu-item.mst).

Edit the *sbadmin-sidebar-menu* section of your *index.meta* file as shown below (leave everything else in the *index.meta* file as before):

```html
 <sbadmin-sidebar-menu>
    <sbadmin-sidebar-heading text="Select a Menu Option" />
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info">
      <div slot="contentpage">About Content will go here...</div>
    </sbadmin-sidebar-menu-item>
  </sbadmin-sidebar-menu>
```

Re-run the Builder and refresh the *index.html* page in your browser.  You should now see the *About* option in the menu panel.  Click it and the menu option will be highlighted and the text we specified will appear in the *content* panel:

![SB Admin UI with menu item](./images/sbadmin-8.png)

Let's now add a second menu item with its own text, and this time we'll make the *About* menu option active, which means it will be automatically selected when the page is loaded/reloaded:

```html
 <sbadmin-sidebar-menu>
    <sbadmin-sidebar-heading text="Select a Menu Option" />
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <div slot="contentpage">About Content will go here...</div>
    </sbadmin-sidebar-menu-item>
    <sbadmin-sidebar-menu-item text="Installation" iconname="wrench">
      <div slot="contentpage">Installation text will go here</div>
    </sbadmin-sidebar-menu-item>
  </sbadmin-sidebar-menu>
```
Re-run the Builder and refresh the *index.html* page in your browser.  You should now see the *About* option highlighted in the menu panel with its associated text showing in the *content* panel.  Try clicking the new *Installation* Menu Option and you'll see the text change in the *content* panel and *Installation* will be highlighted instead of *About*.

![SB Admin UI with 2 menu items](./images/sbadmin-9.png)

### Nested Menus

Being able to group menu items into categories is a very useful feature, and the *sbadmin* Meta Tag Library allows you to achieve this with nested menus.  You can even have multiple levels of nesting if you need to do so.

All you need to use is the *&lt;sbadmin-sidebar-nested-menu>* Meta Tag within which you embed one or more *&lt;sbadmin-sidebar-menu-item>* tags, and/or other *&lt;sbadmin-sidebar-nested-menu>* tags.

Just like the *&lt;sbadmin-sidebar-menu-item>* Meta Tag, the *&lt;sbadmin-sidebar-nested-menu>* Meta Tag has two attributes:

- text: defines the text to appear in the menu
- iconname: (optional) defines the name of the Font Awesome icon to use

Let's add it to our *index.meta* file.  Change the *sdadmin-sidebar-menu* section to this:

```html
 <sbadmin-sidebar-menu>
    <sbadmin-sidebar-heading text="Select a Menu Option" />
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <div slot="contentpage">About Content will go here...</div>
    </sbadmin-sidebar-menu-item>
    
    <sbadmin-sidebar-nested-menu text="Technical" iconname="gears">
      <sbadmin-sidebar-menu-item text="Installation" iconname="wrench">
        <div slot="contentpage">Installation text will go here</div>
      </sbadmin-sidebar-menu-item>
      <sbadmin-sidebar-menu-item text="Configuration" iconname="sliders">
        <div slot="contentpage">Configuration text will go here</div>
      </sbadmin-sidebar-menu-item>
    </sbadmin-sidebar-nested-menu>
    
  </sbadmin-sidebar-menu>
```

Re-run the Builder and refresh the *index.html* page in your browser.  You should now see the *Technical* sub-menu heading below the highlighted *About* option.  If you click it, it will expand to reveal the submenu (*Installation* and *Configuration*), each of which switches the text in the *content* panel:

![SB Admin UI with nested menu](./images/sbadmin-10.png)

## Formatting Content

Now that we know how to construct menus using the *sbadmin* Meta Tag Library, we can now turn our attention to the *content* panel.  So far we've just displayed placeholder text for each menu item using a simple &lt;div> tag.  Now let's look at how we can properly define and style content.

### The *&lt;sbadmin-content-text>* Tag

The simplest of the *content* panel-specific Meta Tags is the *&lt;sbadmin-content-text>* tag.

It's designed to automatically use the *contentpage* slot, and takes a single attribute: *text*.

Let's modify our previous version of the *index.meta* file to use this tag instead of the &lt;div> tags.  For now we'll just continue to use similar placeholder text:

```html
 <sbadmin-sidebar-menu>
    <sbadmin-sidebar-heading text="Select a Menu Option" />
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-content-text text="About text goes here..." />
    </sbadmin-sidebar-menu-item>
    
    <sbadmin-sidebar-nested-menu text="Technical" iconname="gears">
      <sbadmin-sidebar-menu-item text="Installation" iconname="wrench">
        <sbadmin-content-text text="Installation text goes here..." />
      </sbadmin-sidebar-menu-item>
      <sbadmin-sidebar-menu-item text="Configuration" iconname="sliders">
        <sbadmin-content-text text="Configuration text goes here..." />
      </sbadmin-sidebar-menu-item>
    </sbadmin-sidebar-nested-menu>
    
  </sbadmin-sidebar-menu>
```

The *&lt;sbadmin-content-text>* tag also allows you to specify a heading, eg::

```html
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-content-text text="About text goes here..." title="About MetaStatic" />
    </sbadmin-sidebar-menu-item>
```

Re-run the Builder and refresh the *index.html* page in your browser.  You should now see the *About* text in the *content* panel pretty much as before, but now there's big title at the start of it:

![SB Admin UI with content text](./images/sbadmin-11.png)

You can reduce the size of the heading text by adding another attribute - *h* - that specifies the *h* tag styling to be used.  Use a number between 1 and 6 to define *h1*, *h2* etc, eg:

```html
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-content-text text="About text goes here..." title="About MetaStatic" h="3" />
    </sbadmin-sidebar-menu-item>
```

### Using MetaStatic's Content Management System

Im most situations we'll have quite a bit of text to display in the *content* panel for each menu item, and we'll want to be able to style it properly.  A single *text* attribute doesn't seem adequate for that.

That's because you usually won't actually specify the *content* panel text using the *text* attribute.  Instead we'll define the text in a separate file, using [Markdown syntax](https://www.markdownguide.org/basic-syntax/) to style it, and we'll use the *text* attribute to point to that file.  Let's see how it's done.

You'll see that you already have some content files in your MetaStatic repository.  Look in this directory: 

```code
examples/sites/tutorial/content/
```

You can also [view these files here](./examples/sites/tutorial/content).

You'll see that they contain copies of paragraphs taken from the MetaStatic repository's *README.md* file.

So let's amend our *index.meta* file to use the first one for the *About* menu item content.  Just edit this part of the *index.meta* file, leaving everything else unchanged:

```html
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-content-text text="markdown:tutorial.about.md" title="About MetaStatic" h="3" />
    </sbadmin-sidebar-menu-item>
```

Notice the syntax we use in the *&lt;sbadmin-content-text>* tag's *text* attribute.  It consists of three parts:

```code
markdown:{{namespace}}.{{filename}}
```
This syntax can be used for any Meta Tag attribute, and is of course normally used where the attribute value will be blocks of formatted/styled text.

- The *markdown:* prefix tells MetaStatic's Builder to use a text file for the attribute's value rather than the attribute's literal value.

- the *namespace* is an alias for a file path.

  Take a look at the [Builder script](./examples/build.mjs) and you'll see where the namespace to file path mapping is done for the *tutorial* namespace:
  
```code
    contentPath: {
      tutorial: './sites/tutorial/content'
    }
```  
  
- the *filename* is simply the name of the file to be used from within the namespace-aliased directory.  The name must include the file extension which, by convention, will normally be *.md* which denotes these to be Markdown files.

In our example above, *MetaStatic*'s Builder will therefore try to find the file *./sites/tutorial/content/about.md* and will used the Node.js *marked* Markdown processor module to convert its contents to HTML.  This converted content will then be used as the value for the *text* attribute.

Notice in our example that we're going to leave the heading defined for the *beforetext* slot.

Re-run the Builder and refresh the *index.html* page in your browser.  Now you'll see several paragraphs of properly marked-up and styled text that have been imported from the *about.txt* file.

![SB Admin UI with markdown text](./images/sbadmin-12.png)

Note that this text was imported at build time: it's not being retrieved dynamically from the file into the browser: all the text content held in MetaStatic's CMS are pulled into the HTML file that the Builder creates.

**Note**: You might have realised that the markdown text within the content file could have included a title.  If this is the case, simply leave out the *title* attribute from the *&lt;sbadmin-content-text>* tag.

Let's now add similarly-managed text content to our other menu options.  Edit the Menu section of your *index.meta* file to contain this:

```html
 <sbadmin-sidebar-menu>
    <sbadmin-sidebar-heading text="Select a Menu Option" />
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-content-text text="markdown:tutorial.about.md" title="About MetaStatic" h="3" />
    </sbadmin-sidebar-menu-item>
    <sbadmin-sidebar-nested-menu text="Technical" iconname="gears">
      <sbadmin-sidebar-menu-item text="Installation" iconname="wrench">
        <sbadmin-content-text text="markdown:tutorial.install.md" title="Installing MetaStatic" />
      </sbadmin-sidebar-menu-item>
      <sbadmin-sidebar-menu-item text="Configuration" iconname="sliders">
        <sbadmin-content-text text="markdown:tutorial.configure.md" title="Configuring MetaStatic" />
      </sbadmin-sidebar-menu-item>
    </sbadmin-sidebar-nested-menu>
  </sbadmin-sidebar-menu>
```

Re-run the Builder and refresh the *index.html* page in your browser.  You'll now see properly marked-up content for each of the menu options.  For example, the *Configuration* text will display as shown below when you click its menu option:

![SB Admin UI with markdown content](./images/sbadmin-13.png)

## Using Cards to Format Content Text

The *&lt;sbadmin-content-text>* Meta Tag is the most basic one to use for displaying Markup text content.

Since the *sbadmin* UI is based on [*Bootstrap v5*](https://getbootstrap.com/), you can make use of its many built-in styled components.  We've therefore included a number of additional Meta Tags for styling your content.

Let's start with a [*Card*](https://getbootstrap.com/docs/5.3/components/card/) which has been encapsulated in the *&lt;sbadmin-card-content>* Meta Tag.  You can [view its contents here](./examples/metaTagLibraries/sbadmin/sbadmin-card-content.mst).

Let's use this instead of the *&lt;sbadmin-content-text>* Meta Tag for displaying the *About* content.  Edit the *About* menu item in your *index.meta* file as follows:

```html
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-card-content text="markdown:tutorial.about.md" title="About MetaStatic" />
    </sbadmin-sidebar-menu-item>
```

Re-run the Builder and refresh the *index.html* page in your browser.  You'll now see the *About* content nicely displayed in a *card* component.  You'll also see now why we used the separate title text earlier:

![SB Admin UI with card content](./images/sbadmin-14.png)

MetaStatic also allows you to use a Markdown-styled document that has a header as its first line.  Take a look at [this alternative version](./examples/sites/tutorial/content/about-2.md) of the *about.md* file.  You'll see that it includes a header as its first line, denoted by the *#* prefix:

```code
# About MetaStatic

*MetaStatic* is a JavaScript tool that allows you to build and maintain a static web site using:
... etc

```

MetaStatic allows you to specify that you just want the header by specifying:

```code
  title="markdown:tutorial.about-2.md#header"
```

You can also specify that you want the body - *ie* everything after, but not including, the header:

```code
  text="markdown:tutorial.about-2.md#body"
```

So we could use this version of the Markdown content file as follows:

```html
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-card-content text="markdown:tutorial.about-2.md#body" title="markdown:tutorial.about-2.md#header" />
    </sbadmin-sidebar-menu-item>
```

Try it out for yourself.

## Displaying Tabbed Content

Another way to format and display your content is to use a 
[Bootstrap Tab Component](https://getbootstrap.com/docs/5.3/components/navs-tabs/#tabs).

This can be used instead of a nested menu for displaying two or more related topics.

The *&lt;sbadmin-tabs>* and *&lt;sbadmin-tab>* Meta Tags encapsulate the required behaviour for you.

You can view their contents here:

- [*sbadmin-tabs*](./examples/metaTagLibraries/sbadmin/sbadmin-tabs.mst)
- [*sbadmin-tab*](./examples/metaTagLibraries/sbadmin/sbadmin-tab.mst)

Let's use these for our *Installation* menu option content, to separately display the installation steps for Node.js and Bun.js.

So instead of using the current combined text in the *install.md* content file, we'll use two other pre-defined content files for this:

- [install-node.md](./examples/sites/tutorial/content/install-node.md)
- [install-bun.md](./examples/sites/tutorial/content/install-bun.md)

The *&lt;sbadmin-tabs>* Meta Tag is used as the container for the *&lt;sbadmin-tab>* Meta Tags, the latter defining each individual tab and its content.

Similarly to the *&lt;sbadmin-content-text>* Meta Tag, the *&lt;sbadmin-tabs>* Meta Tag allows you to optionally define a title.

Let's put this all together for the *Installation* menu item which you should change in your *index.meta* file as follows:

```html
      <sbadmin-sidebar-menu-item text="Installation" iconname="wrench">
        <sbadmin-tabs title="Installing MetaStatic">
          <sbadmin-tab title="Node.js" text="markdown:tutorial.install-node.md" active />
          <sbadmin-tab title="Bun.js" text="markdown:tutorial.install-bun.md" />
        </sbadmin-tabs>
      </sbadmin-sidebar-menu-item>
```

Note that we've specified the first tab to be *active*, so it's automatically displayed when the content for the *Installation* option is selected, along with its associated text.

Re-run the Builder and refresh the *index.html* page in your browser.  When you click the *Installation* menu option, you'll now see the tabbed display:

![SB Admin UI with tabbed content](./images/sbadmin-15.png)

Of course you're now probably wondering if you can combine Tabs and Cards, ie displaying the tabbed content within a card.  The answer is yes, and it's made possible by an optional slot named *tabcontent* provided by the *&lt;sbadmin-tab>* Meta Tag.  To use this, simply override the *&lt;sbadmin-card-content>* Meta Tag's default slot by specifying the *tabcontent* slot in a *slot* attribute.

Let's use this to change the *Installation* text for the Bun.js tab to use a Card:

```html
      <sbadmin-sidebar-menu-item text="Installation" iconname="wrench">
        <sbadmin-tabs>
          <h1 slot="beforetabs">Installing MetaStatic</h1>
          <sbadmin-tab title="Node.js" text="markdown:tutorial.install-node.md" active />
          <sbadmin-tab title="Bun.js">
            <sbadmin-card-content slot="tabcontent" text="markdown:tutorial.install-bun.md" title="Bun.js" />
          </sbadmin-tab>
        </sbadmin-tabs>
      </sbadmin-sidebar-menu-item>
```
Re-run the Builder and refresh the *index.html* page in your browser.  When you click the *Installation* menu option and select the *Bun.js* tab, you'll now see its content displayed in a Card:

![SB Admin UI with tabs and card](./images/sbadmin-16.png)

## Using Carousels to Display Text Content

Another way to display text content is to use 
[Bootstrap's Carousels](https://getbootstrap.com/docs/5.3/components/carousel/).  These can work well where you have a sequence of related text sections.  Rather than having a lengthy set of paragraphs that the user has to scroll through, you can display each paragraph or section in its own carousel card, and the user can move forwards or backwards through the content, essentially like a set of slides.

Carousels can, of course, also be used for displaying images, but in this example we'll just use one for text.  We're going to use it for the *usecase-{{no}}.md* files that 
[you'll see here](./examples/sites/tutorial/content).

Let's first add a new menu item to the end of the main menu, titled *Use Case for MetaStatic*:

```html
 <sbadmin-sidebar-menu>
    <sbadmin-sidebar-heading text="Select a Menu Option" />
    <sbadmin-sidebar-menu-item text="About" iconname="circle-info" active>
      <sbadmin-card-content text="markdown:tutorial.about.md" title="About MetaStatic" />
    </sbadmin-sidebar-menu-item>
    <sbadmin-sidebar-nested-menu text="Technical" iconname="gears">
      <sbadmin-sidebar-menu-item text="Installation" iconname="wrench">
        <sbadmin-tabs>
          <h1 slot="beforetabs">Installing MetaStatic</h1>
          <sbadmin-tab title="Node.js" text="markdown:tutorial.install-node.md" active />
          <sbadmin-tab title="Bun.js">
            <sbadmin-card-content slot="alttabcontent" text="markdown:tutorial.install-bun.md" title="Bun.js" />
          </sbadmin-tab>
        </sbadmin-tabs>
      </sbadmin-sidebar-menu-item>
      <sbadmin-sidebar-menu-item text="Configuration" iconname="sliders">
        <sbadmin-content-text text="markdown:tutorial.configure.md">
          <h1 slot="beforetext">Configuring MetaStatic</h1>
        </sbadmin-content-text>
      </sbadmin-sidebar-menu-item>
    </sbadmin-sidebar-nested-menu>

    <sbadmin-sidebar-menu-item text="Use Case for MetaStatic" iconname="chalkboard-user">
    </sbadmin-sidebar-menu-item>
    
  </sbadmin-sidebar-menu>
```

Inside this menu item tag, we'll specify that we want to use a Carousel by adding a
[*&lt;sbadmin-carousel>*](./examples/metaTagLibraries/sbadmin/sbadmin-carousel.mst) Meta Tag.  This creates the styled container for the
[*&lt;sbadmin-carousel-item>*](./examples/metaTagLibraries/sbadmin/sbadmin-carousel-item.mst) Meta Tags.

```html
    <sbadmin-sidebar-menu-item text="Use Case for MetaStatic" iconname="chalkboard-user">
      <sbadmin-carousel>
      </sbadmin-carousel>
    </sbadmin-sidebar-menu-item>
```

Then we add each Carousel Item.  We'll start with the first which must be specified as *active*:

```html
    <sbadmin-sidebar-menu-item text="Use Case for MetaStatic" iconname="chalkboard-user">
      <sbadmin-carousel>
        <sbadmin-carousel-item active>
        </sbadmin-carousel-item>       
      </sbadmin-carousel>
    </sbadmin-sidebar-menu-item>
```

Within each Carousel Item we can use either of the text formatting Meta Tags we've used previously:

- *sbadmin-content-text*
- *sbadmin-card-content*

We'll just need to override their default slot with the one provided by the *sbadmin-carousel-item* Meta Tag: *carouselitem*.  Let's use Cards to display each Carousel Item.  Here's the first one:

```html
    <sbadmin-sidebar-menu-item text="Use Case for MetaStatic" iconname="chalkboard-user">
      <sbadmin-carousel>
        <sbadmin-carousel-item active>
          <sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-1.md#header" text="markdown:tutorial.usecase-1.md#body" />
        </sbadmin-carousel-item>       
      </sbadmin-carousel>
    </sbadmin-sidebar-menu-item>
```

**Note**: The *usecase-1.md* file includes a header which we want to display in the Card header, whilst we want to display the Markdown content's body (*ie* everything else apart from the header) in the Card's body.  We therefore use the *#header* and *#body* suffixes at the end of the file references:

```html
          <sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-1.md#header" text="markdown:tutorial.usecase-1.md#body" />
```

We're going to set the card width to 77% to provide room on either side for the Carousel controls.

OK so now we have established the pattern, let's add all the other Carousel Items.  Note that only the first *sbadmin-carousel-item* should be specified as *active*:

```html
    <sbadmin-sidebar-menu-item text="Use Case for MetaStatic" iconname="chalkboard-user">
      <sbadmin-carousel>
      
        <sbadmin-carousel-item active>
<sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-1.md#header" text="markdown:tutorial.usecase-1.md#body" />
        </sbadmin-carousel-item>
        
        <sbadmin-carousel-item>
<sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-2.md#header" text="markdown:tutorial.usecase-2.md#body" />
        </sbadmin-carousel-item> 
        
        <sbadmin-carousel-item>
<sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-3.md#header" text="markdown:tutorial.usecase-3.md#body" />
        </sbadmin-carousel-item>           
        
        <sbadmin-carousel-item>
<sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-4.md#header" text="markdown:tutorial.usecase-4.md#body" />
        </sbadmin-carousel-item> 
        
        <sbadmin-carousel-item>
<sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-5.md#header" text="markdown:tutorial.usecase-5.md#body" />
        </sbadmin-carousel-item> 
                        
        <sbadmin-carousel-item>
<sbadmin-card-content slot="carouselitem" width="77%" title="markdown:tutorial.usecase-6.md#header" text="markdown:tutorial.usecase-6.md#body" />
        </sbadmin-carousel-item> 
 
      </sbadmin-carousel>
    </sbadmin-sidebar-menu-item>
```

Re-run the Builder and refresh the *index.html* page in your browser.  When you click the new *Use Case for MetaStatic* menu option, you'll now see the first of the Carousel items.  Click the *next* and *previous* controls (< and >) to move through the Carousel Items.

![SB Admin UI with carousel](./images/sbadmin-17.png)


## Making Use of the MetaStatic *&lt;foreach>* Tag

You're probably thinking that the specification of each Carousel item in the previous example was both laborious and repetitive.  The only thing that was different for each Carousel item definition was the Markdown file name, each of which had a number from 1 to 6:

- usecase-{{number}}.md

Wouldn't it be nice to define a loop and iterate through each of these?  This is precisely what the special *&lt;foreach>* Tag allows you to do.

Whilst you can use the *&lt;foreach>* Tag in your own *index.meta* file, its use is a little complex and more suited to being used by a developer to construct a Meta Tag with a built-in loop.

Take a look at the [*&lt;sbadmin-carousel-cards>* Tag](./examples/metaTagLibraries/sbadmin/sbadmin-carousel-cards.mst).  You'll see that it includes the *&lt;foreach>* Tag to create a loop:

```html
<template :namespace="^namespace" :prefix="^filenameprefix">
  <sbadmin-carousel>
    <foreach type="filename" namespace=":namespace" prefix=":prefix" >
      <sbadmin-carousel-item active="=><index===0 && 'active'">
        <sbadmin-card-content slot="carouselitem" width="77%" title="markdown::namespace.<iterator#header" text="markdown::namespace.<iterator#body" />
      </sbadmin-carousel-item>
    </foreach>
  </sbadmin-carousel>
</template>
```

If you specify a *foreach* type of *filename*, as in this example, MetaStatic will loop through all the files in the specified *namespace* folder where the filename is prefixed by the text specified by the *prefix* attribute.

So in our example, we would specify a prefix of *usecase-*, and it will find all the files we want and put them into alphanumeric order before processing each one within the loop.

Inside the loop we make use of two special attribute variables that are provided by MetaStatic:

- *<index*: the loop index number, which starts at 0;
- *<iterator*: for a *foreach* of type *filename*, this will be the filename for each loop iteration.

These are simply applied to the standard *sbadmin* Meta Tags that we're using inside the *foreach* loop.

This example also demonstrates another important aspect of MetaStatic: Meta Tags can be layered inside each other.

So, let's modify our previous example to make use of this *&lt;sbadmin-carousel-cards>* Tag.  All those repetitive Carousel tags can be simply replaced with this:

```html
    <sbadmin-sidebar-menu-item text="Use Case for MetaStatic" iconname="chalkboard-user">
      <sbadmin-carousel-cards namespace="tutorial" filenameprefix="usecase-" />
    </sbadmin-sidebar-menu-item>
```

Re-run the Builder and refresh the *index.html* page in your browser.  When you click the new *Use Case for MetaStatic* menu option, you'll see exactly the same set of cards in the Carousel, but these were generated at build time using the *&lt;sbadmin-carousel-card>* Meta Tag's *foreach* loop!

You can see how MetaStatic can be used to create Meta Tags that allow a very succinct and intuitive syntax for describing an otherwise complex user interface HTML file: take a look at the *index.html* file that has been generated and you'll see what we mean!

----

## Conclusions

You've now learnt how to use MetaStatic and how to build a Web Site using a Meta Tag Library.

The *sbadmin* Tag Library implements just a sub-set of the SB Admin UI, but hopefully enough:

- to provide the main components needed for anyone wanting to build and maintain Web Sites;
- to demonstrate to technical developers how to create and design MetaStatic Meta Tags.

Feel free to implement more *sbadmin* Meta Tags of your own, or try creating a completely different Tag Library based on some other template.

We hope you find MetaStatic to be useful, productive and fun!