Modules - PageAmp/pageamp GitHub Wiki

PageAmp supports splitting a page source code into several .htm files included in a main .html file.

For example this page:

<html>
  <head>
    <:include src="style.htm"/>
  </head>
  <body>
    <div class="box"></div>
  </body>
</html>

incorporates into its <head> the content of the root tag in style.htm:

<lib>
  <style>
    .box {
      width: 100px;
      height: 100px;
      background-color: red;
    }
  </style>
</lib>

so the output HTML looks like this:

<html>
  <head>
    <style>
      .box {
        width: 100px;
        height: 100px;
        background-color: red;
      }
    </style>
  </head>
  <body>
    <div class="box"></div>
  </body>
</html>

Note: inclusion doesn't work at text level but rather in a server-side virtual DOM.

In PageAmp parlance, style.htm is called a module.

A module's root tag can have any name, and its attributes are called module attributes.

Module Attributes

Root tag's attributes in a module are special: they are copied to the <:include>'s parent tag unless an attribute with the same name is already there.

This may sound confusing, but in practice it's a quite useful behaviour: modules can specify default values for logic attributes they use, which can be optionally overridden where they are included.

For example, given a module icon.htm, defining a fontawesome icon:

<lib :icon_name="square">
  <i class="fas fa-[[icon_name]]"></i>
</lib>

you can use its module attribute :icon_name like this:

<span :icon_name="circle">
  This is an icon: <:include src="icon.htm"/>
</span>

which results in this output:

<span>
  This is an icon: <i class="fas fa-circle"></i>
</span>

(if you omit :icon_name in the <span>, the icon will be module's default, i.e. a circle)

Note: by convention module attributes are prefixed with <module-name>_ to prevent conflicts.

This example is admittedly a bit contrived: a PageAmp component would be better here. But it's useful to explain the concept, which is used extensively in PageAmp kits to implement customizable visual themes.

Imports

You can include a module with either <:include> or <:import>. The former can be used to repeatedly include a particular module at different points in your HTML. The latter will only perform the inclusion a single time for each module.

PageAmp supports recursive inclusions, meaning a page can include modules which, in turn, include other modules. This is particularly useful for creating kits.

The <:import> tag will guarantee that no matter where a certain module is imported in a tree of recursive inclusions, it will only appear once in the final output.

Note: the src attribute in both <:include> and <:import> can either specify an absolute path, starting with a /, or a path relative to the location of the page (or module) where it's used.

The root of the path is web server's document root. The preprocessor supports ../ paths but will prevents access to files outside the root.

Textual Inclusion

Both <:include> and <:import> will import plain text rather than modules if the target file's extension isn't .htm.

⚠️ **GitHub.com Fallback** ⚠️