Customization¶
ATF’s eRegs instance is made of several non-agency-specific shared libraries (used by multiple eRegs instances) and a set of ATF-specific customizations. Here we will document these ATF-specific features, deferring to the eRegs docs for broader descriptions of agency-specific customizations (such as a full list of eRegs’ extension points).
Landing Pages¶
Each of ATF’s regulations have custom landing page content which is tied to
that CFR part. This content is defined in Django’s templating language, with a mix of raw HTML and Django templating tags. For examples, see the five templates
of the form atf_eregs/templates/regulations/landing_???.html
; each contains
blocks
of content which get merged into appropriate locations within a
larger template. Modifying the content in these files will modify the
corresponding landing page.
Each of the landing pages derive content from
atf_eregs/templates/regulations/generic_landing.html
, which defines the
shared legal disclaimer.
See Django’s documentation for its templating language for an introduction and comprehensive reference guide.
Tags¶
While writing raw HTML into these templates will always work, we strongly recommend using Django’s templating tags to simplify the process of writing content and keeping it up to date. Notably, review the existing landing pages for examples of
url
- dynamically link to another part of eRegsexternal_link
- include aria labeling and visual indicators that this link will open in a new tabsearch_for
- generate a link to search results
Variables¶
Several variables are available for use within your landing page templates. Here we document a few of the more useful.
current_version
- a data structure which includes fields corresponding to the unique version identifier for the current (i.e. effective now) version of the regulationnew_version
- a data structure including information about upcoming versions of this regulationreg_first_section
- not all regulations start at section 1reg_part
- the CFR part of this regulationmeta
- a data structure containing meta information about this regulation (e.g. its letter, CFR title, etc.)
Branded Templates¶
The header and footer of each page have been lightly customized to tie in with
ATF’s branding. This includes linking to other ATF sites and including ATF’s
logo. If you need to modify the content here,
investigate atf_eregs/templates/regulations/favicon.html
,
full_footer.html
, logo.html
, etc. Similarly, about.html
defines
the content present on the “About” page.
Templates in the atf-eregs repository provide customizations that override the core templates provided by the generic/non-agency-specific eRegulations libraries. For example, the about.html
file in the atf-eregs repository only contains part of the content you see live on the ATF eRegulations “about” page. This is because most of that “about” page content is provided by the about.html
template in the shared/non-agency-specific library (regulations-site
).
In other words: eRegs supports customized templates primarily through overriding. A base set
of templates are provided, broken into components we expect agencies would
need to replace. Creating a file of the same name in the
atf_eregs/templates/regulations/
folder effectively replaces the
template present in the “core” library. This is somewhat risky, as said
template might be renamed/moved at a later date (though we strive for
backwards compatibility). As such, we recommend only replacing templates on
the periphery of functionality (e.g. footers, headers, etc.). For a full list
of templates, consult the
regulations-site project.
Posters¶
The core eRegs application allows the templates used to render specific paragraphs/subparagraphs to be replaced on an ad hoc basis. This mechanism is used to render ATF’s “posters” in 27 CFR 478.103, which contain a header linking to a specific document.
Custom templates of this sort must follow a specific naming convention; they
must be in the atf_eregs/templates/regulations/custom_nodes/
directory and
must be named according to the paragraph they seek to replace. For example,
478-103-b.html
will replace the template normally used to render 27 CFR
478.103(b). Consult the regulations-site
documentation for more details.
Style Sheets¶
The core eRegs libraries provide a relatively clean set of stylesheets for
displaying regulations. To integrate with ATF’s branding, however, these
style sheets are modified to use the appropriate colors, fonts, and the like.
Similar to the template overriding process, there exist several SCSS
components which can be completely replaced by corresponding files in the
atf_eregs/static/regulations/css/scss
directory. Consult the
regulations-site
documentation for full details, but two files are
particularly important.
variables.scss
defines common variables used throughout other stylesheets. These largely consist of color schemesmodule/_custom.less
this file exists specifically for ATF-specific modules, such as style sheets related to Posters.
After making edits to any of these files, remember to run
python manage.py compile_frontend
to compile your changes into CSS.