This is the multi-page printable view of this section. Click here to print.
How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented.
– Diátaxis guide to technical documentation
Our guides are always evolving. If you have a request for a guide, please get in touch.
Sometimes, in the process of making successive config changes, we need to maintain old config files so that outdated update hooks can still run successfully for sites who are running a module that might be many releases behind.
When a new update runs into an error like:
Configuration ______ depends on the ____ configuration that will not exist after import.
the error most often means that some configuration that’s expected in a prior update hook has been removed from the codebase.
In order to enable our modules to move quickly and minimize the need for developers to stop their update process at important versions, we have come up with a process of retaining “outdated” configuration when necessary.
This process ends up with a configuration directory that looks like:
config/
|- 1.0/
|--- a.bunch.of.yml
|- 1.3/
|--- some.different.yml
|- install/
|--- the.regular.yml
|- optional/
|--- other.optional.yml
| etc
See a few examples:
config/outdated/x.x.x.$path line in the failing update hook, changing
/config/optional to /config/outdated/x.x.x.The error above is the most significant indicator of an issue, but it would be optimal to avoid those errors altogether.
Look out for changes in these types of files:
core.entity_form_display.block_content.*.default.yml
core.entity_view_display.block_content.*.default
Adding or removing major features or fields could also result in the error.
YMCA Website Services includes robust mapping functionality defined in the
openy_map subproject. Maps typically are displayed on the /locations page using the
Location Finder component and are highly customizable.
These are a few common customizations:
By default, content types have these labels on the map:
These labels can be customized in the Drupal administration pages to better suit your YMCA’s more member-focused terminology. To do so:
/locations and you should see your changes.You can add new content types to the map with a few steps. This may require some trial and error, so be sure to work in a testing environment first. You will need to have the Field UI module enabled to do this through the Drupal admin UI.
field_location_coordinates - requiredfield_location_address and field_location_phone - suggested for display on the map and location teasers.field_location_amenities - if the location should be searchable with the Amenities search./admin/structure/types/manage/branch/display/teaseradmin/openy/settings/openy_map and configure the options for your new location type.From YMCA Link:
Typography is an important element of our brand identity. Cachet and Verdana, the only two fonts used on YMCA collateral, help provide our words with a distinctive look and welcoming feel. And Cachet, as our primary font, should be used for all internal and external materials whenever possible.
To help Ys incorporate the Cachet font into their online applications, Y-USA is now licensing the web font version of Cachet for all YMCAs. Previously, Ys could only access the desktop version of the font from the Brand Resource Center (BRC).
Visit the BRC to:
- Download Cachet as a Web Font (requires YMCA Link login)
YMCA development partners can take advantage of a custom module which allows for automation of this process.
Get in touch or reach out in #developers on the YUSA Slack for more details.
Once you’ve downloaded the WOFF files, you’ll need to add them to your site. These instructions mirror the walkthrough in this video.
| Label | Font Family | Font Style | Font Weight | Font Classification | Font File |
|---|---|---|---|---|---|
| Cachet Extra Light | Cachet | Normal | 300 | Sans Serif | CachetW05-ExtraLight.woff |
| Cachet Book | Cachet | Normal | 400 | Sans Serif | CachetW05-Book.woff |
| Cachet Medium | Cachet | Normal | 500 | Sans Serif | CachetW05-Medium.woff |
| Cachet Bold | Cachet | Normal | 700 | Sans Serif | CachetW05-Bold.woff |
Social media is a great platform for communicating with your Y community, and it’s often helpful to embed feeds or posts on a page to share topical content with users.
The distribution has used several methods over the years to add social content to sites, but all of them are dependent on the specific platforms maintaining open APIs. Unfortunately, many social networks are now locking down and restricting their APIs.
Currently, we recommend using embed codes from the specific platform to embed social posts or feeds on your YMCA Website Services website.
Each platform has its own way of doing embeds. For posts, you can often find an “Embed” button in the options or share menu. For feeds, you often need to use a separate builder. Here are some options we’ve found:
Note: Social platforms may break these embeds at their whim. Use at your own risk.
The Social Feeds Fetcher module that comes with the distribution allows your site to import social media content for syndication.
To configure fetching:
/admin/config/social_feed_fetcher_settings or Configuration > Web Services > Social Feed Fetcher SettingsAll mobile browsers — Firefox, Edge, Safari, Chrome, Opera Mini, UC Browser, Samsung Internet — make it easy to share content directly from their native platforms.
According to their introductory blog post:
AddToAny is the perfect drop-in replacement for AddThis.
As of December 2023, the AddToAny module is included in the YMCA Website Services distribution. It is not enabled out of the box, but if you need to supplement native platforms’ sharing services, here’s how:
/admin/modules) and enable the AddToAny module./admin/config/services/addtoany)Full documentation on AddToAny is available on Drupal.org and AddToAny’s Drupal Sharing Customization.
To integrate AddToAny with the Layout Builder Design System:
a2a_config.icon_color = "var(--wsPrimaryColor),white";
This Social Share Icons paragraph and the AddThis module ceased functioning on May 31, 2023, with the discontinuation of AddThis services.
Before you start your migration, we recommend you:
Layout Builder components for YMCA Website Services were developed and released throughout 2023. The plan at the outset was that Paragraphs-based components would be supported for one year from the time of the Layout Builder components’ completion, then would cease being supported. Site owners can begin migrating their content at any time. Upon the deprecation of Paragraphs components, they will not “disappear”, but they will no longer be supported by the YMCA Website Services core team.
As of October 2023, the timeline is:
Site owners are encouraged to plan a migration of their content to Layout Builder in 2024, after which point they will be responsible for maintaining Paragraphs components.
(Timeline is subject to change based on community feedback and priorities.)
The migration from Paragraphs to Layout Builder is not a small one, but it can be done in bite-sized pieces and spread out over some time if necessary. We recommend working with a partner agency to assist you through the process.
TIP: As you work through the migration, the new pieces of your site will look different than others. Help members through the process with some messaging in an Alert or news post letting them know that things will be changing.
If you’re doing your migration throughout your regular business, without starting from scratch (sometimes called a “lazy migration”), it helps to identify a strategy for planning the migration. These are a few possible strategies:
If you have an upcoming marketing campaign you could build one or a few brand new Landing Pages with Layout Builder to try out the process. This way you’re easing both your editors and members into the new designs without getting too deep.
If you have a natural pause in events (maybe over a holiday) or a big series coming up you could use that as the break point for new events. Old events don’t necessarily have to be converted to the new design as they’re not often viewed after their date has passed.
Maybe you want to ease into the process with some lesser-used pages, maybe you want to change the home page and top-level menu items to show off the new designs right from the outset. Either way, you can decide on a section and carve off a few pages at a time.
Events or News articles are a good option to try out the new designs, although you’ll need to ensure any Landing Pages that display lists of that content are also updated. Branch pages can be converted one by one without changing their listing on the Locations page.
Once you know what you’re going to move, you’ll want to get the content ready to migrate. Most text will need to be copied and pasted to the new pages (this is a great opportunity for review), but images and documents will be able to be re-used from the Media Library.
It could be helpful to print or screenshot pages (Firefox can capture a full-page screenshot) and then annotate them to decide how each section of the page will map to its Layout Builder component. You could even use the Wayback Machine to save a snapshot of the page.
While the exact mappings are up to each site’s content editors, here are some possible mappings from Paragraphs to Layout Builder
- Paragraph
- the Layout Builder component it maps to.
Once you have a plan, go build it! Use the Layout Builder documentation to help you through the process. Building each page might look something like this:
If at any point in this process you need help, be sure to reach out to our community. The functionality is always being improved, and we have a wide variety of developers and builders from other Ys who are happy to help.
Doing a content audit is a useful first step to planning a migration. You can use our content audit template and watch our walkthrough on the May Monthly Call to get started, then follow these steps:
List current website pages in a spreadsheet by menu section.
Visit each page and review content.
composer require ycloudyusa/yusaopeny at the root of the project.The core functionality of the Layout Builder features is packaged inside the
Y Layout Builder module (y_lb). This module is required by the profile and comes with it out of the box.
Layout Builder modules could be disabled by default. The complete
list of available components is available in y_lb/composer.json. There are two different methods to enable them:
/admin/modules) and enable only the components that you choose to use./admin/openy/extend/list). Check the box for Layout Builder, then Install.Layout Builder relies on a system of Layout Defaults and Layout Overrides. An important concept to understand from these pages is:
Once a Layout is overridden on an entity, that entity will not be impacted by changes to Layout Defaults.
In building Landing Pages, we will override the Default Layout for every page (by placing content blocks). For this reason, it is important that we configure the desired defaults before building pages.
You will use the Landing Page (with Layout Builder) content type to build landing pages.
Configure its
content type styles at /admin/structure/types/manage/landing_page_lb/display first. Configure:
You will use the Branch, Camp, and Facility content types to build pages that contain the contact and amenity details for each location.
/admin/structure/types/manage/branch/fields/node.branch.field_use_layout_builder./admin/structure/types/manage/branch/display/admin/structure/types/manage/camp/display/admin/structure/types/manage/facility/display/locations using
Location Finder.Enable
Events with Layout Builder (ws_event) to use Events with Layout Builder.
admin/structure/types/manage/lb_event/display./events using
Events Views & FiltersEnable
Articles with Layout Builder (y_lb_article) to use Articles with Layout Builder.
/admin/structure/types/manage/article_lb/display./news using
Article Views & Filters.Enable openy_node_session, openy_node_program, openy_node_category, openy_node_activity, and openy_node_class to set up the Program Event Framework (PEF) if you plan to use Schedules or Activity Finder on the project.
Then require and enable
yusaopeny_activity_finder to use
Activity Finder.
YMCA Website Services uses the Drupal contrib Google Analytics module to enable Google Analytics tracking on your YMCA Website Services site.
To get started, you should first create a GA property. Use the Analytics Help for assistance.
Configuration is done at the standard module configuration page: /admin/config/services/google-analytics.
In the
9.2.11 release in November 2021, YMCA Website Services
added support for Google Analytics 4. If your site has been updated to YMCA Website Services 9.2.11 or greater AND the google_analytics module has been updated to 4.x you should be able to use GA4. Otherwise you’ll need to stick with GA3.
Log in to Google Analytics account that configured to track your YMCA Website Services site.
Click Admin button in bottom right corner of main screen
Click View Settings
Scroll to “Site Search Settings” section and enable “Site Search Tracking” switch
Fill query parameter field with q, query values and click Save
Reports about the search tracking you can find at main screen in Behavior → Site Search Section
Attention: Data processing latency for search tracking reports is 24-48 hours (see Google’s support doc).
See also the Data Layer module README.
The Data Layers module output data on the page in a json format. By default it will output properties (langcode, vid, name, uid, created, status, roles) and related taxonomy for any node, user, or any route based entity.
A limited set of properties are available via the Data Layers configuration form at /admin/config/search/datalayer (langcode, vid, name, uid, created, status, roles).
Adding additional properties can be done through use of hook_datalayer_meta().
function my_module_datalayer_meta() {
return array(
'property',
);
}
It will be added to the page as:
{
"entityProperty": "whatever the value is"
}
Altering which properties will be output can be done via hook_datalayer_meta_alter().
function my_module_datalayer_meta_alter(&$properties) {
// Override module norm in all cases.
unset($properties['entityUid']);
// Specific situation alteration...
$type = false;
if ($obj = _datalayer_menu_get_any_object($type)) {
if ($type === 'node' && in_array(array('my_bundle', 'my_nodetype'), $obj->type)) {
// Remove author names on some content type.
if ($key = array_search('name', $properties)) {
unset($properties[$key]);
}
}
elseif ($type === 'my_entity_type') {
// Remove some property on some entity type.
if ($key = array_search('my_property', $properties)) {
unset($properties[$key]);
}
}
}
}
Adding additional data can be done using datalayer_add().
function _my_module_myevent_func($argument = FALSE) {
if ($argument) {
datalayer_add(array(
'drupalMyProperty' => $argument,
'userAnotherProperty' => _my_module_other_funct($argument),
));
}
}
To alter the data to be output use hook_datalayer_alter().
function my_module_datalayer_alter(&$data_layer) {
// Make the title lowercase on some node type.
if (isset($data_layer['entityBundle']) && $data_layer['entityBundle'] == 'mytype') {
$data_layer['entityLabel'] = strtolower($data_layer['entityLabel']);
}
}
This configuration enables cross-domain tracking (also known as “cross-domain measurement”) to work through internal redirects like those in
Membership Calculator (that use TrustedRedirectResponse).
When enabled, cookies matching any configured tag will be added to any redirect destination matching a configured domain. For example, a redirect to https://example.com will be transformed to https://example.com/?_gl=.....
This process is illustrated well by Analytics Mania:
Analytics provides code that does this automatically with standard <a> links, but this module is required to enable similar functionality with “server-side” links/redirects.
NOTE: Configuration and testing of analytics is required outside the scope of this module, refer to [GA4] Set up cross-domain measurement for more information.
Successful cross-domain tracking also requires the destination application to retain the passed query strings and load them into the corresponding tracking property.
Many Customer Relation Management (CRM) systems and Member Management Systems integrate with YMCA websites. Those systems often need guidance on hwo to maintain cross-domain tracking support.
Entrance to the CRM/MMS often involves multiple redirects which may drop the required query strings.
When discussing cross-domain support with your vendor, we recommend requesting:
Please support passing query strings/parameters through redirects, specifically maintaining the
_glparameter.
You may also need to request that your GTM/GA code be added to the CRM/MMS to report back these parameters.
drush en openy_xdt
/admin/openy/settings/xdt)Adding structured data can enable search results that are more engaging to users and might encourage them to interact more with your website
The distribution (as of version 10.3.0) leverages the community contributed Schema.org metatag module and custom code to integrate structured data into many content types. You can test if your page is outputting structured data by using the Schema.org Validator or Google’s Rich Results Test
Once your site is updated, structured data will be automatically generated 🎉 with no additional work from content editors.
The Article (Layout Builder) content type implements the Article Schema as per Google’s Article structured data docs.
Articles have three options for the Type, which map to their appropriate Schema:
This mapping is set in code (y_lb_article_metatags_alter in
y_lb_article.module), but all other settings are configurable via the Metatag configuration (/admin/config/search/metatag/node__article_lb).
The Branch content type implements the LocalBusiness Schema as per Google’s Local business structured data docs.
Any time the Branch Hours are updated, that content will also be reflected in the Structured Data that’s read by search engines.
The mapping is configurable in the Metatag configuration (/admin/config/search/metatag/node__branch). Hours configuration uses the
Open Y Hours_metatag tokens.
The Accordion Layout Builder Block has an option to implement the FAQPage Schema as per Google’s FAQ structured data docs.
If an Accordion section contains Frequently Asked Questions, check the FAQ? checkbox to output them as structured data.
Tips for writing good FAQ content:
Due to the complexity of the FAQ data, the structured data is managed entirely in code and is not customizable via the Drupal admin. If you need specific customizations, please post your ideas in Slack or suggest them on the Roadmap for the core team to discuss and implement.
YMCA of the USA has partnered with YMCA Canada to create a brand-compliant and accessible colourway for use by Canadian YMCAs.
The colourway is packaged as the Canada Layout Builder Colorway on Drupal.org and is included with the full YMCA Layout Builder package.
The Canadian Colorway package includes four options for content type or page-level colorways. Each colourway uses the same three primary colors - dark red, lighter red, and grey, along with a highlight color of blue, purple, green, or black.
The Canadian Colorway for Banners package contains 4 banner variations that utilize the unique Y Canada chevron:
These can be selected in the Y Styles selector for each banner on your site.
Y Canada sites can also use the existing “Overlay” Banner style as it does not utilize any YUSA-specific styling.
ws_colorway_canada will immediately changes the site logo from the Y-USA logo to the Y Canada logo, so this should be done on a development environment first.The
ws_colorway_canada module and its submodule lb_hero_canada contain
colorways, logos, and banner styles approved by Canadian Y authorities.
admin/modules) and enable these two modules (search for Canad):ws_colorway_canada)lb_hero_canada)drush:drush en ws_colorway_canada lb_hero_canada -y
After enabling the new colorway, there are a few more steps to ensure the new colorways are used across your site:
Y Canada site developers may want to hide the existing YUSA styles in order to prevent unintentional usage. This is not possible through configuration at the moment, but some custom css can do the trick:
#edit-ws-design-settings-colorway .form-item-ws-design-settings-colorway:has(div[class*="colorway-ws"]),
#drupal-off-canvas .form-item-appearance-ws-style-ws-style-option-hero-banner:not(:has(input[value*="canada"])) {
display: none;
}
Enabling two-factor authentication (2FA or TFA) adds a layer of security to selected roles like admin while allowing other users to log in to the site only with basic authentication with a Drupal username and password.
The community-contributed TFA module is the recommended path to requiring 2FA for users.
The TFA module requires the PHP OpenSSL extension. This is installed with most modern stacks, but you can check to see if it is running with: php -i | grep openssl.
Add the TFA module and its soft dependency:
composer require drupal/tfa drupal/real_aes
We recommend you follow the full installation instructions for the 8.x branch or the 2.x branch.
Once you configure an encryption key and an encryption profile, you will then be able to enable TFA at Admin > Configuration > People > TFA (/admin/config/people/tfa).
Once you enable TFA, you will have the option to require it for specific roles.
