VCU Compass Web Framework

Guidelines

Compass brandmark

Compass v1.7.0

The university web framework. This repository holds the source files of core Compass assets.

Table of contents

  1. Install as an NPM dependency
    1. Install via VCU’s NPM registry
      1. Updating your default registry
      2. Install via default registry
    2. Install via Git
    3. Importing JS
    4. Requiring CommonJS
    5. Using SCSS
    6. Using CSS
  2. Clone the repo
    1. Requirements
    2. Development
    3. Browser support
  3. Guidelines
    1. Development and production modes
    2. JS
    3. SCSS
    4. Twig
    5. Linting and formatting
  4. Contributing

Install as an NPM dependency

You can include Compass as an NPM dependency in your next project, allowing you to pull in just the HTML, JS, or SCSS that you need.

Install via VCU’s NPM registry

The easiest way to include Compass as an NPM dependency in your next project is through VCU’s NPM registry. Compass is hosted on a private software distribution server, and installing it via this method requires you to be on VCU’s network.

npm install cwf --registry=https://nexus.ts.vcu.edu/repository/vcu-npm/

Updating your default registry

To avoid having to include the registry flag every time you install Compass, set your global or project’s NPM registry to VCU’s NPM registry. Our recommendation is to use VCU’s NPM registry globally, as it’s the simplest solution with little-to-no project maintenance.

# Global configuration
echo 'registry=https://nexus.ts.vcu.edu/repository/vcu-npm/' > ~/.npmrc

# Project configuration
cd my-project
echo 'registry=https://nexus.ts.vcu.edu/repository/vcu-npm/' > .npmrc

Install via default registry

With VCU’s NPM registry set as your default, you can now install Compass like any other package.

npm install cwf@latest

Install via Git

If you don’t want to use VCU’s NPM registry, you can install Compass as an NPM dependency from our SCM repo via Git.

npm install git+ssh://git@scm.vcu.edu:7999/cwf/core.git

We don’t recommend this option, as installing via Git causes maintenance issues, such as no version tracking (so NPM will always say Compass is outdated).

Importing JS

If you’re using a build-system that uses something like Webpack with support for ES2015+ modules, you can import any Compass component JS as follows:

// Nav class (from nav JS)
import { Nav } from 'cwf/components/nav/index.js';

// Nav class (from components JS)
import { Nav } from 'cwf/components/index.js';

You can also import all component JS classes as an object:

// All component classes (from components JS)
import * as components from 'cwf/components/index.js';

// All component classes (from root JS)
import { components } from 'cwf';

If you want to include and run all Compass JS (resets and components), just import the bundled JS code:

// All Compass JS
import 'cwf/dist/js/cwf.js';

Requiring CommonJS

This package of type module, meaning import/export (ESM) is used for Node.js functionality instead of require/module.exports (CommonJS). While this probably won’t interfere with CommonJS projects using Compass as a dependency, because most assets are used solely for the purpose of transpilation to front-end browser code, all JS modules have been provided with CommonJS alternatives under the dist directory to ensure compatibility.

// Use the flatten function from the shared route module
const { routes } = require('path/to/routes.json');
const { flatten } = require('cwf/dist/shared/route.cjs');

console.log(flatten(routes));

// Use the markdown function from the shared transform module
const { mardown } = require('cwf/dist/shared/transform/index.cjs');
const input = `
# This is a heading
This is a paragraph
`;
const output = markdown(input);

console.log(input, output);

// Use the breadcrumb component JS
const { Breadcrumb } = require('cwf/dist/components/breadcrumb/index.cjs');

new Breadcrumb();

Using SCSS

You can use any Compass SCSS files as follows:

// Nav styles
@use 'path/to/node_modules/cwf/components/nav';

Compass uses the sass compiler instead of the default but deprecated node-sass compiler for compiling SCSS to CSS. This allows us to use new, powerful syntax when writing SCSS. An example of such syntax is our use of the new @use module imports, which future-proofs the project and allows for better namespacing.

You can avoid having to type the full path to Compass within the node_modules directory by resolving its path within your build system. For Gulp (which is what Compass uses for converting SCSS to CSS), you can do the following within your SCSS task:

...
.pipe(gulpSass({
    includePaths: [ 'node_modules' ]
}))
...

This allows you to write the following, which is much simpler and easier to remember:

// Nav styles (with node_modules path resolved)
@use 'cwf/components/nav';

You can also use all component SCSS as follows:

// Component styles (with node_modules path resolved)
@use 'cwf/components';

If you want to use all Compass SCSS (resets, utilities, and components), just use the whole package:

// All Compass styles (with node_modules path resolved)
@use 'cwf';

Using CSS

If you don’t want to use SASS in your projects, all components, resets, and utilities are packaged with transpiled CSS files in the dist directory for your convenience. You can copy over a specific component, reset, or utility CSS file, or you can pull in all components, resets, or utilities as well.

# Copy the nav component's CSS
cp node_modules/cwf/dist/components/nav/index.css ./nav.css

# Copy all reset CSS
cp node_modules/cwf/dist/resets/index.css ./resets.css

# Copy the text utility CSS
cp node_modules/cwf/dist/utilities/text/index.css ./text.css

# Copy all CSS
cp node_modules/cwf/dist/css/cwf.css .

Clone the repo

To install the repo as an easy way to bootstrap your static Compass site development, clone the repo and install all the required dependencies.

git clone ssh://git@scm.vcu.edu:7999/cwf/core.git compass-web-framework
cd compass-web-framework
npm i

Requirements

This repo was setup using the long-term support release of Node, which at the time of writing is v16.13.2, and NPM v8.3.0. While you may have little to no issues setting up and running the repo with a older/newer version of Node, this has not been tested. To make this process easier, we recommend using nvm to manage Node versions, as this repo includes an .nvmrc to tell nvm which Node version to use when working within the project.

Development

# To develop assets and live-reload them locally
npm run develop
npm run dev
npm run start

# To build production assets...
npm run build
# ... and then to see them locally
npm run serve

Browser support

At the time of writing, this project supports the last two major versions of Chrome, Edge, Firefox, Opera and Safari as noted in the project’s package.json:

defaults and last 2 versions,
not Explorer <= 11,
not ExplorerMobile 11,
not OperaMini all

A full list of supported browsers can be found within the supported browsers list section of our main site’s browser support page.

The grid component utilizes features that will not work with Baidu browsers.

Information regarding Compass’ lack of Internet Explorer support is documented within the why we don’t support Internet Explorer section of our main site’s browser support page.

Guidelines

As the project progresses and grows, it’s important to ensure consistency in the way the code is written and structured. The following are guidelines on how best to do so.

Development and production modes

Compass’ build system has two distinct modes: development and production. Development mode will build out the assets unminified, and is useful for testing purposes. Production mode will build out the assets minified and altered (such as the removal of redundant code or the simplification of variable names), and is used for implementation in production. Commands such as develop, dev, or start are automatically ran in development mode, whereas build is automatically ran in production mode.

  • Assets built in development mode should never be used for production.
  • Development mode can be explicitly set by prefixing any command with NODE_ENV=development.
  • Production mode can be explicitly set by prefixing any command with NODE_ENV=production.

JS

Javascript is to be written in vanilla, ES2015+ syntax; This is to ensure the JS is future proof, clean, and compartmentalized. This is converted to JS targeted for the browsers found in the browsers list in the package.json using the Gulp build system.

Component functionality must be written as a class and extend the global Component class to ensure structural and functional consistency and should rely on super methods and values as much as possible to reduce redundancy.

When writing JS, try and make things reusable by bundling functional logic in a module to later be imported in. In addition, do not use JS frameworks and only use JS dependencies through NPM where absolutely necessary. In addition, please have an ESLint linter running to enforce code style.

JS can be transpiled separately by running npx gulp js.

SCSS

SCSS is to be written as opposed to SASS; This is to ensure it’s closer to vanilla CSS which helps with onboarding. This is converted to CSS using the Gulp build system, which does the following:

  1. Adds vendor prefixes to rules using the browsers list found in the package.json
  2. Minifies the CSS (on production builds only)

The SCSS should be divided up into partials associated with components, utilities, or resets, and follow a BEM structure. This BEM structure is to use double underscores/dashes and no block nesting (or grandchild selectors) when writing classes. Try to keep class nesting to a minimum. Compass-specific classes must be prefixed with cwf-, where cwf is configurable/overridable. Media queries are to be written using the bubbling method, as it is considered industry standard when using SASS/SCSS. Finally, do not use SASS/SCSS frameworks. SCSS partials should include variables and mixins explicitly, as it allows users to pick and choose which partials to pull in without having to a). pull in all of Compass, or b). know what variables/mixins to pull in along with it (see the components/card/_index.scss partial as an example). All functions and mixins within an SCSS partial should have error handling where applicable.

SCSS can be transpiled separately by running npx gulp scss.

Twig

Twig is an HTML templating engine, and this repo uses a Twig.js implementation for Gulp. This allows for easy templating integration and seperating of data/structure. Components and layouts should be within different folders. It is encouraged to download syntax highlighting for Twig in your code editor of choice. It should be noted that at the time of writing, the Gulp implementation of Twig.js used (gulp-twig) hasn’t been regularly maintained; Should you run into any problems templating HTML assets, inform the Compass team of the problem.

HTML can be transpiled separately by running npx run twig.

Linting and formatting

JS linting is handled through ESLint. This can be utilized by your code editor of choice, or can be manually ran using the npm run lint script. The ESLint configuration includes but is not limited to:

  1. Expects import/export modules instead of CommonJS modules
  2. 4-space indents
  3. Unix line-breaks
  4. Single quotes instead of double quotes
  5. Semicolons required

There are pre-commit Git hooks that will lint your JS files (see above) and check to see if all source files are formatted correctly (see below) before committing.

Formatting of all source files is handled through Prettier. This can be manually checked using npm run check and ran using the npm run format script. The Prettier configuration includes, but is not limited to:

  1. Ensures a blank final line appears
  2. Ensures Twig syntax can be parsed and formatted
  3. Semicolons are required (JS)
  4. Single quotes are preferred over double quotes (JS)
  5. 4-space indents
  6. Removes trailing commas

Contributing

If you are contributing to this project, please be sure to follow the above guidelines. In addition, please add your name to the contributors array found within the package.json file, the format of which should be First Last <email>.