Can I become who I want to be?

That's a tough question but thankfully, our team is on it. Please bear with us while we're investigating.

Have you had a chance to answer the previous question?

Yes, after a few months we finally found the answer. Sadly, Mike is on vacations right now so I'm afraid we are not able to provide the answer at this point.

Daily

Slack daily standup

Participants: Entire digital team

• Accomplishments or discoveries from the previous day

• Priorities for the day

• Any roadblocks, questions, or hang-ups?

Weekly

Product development sync

Monday mornings, required

Participants: Developers, Product Managers, Chief Digital Officer, Quality Assurance, UX, etc.

Format: Talk through accomplishment(s) last week, priority(ies) this week, flags

Digital staff meeting

Thursday morning, required

Participants: All digital team members plus invited guests as appropriate

Format: Each team member shares a “brag,” any “flags”, and a “learn” with the rest of the team.

#Demo

Friday afternoons, optional but encouraged

Participants: Any/all

Format: Team members may demo something they’ve accomplished during the week. Prompt on what you’ll demo is made by Slack on Thursday afternoon.

Project team meetings

Participants: Anyone who is a part of the identifying project team. Will typically at least include a product manager and developer from our folks.

Format: Determined by project team, but typically includes a review of the kanban project board for part of it.

Slack

• Our main channel is #digital_team.

• The #digital_builds channel reports build and deployment status.

• The #digital_monitoring channel reports alerts and exceptions.

• Most projects have their own public channel to keep all relevant and/or interested parties in the loop on active project work or to follow along with questions/answers that would benefit at all. Feel free to follow projects that you may not be actively working on.

• There are some 'culture building' channels. Feel free to add yourself to whichever of these channels.

*Note: This is largely used by Digital and Analytics within DoIT. Most others use GChat.

Listservs

The team communicates internally and externally via Google Group listservs:

• [email protected] (entire team) - James Duffy is typically first on deck to respond to these.

• [email protected] (limited folks on Digital) - James Duffy is typically first on deck to respond to these.

• [email protected] (developers, product managers)

• [email protected] (developers, product managers)

City of Boston use docker containers for local development.

Lando is used by the Drupal development team to manage the docker containers and provide basic tooling for the local development environment.

Continuous deployment apps

• We push changes to production as soon as they’re ready. This keeps us from piling up inventory. Shipping small batch sizes is also safer.

• We’ve built a deployment system that has zero-downtime, so it’s always safe to push.

• See each repo’s documentation for instructions on how to deploy it.

Fixed-schedule deployments

• Changes are made against a develop branch rather than production

• develop branch is pushed to a staging environment on a weekly schedule

• Issues in “Inventory” Kanban column get moved to “Staging” column

• Issue creator / feature owner validates fixes on staging

• Code gets merged to production branch and pushed to production the following week

• Issues move from “Staging” column to “Closed” after pushing to Production

Possible change: Adding a “Staging” lane to differentiate with “Inventory” (not yet pushed to staging).

Can I become who I want to be?

That's a tough question but thankfully, our team is on it. Please bear with us while we're investigating.

Have you had a chance to answer the previous question?

Yes, after a few months we finally found the answer. Sadly, Mike is on vacations right now so I'm afraid we are not able to provide the answer at this point.

The authoritative source for existing design is Figma.

UX and website designers design and maintain pages, components and elements in Figma. These are then implemented (in the case of a new component, page or application) or updated in Drupal.

Designers use libraries of existing Drupal components whenever possible to build the new page, component or element.

As designers review and update existing components and elements in Figma, appropriate changes are made in Drupal to mirror.

Figma cannot export wireframes/html templates or css. These are manually built in Drupal and are synchronized with Figma as Designers make changes - there cannot be a physical link between the two systems.

Introduction

The local development version of the CDN is hosted by Fleet at http://localhost:3030. This local CDN is served (by Node/Fractal) from your local environment.

$ give me super-powers

Once you're strong enough, save the world:

# Ain't no code for that yet, sorry
echo 'You got to trust me on this, I saved the world'

Drupal uses Twig (Symfony = templating), css and js all based upon it's (php) framework to allow the creation of elements and components that can be re-used across the site.

We mirror the components in Drupal with the library of elements and components in Figma to enable a consistent use of the City Brand onto the website, boston.gov.

Preparing and Engaging

• All developers will be oriented to the digital development standards

• All developers will be briefed on shared resources (e.g. patterns library)

• Development approach will be approved by the CDO

• Approved approach will be scoped and and specified to the satisfaction of all parties with the minimum standards so the team can test that the code is what was requested

Managing project

• Product owner/Project Manager on Digital Team will oversee communication and management of project utilizing JIRA as as an organizing tool

• Regular communication (e.g. weekly meetings) or stand ups as necessary between partners to understand project timelines and dependencies

  • assigning tickets between teams

Accepting code in the codebase, deploying, and maintenance

• Digital team needs to peer review all code prior to deployment

  • JIRA tickets should have adequate solution and documentation for updating release notes

  • Developer standards should be adhered to for code development

• Digital team conducts the deployment into our deployment pipeline

• Partner is responsible for documenting and digital team is responsible for integrating the documentation into the Digital Team's Gitbook

• Developer to Developer hand over of code for future maintenance of the code

• Digital Team will update release notes when code is released into the PROD code base

Product managers should work with stakeholders and the project team to determine what we'd like to track/count as success metrics.

Product managers are first on deck to enter tags in tag manager to track this information. Developers are a back up for this.

Ideas for potential metrics include:

• Standard high level google analytics, such as page views, unique page views, browser, network, device, time on page, etc.

• Conversions, such as sign ups, participation in events (in-person or online), results in City services (i.e. less towing)

• Completion rates, i.e. if they visited a page that they needed to interact with something or get through a task did the 'page visits' match the 'completed rates'

• Numbers of things, such as orders,

• Savings or revenue: time, money, etc.

Search for Projects on the Building Housing Map

From the building housing landing page a user can click and open a map showing all the current projects. The map and sidebar list are both generated via Building Housing View.

Entry point: /buildinghousing (click show map)

Custom CSS:

• docroot/modules/custom/bos_content/modules/node_buildinghousing/css/node_bh_landing_page.css

• docroot/modules/custom/bos_content/modules/node_buildinghousing/css/views_bh_listings.css

Views Template: docroot/modules/custom/bos_content/modules/node_buildinghousing/templates/views-view--bhmaps--maplist.html.twig

Views Functions: docroot/modules/custom/bos_content/modules/node_buildinghousing/node_buildinghousing.views.inc

Custom Markers: docroot/modules/custom/bos_content/modules/node_buildinghousing/images

Code reviews don’t need to be – nor should they be – only about finding bugs and errors. They give us the opportunity to improve the quality of our codebase by providing feedback that helps move the code forward. Sure, that could be a fresh set of eyes catching a typo... but it’s also about learning new things, asking questions and talking through decisions, and giving praise when you see awesome code!

Our codebase is a team effort and it’s important to remember that we’re reviewing code, not each other. When you’ve spent hours/days working on a piece of code, sometimes it can be easy to take feedback personally. As reviewers, we can minimize the risk of misinterpretation (as well as provide better, more constructive feedback) by keeping a few points in mind:

• , and use the passive voice in your feedback

• When requesting a change, also , and perhaps even

• Remember that you can also use comments to ask questions or start conversations

For a deeper dive, we highly recommend reading How to Do Code Reviews Like a Human (, ). Many of us have found it quite valuable!

General

• Changes are made on feature branches and merged via Pull Request, regardless of whether those PRs are reviewed.

• Preferred naming convention for a feature branch is service-name/feature.

• Never commit directly to develop or production branches.

• Rebase to a single commit before making a PR.

• Commit messages should be written in present tense.

Pull Requests

• PRs should be merged by the assignee, who is typically the person who made the PR.

• Assignee should delete the branch once it has been merged into develop.

• Code reviews are required if more than one engineer has interest in the repo, regardless of the relative experience between the engineers.

• Code reviews take priority over feature work, and must be responded to quickly.

• Reviewer is responsible for approving changes detected by Percy.

Git Branches

For Drupal see:

General documentation

This (GitBook) is the place to document technical information that isn’t specific to a particular project. We should be liberal with documenting our workflows and standards, and aim for the standard that any new developer could independently find everything they needed to start working on any of our technical tasks.

Project-specific documentation

Any technical information that’s specific to a particular project should be in a README.md at the root directory of the project’s source files. Examples include: how a new developer could install the project locally, a list of npm/Yarn tasks... basically, anything that “should be in a README”. is a great reference for the types of information that should be included.

Also see project specific information further down in Gitbook. The project’s page in the “Project” section of this GitBook should include a link to its README on GitHub.

Code comments

Documentation comments are super-useful! See the dedicated page for more guidance.

General familiarity with the Drupal platform is a baseline requirement for anyone working on the site. We suggest reading through the following user guide to Drupal 8:

Additionally, Acquia's free training program Acquia Academy offers a series of Youtube video tutorials which can be found here, including a Drupal 8 Beginner's Course:

Grouping on Form Display

To keep a clear and clean editor experience which uniform across the site, the form display configuration for nodes will contain groups.

There will be a root (parent) group of type tabs. This group will contain child groups of type tab. Each tab group will contain the nodes fields.

The use of further nested groups is discouraged, except for grouping which occurs within paragraph components that are exposed in Components or Sidebar Components tabs.

If other groups are required to help clarify the form display, they should be details type groups, and should be set to be collapsible, and be collapsed by default.

Admin Theme

The bos_admin theme makes some changes to the node administration forms.

Settings collapsed into advanced vertical tab

Config settings provided by drupal core and drupal contributed modules are moved into a tab called advanced, and are set as children of the tabs group as defined above. This manipulation is done in the hookbos_admin_form_alter()found in bos_admin.theme file at themes/custom/bos_admin .

Moderation/workflow collected and move to right sidebar

The moderation state, revision log note and save / preview / delete buttons are grouped together in a details group and moved to the right sidebar area of the administration form. This manipulation is done in the hookbos_admin_form_alter()found in bos_admin.theme file at themes/custom/bos_admin

Content moderation workflows and UX

This is a series of videos around site building and administration tasks. The individual videos in the series are listed in the upper right panel of the screen:

Paragraph Module Components

Modules can contain multiple paragraphs grouped by similar function.

A good example module can be found at:

Module folder

Module naming convention is to call the module bos_moduleName. The "moduleName" should be indicative of the paragraph/s contained within the module.

Digital team is responsible for showing unofficial election results on Boston.gov.

On election night, an HTML file of partial results is generated during tabulation and copied to the cityofboston.gov’s web server. The contents of this file are inserted into the Boston.gov unofficial election results page via a client-side AJAX request.

Historically, election night traffic for these results has been more than cityofboston.gov was comfortably able to handle. We previously ran a job on Heroku that copied the page from cityofboston.gov and put it on an S3 bucket, and the Boston.gov page referenced that S3 version.

As of January 2019, we’ve modified both the source file and our Incapsula settings so that Incapsula caches all requests for the file for 60s. This let us turn off the Heroku job.

Links

• Production:

• Source:

outlines to process for getting the Budget Fiscal Year website together. It has been shared with OBM (Office of Budget Management).

We build digital experiences designed around the needs of our constituents. We work to make these tools beautiful, welcoming, and highly useful.

Getting started is where you’ll find general onboarding/high-level info about our team, the technologies we use, and how we work together.

Standards and best practices ensure that our code and workflows are consistent across the team.

Guides is a collection of how-tos and references for the technologies we work with. These should not project-specific.

Projects is where general documentation for a specific project can be found (project-specific technical documentation is better suited for the project README). This section is primarily the domain of product managers. Private information is kept in Google Docs that are linked to from here. External resources is where to find links to useful information and tools.“Learning resources” are things like tutorials and guides. “Reference links” tend towards specs, references, and tools.

Adding Images

• When adding images to content, must add caption and/or title and/or alt tags. This is especially important because screen readers reads them.

• The editor we are using "ckeditor" provides at least one field to enter either a caption, title, or alt tags. If all three fields are provided please enter content for all three fields.

• Please see the "How guide" section on the best ways to add and edit an image.

Adding Tables

• Tables summaries must be added to each table created. Editors can use "ckeditor" to add summaries to each table. The summary must explain exactly what the table content is about.

• See the "How to guide" section to learn more about adding table summaries to tables

Adding Buttons and Links

• Just like images, links should always have a title if it is to be used as a placeholder or anchor tag. that is it has no content within the <a></a> tag.

• Tip for buttons: When using <div>...</div>, <span>...</span>, or <a>...</a> as buttons always add a role="button" attribute to the html tag. The button role should be used for clickable elements that trigger a response when activated by the user. Adding role="button" will make an element appear as a button control to a screen reader. This role can be used in combination with the aria-pressed attribute to create toggle buttons.

<div id="saveChanges" tabindex="0" role="button" aria-pressed="false">Save</div>

Don't add mailto link as:
<a mailto="[email protected]" class="someclasshere"> Send an email </a>

Do add mailto: link as:
<a href="mailto:[email protected]" class="someclasshere"> Send an email </a>

Don't add the classes "button cta-button" in a "div" like this
<div class="button cta-button">
  <a href="/departments/innovation-and-technology">Test internal link in CTA</a>
</div>

Do add the classes "button cta-button" on the link itself like this
<div class="someclassnamehere">
  <a href="/departments/innovation-and-technology" class="button cta-button">Test internal link in CTA</a>
</div>

The above example creates a simple button which is first in the focus order.

Audios & Videos

• Youtube videos:

• HTML videos:

• Other video types:

Adding images/svgs

• SVGs - please remove all "id" attribute in the svg. It is always the same and creates a BIG error when the browser sees the same id for so many images/svgs

• Images: Always add a title or alt tag to an image. But, make it meaningful. See example below.

• Development: https://access-boston-dev.digital-staging.boston.gov/

DO:
title/alt - "Demolition Delay application: 50 Landseer Street, West Roxbury"

Don't:
title/alt - "Image and/or photo of Demolition Delay application: 50 Landseer Street, West Roxbury" 

Editing/Adding Tables

• Adding Tables: Always make sure you add a table title and/or summary and/or caption

• Test: https://access-boston-test.digital-staging.boston.gov/

• Development: https://access-boston-dev.digital-staging.boston.gov/

Adding nofollow and/or hiding pages

• Production: https://access.boston.gov

• Test: https://access-boston-test.digital-staging.boston.gov/

• Development: https://access-boston-dev.digital-staging.boston.gov/

Adding iFrames

• Production: https://access.boston.gov

• Test: https://access-boston-test.digital-staging.boston.gov/

• Development: https://access-boston-dev.digital-staging.boston.gov/

Content Editor Guide

• The links with the same name should have the same href values when on the same page

• Using classes on html elements you want to hide from screen but allow screen readers to access:

  Copy

  sr-only sr-only-focusable

• Development: https://access-boston-dev.digital-staging.boston.gov/

Local dev environment

Continuous integration

Code comments can save a lot of time and stress for the next person working in the codebase (spoiler: it’s probably future you) by reducing the effort to understand a piece of code, or the intent behind it. Context switching is expensive; a well-placed explanatory comment can reduce or prevent the need, and allow a developer to continue on with their initial task uninterrupted.

Consider including a comment when...

Code is written a certain way for a particular reason

// We use forEach and push as opposed to Array.from or the spread operator
// because both are supported in IE 11 without polyfills.
optionsSet.forEach(option => {
    this.selectOptions.push(option);

You ran into Something Weird during development

/* This component works exclusively in UTC due to bugs / inconsistencies in how
 * browsers handle daylight savings time in the past. E.g., Safari creates
 * midnight 4/10/57 should be as 4am UTC but (correctly) displays it assuming a
 * -500 offset.
 */

You’ve made a fix for a particular issue or PR

// See https://github.com/CityOfBoston/digital/issues/360

Solution has been copied from elsewhere

// see https://react-dropzone.netlify.com/#!/Previews
// Make sure to revoke the data uris to avoid memory leaks
if (this.state.file) {
    URL.revokeObjectURL(this.state.file.preview);

PHP CodeSniffer (https://github.com/squizlabs/PHP_CodeSniffer) is already included with our D8 project with composer. If you run a lando composer install you should have it available at ./vendor/bin/phpcs

Local Setup:

1. You need to specifically download the Drupal coding standards using the coder module. You can do this globally for your computer by running:

composer global require drupal/coder:^8.3.1

2. You need to make sure phpcs knows about your newly installed coding standard (note the path below assumes you're using Ubuntu, yours might be different on a mac):

./vendor/bin/phpcs --config-set installed_paths ~/.config/composer/vendor/drupal/coder/coder_sniffer/

3. Now you can run this manually against your custom modules:

./vendor/bin/phpcs --standard=Drupal docroot/modules/custom/

If you're looking for more info, here's a good place to get started: https://www.drupal.org/docs/8/modules/code-review-module/installing-coder-sniffer

Obtain AWS Credentials from Administrator

Contact the AWS administrator to get credentials for logging into the AWS console and (if necessary) interacting with AWS via the command line.

Add your SSH credentials to AWS

Once you have a login to the AWS console: if you wish to use the AWS-CLI, or use any other command line program which connects to AWS (e.g. git for CodeCommit) you will need to register/add an SSH key on your AWS-CLI account.

AWS CLI

You need to install the AWS CLI if you, or a tool you use, needa to interact with AWS from the command line - for example:

• To use terraform to maintain AWS

• To deploy webapps to AWS

• To modify AWS objects from the command line

Install AWS-CLI

Follow the instructions here.

You want to install the AWS-CLI on you local machine, not inside a container. Follow the Mac, Windows or Linux instructions accroding to the OS you are using.

Add AWS-CLI credentials

Verify AWS is installed using LINUX console:

/usr/local/bin/aws --version

You should see an output something like:

aws-cli/2.7.4 Python/3.9.11 Linux/5.10.102.1 .....

If not then return to the "Install AWS-CLI" section above.

Obtain your secret access keys for AWS from the AWS administrator, and then create the AWS credentials file using the LINUX console:

echo "[cityofboston]" > ~/.aws/credentials
echo "aws_access_key_id = xxxxxx" >> ~/.aws/credentials
echo "aws_secret_access_key = xxxxx" >> ~/.aws/credentials

If the installation has completed without errors, then you should be able to check the following:

The repo that was checked out in Step 1 of the installation instructions is hosted on your dev computer, and is mounted into each of the docker containers. As you make changes to the files on your dev computer, they are instantly updated in all of your local docker containers.

Local boston.gov website

The production/public website is hosted by Acquia and can be accessed at https://www.boston.gov.

The local development version of the public website can be viewed at: https://boston.lndo.site. This local copy of the Drupal website is served (by Apache) from the appserverdocker container, and its content is stored and retrieved from a MySQL database in the database docker container.

You will find the CityOfBoston/patterns repo cloned into the root/patterns folder on your host dev computer.

Local Fleet website

The production/public patterns library is hosted by City of Boston from our AWS/S3 infrastructure and can be accessed at https://patterns.boston.gov.

The local development version of the patterns library is hosted by Fleet and can be viewed at https://patterns.lndo.site. This local copy of the Fleet website is served (by Node/Fractal) from the patternsdocker container.

You will find the CityOfBoston/patterns repo cloned into the root/patterns folder on your host dev computer.

The gulp, stencil, fractal and other services running in thepatterns docker container will automatically build the local fleet static website into root/patterns/public from the underlying files in real-time as they are changed.

Local Patterns CDN

The production/public patterns CDN is hosted by City of Boston from our AWS/S3 infrastructure at https://patterns.boston.gov.

The local development version of the CDN is hosted by Fleet at https://patterns.lndo.site. This local CDN is served (by Node/Fractal) from the patternsdocker container.

You will find the CityOfBoston/patterns repo cloned into the root/patterns folder on your host dev computer.

The gulp, stencil, fractal and other services running in thepatterns docker container will automatically build the local fleet static website into root/patterns/public from the underlying files in real-time as they are changed.

The main code is contained here:

docroot/modules/custom/bos_content/modules/node_buildinghousing/src/Plugin/Field/FieldFormatter/EntityReferenceTaxonomyTermBSPublicStageFormatter.php

Various templates are defined to create each timeline article, one template per timeline type.

Basic Strategy

1. Timeline items are gathered from various places in the system. - text posts are items in the field_bh_text_updates field of the bh_update entity. Tiles are inserted using the messages create date for ordering. If the message is updated in SF, it continues to use the original created date. If the message is deleted in SF it should be deleted from the timeline. Posts are sourced from Salesforce Chatter and imported using this synchronization. - documents are file objects which are referenced as items in the field_bh_attachment field of the bh_project. Tiles are inserted using the create date of the attachment for ordering. If Drupal detects an update to the attachment in SF, it continues to use the original created date for ordering. Documents are sourced from Salesforce and imported using this synchronization. - a single rfp tile is created if the field_bh_rfp_issued_date field is not empty Tile is inserted using the date in the field_bh_rfp_issued_date field. If the date is changed (or deleted) in SF, the rfp tile will be moved or removed from the timeline. RFP date is sourced from Salesforce as part of this synchronization. - meetings are bh_meeting objects which are referenced as items in the field_bh_update_ref field of the bh_update entity. Tiles are inserted using the meetings start date. If the meeting is updated in SF, meeting will move accordingly in the timeline. Meetings are sourced from Salesforce and imported using this synchronization. - stages

2. Timeline icons are controlled by css and are defined in function getStageIcon() in EntityReferenceTaxonomyTermBSPublicStageFormatter.php

3. The various stages are defined at items in the bh_public_stage taxonomy

Content Type Module Components

Modules can define multiple content types (nodes) grouped by similar function.

A good example module can be found at:

docroot/modules/custom/bos_content/modules/article

Module folder

Module naming convention is to call the module module_name. The "module_name" should be indicative of the node/s contained within the module.

docroot/modules/custom/bos_content/modules/module_name

A breadcrumb is an ordered collection of crumbs, with each crumb having a title and a link.

Drupal Core Breadcrumb Functionality

Drupal has a built-in breadcrumbs methodology, which will attempt to build out a pathway based on the URI (e.g. /departments/housing/metrolist) defined by the pages (i.e. nodes) URL Alias.

The Drupal core process creates the breadcrumb by scanning the path represented by the URI, and testing if a local page exists for each path element. It stops adding crumbs when a path element does not resolve.

FOR EXAMPLE an article is created with a URI (as defined in its URL Alias): /departments/housing/boston/housing-information-in-boston.

When the page is rendered, Drupal scans the articles URI and

• if we have a breadcrumb setting which stipulates that the homepage should always be shown as the first crumb, then a crumb of home with a link to https://site is created, then

• checks if /departments is a valid URI. https://site/departments is a valid URI, so it creates a crumb of "departments" with a link to https://site/departments , then

• checks if /departments/housing is a valid URI. https://site/departments/housing is a valid URI, so it creates a crumb of "housing" with a link to https://site/department/housing , then

• checks if /departments/housing/boston is a valid URI. https://site/departments/housing/boston is NOT a valid URI - there is no page with that name on https://site so the breadcrumb scanner stops evaluating at this point, but

• if we have a breadcrumb setting to display the actual page in the breadcrumb then a final crumb of housing information in boston is added, with no link (because this is the page showing).

The final breadcrumb in this instance would be HOME > DEPARTMENTS > HOUSING > HOUSING INFORMATION IN BOSTON with links on the first 3 crumbs.

CoB Theme extension for breadcrumbs

Where Drupal core cannot build out its own breadcrumb trail, there is some additional custom code intended to help make a logical breadcrumb.

Scans Redirects

The custom code scans URL redirects as well as URL Aliases when building out the breadcrumbs.

Custom Replacements

Some URI paths are hard-coded to build specific breadcrumbs.

For example pages which have a URI path starting with government/cabinet . The custom code ignores the "government/cabinets" part of the path and then build the breadcrumb from the remainder of the path.

Quick install guide

For more detailed install and usage instructions for various platforms, see "More Help" below.

Ensure you have set up your development environment as described here:

1. Clone the public boston.gov-d8 repo into a local folder git clone -b <branchname> [email protected]:CityOfBoston/boston.gov-d8.git (City of Boston DoIT recommends that the develop branch be used)

2. On host computer, change directory to the repository root and use lando to create and start containers: lando start

Pro-tips

Linux aliases

To reduce typing at the console, you can add the following aliases to your ~/bashrc, ~/.bash_aliases or ~/.bash_profile files on your development (host) OS.

alias ldrush='lando drush'
alias lssh='lando ssh'
alias lsshroot='lando ssh --user=root'
alias lphing='lando phing'
alias lcomposer='lando composer'
alias lnpm='lando npm'
alias ldrupal='lando drupal'
function lls() {
  lando ssh -c "ls -la $1"
}

With these aliases, typing (in a console) lls <folder> will use lando to run ls -la <folder> in the default container (in our case appserver) and list files there. Whereas, ls <folder> will list the folder locally (i.e. on the host) as usual.

More help

For more information on installation, usage and administration of the development area, go to the next section.

Description

This Drupal App allows residents to browse all active housing, open space, commercial, and to be decided (TBD) projects. It also provides information on city-owned land for sale.

Residents can click search for a specific project and/or view a map of all projects. A drill-down into a project page displays goals, a timeline, photos, meetings and more.

Features

• Search for Projects on the Building Housing Map

• View details of a Project

• Auto-create Community Meeting Events from Sales Force on CRON (5 minutes)

• Auto-create and update Projects from Sales Force on CRON (5 minutes)

Technologies Used

• Drupal

• Sales Force

• Google Maps API

Major Drupal Modules used

• node_buildinghousing (docroot/modules/custom/bos_content/modules/node_buildinghousing)

• Views

• Webforms

• Geolocation

• Salesforce

Articles

Tools and Other Resources

• ANDI

• VPAT

• A Complete Guide To Accessible Front-End Components

• Intro to Web Accessibility

• Focus and Focus Styles

• More about Keyboard :hover, :focus, and :active pseudo-classes

• https://learn-the-web.algonquindesign.ca/topics/html-semantics-cheat-sheet/

• https://learn-the-web.algonquindesign.ca/topics/accessibility-cheat-sheet/

• https://www.deque.com/blog/auditing-design-systems-for-accessibility/

• https://www.w3.org/WAI/WCAG21/quickref/

• https://storybook.js.org/blog/accessibility-testing-with-storybook/

Visit them at:

Trusted Tester Tests: The Section 508 Trusted Tester program groups the WCAG requirements into related groupings that can be tested (and developed) at the same time. With the help of Iterators the VPAT documentation for boston.gov was created. You can read the

Test #4) Keyboard and Focus

Purpose:

• Many different types of users decide to use a keyboard to navigate a web page. Some

  examples are screen reader users that will tab through an interface. Other users have

  motor impairments and must control a computer through a switch (such as puffing into a

  straw, etc).

• People that use a mouse can quickly navigate a website. Additional design features are

  needed to allow the same level of access to people that use a keyboard to navigate a user

  interface.

Requirements:

1) Users should be able to access all functionality by using only the keyboard.

a. First, use a mouse to identify all functionality (buttons, links, etc)

b. Second, try to utilize all of the same functions using the keyboard, mainly using the tab and enter keys.

c. This also applies if popup features are implemented, such as an informational dialog, etc.

2) Tabbing through a user interface should occur in a logical order that matches the visual pattern on the screen, such as left to right, top to bottom.

3) Tabbing through a user interface should cycle completely through the interface and not be “trapped” in a cycle.

4) Focus is visible when using a keyboard

a. Sometimes a blue border is used to show the currently active element when using a keyboard. This should be easily visible with all elements.

b. Sometimes using a mouse will also highlight an element or reveal some information. These two methods should be compatible with each other.

c. The focus should always be visible and there should not be any invisible elements when using a keyboard.

Test #9) Repetitive Content

Purpose:

It is easy to skip over content using a mouse. However, keyboard navigation users must traverse many repetitive elements such as menus.

Requirements:

1) Identify all areas of a page with repetitive content.

a. A typical example is the navigation menu at the top of web page.

b. Some web pages have multiple sections of different content, such as “news”, “events”, etc. If there are many sections, then a user might like to skip the “news” section and jump to the next section without traverse all of the elements in that section.

2) Provide a “Skip” link, such as “Skip to Main Content” for each of these repetitive areas. This skip link is typically only visible when a user is using a keyboard to navigate through a web page.

Test #6) Links & Buttons

Purpose:

• Keyboard users should be able to determine the context for any link or button. Often

  users determine the context by visually examining nearby text or graphics.

• Additionally, some links and buttons cause a change in content on a website which is

  visually observable and also needs to be accessible to keyboard users.

Requirements:

• The major requirement is that accessible and unique descriptions are available for each

  link and button. For example, a set of links to news events might be labeled as “Read

  More…”. However, the user may not be able to determine which news event is

  associated with each link. The link may still be labelled as “Read More…” as long as

  there is also accessible text that provides more description, such as “Read More about the

  City of Boston”.

• Any new content that becomes visible with a link or button should be identified with

  accessible text before the user clicks on the link or button. An example of this is a

  “Learn More…” button that causes a new modal dialog to be shown. Also, the keyboard

  navigation should move to the new content.

Environments

• Production:

• Test:

• Development: , , ,

You will use the Git as the version control system for the City of Boston website and to manage code in the Acquia Cloud environment. If you are not already familiar with Git, you will want to check out this in-depth Git series. The first seven videos will give you most of what you need to know:

• Introduction to the Git Series

• What is Version Control?

• Installing and Configuring Git (Dev Desktop comes with Git)

• Getting Help with Git

• Git Crash Course

• Working with Git Branches and Tags

• Moving through Git History

The next fourteen videos are more advanced Git topics, so you might want to save those for a later time.

Find the full Git series at:

You will see the listing of videos in the series in upper right panel; there are also a couple of different levels of scrollbar, so it’s easy to miss the later videos.

Process for creating component modules:

1. Login to the website and go to the paragraphs admin page (/admin/structure/paragraphs_type) and delete the paragraph you want to work on

2. Step 1 above may delete some of the field.storage dependencies (field definitions), so just re-import all the bos_component module config to make sure you get all the shared config back into the database: lando drush config-import --partial --source=/app/docroot/modules/custom/bos_components/config/install

3. Create the module scaffolding using drush, for example: lando drush componetize bos_discussion_topic --components=discussion_topic

4. Add hook_theme() to .module file to connect to the paragraph template

5. Copy the corresponding paragraph template from boston.gov-d8/docroot/themes/preConversion/component and put it in the scaffolding that the drush command from step 3 created: docroot/modules/custom/bos_components/modules/bos_discussion_topic/templates

6. Enable the module: lando drush en bos_discussion_topic

7. In the Drupal UI, add the new bundle to the field_components paragraph types list for the Test Component Page content type: /admin/structure/types/manage/test_component_page/fields/node.test_component_page.field_components

8. Create a test page with the component added to review admin UI and display

Other helpful commands:

• Importing a single config file:

• Exporting database config directly to your module (Important: the config file needs to be referenced in your module's info file under the config-devel key): lando drush config-devel-export bos_cabinet

Overview

Entry point: /buildinghousing (click show map)

URL pattern: /buildinghousing/{ProjectName}

Custom CSS: docroot/modules/custom/bos_content/modules/node_buildinghousing/css/node_bh_project.css

Field Templates: docroot/modules/custom/bos_content/modules/node_buildinghousing/templates/snippets

Field Formatters: docroot/modules/custom/bos_content/modules/node_buildinghousing/src/Plugin/Field/FieldFormatter

Helper Functions (Pre-process, alters, fields):

• docroot/modules/custom/bos_content/modules/node_buildinghousing/node_buildinghousing.module

• docroot/modules/custom/bos_content/modules/node_buildinghousing/src/BuildingHousingUtils.php

Page Elements

1. Parcel Map - settings

   • Uses BuildingHousingUtils->setParcelGeoPolyData() and Arcgis to set the Polygon geo data for the parcels

2. Photo gallery - settings

3. Building Housing Project Map (same as above Map feature)

4. Project information

5. Developer Information - Custom field in node_buildinghousing.module

6. Project Goals

7. Project Timeline - Altered field to combine other fields

   • docroot/modules/custom/bos_content/modules/node_buildinghousing/src/Plugin/Field/FieldFormatter/EntityReferenceTaxonomyTermBSPublicStageFormatter.php

   • docroot/modules/custom/bos_content/modules/node_buildinghousing/src/BuildingHousingUtils.php

8. Project Type - Custom field in node_buildinghousing.module

9. Contact information - Custom field in node_buildinghousing.module

10. Email sign-up - Custom field in node_buildinghousing.module

11. Feedback form - settings

The Project Timeline

We currently have 2 or more versions of CKEditor we use plus extension of the plugin in 2 other components.

Drupal 9

Our current Drupal version D9 uses the CKEditor 4 in modules/contributor folder.

Drupal 10

Once we upgrade to Drupal 10, will need to move from CKEditor 4 to 5. That is because Drupal 10 does not use CKEditor 4.

Samples of CKEditor 5 we can explore to integrate/use can be found here:

Related Jira tickets

Taxonomy Module Components

Modules can contain a single vocabulary taxonomy.

A good example module can be found at:

Module folder

Module naming convention is to call the module vocab_moduleName. The "moduleName" should be indicative of the taxonomy contained within the module.

Requirements

Node: field_components.

If the node has components (paragraphs) embedded, then the node will have a field called field_components and this field will be of a type Entity reference revisions. The field will allow only paragraphs, and will specify the paragraph types that are allowed on the node.

Paragraph: field_short_title.

To enable in-page navigation, each paragraph must have a (text field) field_short_title, and to reduce confusion for content editors, that field should be named "Navigation Title".

Node: template.

To enable the in-page navigation menu, the nodes template should include the following:

{% if navOutput %}
    <div class="sub-nav-trigger drawer-trigger">
        <div class="sub-nav-chevron">
            {{ sub_nav|raw }}
        </div>
        Page Sections
    </div>
    <nav class="topic-nav topic-nav__left">
        <a name="section-nav"></a>
        {{ navOutput }}
    </nav>
{% endif %}

• The div drawer-trigger block is required to collapse menu for mobile devices

• The div topic-nav is required for menu on desktop devices.

How it works

Expected behavior

When there is more than 1 paragraphs embedded in a nodes web page, an in-page navigation menu should appear on the page. The menu should be styled from the patterns library.

UX Desktop: When the page first loads, the menu should display above the fold. As the user scrolls down the page, the menu should collapse into a fixed toolbar at the top of the page, below the seal menu with the seal retracted. Theme should come from patterns.

UX Mobile: Menu should appear as a collapsed set of drawers with a chevron icon to expand. Css from patterns controls the collapse across the responsive page width.

In either UX, when the user clicks on the menu, the page should scroll smoothly down to the correct paragraph display on the webpage.

Locating and creating menu

The twig template (e.g. node--xxx.html.twig) for the node is responsible for locating the menu on the node. The code required is described above.

On-page menu elements are rendered from the bos_theme_preprocess_node() and bos_theme_preprocess_field() hooks in bos_theme.theme found in /themes/custom/bos_theme/.

UX

The page click and scrolling is provided by component-navigation.boston.js which is found in /themes/custom/bos_theme/js/.

Making paragraphs compatible

To make a paragraph include itself in the in-page navigation menu, it just needs to contain a text field named field_short_title (and for that field to be included in the display being used on the node).

Auto-create Community Meeting Events from Sales Force on CRON (5 minutes)

A DND Development Officer is able to create a Meeting object in Sales Force, with all the meeting information, and attach it to a Project in Sales Force. When CRON runs on Drupal it then will sync any new or updated Meetings from Sales Force with a Drupal BH Meeting. After the new meeting is crated in Drupal, we also creat a Drupal Event so that the meeting will be listed on the Boston.gov Events page. The Meeting is also then displayed on the corresponding Drupal BH Project.

BH Meeting Content Type: /admin/structure/types/manage/bh_meeting

Sales Force Mappings: /admin/structure/salesforce/mappings/manage/bh_community_meeting_event

Templates:

• docroot/modules/custom/bos_content/modules/node_buildinghousing/templates/snippets/bh-project-meeting-notice.html.twig

• docroot/modules/custom/bos_content/modules/node_buildinghousing/templates/snippets/bh-project-timeline-meeting.html.twig

Helper Functions (Pre-process, alters):

• docroot/modules/custom/bos_content/modules/node_buildinghousing/node_buildinghousing.module

• docroot/modules/custom/bos_content/modules/node_buildinghousing/src/BuildingHousingUtils.php

Auto-create and update Projects from Sales Force on CRON (5 minutes)

This feature allows Drupal entities to sync back and forth with Sales Force Objects via the Drupal Sales Force module. It is primarily used by DND to use the data and access that is already on DND's Sales Force server to automatically sync with the Boston.gov Drupal site. This is controlled by field mapping configurations in the Drupal Sales Force module. Currently, all syncing is scheduled to happen on Drupal CRON run, every 5 minutes, with only updated objects.

Sales Force Mappings:

• Building Housing - Projects (/admin/structure/salesforce/mappings/manage/building_housing_projects/fields)

  • bh_project --> Project__c

• Building Housing - Website Update (/admin/structure/salesforce/mappings/manage/bh_website_update/fields)

  • bh_update --> Website_Update__c

• Building Housing - Project Update (/admin/structure/salesforce/mappings/manage/building_housing_project_update/fields)

  • bh_update --> Update__c

• BH Community Meeting Event (/admin/structure/salesforce/mappings/manage/bh_community_meeting_event/fields)

  • bh_meeting --> Community_Meeting_Event__c

• Building Housing - Parcels (/admin/structure/salesforce/mappings/manage/building_housing_parcels/fields)

  • bh_parcel --> Parcel__c

• Building Housing - Parcels-Project Assoc (/admin/structure/salesforce/mappings/manage/bh_parcel_project_assoc/fields)

  • bh_parcel_project_assoc --> ParcelProject_Association__c

Sales Force Settings:

• Building Housing - Projects (/admin/structure/salesforce/mappings/manage/building_housing_projects)

• Building Housing - Website Update (/admin/structure/salesforce/mappings/manage/bh_website_update)

• Building Housing - Project Update (/admin/structure/salesforce/mappings/manage/building_housing_project_update)

• BH Community Meeting Event (/admin/structure/salesforce/mappings/manage/bh_community_meeting_event)

• Building Housing - Parcels (/admin/structure/salesforce/mappings/manage/building_housing_parcels)

• Building Housing - Parcels-Project Assoc (/admin/structure/salesforce/mappings/manage/bh_parcel_project_assoc)

Troubleshooting Salesforce Connection

Troubleshoot Sales Force connection issues

If Drupal and Sales Force are not connecting or syncing please check the Authorization from Drupal to Sales Force (/admin/config/salesforce/authorize/list). You may need to Re-auth or even make a new connection if you need to connect to a lower development or testing environment on Sales Force. If you need access to an instance contact DND's Sales Force developer/administrator.

If a single item is not syncing or if you need info about the Drupal to Sales Force connection you can view the list this admin page. If you edit the instance you then have the option to force pull or push the Drupal entity with the Sales Force Object. If there is an issue you should see an error message in the response. You can also find other useful info like timestamps and record ids.

Creating new pages

“Guide” or “Standards and best practices”?

If you’re documenting how to perform a task, organize it as a Guide. Most of the docs in our GitBook space will be Guides. (e.g. How do I start a new project?)

“Standards and best practices” is where to document things like What files need to be included in every project? What library should I be using?

Make sure you’re in editing mode

In order to add new pages, you need to switch into editing mode first. It’s easy to forget!

Use H1 and H2 headings to organize your content

GitBook will automatically create a list of hyperlinks from H1s and H2s as the page “contents” block in the upper-right of the page. Although it isn’t semantically correct, use H1s for all section titles within a page, and H2s for subheadings.

General tips and quirks

Moving in and out of editing mode

When you are in editing mode, any changes you make will be autosaved as one draft: you can click through and edit multiple pages without needing to save before leaving a page. When you’ve finished, make sure to save the draft! Note that the “cancel” button will discard all changes you’ve made, not just the page you are currently on. Your changes will not be live until you merge in your draft.

Adding a file to gitbooks

If you add a new file in github, then you must also add it to the summary for it to appear in gitbooks.

These accounts should all be members of the (secret) Digital Service Accounts GitHub team so we can keep track of them.

cob-deployer (Twicki) — This is a legacy service account that appears not to be currently used. It has 2-factor auth on but no registered SSH keys, so it doesn’t seem like any automated process can be using it. (The cloning of boston.settings as part of the Travis build comes from a “deploy key” specifically added to that repo.) As of 5/22 this account has no special permissions, and probably can be deleted if we can go a few weeks of deploys with nothing breaking.

cob-digital-atlantis (Atlantis) — Account for the Atlantis app used in Terraform deployment. Needs permission to the private digital-terraform repo so that it can see the Terraform templates and post its comments about plan and apply success and failure. (See: CityOfBoston/digital-terraform)

cob-digital-bot (Shippy-Toe) — Used by the internal-slack-bot tool as part of Digital monorepo deployments. Needs write access to digital repo so it can update production branches as part of deployment. (See: Digital Webapp DeploymenT)

cob-heroku (City of Boston Heroku Deployer) — Used for connecting GitHub and our dwindling number of Heroku apps. At this point just needs read/write access to patterns so it can make apps for each PR and report the deployment back. (Admin access is needed only when first connecting the account to Heroku so it can set up webhooks.)

Hosting

Apple Developer and Google Play

Digital is in charge of maintain/help support/be technical advisors on nearly all of the mobile apps obtained by the City. They can be found on these.

Amazon Web Services

• We use Terraform for describing our infrastructure. See the digital-terraform repo.

• Do not make one-off changes in the UI or with the command line. Everything should be updated through Terraform so we have transparency about what we’re running and why.

• Terraform changes should be made through Atlantis.

Acquia Cloud

• Acquia externally hosts our main website, boston.gov in their cloud instance.

Heroku

• Heroku is appropriate for very one-off apps (such as the 311 crowdsource app) where we don’t mind not being on a boston.gov URL or waiting for the dyno to spin up after inactivity.

• We only want to use free tier dynos going forward.

• We need to get off all paid Heroku services, migrating to AWS/S3 as appropriate. Staging apps, however, should generally deploy to AWS to match production-like environments.

  • App status / migration plan spreadsheet

Monitoring

We should never be surprised by an outage. CloudWatch and/or Updown.io should be monitoring our apps and the services they depend on.

If an alarm goes off regularly, either its root cause should be fixed or the alarm should be adjusted or removed.

CloudWatch

• We have a handful of CloudWatch alarms to monitor our instances, VPN, and services.

• These alarms are sent to the [email protected] email address and posted in the #digital_monitoring Slack channel via a custom Lambda function.

Rollbar

• We use Rollbar to track server-side and client-side exceptions.

• Exceptions we cannot eliminate should be silenced on the Rollbar side or prevented from throwing in the first place. If necessary, they should be converted to logs that can be monitored.

Updown.io

• We use Updown.io for blackbox monitoring of our sites’ availability.

• Yes, parking tickets goes down every night and it’s annoying.

The bos_theme manages the templates, css, php and js code required by boston.gov to items which appear on pages.

• Atoms ⇒ basic design items which do not contain any other items. e.g. Button.

• Elements ⇒ more complex items which are comprised of one or more atoms or other Elements. e.g. Card (contains textfields, images and buttons).

Other design items required by boston.gov include:

• Components ⇒ items that represent complete functional page sections/components. These are added webpages (nodes) by content authors, and are pre-configured of elements, atoms and other components. e.g. Grid of Cards (contains Cards, Component Titles and navigation elements).

• Content Types ⇒ the framework for a type of webpage (node). This contains elements and atoms and has a section where components can be added by content authors. e.g. Public Notice.

Atoms, Elements, Components and Content types are design items, and page built from them is an Entity.

State and Local Gitub Reps/Team/Sales Development Team @ GitHub (don't know much more)

Tanner Hogan, [email protected]

Eric Johnson, [email protected]

Michaela Yamamoto [email protected]

CoB use the following modules for moderation:

• Content Moderation: [core] Provides moderation states for content.

• Workflows: [core] Provides UI and API for managing workflows. This module can be used with the Content moderation module to add highly customizable workflows to content.

• Moderation Note: [contrib] Provides the ability to notate elements of a moderated Entity.

• Moderation Sidebar: [contrib] Provides a frontend sidebar for Content Moderation.

Prerequisites:

1. Have stable local build of Drupal 8 website running on your machine.

2. Make sure you are “logged in” or have “admin” access to view the CMS and add new content / nodes.

   • Using Drush: lando drush uli

   • Using Drupal web login: https://boston.lndo.site/user/login?local

Part 1: Drupal CMS

1. Navigate to Content menu item (make sure you are logged into Drupal to view) https://boston.lndo.site/admin/content

2. Scroll to bottom of the page and add content item by clicking “Add Content”, . Select “Listing Page” content type.

3. Give new Page content a Title. This is required.

4. Click on the “Components” tab on the left menu

5. Find the dropdown Select menu to add “new component” and select “Web App” from the list.

6. Name the Web App something appropriate as it relates to your project. (i.e. Metrolist or My Neighborhood)

7. Click “Save” near the bottom or side of the page to save and create a new page / node. This will serve as the container page / component for your new web app.

Part 2: Drupal file system

1. Navigate to the “bos_web_app” directory of the drupal 8 repository that is checked out to your local machine /docroot/modules/custom/bos_components/modules/bos_web_app.

2. Locate the “apps” folder / directory. If one doesn’t exist, please create. /docroot/modules/custom/bos_components/modules/bos_web_app/apps

3. Inside this “apps” directory create an empty folder and name it the same name you called your Web App in Step 6 of Part 1 above. /docroot/modules/custom/bos_components/modules/bos_web_app/apps/my_neighborhood NOTE: Any spaces in your app name should be treated with underscores. For example, My Neighborhood would have a folder name of “my_neighborhood”.

4. Locate and open the libraries yml file named “bos_web_app.libraries.yml”. This file will serve as the pointer and compiler that will tell Drupal to attach and bunde all your JS and CSS files for your application. /docroot/modules/custom/bos_components/modules/bos_web_app/bos_web_app.libraries.yml

5. Once you have the libraries file open, add an entry with the name of your application and add / attach necessary items to your application. For example, the application “My Neighborhood” would have a library entry as such…

   See an example libraries.yml file on GitHub for a project that is currently being developed. https://github.com/CityOfBoston/boston.gov-d8/blob/mnl_12-9-2019/docroot/modules/custom/bos_components/modules/bos_web_app/bos_web_app.libraries.yml Drupal also has good documentation on using libraries and attaching files. https://www.drupal.org/docs/8/creating-custom-modules/adding-stylesheets-css-and-javascript-js-to-a-drupal-8-module

6. Once you have libraries file setup, go create the files needed, OR first create the files you’d like and then add them to the libraires.yml as laid out in Part 2 - Step 5 above.

7. It’s important to note that any time you add a new attached file to libraires.yml, the Drupal cache will have to be cleared for changes to take effect. You can clear the cache either through the Drupal CMS or via Drupal drush CLI

   • Drupal CMS: navigate to admin/config/development/performance, and click button at top of the page labeled “clear all caches”

   • Using Drush CLI: drush cr

8. After clearing the cache, you should now see your application load on the Drupal page you created and saved in Part 1 - Step 7. NOTE: You will NOT have to clear the Drupal cache every time you make a change to a CSS or JS file. This is only for new items in the libraires.yml file.

Since we are using Prettier to enforce basic code style, there’s no need to go into detail on those bits of syntax (e.g. always using semicolons, avoiding extraneous whitespace, etc).

General

• In nearly all cases, there should be only one React component per file. The file name should match the component name.

• A component’s story file (or test file) should be colocated with the component.

Naming

• File/component name should be descriptive.

• Use .tsx extension for React components.

• Storybook files should be named ComponentName.stories.tsx.

• Unit test files should be named ComponentName.test.ts.

• Interface and type names should be in PascalCase.

• Constant value names should be in ALL_CAPS.

Syntax

• Prefer <></> shorthand over <React.Fragment></React.Fragment>.

• Avoid var; use const by default, or let when necessary.

Comments

Use JSDoc style when documenting classes and functions, and standard // elsewhere in the code.

TypeScript

Overriding type errors

Remember: TypeScript errors are for our benefit as developers, so we should always take the time to resolve type errors as often as possible. Override only as a last resort!

React

Specifying defaultProps

Declare as a field on the component’s Class definition, and set its type as a Partial of the component’s Props interface.

Using Refs

See for detailed information. When referencing a Ref in your code, don’t forget that you need to use the current attribute to access the actual DOM element!

Emotion

See the .

Select your operating system from below, and follow the instructions to setup your development environment and prepare to install the City of Boston Drupal 8 website.

For an explanation on what DI is and why it's a good idea to use it, refer to the .

When you're using DI, you're asking the , which Drupal borrows from Symfony, to pass the correct object into your class so that you can interact with it in some way. See for a full list of services provided by Drupal core.

The main thing to keep in mind is that any time you are writing a class in Drupal 8, you should be accessing external services through the service container (SC). If you use \Drupal::someMethod() within a class, that is a red flag as it's an opportunity to use DI instead.

Blocks, Controllers, Forms

Controllers (extending ControllerBase), blocks (extending BlockBase) and forms (extending FormBase) have special access to the SC. They can access it directly via their create()method. The example below gets access to the database and request_stack services, and then passes those into the __construct() method so that they can be used later on in the class. These services could also be accessed statically, \Drupal::database(), \Drupal::service('database'), \Drupal::request(), \Drupal::service('request_stack'), but since we're writing a class that's not the recommended approach.

In the other methods of our class, we can now access our services like this: $this->db->someMethod() or $this->requestStack->someMethod().

Roll your own service

If you're writing a class with functionality that will be (or could be) used multiple other places in the application, consider making it a service. For instance, if you're interacting with a 3rd party API, you may want to write a class to make common interactions easier (connect, fetch, etc).

In this case, refer to for creating a service. The part of the .services.yml relevant to this article comes in the arguments line:

This instructs Drupal to reach into the SC and pass the database and request_stack services into your class. This replaces the create() method in the example above. You can then add your services to your constructor like this:

Now the other methods of your class can reference these services like this: $this->db->someMethod() or $this->requestStack->someMethod().

Add XDebug

1. Under Extensions in the left sidebar, search for "PHP Debug" and click "Install"

2. Edit .vscode/launch.json

3. Add the following configuration:

Add Drupal coding standards

1. Under Extensions in the left sidebar, search for "phpcs" and click "Install"

2. Click in top navbar navigate to file > preferences > settings

3. Under Workspace Settings expand the Extensions option

4. Locate PHP CodeSniffer configuration and scroll down to the Standard section and click the "Edit in settings.json" link

5. Add the following configuration to your Workspace Settings:

Version control

• All new software is checked in to GitHub.

• Legacy software that needs maintenance gets moved to GitHub.

• Absent a very compelling reason, repos are public from day one and source code is released under the public domain license.

Project structure

Local environment

Subdomains

Criteria

Boston.gov subdomains are assigned on a case-by-case basis. Typically, anything that is a core city service will qualify for a subdomain.

Naming Conventions

If the website qualifies for a subdomain, it should adhere to the following conventions:

Specific to the purpose

• Example: fulfills service requests for the Mayor’s 24

Descriptive of content on the site

• Example: is the data hub for the City

Is not misleading/does not interfere with other City services

• does not use talent.cityofboston.gov because “Talent” could be interpreted as “Employees”, thus misleading users who are searching for the .

Conduct

Engineers on the Digital team will treat each other with kindness and respect. We will support each other in learning new things, honing our craft, and building great software for the people of Boston. We do not look down on each other for any reason, including background, area of expertise, or identity.

Values

We value iterative development and continuous deployment. We recognize that delivering changes in small batches means that we go faster with a lower risk of breaking something.

We value communication and shared knowledge. While we may work on separate areas of Digital’s portfolio, we develop and document so that others can step into our shoes as needed. We visualize work to better communicate and hold ourselves accountable. We celebrate each other’s wins.

We value transparency. We are part of a public institution working for the people of Boston, and we are accountable to that. We make our roadmap, work in progress, and results public to all.

We value continuous improvement. We hold retrospectives and experiment with our process in order to learn and work together more effectively.

We value consistency in user experience, and in code.

We value automation and defaults. Out-of-the-box solutions are easier to maintain and teach than custom ones.

We value security and privacy. We are stewards of the public’s data and take that responsibility seriously. We will not build software that can be used for abuse or harassment.

We value maintainability. Because projects move in and out of active development, we need good test coverage to guard against accidental breakages and easy development setup so that others can work on the code.

We value monitoring. We use services to report on exceptions and add alerts so that we know when our services are down. We record analytics for insight into how constituents use our products.

We value diversity of background, experience, and identity. Bringing people with different perspectives together to solve a problem leads to a stronger, more inclusive solution.

Process

We run fairly process-lite, not because we reject process in general, we just only want to adopt what’s useful for doing the best work. The practices we have adopted are described in .

Prioritization

The overall prioritization of projects is the responsibility of the Chief Digital Officer, and should be the overall guide for deciding which new work to “pull.” (Glossary: ) Engineers have some leeway in this area to try and minimize switching cost between projects.

Prioritization of a project’s features is the responsibility of the product manager for that project. Work for a project should generally be pulled in priority order. Use good judgement to pull other work in exceptional cases (for example, someone you need to work with has free cycles).

It is the responsibility of engineering to provide honest information and be a good collaborator in the prioritization process. “Responsibility” for the CDO and PM is not “sole responsibility.” Engineering is expected to be a participant in the prioritization process.

about using a Kanban board to track prioritization within a project.

Browsers We Support

These are browsers we support for development and quality assurance testing. Note: These are based on the City's top browser versions tracked via City's analytics traffic. These will be revisited quarterly by the product development team and quality assurance lead.

• Google Chrome 68 and higher

• Safari 11 and higher

• Internet Explorer 11 and higher

• Firefox 61 and higher

• Edge 17 and higher

Testing Breakpoints

• 320

• 840

• 1280

Contributing to Boston.gov

:+1::tada: Thank you for being interested in contributing to Boston.gov! :tada::+1:

This is a guideline for contributing to the development of Boston.gov. We're open to improvements, so feel free to send a PR for this document, or create an issue.

Jump right in

• Report issues on Boston.gov

• Suggest new features

• Contribute to development

Reporting bugs

If you need to submit a bug report for Boston.gov, please follow these guidelines. This will help us and the community better understand your report, reproduce the bug, and find related issues.

Before you submit a bug

• Verify that you are able to reproduce it repeatedly. Try multiple browsers, devices, etc. Also, try clearing your cache.

• Perform a quick search of our existing issues to see if it has been logged previously.

Submit a bug

• Use a clear and descriptive title when creating your issue.

• Include a bulleted list of steps to reproduce your issue.

• Include the URL of the page that you're seeing the issue on.

• Include screenshots if possible. Bonus points if you include an animated GIF of the issue.

• Include details about your browser (which one, what version, using ad blockers?).

• When filing your issue, assume that the recipient knows nothing about what you're talking about. There is no such thing as too many details when filing your issue.

Bug report template

## Basic details

URL: [URL]

## Steps to reproduce

1. [FIRST]
2. [SECOND]
3. [THIRD]

## What I think should happen

[Describe your expected behavior here]

## What did happen

[Describe the actual behavior here]

## Browser details

Browser: [Enter browser]
Version: [Enter version]
Ad blocker: [Ad blocker?]

[SCREENSHOT]

Suggest new features

Have an idea for Boston.gov? If so, create an issue. Prior to submitting your feature request, please do a basic search of existing issues to see if it's already been suggested.

Feature template

## User story

[Don't write:
  "As a <type of user>, I want <some goal> so that <some reason>."]

[Tell us a story instead:
  "I like knowing what major construction projects are planned for my neighborhood. It makes me good to review
  those project documents and share my opinion on them at any public hearings. It's a hassle to constantly 
  check the website, though. Is there any way I can automatically get an email when something is happening
  within a certain distance from my apartment?]

## Acceptance criteria

1. [FIRST]
2. [SECOND]
3. [THIRD]

[Example:
1. Be able to sign up for an email notification.
2. Receive an email notification with proposed construction projects and associated hearings.
3. Be able to indicate an intent to attend a specific hearing.]

## Good examples to share

[Add links, screenshots, mockups, or any other example of where you've seen someone do what you're requesting
_well_. Add a brief description of what you like and/or dislike about it.]

Contribute to development

To contribute to the development of Boston.gov, you'll need to get a development environment up and running. This section will get you started.

Contributors should first review our [[Development Standards]].

Our process resembles a Gitflow Workflow with the following specifics:

• The master branch is always ready for deployment.

• All development is performed against a develop branch.

• Before release, develop is deployed to our staging environment and tested. It is then merged into master and master is deployed to production.

Project setup

Each contributor should fork the primary Boston.gov repo. All developers should then checkout a local copy of the develop branch to begin work.

For any work, pull requests must be created for individual tasks and submitted for review. Before submitting a pull request, be sure to sync the local branch with the upstream primary branch.

Pull requests should be submitted from the forked repo to the develop branch of the primary repo. Make sure to give your pull request a clear and descriptive title and use the template below.

Pull request template

## Changes

 * [First change]
 * [Second change]
 * [Third change]

This PR references #[GitHub issue number]

Acquia Hooks

• In the CoB Drupal 8 private gitHub repository edit the Acquia Hook scripts in the /hooks/common folders, looking for the following code in thepost-code-update.sh and post-code-deploy.shfiles:

  Copy

  if [[ "${target_env}" == 'uat' ]] || [[ "${target_env}" == 'ci' ]] ... ; then

  and adding in a new condition for the new envname:

  Copy

  ... || [[ "${target_env}" == 'envname' ]] ...

  save the updated files and commit to the private repo.

• In the CoB Drupal 8 private gitHub repository find the following line in the script at/hooks/common/cob_utilities.sh file (approx line 270):

  Copy

  elif [[ "${target_env}" == "ci" ]] || [[ "${target_env}" == "uat" ]] || ... ; then
      site_machine_name="none"
  fi

  add in the a new condition for the new envname:

  Copy

  ... || [[ "${target_env}" == "envname" ]] ...

  save the updated file and commit to the private repo.

Acquia Settings

• In the CoB Drupal 8 private gitHub repository find the following line in the script at/sites/default/settings/hooks/common/cob_utilities.sh file (approx line 63):

  Copy

  ...
  elseif ($_ENV['AH_SITE_ENVIRONMENT'] == 'uat') {
    $conf['acquia_purge_domains'] = array(
      'bostond8uat.prod.acquia-sites.com',
    );
  }
  ...

  add in a new else statement for the new environment:

  Copy

  elseif ($_ENV['AH_SITE_ENVIRONMENT'] == 'envname') {
    $conf['acquia_purge_domains'] = array(
      'bostond8envname.prod.acquia-sites.com',
      'd8-envname.boston.gov',
    );
  }

  (replace "envname" with the new environment name)

• In the same file find the following section (around line 79):

  Copy

  ...
  if (in_array($siteEnv, ["test", "ci", "uat"])) {
    $settings['file_public_path'] = 'sites/default/files/linked';
  ...

  and add the new environment name to the list of environments.

  Copy

  if (in_array($siteEnv, ["test", "ci", "uat", "envname"])) {

  save the updated file and commit to the private gitHub repository.

Drush

• In the CoB Drupal 8 private gitHub repository edit the drush environment definition script in the /drush/sites/bostond8.site.yml file. Add a new entry at the bottom of the file:

  Copy

  envname:
    root: /var/www/html/bostond8.envname/docroot
    ac-site: bostond8
    ac-env: envname
    ac-realm: prod
    uri: d8-envname.boston.gov
    host: bostond8envname.ssh.prod.acquia-sites.com
    user: bostond8.envname
    envname.livedev:
      parent: "@bostond8.envname"
      root: "/mnt/gfs/bostond8.envname/livedev/docroot"
    paths:
      drush-script: drush9

  (replace envname with the new environment name). Save the updated file and commit to the private gitHub repository.

.htaccess

• In the .htaccess file in the CoB Drupal 8 private gitHub repository alter the domain filters as follows: Everywhere you see this pattern in the file:

  Copy

  RewriteCond %{HTTP_HOST}... dev|stg|ci|ra|uat ...

  Add the following entry:

  Copy

  RewriteCond %{HTTP_HOST}... dev|stg|ci|ra|uat|envname ...

  Save the updated file and commit to the private gitHub repository.

Acquia Cloud

• Login to the Acquia Cloud Console and click on the bostond8 application.

• Click on the new environment to open the configuration page for that environment.

• CRON: Click on "Scheduled Jobs" and create the following new Job: Job name: Envname Site Cron Command: cd /var/www/html/${AH_SITE_NAME}/docroot && drush @bostond8.envname cron -dv &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log Command frequency: */15 * * * * (entered as a string)

• ENVAR: Click on "Variables" and create variables copied from the dev environment.

• DOMAIN: [optional] Click on Domains and add an edit sub-domain. (this is requested from the LAN team, and should be in the pattern of d8-envname.boston.gov. Ask them to set it up the same way that d8-dev.boston.gov is set up. The DNS they create would ideally be private (only to city hall) but they may need to make it on the public DNS servers, which is OK too).

Single Sign On

The following steps need to be completed to allow single sign on via Ping Federated.

• aa

Using the Environment

To use the environment as a Drupal site, you need to attach a branch from the Acquia git repository. For detailed instructions see On Demand section.

Introduction

Because Drupal is most commonly installed on Linux servers, City of Boston DoIT does not recommend using Windows® as a developer machine due to the increased difficulty in emulating the most common Drupal production web server. However, if you have no alternative, or harbor an unquenchable desire to use Windows® then the following best practices and instructions should get you headed in the right direction. There are 3 strategies to choose from:

Layered approach to caching.

City of Boston use Acquia to host all non local (docker) servers on our deployment workflow.

Varnish

Acquia's servers are contained within an Acquia Cloud subscription and implement a Varnish cache outside the load-balancer, as described here.

Drupal Core Cache

The release of Drupal 8 contains a rebuilt cache strategy using "Tags". Drupal 7's cache expired items based on a lifetime for that item. Drupal 8 introduces another option called cache invalidation. This is where you set the cache lifetime to be permanent and invalidate (purge) that cached item when its no longer relevant. Drupal 8 does this by storing metadata about the cached item. Then, when an event occurs, such as an update on a node, the metadata can be searched to find all cache items that contain computed data about the updated node, and can be invalidated.

Memcache

Memcache (for the purposes of this summary document) can be considered to be a low-level cache which optimizes caching by saving more dynamic process responses to memory. The principal value is to minimize requests between the Drupal kernel and MySQL for queries that are run multiple times during bootstrap and page requests.

Memcache is not used on boston.gov (at this time).

Discover cache activity.

You can inspect the headers of requests to a webserver to see if varnish is enabled, and if content was served from the Varnish and/or Drupal caches.

This terminal command will return the headers from a request to a URL:

curl -IXGET <URL>

Examples:

# Production website.
curl -IXGET http://www.boston.gov

# Acquia cloud development environment.
curl -IXGET http://d8-dev.boston.gov

# Local website (if entered on your local development machine).
curl -IXGET http://boston.lndo.site

Cache layer highlights by layer.

Overview

1. A contact us form template is maintained (within script tags) in bos_theme/templates/snippets/contactFormTemplate.html.twig and is included on every boston.gov (Drupal) page.

2. The patterns library contact form javascript function start()(in scripts/components/contact.js ) is executed when a boston.gov (Drupal) page loads. The start() function scans the completed page looking for email addresses anywhere in the html being served. Essentially, it: - replaces the default mailto directive for each email address with a click event listener which will trigger the handleEmailClick() function, and - attaches a click event listener to the forms' submit button and calls the handleFormSubmit()function when the user clicks the submit button on the contact form.

1. When an email address is clicked on the page, handleEmailClick() - copies the template form from the script tags, - inserts the correct email recipient to a hidden field, - inserts all this onto the page and displays the contact us form, and - in the background makes an ajax request to /rest/email_token/create, generating and saving a unique "session" token in the form.

2. When the submit button is clicked, handleFormSubmit() validates the form, and then submits, along with an authorization token to /rest/email_session/contactform.

Notes

Sender email address

Emails are sent from an email address that is generated for each email sent. The format of the email address is:

{random_string}@contactform.boston.gov

We don't send the email from the original sender's email address as that could be a vector for an email spoofing attack.

The reply_to header of the email is set to the constituents email first and the unique address of the contact form second. When someone replies to the email the to address of the email is set to the constituents email first and the unique address second. This delivers two copies of the email. One goes directly to the constituent, and one to the contact form API. We log the response time using the copy that gets sent to the contact form API. Once the reply email is delivered to the constituent, further replies will be direct between the constituent and city.

Process Workflow Diagram

Diagram of the overall flow (needs updating)

Future Enhancements

HTML Emails

The contact us email which is sent from postMark to the cob recipient is a plain text email.

The PostmarkAPI is capable of generating HTML emails. A nicer experience for cob staff would be to receive an html email.

IP Locking

As well as the tokens etc, we could consider introducing an IP lock for say 60sec after a contact form submission is made (the timer should be managed on the server side, inside the endpoint). It should not affect genuine users but would minimize the impact (and success) of flood attacks and relay exploits on the endpoint. If there were a rapid second submission from the same IPAddress, we would flash a warning back to the user to try again after 60 seconds.

Email Confirmations

At the moment, there is no confirmation of a successful submission other than the on-screen notification. We have the submitters' email address, so we could send an email confirming the submission (see next enhancement).

Sender Email Validation.

There is little in the way of validation of the email the submitter provides as a contact for responses.

• The JavaScript validation process does checks that a "visually" valid email pattern is entered, (i.e. it is an email pattern string) but does not validate the email address exists.

• 2022 this ticket (DIG-438) added a second email address box to try to prevent typos in the email address. While it helped a lot, it is not 100% effective and some emails from innocent errors and malicious actors (e.g. spammers) still slip through.

• 2023 DIG-1675 provided some modules which can check for DNS validity, disposable emails and also email blacklists. This would further help reduce invalid sender email addresses being provided.

• If we send email confirmations, then we could use that process to determine if the email address is active and does not have temporary errors (mailbox full etc). Since we are using AJAX it would be simple to end the confirmation email, wait a period of time (say 10sec) and then query postMark to see if the email was delivered. If it was then return success, if not then flag to the submitter on the form. This would not be 100% effective because some errors take time to be reported, and we cannot wait too long during validation. The other two approaches above should still be implemented to try to filter out malicious actions, and to detect innocent errors before consuming email server resources.

Contributor Covenant Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language

• Being respectful of differing viewpoints and experiences

• Gracefully accepting constructive criticism

• Focusing on what is best for the community

• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances

• Trolling, insulting/derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others' private information, such as a physical or electronic address, without explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at . All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

Attribution

This Code of Conduct is adapted from the , version 1.4, available at .

What to look for

• Keyboard focus on focusable elements

• Tab order

• Label tags

• Title attributes

Keyboard access

• All "clickable" elements must be keyboard accessible

• Likewise all hover/focusable elements must have alternate keyboard focus matching the mouse hover

Colors and fonts

• Text colors should be tested for contrast. Make sure there is good color contrast between the text and the background

• A recommended minimum font size is 16 px. Use bold to add emphasis rather than italics or UPPERCASE, but use it sparingly!

Images vs background images

• Use background images only if necessary

• All images must have an alt tag

• Actual images must be use if it gives content more meaning or is the only content.

HTML Structure

• Content will be read from left to right, therefore html should be written out the way the keyboard will tab through content

• Input elements should have labels. They can hidden if not part of the design, but needs to be there for screen readers

• All HTML should have proper aria attributes

• Lists should have the proper role attribute

Titles, captions, and summaries

• Iframes should always have a title to explain the content of the iframe

• Tables must have summaries explaining the content of the table and Captions foe really large tables.

• Images should always have meaningful titles for screen readers to read

• Anchor tags <a>...</a> should always have a title

Links and buttons

• A link should always be a link and not a placeholder

• Buttons

Miscellaneous

See boston.gov/digital for a lot of historical write ups on this work.

Write up on accessibility and text to speech completed for Jeniffer Vivar Wong/Office of Language and Communications Access on 4/5/21:

Potential ideas we found/brainstormed while writing this:

Tools/things Reilly found via Googling:

• https://www.techradar.com/best/best-text-to-speech-software

Things Digital could consider:

• Bringing back the ‘accessibility’ header. Can’t remember if it ever got built and we just turned it off but there are designs for it

• Drupal modules for text to speech - would need devs to advise

  • Would want to do some market research with other govs or places before implementing

  • Lots of reference to Google cloud text to speech or Amazon Polly - unsure if this would be included in free license or we’d need to pay

• General Assembly project for general user experience/desire of this or the City spending some money and hiring a consultant for this or a USDR volunteer

Libraries

@cityofboston internal modules

Useful modules we’ve created and use across our apps in the monorepo.

What is Lando ?

For our purposes, Lando is a PHP-based tool-set which does 3 main things:

1. Provides a pre-packaged local docker-based development environment,

2. Provides a wrapper for common docker container management processes,

3. Provides a means to execute development commands inside the container from the host.

Lando 101.

1. A Pre-packaged Drupal infrastructure on your local computer.

Lando curates an appropriate LAMP stack for Drupal development, largely removing the need for this skill in the local development team. The stack is contained within:

• Docker images that are maintained by Lando.

• A configuration file (landofile) which Lando parses into the necessary dockerfiles and utility scripts

2. Container Management

Lando provides a CLI for tasks developers commonly need to perform on the container.

3. Command Line Interface for tasks in the

Lando provides a CLI for tasks developers commonly need to perform in the container.

Lando Workflows.

- Pull and sync latest version of the github for the checked-out branch.

lando drupal-pull-repo

- Update local DB with content from Acquia Stage site

lando drupal-sync-db

- Update both code and DB locally, but leave container intact

lando drupal-pull-repo --no-sync && lando drupal-sync-db

- Completely rebuild local development environment

lando rebuild or to be completely sure, run these commands from the lando destroy && rm -rf <repo-path> git clone -b develop [email protected]:CityOfBoston/boston.gov-d8.git <repo-path> lando start

When you make an html.twig file and add it to the templates folder of a custom theme you are pretty much done (after refreshing caches!). The Drupal theme rendering processes detect the template and uses it in preference to any template of the same name from a parent or default theme. You don't really have to do anything more than add the file and refresh cache.

But, if you add a template to a custom module -even if your intent is just to override a theme default template (e.g.field.html.twig) or to provide a suggested template, there are a few extra things you must do.

1. Create the twig template you wish to use, and give it a name that matches an existing Drupal theme suggestion with ".html.twig" as the extension. In rare cases you may want to create a new template suggestion. Do this by returning an array of suggestions from ahook_theme_suggestions_hook()in your custom module (see last example below). Convention is to name the template using an "entity breadcrumb" style, with "--"'s between entities and no spaces.

2. Save the template file in a folder called templates in your custom modules root folder. In our example docroot/modules/custom/node_landing_page/templates . - You could organize files by creating a sub-folder tree - but if you do, you will then have to specify the path to your template in the hook_theme - see step 3 below.

3. In the hook_theme of your module you must define your new template. This hook is read by the Drupal core theme engine and loaded into a template cache (aka register). Whenever a change is made to this hook you need to clear all caches to load your changes into the cache. In hook_theme return an assoc array with key-value pair nested arrays for each template you wish to define. - The outer keys (template-keys) should be one for each of the templates you are defining. Keep it simple and traceable by setting the the template-key name to be the template filename without the ".html.twig". Important: Replace all "-"'s with "_"'s in the template-key string. (in our example the template-key is node__landing_page_full) - The value for the key (template-key) is an array with a required base_hook and several other optional fields. The base_hook should define the entity type this template is used to render (in our case node but other common entities we theme are field, region, block, paragraph, taxonomy_term ) . [optional] The render element defaults to elements if not specified. [optional] If you wish to use a template file which is not the same name as the suggestion (with "_"'s replaced with "-"'s) then you must specify its name in the template field. Omit the "html.twig" extension. This could be useful if you want 2 display to share the same template. [optional] If you want to use a custom path to the template file (i.e. not the default templates folder) then use the path field. (see bos_link_collections_theme in boston.gov for example) (see "Our Example hook_theme" below for the complete hook)

4. [optional] Once the cache is cleared you can then catch pre-process events using hook_preprocess_hook in our example this would be node_landing_page_preprocess_node (to catch all node pre-process events) or node_landing_page_preprocess_node__landing_page__full (to catch only this new template pre-process events) - notice that the hook uses the template-key defined in the hook_theme array.

5. [optional] You can also catch template_preprocess_hook events (in our example this is template_preprocess_node__landing_page__full). This hook is commonly used to create a content variable which contains all the rendered (or renderable) elements of the elements (or whatever the field is named in the templates render element) array.

Our Example template file:

Our Example hook_theme:

Our Example hook_preprocess_hook (version 1):

Our Example hook_preprocess_hook (version 2):

Our Example template_preprocess_hook:

Our Example hook_theme_suggestions_hook:

Boston.gov Conventions

The following development conventions are being followed in developing boston.gov modules.

Module naming and location

City of Boston have the following naming and grouping conventions for custom modules:

• Content Types: module_name in folder docroot/modules/custom/bos_components/modules/

• Paragraphs: bos_module_name in folder docroot/modules/custom/bos_content/modules/

• Taxonomy: vocab_module_name in folder docroot/modules/custom/bos_vocab/modules/

• Views, blocks, actions etc: Generally grouped with the main paragraph, node or vocab that uses them.

• Core: The module bos_core defines core services such as REST, Drush and any views or blocks that are used globally (by more than one node, paragraph or vocabulary).

• Theme: boston.gov has two custom themes; bos_theme for all UX theming, and bos_admin for all content editor UX theming.

• Profile: boston.gov does not have a custom profile. Drupal default minimal is used.

• Custom: Custom modules containing backend code are named appropriately and added to the folder docroot/modules/custom.

Twig Templates

Templates for the component should be saved in:

To add a customized template, select a suggestion for the base (node, field, region etc), then

1. Save the template in the folder above

2. In the module_name_theme() hook in module_name.module add the following:

3. If a new suggestion is needed, then add the following:

   Where XXX is the appropriate entity type (node, field, region, etc etc) to add a suggestion to.

Theme overriding

Wherever possible, the style provided from the patterns library should be used. In practice this means that boston.gov can be styled by a Drupal developer ensuring that the twig template files provide HTML structured and given classes that the patterns library expects.

Should the need arise, then the patterns library style sheets can be overridden. Typically this is done at the module level, although if multiple modules will use the override, consider placing it in the bos_theme theme.

To add overrides,

1. Create the style sheet module_name.css and appropriate markup in the relevant template (see above section),

2. Save the stylesheet in:

3. Update (or create) the module_name.libraries.yml file with the following:

4. Using a module_name_preprocess_HOOK() hook in module_name.moduleattach the css where and only when it is required. For example:

Using JavaScript

Wherever possible, JavaScript should not be used on boston.gov. This is to maintain compatibility with as many browsers as possible, and to maximize accessibility for screen readers etc.

Should the need arise, then a JavaScript library can be created and deployed. Typically this is done at the module level, although if multiple modules will use the override, consider placing it in the bos_theme theme.

To add overrides,

1. Create the JavaScript library module_name.js,

2. Save the library in:

3. Update (or create) the bos_modulename.libraries.yml with the JavaScript directive - for example you could add the following:

4. Using a bos_modulename_preprocess_HOOK() hook in bos_modulename.moduleattach the JavaScript library where and only when it is required. For example:

Site and Module Configuration

Drupal 8 defines settings and configurations in YML files with the actual "current" settings and configurations being stored in the Drupal (MySQL) database.

Importing YML configuration into the database.

YML files in a modulesdocroot/modules/custom/ ... /module_name/config/install folder will be imported into the database when a module is first installed.

YML files in the docroot/../config/default/ folder will be imported into the database when the configuration is imported via the Drupal UI, or the drush command.

Exporting all database settings to YML files.

Current (run-time) settings and configurations in the database can be exported to the docroot/../config/default/ folder via the Drupal UI, or the drush command.

Defining module-specific configurations using config_devel.

If the config_devel module is enabled then a modules configuration can be exported to the modules config/install folder.

The dependent configurations are defined in the module_name.info.yml file as follows:

To export these configurations to the config/install folder use the following drush command:

Configuration considerations

• Modules should try to reuse field.storage.entity-type.field_name configurations wherever possible.

• field.storage.entity-type.field_name configurations should be: 1. saved in the modules parent module (e.g. bos_components or bos_content)to enable sharing, and 2. added to the parents config_devel section of the .info.yml file.

Custom Entities

Data Schema

As at March 2023