Front end

In general, front end code is in the frontend directory.

This guide is about the nuts-and-bolts of developing front end code; for details on how to use or style individual components, see the style guide.

The static asset generator

If you haven’t already, make sure you’ve followed the setup guide; it explains how to run docker-compose up, which (among other things) will watch for changes to front end code and re-build bundles as needed.

All the static assets (SASS for CSS and ES6 JavaScript) are located in the frontend/source/ directory. Outputs from the static asset generator are placed in frontend/static/frontend/built/.

Examine gulpfile.js for details about the generator’s pipeline.

If you just want to build the assets once without watching for changes, run:

docker-compose run app yarn gulp build

Developing the front end

JavaScript

Globally, we use yarn to manage our node dependencies and run node tasks. yarn, in addition to being faster than using npm install, has the benefit of locking dependency versions via a yarn.lock file. Read the yarn workflow docs if you are not familiar with how to use it.

Parts of the site use React and Redux. More information available below.

CSS

We use Sass for our stylesheets. Their basics guide is a good place to start if you’ve not used it before. Sass allows us to abstract frequently used parts of the CSS into reusable components like variables and mixins. Some variables come directly from the U.S. Web Design System and we define new values for them in frontend/source/sass/base/_uswds_variables.scss. Other variables are specific to CALC, and those are defined in frontend/source/sass/base/_variables.scss.

This project generally follows a modified BEM (Block, Element, Modifier) naming scheme. This prevents namespace collisions and alleviates the need for too much nested Sass.

The Sass files follow a few conventions:

  • Core styles are divided into four categories: admin (controls styling for the Django site admin), base (styles like resets, grid, and variables), components (individual site components like the header and footer), and libs (vendored CSS).
  • All of the site’s core styles are imported in frontend/source/sass/main.scss.
  • Partials (also called includes or imports) are files that will get compiled into the main CSS file. These are prefixed with an underscore (such as components/_footer.scss).

A more detailed explanation of how to use specific components can be found in the CALC style guide.

Templates

The site makes use of Django’s templating system to ensure common elements like the header, navigation, and footer are applied consistently. The main base template lives at data_explorer/templates/base.html.

Site section-specific implementation details

Different parts of CALC are constructed in different ways, so developing the front end depends on which part you want to change.

There are three distinct sections of the site that rely on different technologies: The data explorer (the publicly available tool that lives at calc.gsa.gov), the data capture tool (which encapsulates both the workflow that starts at calc.gsa.gov/data-capture/step/1 and the bulk upload available to site admins at calc.gsa.gov/data-capture/bulk/region-10/step/1), and the site admin (the place site admins can approve submitted price lists, manage users, and more, available at calc.gsa.gov/admin/).

Data explorer

The data explorer is a React-based app that uses Redux for data flow and state management. It’s located in frontend/source/js/data-explorer.

Testing

The data explorer’s test suite uses Jest, and the tests are located in frontend/source/js/data-explorer/tests.

To run all the tests, run:

docker-compose run app yarn test

You can also run the tests in a continuous “watch” mode, which re-runs tests as you change your code:

docker-compose run app yarn test:watch

You can run jest directly, too: docker-compose run app jest, followed by any Jest CLI options.

Analyzing bundles

To see a visual representation of the bundles generated by Webpack, you can use webpack-bundle-analyzer.

docker-compose run app yarn gulp build
docker-compose run -p 8888:8888 app yarn analyze-webpack

Then visit http://localhost:8888 to explore the modules that comprise each bundle.

Data capture

Data capture largely consists of Django templates combined with HTML5 Custom Elements to provide a progressively-enhanced experience.

The source code is located in frontend/source/js/data-capture.

Tests are QUnit-based and are located in frontend/source/js/tests. They are run as part of our Python test suite via frontend/tests/test_qunit.py.

You can also visit /tests/ on your local development instance to run the QUnit tests directly in your browser.

Site admin

We skin the Django administrative UI to look like part of the CALC site; its templates are located in calc/templates/admin.

Other components

Other parts of CALC are usually stored in either Django templates or somewhere under the frontend/source/ hierarchy.

When in doubt, see the style guide!