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.
There are two ways to customize Dispatch:
-
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. -
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 tothemes/YOUR_THEME_NAME
, and change theTHEME
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.
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.
You can change Dispatch's colors by modifying the variables in themes/dvl-core/assets/stylesheets/theme/branding.scss
.
You can change the hero image by uploading a file to themes/THEME_NAME/assets/images/hero.jpg
.
You can add custom assets by adding files to themes/THEME_NAME/assets/
.
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
.
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.
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
Override the template views/users/registrations/_business_data.html.erb
.
Add templates to themes/THEME_NAME/views/static
, and matching keys to the static_pages
configuration setting.
Assume that you forked Dispatch, here's how you can merge the latest changes:
git remote add upstream [email protected]:dobtco/dispatch.git
git fetch upstream
git merge upstream/master
Then, take a look at CHANGELOG.md and review the changes. There may be additional upgrade instructions to follow.