Skip to content

Latest commit

 

History

History
71 lines (39 loc) · 3.83 KB

customization.md

File metadata and controls

71 lines (39 loc) · 3.83 KB
Raw

Customizing Dispatch

Dispatch is designed to allow for significant customization without needing to override the "core" of the application. This allows for a cleaner upgrade path, and a better pattern for re-use across multiple government agencies.

Dispatch exposes the concept of "themes". When you customize Dispatch, you should always use this theme mechanism instead of editing the core Dispatch files. If you do not — that is, if you make custom changes to the main Dispatch source code — you may not be able to update your site with newer Dispatch code (new features and occasional bug fixes).

Sometimes you may want to change the core templates in a way that would benefit everyone, in which case: great! But please discuss the changes in our issue tracker, make them in a fork of Dispatch, and then open a pull request.

Getting started

There are two ways to customize Dispatch:

  1. You can use the dvl-core theme, but modify its colors and imagery to match your branding. This will require less ongoing maintenance, but you will be limited in what you can customize.

  2. You can create a new theme, which allows you to override almost every part of Dispatch's view layer. This will require you to keep your theme in-sync with Dispatch Core, which might require a few hours every month. To create a theme, clone the themes/dvl-core directory to themes/YOUR_THEME_NAME, and change the THEME configuration setting to match your theme name.

No matter which option you choose, the current mechanism for standing up an instance of Dispatch is to fork this repository and make changes in your fork.

Editing configuration settings

There are many options that you can set with simple configuration settings. Copy config.yml.example to config.yml and look at the inline comments for guidance. Any secrets should be set in environment variables instead.

Customizing the dvl-core color scheme

You can change Dispatch's colors by modifying the variables in themes/dvl-core/assets/stylesheets/theme/branding.scss.

Adding your logo and imagery

You can change the hero image by uploading a file to themes/THEME_NAME/assets/images/hero.jpg.

Adding custom JS/CSS

You can add custom assets by adding files to themes/THEME_NAME/assets/.

Changing CSS class names

To change CSS class names, you'll need to create your own theme and override Dispatch's core templates. For each template in app/views, you'll create a matching template in themes/THEME_NAME/views. Warning: the more you customize, the harder it will be to upgrade later.

To change the class names for forms generated by simple_form, add a file at themes/THEME_NAME/simple_form.rb .

Editing site copy

To change the site copy, create a YAML file inside the theme/THEME_NAME/locales directory. Any of the keys in config/locales can be overridden by your theme.

Adding new submission adapters

To add a new submission adapter, create a Ruby class inside of themes/THEME_NAME/submission_adapters that inherits from SubmissionAdapters::Base. At the end of your file, include this line:

SubmissionAdapters.all_adapters << MySubmissionAdapter

Adding fields to vendor registration

Override the template views/users/registrations/_business_data.html.erb.

Adding static pages

Add templates to themes/THEME_NAME/views/static, and matching keys to the static_pages configuration setting.

Upgrading Dispatch

Assume that you forked Dispatch, here's how you can merge the latest changes:

  1. git remote add upstream [email protected]:dobtco/dispatch.git
  2. git fetch upstream
  3. git merge upstream/master

Then, take a look at CHANGELOG.md and review the changes. There may be additional upgrade instructions to follow.