Code Modules — Docs
Tech Module
Tech Module
Overview of Tech Module
Each page calls both the “head” and “foot” templates of the Tech module. The Tech module’s head template calls lists of meta tags and link items. The foot template calls a list of javascript items. Special templates can be set up for pages — often the home page — with special needs.
The Tech module is like a kitchen tool drawer. It can contain a bit of everything and be a bit disorganized. My conventions for the Tech module are not very important. I’ll document them here, but feel free to change the internal organization to fit your preferences. The only really important bit — like all modules — is to never call any file within the module directly. Always go through the module’s entry file: app/modules/tech/entry.shtml
The Sample Website’s Tech module has three templates: head, head-home, and foot. The head is everything that goes within a web page’s <head> tag and usually contains metadata, links to stylesheets and fonts, and other content that needs to load first. The head-home is just a variation of the head template, adjusted because there are preload links in the head of the home page that support the carousel. The foot is everything that goes after the visible content of the page. The foot usually contains javascript content or calls to javascript files.
I've found it useful to organize the Tech module so that it contains a meta/ folder, a links/ folder, and a js/ folder.
The meta/ folder is almost like a module within the Tech module. Within it, there are items/, lists/, and types/. Items can just contain data and call a Type file. But, sometimes, they just contain markup and don’t call a Type file.
The links/ folder is similar with items/, lists/, and types/ subfolders.
The js/ folder is somewhat barren in the Sample Website because all javascript is being bundled by Parcel. In other websites, there would be items for jquery, bootstrap, modernizr, google-analytics, and so on.
Tree List of Tech Folder from Sample Website
1tech/2├── _notes.txt3├── entry.shtml4├── js/5│ ├── items/6│ │ └── load-bundle.shtml7│ └── lists/8│ └── default.shtml9├── links/10│ ├── items/11│ │ ├── blank.shtml12│ │ ├── canonical-url.shtml13│ │ ├── preload.shtml14│ │ ├── stylesheets.shtml15│ │ └── webfonts.shtml16│ ├── lists/17│ │ ├── default.shtml18│ │ └── home.shtml19│ └── types/20│ └── default.shtml21├── meta/22│ ├── items/23│ │ ├── author.shtml24│ │ ├── blank.shtml25│ │ ├── charset.shtml26│ │ ├── copyright.shtml27│ │ ├── http-equiv.shtml28│ │ ├── open-graph.shtml29│ │ ├── title.shtml30│ │ ├── twitter-card.shtml31│ │ ├── verification.shtml32│ │ └── viewport.shtml33│ ├── lists/34│ │ └── default.shtml35│ └── types/36│ └── default.shtml37└── templates/38 ├── foot.shtml39 ├── head-home.shtml40 └── head.shtmlJavascript Files and Bundles
All the javascript files used in the Sample Website are packaged in a bundle that’s loaded in the tech/js/items/load-bundle.shtml file. On other websites, each javascript program has an item file.
By splitting each javascript file into its own item, it’s easy to create list files that have just the right files for each page. If the carousel feature is only used on one page of the site, that page can have a special list that first just calls the default list and then adds the carousel item to it.
The Sample Website is using the Parcel bundler. Parcel requires a link from the top level html page to the javascript used on the site so that it can bundle it together. That is accomplished on this site with a path that steps out of the modules/ folder and into the app/js/ folder.
<!-- JavaScript Bundle (includes jQuery and Bootstrap) --><script src="/../app/js/app.js"></script>Tech Module’s Entry file
The Tech modules entry file is:
<!-- #bbinclude "/#MODULE#/templates/#TEMPLATE#.shtml"#bbincludeoptions#="inline=true"#MODULE# = 'tech'#DESCRIPTION# = '#BASE-DESCRIPTION# #LONG-DESCRIPTION#'--><!-- end bbinclude -->The head.shtml template file calls the lists for meta/ and for links/. The foot.shtml file calls the js/ list file. By separating items out in this way, the head and foot of the site are kept flexible and maintainable.
Metadata and Links
The #DESCRIPTION# variable is used throughout the metadata, especially in the Description metatag, and the Open Graph and Twitter Cards. In the example above, the description is built from two variables defined in the Page module global variables and will be the same on every page. If each page requires a different set of metadata, the Tech module’s meta/ section (i.e. app/modules/tech/meta/items/description.shtml) can pass the #PAGES# variable to a Description module to return custom description metatag data for each page of the site.
The Head template file is:
#bbinclude "/#MODULE#/meta/lists/default.shtml"#bbinclude "/#MODULE#/links/lists/default.shtml"It calls the default lists in the meta/ and the links/ folders.
#bbinclude "/#MODULE#/js/lists/default.shtml"The Foot template file calls the default list in the js/ folder.
The Meta default list is:
#bbinclude "/#MODULE#/meta/items/charset.shtml"#bbinclude "/#MODULE#/meta/items/http-equiv.shtml"#bbinclude "/#MODULE#/meta/items/viewport.shtml"#bbinclude "/#MODULE#/meta/items/title.shtml"#bbinclude "/#MODULE#/meta/items/author.shtml"#bbinclude "/#MODULE#/meta/items/copyright.shtml"#bbinclude "/#MODULE#/meta/items/open-graph.shtml"#bbinclude "/#MODULE#/meta/items/twitter-card.shtml"#bbinclude "/#MODULE#/meta/items/verification.shtml"The Links default list is:
#bbinclude "/#MODULE#/links/items/canonical-url.shtml"#bbinclude "/#MODULE#/links/items/webfonts.shtml"#bbinclude "/#MODULE#/links/items/stylesheets.shtml"One of the meta items — copyright — looks like this:
<!-- #bbinclude "/#MODULE#/meta/types/default.shtml"#bbincludeoptions#="inline=true"#NAME# = 'Copyright'#CONTENT# = 'Copyright © #YEARNUM#, #COMPANY#. Open Source #LICENSE#.'--><!-- end bbinclude -->The copyright item calls a Type file and slots its variables into standard metatag markup. The odd optional use of white space makes the metatags easier to scan in the source code.
<meta name="#NAME#" content="#CONTENT#" />A meta item — open-graph — returns markup directly rather than through a Type file:
<!-- Open Graph --><meta property="og:title" key="ogtitle" content="#PAGE-TITLE# — #COMPANY#" /><meta property="og:site_name" key="ogsitename" content="#COMPANY#" /><meta property="og:url" key="ogurl" content="#URL-ROOT##CANONICAL-URL#" /><meta property="og:description" key="ogdesc" content="#DESCRIPTION#" /><meta property="og:type" key="ogtype" content="website" /><meta property="og:locale" key="oglocale" content="en_US" /><meta property="og:image" key="ogimage" content="#URL-ROOT##PAGE-IMAGE-PATH#/#PAGE-IMAGE#" />Since each item is isolated from the other, but also able to access global variables, the metadata for the site is easy to maintain.