How-to Guides

• 1: Migrate from Paragraphs to Layout Builder
• 2: How to avoid outdated configuration
• 3: How to customize your locations map
• 4: How to install Cachet (the official Y Font)
• 5: How to integrate with social media
• 6: How to migrate content into Layout Builder
• 7: How to perform a content audit
• 8: How to set up a Layout Builder site
• 9: How to set up a site with the Small Y template
• 10: How to track & analyze user actions
• 11: How to leverage structured data
• 12: How to use the Canadian Colourway for Layout Builder
• 13: How to use two-factor authentication

1 - Migrate from Paragraphs to Layout Builder

This guide will help you migrate your YMCA website from legacy Paragraphs-based content types to modern Layout Builder content types.

Overview

What You’ll Learn

By the end of this guide, you’ll understand:

• ✅ When to migrate vs. when to use alternatives
• ✅ How to audit your existing Paragraphs content
• ✅ Migration approaches and their trade-offs
• ✅ Step-by-step migration process
• ✅ Tools and resources available

Estimated time: Planning: 1-2 hours | Migration: Varies by content volume

Step 1: Assess Your Migration Need

Should You Migrate?

✅ Strong reasons to migrate:

• Your site is on the legacy Paragraphs system (landing_page, blog, news)
• You want modern drag-and-drop Layout Builder experience
• You’re planning a site redesign or major content refresh
• You have < 500 pages to migrate (manageable manual effort)
• Your team prefers visual page building over structured forms

⚠️ Consider alternatives if:

• You have thousands of Paragraphs pages (migration effort is high)
• Your content editors are comfortable with current Paragraphs workflow
• You need a hybrid approach (some Paragraphs, some Layout Builder)
• You have complex nested Paragraphs structures
• Budget/timeline is constrained

Content Types Affected

Legacy Paragraphs-based content types in YMCA Website Services:

• landing_page - Landing Page (Paragraphs) → Migrate to: landing_page_lb (Layout Builder)
• blog - Blog Post (Paragraphs) → Migrate to: article_lb (Layout Builder)
• news - News Post (Paragraphs) → Migrate to: article_lb (Layout Builder)

Note: Location content types (Branch, Camp, Facility, Program) use structured fields, not true Paragraphs page building. These typically don’t need Layout Builder migration.

Step 2: Audit Your Content

Before migrating, understand what you have.

Run a Content Audit

1. Count your Paragraphs content:

# Count Landing Pages (Paragraphs)
drush sqlq "SELECT COUNT(*) FROM node_field_data WHERE type = 'landing_page'"

# Count Blog Posts
drush sqlq "SELECT COUNT(*) FROM node_field_data WHERE type = 'blog'"

# Count News Posts
drush sqlq "SELECT COUNT(*) FROM node_field_data WHERE type = 'news'"

2. Identify your most-used Paragraph types:

# List all paragraph types in use
drush sqlq "SELECT DISTINCT type, COUNT(*) as count FROM paragraphs_item_field_data GROUP BY type ORDER BY count DESC"

3. Export content inventory:

# Export all landing pages to CSV
drush sqlq "SELECT nid, title, status, created, changed FROM node_field_data WHERE type = 'landing_page' ORDER BY changed DESC" --extra=--csv > landing_pages_audit.csv

Analyze Your Content

Questions to answer:

• How many pages use each Paragraph type?
• Which pages are most important (high traffic, business-critical)?
• Which pages are outdated and can be archived?
• Are there common patterns you can templatize in Layout Builder?

Create a migration priority list:

1. High priority: Homepage, key landing pages, high-traffic content
2. Medium priority: Active campaign pages, recent content
3. Low priority: Archived content, low-traffic pages

Step 3: Choose Your Migration Approach

There are three main approaches to migrating Paragraphs content to Layout Builder:

Approach 1: Manual Recreation (Recommended for Most)

Best for: < 500 pages, significant content refresh desired

Process:

1. Create new Layout Builder pages (landing_page_lb)
2. Manually recreate content using Layout Builder blocks
3. Review and improve content during migration
4. Redirect old URLs to new pages
5. Archive or delete old Paragraphs content

Pros:

• ✅ Clean slate - opportunity to improve content
• ✅ No custom code required
• ✅ Quality control on every page
• ✅ Learn Layout Builder thoroughly
• ✅ Can be done incrementally

Cons:

• ⏱️ Time-consuming for large sites
• ⏱️ Requires content editor availability

Estimated effort: 15-30 minutes per page

Approach 2: Automated Migration (Advanced)

Best for: Large sites (500+ pages), technical resources available

Process:

1. Develop custom Drupal migration module
2. Map each Paragraph type to equivalent Layout Builder blocks
3. Create migration process plugins
4. Test thoroughly on staging environment
5. Run automated migration in batches
6. Manual QA and cleanup

Pros:

• ✅ Fast for large content volumes (1000+ pages)
• ✅ Consistent mapping rules applied uniformly
• ✅ Preserves exact content structure
• ✅ Repeatable and version-controlled

Cons:

• 🔧 Requires experienced Drupal developer
• 🔧 Complex for nested Paragraphs structures
• 🔧 May miss content nuances
• 💰 Higher upfront development cost
• ⚠️ Still requires manual QA afterward

When to consider: If you have 500+ pages AND in-house Drupal development expertise OR budget to hire professional help.

Approach 3: Phased Migration

Best for: Large sites with limited resources, need gradual transition

Process:

1. Keep both old Paragraphs and new Layout Builder content types enabled
2. Create new content using Layout Builder (landing_page_lb, article_lb)
3. Migrate high-priority pages manually first (homepage, key landing pages)
4. Leave low-traffic legacy content as-is temporarily
5. Set migration deadlines by content category
6. Gradually migrate remaining content over 6-12 months

Pros:

• ✅ No “big bang” cutover - reduced risk
• ✅ Spread effort over time
• ✅ Learn and improve process as you go
• ✅ Prioritize business-critical content
• ✅ Staff can learn Layout Builder gradually

Cons:

• ⏱️ Longer overall timeline
• ⏱️ Maintain both systems during transition
• 🔧 Risk of leaving old content unmigrated

Step 4: Manual Migration Process (Recommended)

Here’s the step-by-step process for manually migrating Paragraphs content to Layout Builder.

Prepare Your Environment

1. Enable Layout Builder content types:

# Ensure Layout Builder content types are available
drush pm:list --type=module --status=enabled | grep openy

# If not enabled, enable them
drush en openy_node_landing_page_lb openy_node_article_lb -y
drush cr

2. Set up parallel content workflow:
   • Keep old Paragraphs content published during migration
   • Create new Layout Builder versions at new URLs (e.g., /new-about-us)
   • Switch URLs when migration is complete

Migrate a Single Page (Example Workflow)

Original: Landing Page (Paragraphs) at /about-us New: Landing Page (Layout Builder) at /new-about-us

Step 1: Create New Layout Builder Page

1. Navigate to Content > Add content > Landing Page (Layout Builder)
2. Fill in basic fields:
   • Title: Same as original
   • URL alias: /new-about-us (temporary)
   • Leave Published unchecked (draft mode)
3. Click Save and edit layout

Step 2: Recreate Content with Layout Builder

For each Paragraph on the original page:

1. Identify the Paragraph type (Banner, Text, Cards, etc.)
2. Find equivalent Layout Builder block (see mapping table below)
3. Add section → Choose layout (1 column, 2 column, etc.)
4. Add block → Create custom block → Select block type
5. Copy content from original Paragraph fields
6. Configure block settings (colors, alignment, etc.)
7. Repeat for all Paragraphs

Step 3: Review and Improve

• Check responsive display (mobile, tablet, desktop)
• Optimize images (compress, alt text, proper sizing)
• Improve content (update outdated info, fix broken links)
• Test all CTAs and forms
• Preview before publishing

Step 4: Publish and Redirect

1. Unpublish old page (Content → find old page → Edit → uncheck Published)
2. Update new page URL to /about-us
3. Publish new page (check Published → Save)
4. Add redirect (if old page had different URL):

drush redirect:create /old-url /about-us

5. Archive old content (optional: keep for reference or delete)

Paragraph to Block Mapping

Missing a block type? Check the Block Library for 30+ available blocks.

Step 5: Bulk Migration Tips

If you’re migrating many pages, use these strategies to speed up the process:

Batch Migration Strategy

1. Create templates for common page patterns:

   • Homepage pattern
   • Program landing page pattern
   • Event landing page pattern
   • Branch landing page pattern

2. Use Layout Builder templates (if available):

   • Save frequently-used layouts as templates
   • Clone similar pages and update content

3. Assign migration in batches:

   • Batch 1: High-priority pages (team leads)
   • Batch 2: Program pages (program coordinators)
   • Batch 3: News/blog migration (communications team)

Quality Assurance Checklist

For each migrated page, verify:

• All content present (no missing Paragraphs)
• Images display correctly (proper sizing, alt text)
• Links work (internal and external)
• Forms function (webforms, buttons)
• Mobile responsive (test on phone)
• SEO metadata (page title, description)
• URL redirects (old URLs point to new)

Step 6: Automated Migration (Advanced)

For sites with 500+ pages, automated migration using Drupal’s Migrate API can speed up the process significantly.

Prerequisites

• Experienced Drupal developer on staff or contracted
• Development environment (local DDEV/Docker setup)
• Version control (Git)
• Staging environment for testing

High-Level Approach

Note: Automated migration is technically complex and requires custom development. This is an overview of the approach, not a complete tutorial.

1. Create custom migration module in modules/custom/ymca_paragraphs_migration/

2. Map Paragraph types to Layout Builder blocks:

   • Analyze your existing Paragraph types
   • Identify equivalent Layout Builder blocks
   • Document field mappings (Paragraph fields → Block fields)

3. Develop migration process plugins:

   • Custom PHP code to transform Paragraph data into Layout Builder section structure
   • Handle field mappings, media references, and nested structures
   • Create Layout Builder sections and regions
   • Place blocks in appropriate sections

4. Test thoroughly:

   • Migrate 5-10 sample pages
   • Verify content accuracy
   • Check responsive display
   • Test all links and media
   • Iterate and fix issues

5. Run production migration:

   • Backup database
   • Run migration in batches (100-200 pages at a time)
   • QA each batch before proceeding
   • Manual cleanup as needed

Complexity Factors

Simple migrations (easier):

• Flat Paragraph structures (no nesting)
• Standard Paragraph types (Banner, Text, Cards)
• Small number of unique Paragraph types (5-10)

Complex migrations (harder):

• Deeply nested Paragraphs (3+ levels)
• Custom Paragraph types
• Complex field relationships
• Media galleries with custom displays

When to Hire Professional Help

Consider contracting a Drupal developer if:

• You have 1,000+ pages to migrate
• You have complex nested Paragraphs structures
• You lack in-house Drupal development expertise
• You need the migration completed quickly (< 3 months)
• You want post-migration support and training

→ Contact YMCA community for developer recommendations

Step 7: Post-Migration Cleanup

After migrating all content, clean up legacy systems:

Archive Old Content

# Export old Paragraphs content for archival
drush sql:dump --gzip --result-file=backup-pre-paragraphs-cleanup.sql

# Unpublish all old landing pages
drush sqlq "UPDATE node_field_data SET status = 0 WHERE type = 'landing_page'"

Remove Old Content Types (Optional)

⚠️ Warning: Only do this after confirming all content is successfully migrated!

# Disable old content types
# (This is permanent - backup first!)
drush entity:delete node --bundle=landing_page

# Or keep for reference but hide from editors
# Configuration → Content types → Landing Page → Edit → Disable

Update Documentation

• Update internal wiki/documentation to reference new Layout Builder pages
• Train content editors on Layout Builder (if not done already)
• Update style guides to reflect new block library

Troubleshooting

Common Issues

Issue: “Block not found” error during automated migration

Solution: Ensure all Layout Builder blocks are enabled. Check that custom blocks exist before running migration.

Issue: Migrated pages missing images

Solution: Images may not migrate automatically. Check file references in source Paragraphs and manually map to Layout Builder blocks.

Issue: Layout looks different than original

Solution: Layout Builder uses different CSS classes than Paragraphs. Update theme styling or recreate layouts to match desired design.

Issue: Performance issues after migrating thousands of blocks

Solution: Set reusable field to 0 for migrated blocks to avoid permission calculation overhead:

$block->set('reusable', FALSE);

Related Resources

YMCA Website Services Documentation

• Content Types Library - Browse all available content types
• Block Library - 30+ Layout Builder blocks
• Layout Builder Documentation - Complete Layout Builder guide
• Content Editor Getting Started - Learn Layout Builder basics
• Site Builder Getting Started - Configuration and setup

Get Help with Your Migration

• YMCA Community Slack - Join #development channel for migration questions
• Monthly Community Calls - Ask questions live, share experiences
• GitHub Discussions - Community Q&A
• Troubleshooting Guide - Common issues and solutions

Decision Framework

Still not sure which approach to take? Use this decision tree:

Do you have < 100 pages to migrate?
├─ YES → Manual recreation (Approach 1)
└─ NO → Do you have < 500 pages?
    ├─ YES → Manual or Phased migration (Approach 1 or 3)
    └─ NO → Do you have in-house Drupal developers?
        ├─ YES → Automated migration (Approach 2)
        └─ NO → Do you have budget for professional help?
            ├─ YES → Hire Drupal developer
            └─ NO → Phased migration (Approach 3) - spread over 6-12 months

Success Patterns from YMCA Migrations

Medium-sized YMCA (200 pages):

Manual migration over 3 months worked well. The process provided an opportunity to refresh outdated content and archive low-value pages. Content editors reported that Layout Builder reduced page creation time from 45 minutes to 15 minutes.

Large YMCA (500+ pages):

Phased approach with high-priority pages first. Migrated homepage and program landing pages manually (50 pages), then tackled category pages over 6 months. Still have low-traffic archive content on old system - planning to migrate or archive in year 2.

Small YMCA (75 pages):

Completed manual migration in 6 weeks with part-time content editor. Spread work across team - different staff owned different content areas. Used migration as training opportunity to learn Layout Builder.

Next Steps

Ready to start your migration? Follow these steps:

1. Run content audit - Understand your content volume
2. Choose approach - Manual, automated, or hybrid
3. Create migration plan - Prioritize pages, assign owners
4. Start small - Migrate 5-10 pages as pilot
5. Get help if needed - Contact agency partners

Questions? Join YMCA Community Slack and ask in #development! 🚀

2 - How to avoid outdated configuration

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.

Overview

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:

• ws_event - MR !72
• lb_accordion - MR !24
• lb_cards - MR !45

Fixing an update hook

1. Find the version of the module where the failing update hook was committed.
2. Checkout or download the old version to a separate working directory.
3. Copy all config files that are being imported in that hook into a new directory, like config/outdated/x.x.x.
4. Change the $path line in the failing update hook, changing /config/optional to /config/outdated/x.x.x.
5. Commit those changes and test thoroughly.

Warning signs

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.

3 - How to customize your locations map

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:

Changing Map Options

By default, content types have these labels on the map:

• Branch = YMCAs
• Camp = Camps
• Facility = Facilities

These labels can be customized in the Drupal administration pages to better suit your YMCA’s more member-focused terminology. To do so:

• In the Admin Menu, go to YMCA Website Services (or Open Y on prior versions) > Settings > Map Settings
• In the Branch/Camp/Facility Content Type sections you can:
  • edit the label names,
  • show or hide the content type on the Locations page,
  • set the filter to be on or off by default, and
  • set the map icon.

    

• Edit each content type as needed then Save the form.
• Reload /locations and you should see your changes.

Adding Additional Location Types

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.

• Create a new content type via Structure > Content types > Add content type
• Add these existing fields to the content type:
  • field_location_coordinates - required
  • field_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.
• Set up the Teaser display on the new content type:
  • Navigate to Manage display then Teaser
  • Update these settings to match the Branch Teaser display at /admin/structure/types/manage/branch/display/teaser
• Go back to the Map Settings at admin/openy/settings/openy_map and configure the options for your new location type.

4 - How to install Cachet (the official Y Font)

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)

For developers

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.

For site builders

Once you’ve downloaded the WOFF files, you’ll need to add them to your site. These instructions mirror the walkthrough in this video.

• Visit Admin > Extend and ensure the “@fontyourface” and “@fontyourface - Local Fonts” modules are enabled.
• Visit Admin > Appearance > @font-your-face > Custom Fonts
• Click + Add Custom Font and add each of the Cachet font files you downloaded above with the following settings:

• After you’ve added each font, Enable them.

• Your site should now use the Cachet font in headers and other areas. Usage is dependent on the YMCA Website Services theme you choose.

5 - How to integrate with social media

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.

How to embed social content in your YMCA website (in 2023)

Currently, we recommend using embed codes from the specific platform to embed social posts or feeds on your YMCA Website Services website.

Find the embed code

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:

• Twitter / 𝕏 Publish
• Meta (Facebook/Instagram) Social Plugins

Note: Social platforms may break these embeds at their whim. Use at your own risk.

Embeds using Paragraphs

• Navigate to a content page on your site, then click Edit.
• Add a Code Paragraph to the section where you’d like to do the embed.
• Paste in the embed code generated above.
• Save the page.

Embeds using Layout Builder

• Navigate to a content page on your site, then click Layout.
• Add a Code Blockto the section where you’d like to do the embed.
• Paste in the embed code generated above.
• Save the block, then Save layout on the page.

Alternatively, try Social Feeds Fetcher

The Social Feeds Fetcher module that comes with the distribution allows your site to import social media content for syndication.

To configure fetching:

• Open the configuration page at /admin/config/social_feed_fetcher_settings or Configuration > Web Services > Social Feed Fetcher Settings
• Select the checkbox for your chosen social networks and add additional settings. Every social network has its own API and requires different configuration.
• When all settings are completed, click Run Cron. The import is started and if the configuration is correct, items will appear in the content list.

How to share content from your site to social media

All mobile browsers — Firefox, Edge, Safari, Chrome, Opera Mini, UC Browser, Samsung Internet — make it easy to share content directly from their native platforms.

– UX Considerations for Web Sharing

Using AddToAny

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:

• Go to Admin > Extend (/admin/modules) and enable the AddToAny module.
• Configure the module at Admin > Configuration > Web Services > AddToAny (/admin/config/services/addtoany)

Full documentation on AddToAny is available on Drupal.org and AddToAny’s Drupal Sharing Customization.

AddToAny with Layout Builder

To integrate AddToAny with the Layout Builder Design System:

• Set the following configuration options for AddToAny:
  • Icon size: 36 pixels
  • Service Buttons: Change to any number of standalone service buttons that you would like.
  • Additional JavaScript: Add this code to have the buttons follow the configured colorway:

    a2a_config.icon_color = "var(--wsPrimaryColor),white";
    

  • Save the configuration
• Add the AddToAny share buttons to the default Layout Builder display.
  • Edit a single Page Layout or the Content Type Layout.
  • Decide where to add the share block. We recommend the right side of the footer, above or below the “Stay Connected” block, but any section of the page would work.
  • In Layout Builder, Add block, then choose All system blocks > AddToAny share buttons.
    • Set a Title like “Share this”.
    • Choose to Display title.
    • Leave other configuration as their defaults.
    • In the Style settings, expand Spacing and add a top or bottom margin of 32px to ensure the block is spaced properly from the block above or below it.
• Save the Block and the Layout.

Using AddThis

This Social Share Icons paragraph and the AddThis module ceased functioning on May 31, 2023, with the discontinuation of AddThis services.

6 - How to migrate content into Layout Builder

Before you start your migration, we recommend you:

• understand your current site with a Content Audit,
• familiarize yourself with the new Layout Builder Components,
• watch our comparison of Paragraphs and Layout Builder, and
• see a side-by-side demo of the old vs. new page building experiences.

How long do I have?

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:

• December 2023 - Layout Builder components are considered “feature complete”
• 2024 - refinement and bug fixing of Layout Builder components, basic bug fixing only for Paragraphs components.
• December 2024 - end of support for Paragraphs components.

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.)

Plan your migration

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.

Decide where to start

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:

A campaign or goal

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.

A section of the site

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.

A content type

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.

Prepare your content

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.

Component mapping

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.

1 Column

2 Columns

3 Columns

4 Columns

Secondary Description and Sidebar

These paragraphs can be replicated using 1-4 column Layouts

Activity Finder

Activity Finder

All Amenities

Branch Amenities

Banner

Small Banner

Banner

Blog Posts Listing

Featured Blog Posts

Featured News Posts

Latest Blog Posts

Latest News Posts

News Posts Listing

Articles Filter, Articles Listing, Featured Articles

Camp Menu

Camp Menu

Categories Listing

TBD

Code

Code

Date Block

None

Embedded GroupEx Pro Schedule

Due to changes in the GroupEx Pro embed functionality, we recommend moving to a Code block.

FAQ

Accordion

Featured Content

Story Card

Cards or Grid CTA

Gallery

Carousel

Grid Content

Grid CTA or Icon Grid

Limited Time Offer

Banner (small variant) or Alert

Membership Calculator Paragraph

Membership Calculator

Promo Card

Promo Card

Simple Content

Table

Social Share Icons

Deprecated

Teaser

Ping-pong

Webform

Webform

Build it

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:

• Create a new, unpublished, Landing Page (with Layout Builder)
• Add blocks and content to the new page
• Ensure the URL Alias of the new page matches that of the old page
• Un-publish the old page and publish the new page.
• Test out the new page in a new browser, an incognito window, or your phone or tablet

Get help

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.

7 - How to perform a content audit

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:

Audit

List current website pages in a spreadsheet by menu section.

• This will give you a visual overview of how your site is structured.
  • Be sure to audit your Drupal Admin back end for unpublished pages that can be removed/deleted!

Review

Visit each page and review content.

• Identify key pages & content types
• Locate content that is outdated, duplicated, needs further review, consolidation etc.
• Find content gaps - what might be missing?
• Identify commonly used page components (i.e. Cards, Carousels, Accordions, Ping Pongs, etc.)

Additional Resources

For more information on content audits, check out these resources:

• Content Audit: A Step-By-Step Guide (MightyBytes)
• Content Inventory and Auditing 101 (Nielsen Norman Group)
• Time to Revamp Your Nonprofit Website’s Content Strategy? 5 Tips to Get Started (ImageX)
• Best Website Audit Tools (Five Jars)

8 - How to set up a Layout Builder site

Install and prepare

1. Install YMCA Website Services 10.3.0 or higher.

• If you are starting a new site, follow the distribution install instructions.
• If you are starting with an internal toolchain, composer require ycloudyusa/yusaopeny at the root of the project.

2. Go to Admin > Configuration > Basic site settings and configure the website name and slogan.

Enable Layout Builder modules

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:

1. To install only selected modules: Go to Admin > Extend (/admin/modules) and enable only the components that you choose to use.
2. To install all the modules: Go to Admin > YMCA Website Services > Extend > Install (/admin/openy/extend/list). Check the box for Layout Builder, then Install.

Configure layouts & listings

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.

Landing 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:

  • Colorway
  • Border style
  • Border radius
  • Text/button alignment
  • Button position
  • Button fill

Locations

You will use the Branch, Camp, and Facility content types to build pages that contain the contact and amenity details for each location.

• For new sites, you may set the Use Layout Builder checkbox to be true by default at /admin/structure/types/manage/branch/fields/node.branch.field_use_layout_builder.
• Configure the default layout and settings for each type on their corresponding layout settings pages:
  • Branch: /admin/structure/types/manage/branch/display
  • Camp: /admin/structure/types/manage/camp/display
  • Facility: /admin/structure/types/manage/facility/display
• Create a locations page with the URL alias /locations using Location Finder.

Events

Enable Events with Layout Builder (ws_event) to use Events with Layout Builder.

• Configure its default layout and settings at admin/structure/types/manage/lb_event/display.
• Create an events listing page with the URL alias /events using Events Views & Filters

Articles

Enable Articles with Layout Builder (y_lb_article) to use Articles with Layout Builder.

• Configure its default layout and settings at /admin/structure/types/manage/article_lb/display.
• Add an article listing page with the URL alias /news using Article Views & Filters.

Activity Finder

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.

Canadian YMCAs

See How to use the Canadian Colorway for Layout Builder.

Configure Permissions

By default (as of September 2024), Layout Builder content is only editable by the Administrator user. In order for Layout Builder to be used by the Contributor or Editor Roles (or any custom roles), a number of permissions must be set. To get started, go to Admin > People > Permissions (/admin/people/permissions).

This list contains the relevant permissions for using Layout Builder in the YMCA Website Services distribution (out of the box). Assign permissions to roles on your site based on your individual content workflows.

• In this Permissions Section…
  • assign these permissions.
• Layout Builder - These permissions allow users to use “layout overrides” (aka the “Layout tab”), which is how pages are composed with Layout Builder.
  • Either give permission for all content types:
    • Configure any layout - will give permission to edit layouts for ALL content types
  • Or give permission to only specific content types:
    • Content - {Content Type}: Configure all layout overrides
  • Create and edit content blocks is required for anyone who needs to build Layout Builder pages.
• Block content - These permissions allow users to create, edit, delete, or revert specific block types.
  • Either give permission for all block types:
    • Administer block content
  • Or, give permissions to only specific block types:
    • {Block type}: {View/Edit/Delete/Revert} content block
• Add other necessary permissions for managing content:
  • Entity Browser
    • Access Media Directories: Field widget pages
    • Access Media Directories: Standalone pages
  • Media Directories UI
    • Access to Media Directories browser
  • Contextual Links
    • Use Contextual Links
• Node - These permissions allow users to create, edit, delete, or revert the Layout Builder content types.
  • Either give permission for all content types:
    • Administer content
  • Or give permission for only specific content types:
    • {Content Type}: {Create/Edit/Delete/Revert} {Own} content
    • For example:
      • Landing Page (Layout Builder): Create new content
      • Landing Page (Layout Builder): Delete any/own content
      • Landing Page (Layout Builder): Edit any/own content

9 - How to set up a site with the Small Y template

What is the Small Y template?

The Small Y template is a set of modules and themes tailored to the needs of Small YMCAs. It is designed to be a lightweight, easy-to-use solution for small organizations that need a simple, effective website.

A full working sandbox of the Small Y template is available at https://small-y-stable.y.org/demo-ui-kit.

What’s different?

New, simplified theme

The Small Y template includes updates to the Layout Builder design system provided by VML in collaboration with the YMCA of the USA. View a mockup of the new theme (Figma).

Only the most essential modules

The Small Y template is built with a small set of modules that are essential for a basic YMCA website. This makes it easier to set up and maintain, and reduces the weight of the site.

Modules and features included with the Small Y template include:

• Updated header and footer
• Layout Builder
• Articles
• Events
• Branches
• Camps
• CKEditor 5 Text Editor

Any other modules or features of the distribution can be added as needed via the Drupal admin interface.

Additions to the main distribution

The Small Y Template provided a number of features back to the main distribution for all YMCA Website Services users to benefit from. These include:

• Partners/Sponsors block now allow for partners to be split into multiple tiers.
• Simple Text/Table block now applies responsive table styles more consistently.
• An additional Utility Menu has been added to the Header to allow content editors to add additional links in the top right of the header.
• Events Listings and Articles Listings have been updated to include a Number of items field to limit the number of items displayed.
• Alerts have a new set of styles that follow the colorway color scheme.

Small Y Specific Features

The Small Y template includes a few additional features that are not included in the main distribution. These are intended to simplify the setup process for small organizations and add guardrails to keep content consistent.

• Limits have been added to the number of items for the main menu and many components.
• Breadcrumbs are now automatically added to all pages.
• Additional variants have been added to the Banner block. Each banner can be used with the colorway color or grey background.
  • Tall - for use as the primary hero banner on a page.
  • Sub-page chevron - for use as a secondary banner on a page.
  • Sub-page chevron (no media) - for use as a secondary banner on a page with no media.
  • Sub-page frame - for use as a secondary banner on a page with dark text on a white background.
  • Promo - for use as a smaller banner on a page with a call to action and no media.

    

• Ping-pong blocks can be added in sections using the Ping-pong Section content block. This allows for alternating content blocks to be added to a page with section-level formatting, instead of block-by-block formatting.
  • When adding a Ping-pong Section, you can choose from two sets of options for the blocks contained within in Styles > Y Styles.
    • Image Alignment - Choose whether the image starts on the left or right.
    • Background colors - Choose between a colorway, white, or grey background for items in the section.

      

• Statistics blocks have been redesigned and have the option to be displayed with a grey or colorway background.
• Grid CTA blocks have their CTA buttons moved between the subheading and the items. Icon Grid blocks have the CTA below the items.

Install the Small Y template

The Small Y template can be installed via the YMCA Website Services Installation wizard or the command line.

• Installation Wizard: The YMCA Website Services Installation wizard is a web-based tool that guides you through the process of setting up a new YMCA website. It includes a step-by-step process for configuring the site.
  • When asked to choose the Installation Type, choose “Small Y” and proceed with the installation steps.
• Command line
  • drush -vy si openy openy_configure_profile.preset=small_y openy_theme_select.theme=openy_carnation openy_terms_of_use.agree_openy_terms=1 install_configure_form.enable_update_status_emails=NULL --account-name=admin --site-name='YMCA Website Services'

Build your site

Once you’ve installed a site with the Small Y template, you can start building your site by adding content and configuring the layout. See How to set up a Layout Builder site.

10 - How to track & analyze user actions

Google Analytics

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

Configuration is done at the standard module configuration page: /admin/config/services/google-analytics.

Google Analytics Version Compatibility

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.

Search Tracking with Google Analytics

Prerequisites

• Google Analytics account to track you site should be created.
• Google Analytics contrib module should be enabled and configured to use existing GA account.

Steps

1. Log in to Google Analytics account that configured to track your YMCA Website Services site.

2. Click Admin button in bottom right corner of main screen

   

3. Click View Settings

   

4. Scroll to “Site Search Settings” section and enable “Site Search Tracking” switch

   

5. Fill query parameter field with q, query values and click Save

6. 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).

Data Layer

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']);
  }
}

Cross-domain Tracking

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.

Requesting cross-domain tracking support

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 _gl parameter.

You may also need to request that your GTM/GA code be added to the CRM/MMS to report back these parameters.

Configuration

1. Enable the “YMCA Website Services Cross-domain Tracking (XDT)” module at Administration > Extend, or via drush:

   drush en openy_xdt
   

2. Configure the module at Administration > YMCA Website Services > Settings > Cross-domain Tracking Settings (/admin/openy/settings/xdt)
   • The cookie defaults to the standard for GA4, but can be modified for use with different systems.
   • The module will not have any effect until a domain is configured. Add the domains of any external sites where you would like to enable tracking.

11 - How to leverage structured data

Adding structured data can enable search results that are more engaging to users and might encourage them to interact more with your website

– Why add structured data to a page (Google)

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.

Articles

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:

• Blog → BlogPosting
• News → NewsArticle
• Press Release → Article (there is currently no other appropriate Schema)

Customizing Articles

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).

Branches

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.

Customizing Branches

The mapping is configurable in the Metatag configuration (/admin/config/search/metatag/node__branch). Hours configuration uses the Open Y Hours_metatag tokens.

FAQs

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:

• Ensure the content contains individual sets of questions (“How old does my child need to be to swim at the YMCA?”) and answers (“The YMCA offers swim classes starting at age 3 and the pool is open to children of all ages with parental supervision”).
• Only one FAQ should be added to a page. If more than one is added, only the first will be output to the structured data.

Customizing FAQs

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.

Other Metatags

The distribution also includes metadata configuration for each content type, which can be found in the Metatag configuration (/admin/config/search/metatag).

Homepage Metatag Overrides

On some sites, the homepage may have unique metadata requirements. The homepage metatags can be overridden in the “Front page” metatag configuration.

For sites that use Layout Builder, it may be necessary to disable the Front Page metatag settings so that the Landing Page (Layout Builder) tags can be used instead.

1. Go to /admin/config/search/metatag/front
2. Scroll to the bottom of the form.
3. Uncheck Active and Save the settings.

Once you have changed the settings, check the metadata of the homepage with a tool like Social Share Preview to ensure the correct data is being output.

12 - How to use the Canadian Colourway for Layout Builder

YMCA of the USA has partnered with YMCA Canada to create a brand-compliant and accessible colourway for use by Canadian YMCAs.

Designs

The colourway is packaged as the Canada Layout Builder Colorway on Drupal.org and is included with the full YMCA Layout Builder package.

• YMCA Canada UI Kit
• YMCA Canada Components
• YMCA Canada Demo Pages

Colourways

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.

Banners

The Canadian Colorway for Banners package contains 4 banner variations that utilize the unique Y Canada chevron:

• Black
• Red
• White
• Short (no image, title and subtitle only)

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.

Setup

Enable the required modules

The ws_colorway_canada module and its submodule lb_hero_canada contain colorways, logos, and banner styles approved by Canadian Y authorities.

• Visit Admin > Extend (admin/modules) and enable these two modules (search for Canad):
  • Layout Builder - Canadian Colorway (ws_colorway_canada)
  • Y Layout Builder - Canada Colorway for Banner (lb_hero_canada)
• Alternatively, enable the modules via drush:

  drush en ws_colorway_canada lb_hero_canada -y
  

Configure site defaults

After enabling the new colorway, there are a few more steps to ensure the new colorways are used across your site:

1. Set the default layout styles to use the Canadian colorway of your choice.
2. For any existing demo content and pages:
   • Set the page colorway to one of the new “Y Canada” options.
   • Change the banner style to one of the new Y Canada Styles.

Hide YUSA Styles

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;
}

13 - How to use two-factor authentication

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.

Requirements

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

Installing

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.