Kits - PageAmp/pageamp GitHub Wiki

Kits leverage modules and components to create coherent and visually themable collections of UI building blocks. They are not called "libraries" to avoid confusion with JavaScript libraries you may use in your projects.

Kits live in their own directory placed in the server's document root, prefixed with a . to prevent conflicts and keep them out of the way.

Let's create a very simple one to show their features.

A Sample Kit

Our kit lives in directory .samplekit inside the document root:

.samplekit/
  sk/
    base.htm
    fontawesome.htm
  res/
    fontawesome-free-5.15.3-web/
  sk.htm
index.html

/.samplekit/sk.htm

<lib>
  <:import src="sk/base.htm"/>
  <:import src="sk/fontawesome.htm"/>
</lib>

/.samplekit/sk/base.htm

<lib :sk_base_fontFamily="sans-serif">
  <style>
    body {
      font-family: [[sk_base_fontFamily]];
    }
  </style>
</lib>

/.samplekit/sk/fontawesome.htm

<lib :sk_icon_color="red">
  <:import src="base.htm"/>
  <link href="/.pageamp-kit/res/fontawesome-free-5.15.3-web/css/all.css" rel="stylesheet">
  <style>
    .sk-icon {
      color: [[sk_icon_color]];
    }
  </style>
  <:define tag="sk-icon:i" class="sk-icon fas fa-[[name]]"/>
</lib>

/index.html

<html>
  <head :sk_icon_color="blue">
    <:import src="/.samplekit/sk.htm"/>
  </head>
  <body>
    A square icon: <sk-icon name="square"/><br/>
    A circle icon: <sk-icon name="circle"/><br/>
  </body>
</html>

This is its output HTML:

<html>
  <head>
    <style>
      body {
        font-family: sans-serif;
      }
    </style>
    <link href="/.samplekit/res/fontawesome-free-5.15.3-web/css/all.css" rel="stylesheet">
    <style>
      .sk-icon {
        color: blue;
      }
    </style>
  </head>
  <body>
    A square icon: <i class="sk-icon fas fa-square"></i><br/>
    A circle icon: <i class="sk-icon fas fa-circle"></i><br/>
  </body>
</html>

Notes:

Our kit defines basic page styles and an sk-icon component.
Kits name all their CSS classes and components with a common prefix, sk in our example.
The kit defines the :sk_base_fontFamily and :sk_icon_color module attributes.
The kit includes the resources it needs in its res/ directory.
index.html overrides :sk_icon_color to "blue".
index.html imports the whole kit using /.samplekit/sk.htm, but components are designed to be usable even when imported one by one, and in turn import all their prerequisite modules.