Code Modules — Docs

High Level Modules

High Level Modules

Overview of Code Modules’ Include-based Architecture

High Level Overview of Code Modules’ Include-based Architecture.

Call from a top level HTML page to its doppelgänger in the Pages modules. The doppelgänger calls the Markup modules and the other high level modules to construct the page which it then passes back to the top of the calling chain.

There are five major types of modules (high level modules) used in Code Modules. Each of these module types are different from one another in their internal structure and purpose. But they all adhere to the primary module rule: all external calls to the module goes through the entry page — the entry.shtml in each module’s root. Each website will have many Markup modules, but only one each of the Pages, Nav, Tech, and (optional) Elements module.

Click on the links, above, to get a detailed description of each of these high level module types on their dedicated documentation pages.

The collapsed tree for the app/modules/ folder looks like:

app/modules — high level modules folders
├── elements
├── markup
├── nav
├── pages
└── tech

Below is an introductory overview of each type.

Markup Modules

Markup modules return some markup. Markup modules are particularly well-suited for data that repeats its markup for each item — often a list. Every website displays different content, but here are some common use cases:

  • Team members with their portraits
  • Slideshow with images and captions
  • Videos each with a title and some text
  • Page description metadata customized for each page
  • Services and their prices
  • Products and their descriptions
  • FAQ questions and answers
  • Blog posts
  • Portfolio items
  • Contact list
  • Testimonials
  • List of customers with their logos
  • Social media links

Each of these modules live as a subfolder of app/modules/markup/. For example, the Team module would be at /app/modules/markup/team/ and the Faq module would be found at /app/modules/markup/faq/.

Pages Module

The Pages module is located at app/modules/pages/. Every top level HTML page on the site has a unique doppelgänger within the Pages module. So the about.html page has a Pages module template file about.shtml. The top level HTML page about.html calls the Pages module entry file, passing a variable to access the about.shtml template.

The entry file for the Pages module defines all the global variables used on the site. From there, flow is directed to the unique doppelgänger file — one for each of the site’s pages — within app/modules/pages/templates/. That template file contains any unique markup for its top level HTML page and it calls all the other modules that are needed to build that top level page. That will include calls to the Tech module, for the top and bottom of the page, and the Nav module for the page’s navigation. It also probably includes calls to one or more Markup modules for the page’s content.

Tech Module

The Tech module is responsible for building the <head> section — for titles, metatags, and links to stylesheets and fonts. It’s also responsible for the non-displaying “foot” section of a web page, where scripts are often placed.

Navigation is an important feature of most websites; even single page websites often have anchor links down to sections on their page. The Nav module returns the markup necessary for both desktop and mobile navigation. Sometimes, nav markup will be placed in headers, and sometimes within sidebars and footers. The markup can be different depending on where it’s used. But all the nav markup comes from the same source of data.

The Nav module is the most complex module in this documentation; it’s complicated in order to demonstrate that a Nav module can have a range of features. Yours doesn’t need to be nearly as complex.

Elements Module

Websites usually have pieces of markup that don’t deserve a whole module — these are akin to a traditional include. It can still be handy to organize these bits and allow them to access global variables. I use a high level Elements module for this purpose. It’s found at app/modules/elements/. The internal structure of the Elements module is more free-form than a normal Markup module; it usually doesn’t use lists/ and types/ folders. But, like all modules, it’s called through its root entry.shtml entry file.

Some examples of items suitable for the Elements module:

  • Forms
  • iFrames
  • Logos
  • Widgets
  • Icons
  • Policies

If there’s a lot of one type — i.e. a lot of forms — then I could make a separate forms/ subfolder to keep the Elements module organized.