Conventions Overview

Conventions underlie Code Modules (CM). This standardized approach has been developed over years to be flexible enough for most use cases. Someone could create a different set of conventions, but these are ones that we’ve found useful for our purposes.

In the module system, each module handles its own tasks without knowing about the other modules. One communicates with a module only through a call to its entry file. A module has a standardized way to handle its tasks, with separate subfolders — templates, lists, items, and types — generally called in that order.

Each module encapsulates its complexity behind a public interface located at the root for that module. The entry file — a file always named entry.shtml at the root of the module — is the only file ever called from outside the module. The module’s entry has an exposed interface for how to interact with the module — usually, what variables to define including which templates to call. One can change the internals of the module knowing that it won’t break the rest of the site so long as the calls to the entry — the “promises” of that module — are handled properly. What happens in the internals of the module are not part of the module’s promises and can be refactored as needed.

Modules can communicate with each other. When one module needs information found in another module, it calls it in a standardized way — through the second module’s entry file, never directly accessing another module’s internals. The second module returns the requested markup to the first module that called it.

This is a system that needs to be described both from the top-down and from the bottom-up. Top-down follows the flow of includes, which starts from the highest level — a top level HTML page which will be served to the public — and flows down through the chain of includes that are called to build that page. Bottom-up details what’s going on within individual modules. More complicated modules can call other modules or even call themselves. We’ll see examples of that on the Markup modules page and in the Nav module.