Developer Documentation

Introduction

See documentation/README.md for an overview of the project structure and general guidelines for using BXI before digging into docs on this page.

Adding a new vertical

To add a new vertical add a folder for it in public/ (put images here if you have them) scss/ and src/pages/ along with appropriate files (see an existing vertical as an example). At this point you'll need to add the customizations.scss file in scss/index.scss, and adjust the vertical values in the newly created index and dashboard files (see the branding partial and body class). Then you will need run npm run start from the BXI repo. At this point server.js should pick up the new vertical and you should be able to access it via your browser and start developing!

Branding and Content

Each vertical has a branding.hbs and settings.json file next to the index.hbs (/<vertical>) and dashboad.hbs (/<vertical>/dashboard) pages. The branding file contains various css vars that typically handle colors and make re-branding a vertical easy for the user. Each branding file has a Global vars sections (variables that are using in the common scss styles and are typically the same across all verticals) and a vertical specific section (variables that are used in scss/<vertical>/customizations.scss). Generally you should never hard-code a color in a customizations or common scss file since it wouldn't be easy for users to customize. Some exceptions are made for non-brand specific colors (e.g. white). Content such as text and image locations should always be in the settings.json file for the vertical.

CSS and Layout

The general philosophy for page structure is use bootstrap 5.2 for as much as possible. If layout or adjustments can't be done with bootstrap, check for a BXI utility CSS class or add one (if it makes sense). Specific size values or colors that don't make sense as a common utility class can be added to customizations.scss for that vertical. Utility classes and classes added to the customizations file should be prefixed with .bxi- this is particulary important for trials and DV flows to help prevent styles from leaking outside of BXI. A similar pattern should also be followed with CSS variables.

Buttons

                  
<footer class="bxi-footer">
  ...
  <button class="bxi-button bxi-button--md bxi-button-outline">
    Click Me
  </button>
  ...
</footer>
                  
                

                  
<footer class="bxi-footer">
  ...
  <button class="bxi-button bxi-button--outline bxi-button--icon">
    {{> twitterIcon }}
  </button>
  ...
</footer>
                  
                

Auth Buttons

These are pretty confusing, there were no "stardards" followed when the original verticals were designed so each vertical has slightly different sizes, colors, borders etc. Here are some common examples, however often-times customizations to colors and sizes are necessary in the vertical's customizations.scss file (especially on mobile sizes where bg color can vary). Furthering the problem, since the nav buttons are in one file (home-nav-button.hbs) to make it easy to configure common buttons, the classes on the buttons cannot be modified directly, forcing us to rely on the bxi-auth-buttons parent element.

Navigation Links

All navigation links have an accompanying breakpoint version that activates on large + screen sizes, this is used for links that need to be a different color in the dropdown hamburger menu.

BXI Utility CSS

Note: the first few are not prefixed with bxi- I did this on purpose as they are filling in gaps with Bootstrap's utility classes.

SCSS Mixins

These are a collection of SCSS mixins that can be used within SCSS files (make sure to add @import "./mixins"; to the top of your scss file to use them).

Icons

To add a new icon, first create a new .hbs file for it in the src/partials/icons folder. Then copy the svg into the new file. After the file has been created change the class on the svg element to class="{{class}}" so that classes can be passed as parameters. Also make sure to find fill and stroke attribute on all path elements and change them to #fff (white). Any path element that has a fill attributes also needs class="fill-target" added to it, and all path elements that have a stroke attribute need to have class="stroke-target" added. This ensures our color-icon SCSS mixin will work with it. After you are done you will need to restart npm run start before the new icon partial will be picked up in server.js.

Trials

When a new vertical is added and complete it must be configured in the trials export as well. To do this ensure all of your changes are checked in and pushed (preferably merged into qa as well). And merge qa into the trials branch, then push it to origin. Before you can run the trials build, you need to add a settings override file (trials/settings/<vertical>.json) and a scss file (trials/scss/<vertical>.scss). The scss file is typically only needed for background-image style properties because webpack on the P1 side doesn't handle those inline properties (you'll notice these inline styles are removed in html-manipulations as well). The settings override file is merged into the main settings vertical file when a trials build occurs. This allows us to remove CTA buttons and override image locations (P1 needs ./<image-location>.(png|svg|jpg) instead of /<vertical>/<image-location>.(png|svg|jpg). Please note if you need to update images within an array whole array (including text values and all) must be preserved because they are overridden in their entirety.

You can test out changes in a "trials like" build by navigating to the trials folder in a terminal and running npm run test-build then cd dist and http-server in that dist folder. Run npm install -g http-server if you receive a package not found error. After you have verified changes and made any tweaks run npm run build to generate the files we merge into the trials repository in gitlab.