Development Guidelines

Overview

The Central Supply Catalog (CSC) is a static website that is generated using the following technologies:

• Eleventy - static site generator
• Node.js - required for Eleventy
• Nunjucks - templating engine
• Gulp - task runner
• HTML 5 - Markup Language
• CSS 3 - Cascading Style Sheets
• Javascript - scripting language

Design Goals

The CSC has been designed with the following goals:

• Ease of deployment
• Minimal dependencies
• Highly responsive
• Robust
• Secure
• Mobile-First design

Repository Design

The repository houses two categories of files:

• System-related (lives in the root directory)
  • .babelrc - Babel configuration file
  • .eleventy.js - Eleventy config file
  • .gitignore - files to ignore
  • .gulpfile.js - Gulp task runner
  • package.json - project package list^*
  • sw.js - service worker

^*Only the package.json file is checked into the project. It contains a list of the packages and version numbers required by the project. (See Setting up the Development Environment)

• Site-related (lives in the src directory)
  • _data - data files for catalog items; also holds search index file
  • audio - audio files (future release)
  • img - image files
  • js - Javascript files
  • pages - page templates
  • partials_layouts - partials (components) and page layouts
  • scss - SASS files
  • util - miscellaneous command line utilities

Setting up the Development Environment

To set up the development environment, clone the project:

git clone https://cmcknight/central-supply-catalog.git

Download NodeJS v15.11.0 link and install it.

NOTE: NodeJS v15.11.0 is the latest version tested for the project. The current version (16.x) broke several libraries. When that situation is rectified the project will move to NodeJS v16.x.

Install Node package dependencies:

cd central-supply-catalog
npm -i

This action will create a directory named node_modules that contains all of the dependencies for the project. Per NodeJS best practices, this folder should not be checked into version control.

Launching the Developer Version Site

At this point you will need to run either the dev npm script from a terminal:

npx run dev

or the watch:eleventy and watch:sass scripts from separate terminals:

npx run watch:sass
npx run watch:eleventy

NOTE: Many editors, such as Atom, Visual Studio Code, etc., have plugins that will allow you to run the NPM scripts from within the editor.

When the site has built and loaded, you should see the following in the terminal:

[Browsersync] Access URLs:
--------------------------------------
       Local: http://localhost:8080
    External: http://192.186.1.58:8080
---------------------------------------
          UI: http://localhost:3000
 UI External: http://localhost:3000
---------------------------------------
[Browsersync] Serving files from: build

Point the browser to http://localhost:8080 to see the development version of the site.

NOTE: The external address may differ depending on the IP address of your system.

Building the Search Index

The development version does not automatically build the search index at this time, so this must be built manually using a NodeJS script. At the project root type:

node src/util/search.js

This action will create the searchindex.idx file in the src/_data directory.

Building the Production Site

The production version of the site is built into the dist directory off of the project root. The project uses the Gulp taskrunner to build the production version of the site. Gulp is essentially a "make" file utility that executes a series of command in a gulpfile.js configuration file.

To build the production version of the site, install the Gulp command line (gulp-cli):

npm -i --global gulp-cli

then run the following command from the project root:

npx gulp

The gulpfile.js has several visible tasks that can be run if you like:

• default - build production site
• monitor - build production site, start webserver on port 5500, open browser to http://localhost:5500
• clean_prod - delete the contents of the dist directory
• build_index - build the search index in the dist/_data directory

Deployment

Deployment to the official site is restricted to the admins. However, the dist folder contains everything necessary to deploy to a separate site should that be desired.

Reporting Bugs

Use the issue tracker to report all bugs. Please include the following information:

• Device (desktop, phone, tablet) Include manufacturer and model if device is a phone or tablet.
• Operating System & Version
• Screen size (width / height)
• Browser & Version
• Steps to reproduce
• Detailed description of the bug

New Features

Use the discussions forum to propose new features.

Support

Contact the support team via email