The YMCA Website Services platform is a content management system (CMS) that leverages Drupal’s robust functionality, enhanced with a suite of modules developed by YMCAs and their digital partners. This platform is designed to be both user-friendly and freely accessible, encouraging widespread adoption and collaborative project development within the YMCA community.
History
YMCA Website Services was established in 2016 by a collective of YMCA digital, marketing, and technology professionals who recognized the potential for synergistic digital advancement through community collaboration.
The current core team, comprising Y-USA,
ITCare,
ImageX, and
Five Jars, is responsible for:
Covering the operational costs associated with managing YMCA Website Services.
Maintaining and updating the YMCA Website Services content management system.
Ensuring that all basic functionalities within the CMS remain accessible without charge; contributions are shared freely within the community.
Proactively identifying and addressing issues within the YMCA Website Services CMS.
Disclaimer: The core team is not liable for bugs, crashes, or performance issues affecting the CMS.
Vetting and approving new digital partners to join the community.
Providing training resources for YMCA Website Services Specialists, who are digital partners possessing extensive platform expertise.
Offering certification for YMCA Website Services Integrators, digital partners with the capability to install and directly modify the codebase.
Disseminating information and updates regarding YMCA Website Services.
Organizing community events to foster collaboration and knowledge sharing.
Inspiration
YMCA Website Services draws inspiration from the
Thunder Coalition model used in the publishing industry, adopting similar concepts and content strategies.
Everything you’ve wanted to know about using YMCA Website Services.
These documents are a combination of the former YMCA Website Services Community User Documentation and the
User Manual.
If you see something missing or would like to request a new topic, please
open an issue.
1.1 - Text Editor
Some fields in YMCA Website Services allow you to format your text with a WYSIWYG (What You See Is What You Get) editor. These editors are typically CKEditor 5 instances and provide various text formatting options.
This tool allows you the flexibility to format content however you want within a certain container or area.
Bundled with the Drupal core and the distribution,
CKEditor provides a number of different buttons for styling and formatting, as well as a Source editor if you are so inclined to edit HTML directly.
CKEditor has been
upgraded to version 5 as of Drupal 10 and is a significant improvement over CKEditor 4. The linking experience is much smoother, uploading images is faster, and it offers a more modern user interface.
The specific toolbar configuration may vary depending on the text format being used (e.g., Basic HTML, Full HTML). Here’s a general overview of available features:
Links are simple in YMCA Website Services. Highlight your text, then click the link icon (🔗) in the editor toolbar, or use the keyboard shortcut Ctrl + K (Windows) or Cmd + K (Mac). In the pop-up window, type or paste your URL into the field and click Save.
The link dialog’s Advanced options let you add attributes to links, including a title (tooltip), id, and CSS classes. You can also configure the link to open in a new browser window or tab.
The
Button editor that existed in CKEditor 4 has
changed with CKEditor 5 and Drupal 10. Content editors can now add button classes directly through the Advanced Link Options. This allows for more flexible button styling using
Bootstrap classes.
To create a button:
Create a regular link in a Layout Builder block or Text Editor.
We recommend using custom buttons primarily within larger text blocks, such as those found in the
Table or
Code blocks.
Open the Advanced options for the link.
In the CSS Classes field, add the desired button classes for Color, Size, and Style (see
Button Classes). Always begin with the btn prefix.
For example: btn btn-primary.
Button styles displayed in the editor might not precisely match the final rendered styles on the live site.
Any button’s CSS classes should begin with btn to establish the base button styles.
Choose a button style, such as btn-primary or btn-light.
Generally, button styles should not be combined.
Our theme may override some default Bootstrap styles.
The btn-primary style will adopt the selected colorway’s color. Other styles might use non-compliant colors.
The CSS classes field should contain at least two space-separated items, like btn btn-primary.
It is recommended to experiment with different styles and verify the button’s appearance before saving the page.
Anchor Links
For long landing pages, anchor links (also known as “in-page” links or
URI fragments) allow users to jump directly to specific sections.
The process consists of two steps:
Adding an in-page anchor.
Creating a link to that anchor.
Adding an Anchor
An anchor is a point on the page designated with an id attribute in its code. The easiest way to create an anchor is to add a small, hidden link at the beginning of the target section.
Edit the section where you want to add the anchor.
Insert an empty space at the end of the section’s first line.
Select only that space, and click the 🔗 button in the editor toolbar.
In the Link popup, set the URL to #.
Expand the Advanced options and set the ID field to a short, descriptive name containing only lowercase letters and dashes (e.g., thank-you or adding-an-anchor).
Click Save in the Link popup, then save the page.
After saving, you can test the anchor by appending #anchor-id to your page URL. For example:
Entering this URL in your browser should navigate directly to the “Adding an Anchor” section.
Linking to the Anchor
To create a link to the anchor:
Create an in-page link using the Link field or the Text Editor as you normally would.
Instead of using autocomplete (if available), use the “relative path” of the page—everything after the domain. For example, to link to this page, use /docs/user-documentation/text-editor/adding-links.
Append the anchor ID to the path, so the complete link looks like /docs/user-documentation/text-editor/adding-links#adding-an-anchor.
Save the page.
The internal link should now direct users to the specified location within the page.
Tip: If the anchor doesn’t position the section correctly, or the navigation obscures the linked section, try moving the anchor to the end of the preceding section. This ensures the target section is fully visible.
Linking Tips
Internal Links: Use relative paths. Omit everything before the first / after your domain (e.g., .com, .org). For ymca.org/about, use /about. This improves analytics tracking.
External Links: Use the complete URL, including https:// (e.g., https://example.org/about).
Email Links: Use the format mailto:example@example.org.
To update a link, click the linked text, then click the link icon, or use the popup options (in CKEditor 5).
To remove a link, highlight the linked text and click the unlink icon.
provides an autocomplete interface for internal and external linking in rich-text editors. Linkit supports nodes, users, taxonomy terms, files, comments and basic support for all types of entities that define a canonical link template.
Once your site is updated to use CKEditor 5 you will see a new Insert Media button that unifies the processes for embedding Images, Documents, and Videos.
Add or select media
To get started, click Insert Media in the CKEditor toolbar (or try the ⋮ button if it’s hidden). You will be presented with the Add or select media dialog.
Choose the media type (Image, Document, etc.) that you would like to embed from the list on the left.
Add or upload your media:
If you are adding new media:
If given the option, drag and drop the item from your filesystem to the dialog, or click Select File.
For Video (via YouTube or Vimeo), add the video directly via Admin > Content > Media > Add Media > Video before opening the dialog.
If you are reusing media that exists on the site, scroll down and search for the item, then click the checkbox to select it.
Choose Insert selected to embed the chosen media.
Customizing your media
Once your media has been inserted into the field, you can hover over the media to choose from a variety of options.
Toggle caption on
Displays a Caption area below your image. Once toggled, type your caption below the image.
Link media
Allows the media to be linked. See
Adding Links for more information.
Allows you to select the size of the image. Typically you might choose “Full”, “Half”, or “Thumbnail”. Options may vary depending on site configuration.
Alignment
Choose how to align the media:
Break text
Align left and wrap text
Align center and break text
Align right and wrap text
Moving your media
Click and drag anywhere on the inserted media to relocate it in the WYSIWYG area.
Use the ⮐ button at the top or bottom of the media to insert a paragraph before or after it.
Deleting your media
Click to select the media, then type Delete to remove it.
1.1.3 - Basic Text Formatting
Choose any of the options for your text below by clicking on the icon or performing the keyboard shortcut indicated. To format text you’ve previously typed, highlight the text and then click on the button in the editor. Many formatting options also have
keyboard shortcuts.
Heading - Set paragraphs or heading levels—headings in your content
should be ordered sequentially for the best accessibility.
Code Block - For inserting multi-line code snippets. Supports syntax highlighting for various languages (Plain text, C, C#, C++, CSS, Diff, HTML, Java, JavaScript, PHP, Python, Ruby, TypeScript, XML).
Source - View or edit the source code of the content. Be aware that some HTML tags may be stripped out due to Drupal’s Text Format rules. Click About text formats below the editor to learn more.
Bold Text - Ctrl+B (Windows) or Command (⌘)+B (Mac) or clicking/unclicking the B icon
Italics -Ctrl+I (Windows) or Command (⌘)+I (Mac) or clicking/unclicking the I icon
Underline -Ctrl+U (Windows) or Command (⌘)+U (Mac)or clicking/unclicking the U icon
Strikethrough - Clicking/unclicking the S icon
Alignment controls - Left, Center, Right, and Justify.
Font Color - A small grid of swatches you can apply to your text. Overrides the default font-color
Text Background color (not recommended)
Font (should remain Cachet or Verdana to conform to YMCA brand standards)
Font Size - A dropdown to select the size of your text. Measured in points, not pixels. Overrides the default font size for your text, including styles and format.
Indent - Add one or more indents to your copy. Also, have the option to undo the indent.
Format - A dropdown list of text formats you can apply to your content. Helps to create sections. Comes out-of-the-box with six heading formats.
Most Ys will not use the “Formatted” format, which styles text like HTML code.
Bulleted/Numbered lists - Click the numbered or bulleted list icon to create a list. You can create indented bullets by hitting your tab key or clicking on the indent icon
1.1.4 - Building Buttons
This document applies to the legacy WYSIWYG editor, CKEditor 4. See the
Using Button Classes for updated instructions on creating buttons using CSS classes in the current editor.
As an alternative to using the link tool, you can create buttons with YMCA Website Services using the button editor in CKEditor 4. When you click the button icon, a pop-up window will appear.
You can also edit a button you’ve created previously by clicking on the link within the text editor.
The button editor has three tabs: Info, Target, and Icons.
Info Tab
This tab provides basic styling options for your button or link. The Style Option dropdown menu in the top-left corner allows you to style your button or output it as a plain link.
Link: Embeds your link text inline within a paragraph.
Button Styles: The appearance of the button styles depends on your website’s theme:
Lily: All button styles other than “Link” default to purple.
Rose: All options except “Default” will output a blue button. “Default” outputs a white button.
Carnation: The button options all output different colors.
Button Style Guide Example:
@mlefler From the YMCA of Lincoln, NE,
built this guide to provide examples of possible styles for buttons. Consult your developer or designer for a style guide specific to your YMCA website.
The Size dropdown menu in the top-right corner offers four options for your button size. If you select the “Link” style option, the Size option will not affect your link’s appearance.
Add the text for your link/button in the bottom-left Text field. Enter the destination URL in the URL field on the bottom right.
Internal Links (links within your website): Use a relative path, starting with a / after your domain.
For example, to link to example.org/about, enter /about. This is called a relative path and helps with analytics tracking.
External Links (links to other websites): Use the full URL, including https://.
For example, to link to example.org/about, enter https://example.org/about.
Email Links: Use the mailto: prefix followed by the email address.
This tab allows you to control the link’s behavior when clicked. By default, all links have a “Not Set” behavior, which means the link opens in the same tab. The other options include:
You can add icons to your buttons or links using the Icons tab. Use the Left Icon and Right Icon text fields to integrate icons from the Font Awesome library.
Example: To display a right-facing chevron, type fa-chevron-right in the Right Icon text field.
Note: The left fields reference the Bootstrap Glyphicons library. This icon library has been deprecated, and the Glyphicons fields will not function correctly in YMCA Website Services. These fields will be removed once the code is updated by the tool’s maintainer.
1.1.5 - Building Tables
Display contact information, pricing tables, and more using flexible, responsive tables.
Tables in CKEditor 5
The table editor has been drastically improved in CKEditor 5 and is described in detail
in their documentation.
Adding a New Table
To add a table, click on the table icon in the toolbar. A grid will appear, allowing you to select the desired number of rows and columns.
Alternatively, you can use the dropdown menu to insert a table. This option might offer more advanced configurations and properties directly upon insertion.
Table Properties
To adjust the table’s overall appearance and structure, access the “Table Properties” option. This can usually be found by right-clicking on the table.
The properties dialog typically allows you to configure:
Dimensions: Setting the number of rows and columns.
Width & Height: Defining the table’s size. You can specify these in pixels or percentages. Percentages are generally recommended for responsive layouts.
Borders: Adjusting the border size, style, and color.
Background: Changing the background color of the table.
Alignment: Positioning the table within the content.
Caption: Adding a descriptive caption that appears above or below the table.
Summary: Providing a brief description for screen readers to enhance accessibility.
Editing the Table
To edit a table after you’ve built one, right-click on the table to bring up a contextual menu with options such as:
Table Properties: Opens the table properties dialog.
Row: Options to insert, delete, or manage rows.
Column: Options to insert, delete, or manage columns.
Cell: Options to insert, delete, merge, split, or manage individual cells.
You can also double-click inside a table cell to edit its content.
Adding Rows/Columns
To add a row or column, right-click on the table and navigate to either “Row” or “Column” in the options that appear. You can insert a row or column before or after the current row/column.
Deleting Rows/Columns
Both the row and column options allow you to delete from the right-click menu as well. Just right-click > Row or Column > Delete Row OR Delete Column.
To delete multiple rows or columns, just highlight the rows or columns you want to delete and then right-click and select the delete option.
Formatting Individual Cells/Groups of Cells
The “Cell” option from the right-click menu gives you same options as Row and Column, including inserting cells and deleting cells. You can also merge cells or split cells as you would in an excel table by selecting those options from the right-click menu.
Cell Properties
The “Cell Properties” option allows you to style your cells. Just right-click > Cell > Cell Properties.
This opens a dialogue box similar to the table properties. You can set the width/height for your cell (pixels only for height; pixels or percentages for your width) in the fields on the left.
Text Wrapping: Choose from a dropdown whether or not to wrap the text in a cell.
Alignment: Use dropdowns to set your vertical and horizontal alignments for your cells.
Colors: Set your border and background colors for your cells. These field support hexadecimal (#FFF) and rgba (256,256,256,1.0) color formats.
Span: Edit your cells to “span” two or more rows or columns. For example, if you have a header cell you want to span two columns, you can set the “Columns Span” field to 2.
If you would like to apply these styling options to multiple cells, just highlight the cells you want to edit and Right-Click > Cell > Cell Properties.
Table Examples
To see an example of what a table might look like on your site, open the “Source” tab on your text editor and insert the HTML. You can then edit the content inside using the WYSIWYG text editor.
Pricing Table
<h2>Registration and Pricing</h2><tablealign="left"border="1"cellpadding="5"cellspacing="1"style="width: 500px;"><caption>*A $25 deposit is due at the time of registration.</caption><thead><tr><thscope="col">Pricing Period</th><thscope="col">Dates</th><thscope="col">Member Pricing</th><thscope="col">Non-Member Pricing</th></tr></thead><tbody><tr><td>Early Registration</td><td>Feb. 1-29</td><td>$120/week</td><td>$135/week</td></tr><tr><td>Regular Registration</td><td>March 1-May 1</td><td>$130/week</td><td>$150/week</td></tr><tr><td>Late Registration</td><td>May 1-End of Summer</td><td>$150/week</td><td>$175/week</td></tr></tbody></table>
Camp Locations
<style>/* To achieve the full effect of this table, insert this style tag above the table or insert it into the CSS Editor module. *//* margin fix for h6 embedded inside table */td>h6{margin-bottom:0;}/* Fix for mobile table -> issue seems to be related to aggregate CSS file */.field-answertr,.field-answertd,.paragraph--type--simple-contenttr,.paragraph--type--simple-contenttd{display:block!important;border:none;}.field-answertd,.paragraph--type--simple-contenttd{padding:.75rem.31rem;text-align:left;vertical-align:middle;}.field-answertr,.paragraph--type--simple-contenttr{padding:.625rem0;}.field-answerthead,.paragraph--type--simple-contentthead{display:none;}@media(min-width:992px){.field-answertr,.paragraph--type--simple-contenttr{display:table-row!important;}.field-answertd,.paragraph--type--simple-contenttd{display:table-cell!important;}.field-answerthead,.paragraph--type--simple-contentthead{display:table-header-group;}}</style><divclass="table-responsive"><tablealign="left"cellpadding="10"cellspacing="10"class="w-100 table table-striped"><thead><tr><thscope="col"><h5>Center</h5></th><thscope="col"><h5>Address</h5></th><thscope="col"><h5>Contact</h5></th><thscope="col"><h5>Schedule (PDF)</h5></th><thscope="col"> </th></tr></thead><tbody><tr><td><h5>Bellevue</h5></td><td>8101 TN-100<br/> Nashville, TN 37221</td><td><ahref="tel:615-646-9622">615-646-9622</a></td><td><p><ahref="/sites/default/files/2020-01/dycmp-20-dycmp-pdf-bellevue-menu.pdf"><iclass="far fa-file-pdf"> </i>Print Info</a></p></td><td><strong><aclass="btn btn-outline-primary"href="https://operations.daxko.com/Online/4002/ProgramsV2/Search.mvc?program_id=TMP8151&location_ids=B58&category_ids=TAG12062">Register ></a></strong></td></tr><tr><td><h5>Brentwood</h5></td><td>8207 Concord Rd.<br/> Brentwood, TN 37027</td><td><ahref="tel:615-373-9622">615-373-9622</a></td><td><ahref="/sites/default/files/2020-01/dycmp-20-dycmp-pdf-brentwood-menu.pdf"><iclass="far fa-file-pdf"> </i>Print Info</a></td><td><strong><aclass="btn btn-outline-primary"href="https://operations.daxko.com/Online/4002/ProgramsV2/Search.mvc?program_id=TMP8151&location_ids=B45&category_ids=TAG12062">Register ></a></strong></td></tr><tr><td><h5>Clarksville</h5></td><td>260 Hillcrest Dr.<br/> Clarksville, TN 37043</td><td><ahref="tel:931-647-2376">931-647-2376</a></td><td><ahref="/sites/default/files/2020-01/dycmp-20-dycmp-pdf-clarksville-menu.pdf"><iclass="far fa-file-pdf"> </i>Print Info</a></td><td><strong><aclass="btn btn-outline-primary"href="https://operations.daxko.com/Online/4002/ProgramsV2/Search.mvc?program_id=TMP8151&location_ids=B54&category_ids=TAG12062">Register ></a></strong></td></tr><tr><td><h5>Donelson</h5></td><td>3001 Lebanon Pike<br/> Nashville, TN 37214</td><td><ahref="tel:615-889-2632">615-889-2632</a></td><td><ahref="/sites/default/files/2020-01/dycmp-20-dycmp-pdf-donelson-menu.pdf"><iclass="far fa-file-pdf"> </i>Print Info</a></td><td><strong><aclass="btn btn-outline-primary"href="https://operations.daxko.com/Online/4002/ProgramsV2/Search.mvc?program_id=TMP8151&location_ids=B41&category_ids=TAG12062">Register ></a></strong></td></tr><tr><td><h5><a>Franklin</a></h5></td><td>501 S Royal Oaks Blvd.<br/> Franklin, TN 37064</td><td><ahref="tel:615-591-0322">615-591-0322</a></td><td><ahref="/sites/default/files/2020-01/dycmp-20-dycmp-pdf-franklin-menu.pdf"><iclass="far fa-file-pdf"> </i>Print Info</a></td><td><strong><aclass="btn btn-outline-primary"href="https://operations.daxko.com/Online/4002/ProgramsV2/Search.mvc?program_id=TMP8151&location_ids=B53&category_ids=TAG12062">Register ></a></strong></td></tr></tbody></table>
1.1.6 - CKEditor 4: Adding and Embedding Videos
This document applies to the legacy WYSIWYG editor, CKEditor 4. See
Adding Media for updated instructions on using the CKEditor 5 media embedding features.
Adding/Embedding Videos with the YMCA Website Services Text Editor
YMCA Website Services allows you to upload and embed videos directly into a block of text, either from a supported external source (like YouTube or Vimeo) by pasting the video URL or from the YMCA Website Services media library.
Adding Videos from an External Source
Click the Embed media button (usually a filmstrip icon) in the text editor toolbar.
In the Source URL field, paste the URL of the video you want to embed.
Hit Save to embed the video. The editor will automatically generate a preview of the video.
Adding Videos from the Media Library
Click the Media button (if available, may look like an image icon or filmstrip) in the text editor toolbar.
In the Media library popup, select the video you want to embed.
(Optional) Configure the video’s display settings.
Click Embed or Insert to add the video to your content.
Configuring Video Display Options
After embedding your video, you may be able to adjust additional options. Note: These options depend on the configuration of your specific YMCA Website Services instance and may not all be available.
Entity Name: This field displays the name of your video.
Display as: This setting controls the size and appearance of the video within your content area. Available options might include:
Full: The video will fill the width of its container.
Half: The video will take up half the width of its container.
Link: The video will be displayed as a text link to the video file.
Link to: This option wraps the video in a link, allowing you to specify a destination URL that users will be directed to when they click on the video.
Align: Use this setting to float the video to the left, right, or center of the page, allowing text to wrap around it.
Caption: Adds a descriptive caption below the video.
When you are satisfied with the video’s settings, click Embed.
If you want to make changes to the video you just embedded after you’ve added it, double click on the video placeholder in the editor, and the “Embed media” dialogue will appear.
1.1.7 - CKEditor 4: Adding Images
This document applies to the legacy WYSIWYG editor, CKEditor 4. See
Adding Media for updated instructions on using the CKEditor 5 media embedding tool.
Adding Images with the YMCA Website Services Text Editor
YMCA Website Services allows you to upload and embed images directly into a block of text, either from your computer or from the YMCA Website Services media library.
Uploading Images
To add an image, click on the image button in the text editor toolbar.
Make sure you’re on the “Upload Images” tab.
Next, either drag your image into the upload area or click the button to select an image from your library.
Name your image, tag it, and write your alt description.
Hit “Save” to go through to the next step.
Adding Images from the Media Library
To add an image from the library, click on the image icon in the text editor toolbar.
Next, click on the tab that says “All Images”
Name your image, tag it, and write your alt description.
Hit “Save” to go through to the next step.
Sizing and Floating Your Images
After you save your image to the media library, a dialogue box will appear, giving you some additional options for embedding your image inline.
Entity Name simply refers to the name of your image, which you provided on the previous screen.
Display as allows you to change the size of the image display without affecting the size of the original image. By default, YMCA Website Services comes with Full, Half, and Link display modes.
Full means your image fills the area where it’s inserted.
Half means the picture is half the size of its area.
Link outputs the image as a simple link to the picture.
Link to wraps the image in a link so that when users click on it, it goes to another page.
Align allows you to float an image to the center or either side of the page.
Caption outputs a caption below the image.
When you’re ready to embed the image, just click “Embed.” You can also click the back button on the bottom to choose a different image.
If you want to make changes to the image you just embedded after you’ve added it, double click on the icon, and the “Embed media” dialogue will appear.
This document applies to the legacy WYSIWYG editor, CKEditor 4. See
Adding Media for updated instructions using CKEditor 5.
YMCA Website Services allows you to upload and embed documents directly into a block of text, either from your computer or from the YMCA Website Services media library and browser.
## Adding Documents
* To add a document, click on the document button (usually represented by a paperclip or document icon) in the text editor toolbar.
* Make sure you're on the *"Add Document"* or *"Upload"* tab.
* Next, name your document.
* Paste the document URL into the appropriate field, or upload the document from your computer.
* Hit "Save" to proceed.
## Adding Documents from the Media Library
* To add a document from the media library, click on the document icon in the text editor toolbar.
* Next, click on the tab that says *"Media Library"* or *"All Documents"*.
* Select the desired document from the library.
* Name your document, tag it, and write your alt description as needed.
* Hit "Save" to proceed.
## Sizing and Floating Your Document
After you save your document to the media library, a dialogue box will appear, giving you some additional options for embedding it inline. These options may vary depending on your specific configuration. Common options include:
***Entity Name:** This is simply the name of your document, which you provided earlier.
***Display as:** This option allows you to change the size or format of the document display without affecting the original document. By default, YMCA Website Services may offer *Full, Half, and Link* display modes:
***Full:** Your document fills the available area where it's inserted.
***Half:** The document is displayed at half the size of its available area.
***Link:** The document is output as a simple text link to the document file.
***Link to:** This option wraps the document (or the link, if "Display as Link" is selected) in a hyperlink. When users click on the document, they will be directed to the specified URL.
***Align:** This allows you to float the document to the left, center, or right of the page.
***Caption:** This option adds a descriptive caption below the embedded document or link.
When you're ready to embed the document, click "Embed." You can also click the back button to choose a different document.
> *If you want to make changes to the document you just embedded after you've added it, double click on the icon, and the "Embed media" dialogue will appear. Note that the exact wording of the dialogue box may vary.*
1.2 - Page/Content Types
YMCA Website Services features many different kinds of pages, or content types. Choosing the right content type will ensure you collect the right information and allow you the flexibility to create layouts.
A content type is a reusable container for content, defining its structure and purpose. Utilizing content types supports consistent site architecture and content presentation, helping users efficiently find what they need. In Drupal terminology, content types are entity sub-types for the “Content item” entity type, allowing each content type to have its own fields and display settings.
There are two main categories of Content Types in the YMCA Website Services distribution:
Standalone types: These content types are designed to be displayed directly to users as individual pages. Examples include Landing Pages and Branches. They can also be displayed in views or other groupings.
Helper types: These content types are not typically displayed on their own. Instead, they are used to support applications or to display aggregated information, such as within the Activity Finder or Membership Calculator.
Most sites utilize a combination of these content types. The appropriate content type depends on how the content will be used and displayed. While Landing Pages often constitute the majority of a site’s content, other types like Events, Articles, and Branches may be necessary to achieve specific site goals.
Choosing the Right Content Type
Before building your site, identify the types of content you’ll be creating. A
content audit can help you understand your existing content and identify what new content needs to be developed.
Landing Pages are often the starting point for site construction due to their flexibility. They can accommodate a wide range of content.
Location pages, such as Branches and Camps, are also important for promoting individual locations.
Supporting content types like Events and Articles provide timely information to users.
Standalone Content Types
These content types are designed for use with Layout Builder or are compatible with Layout Builder when the supporting module is enabled:
The Article content type combines news-related content into a single content type, offering flexible layout options with Layout Builder.
The Article content type allows content editors to create various news-related content such as news items, blog posts, and press releases using a single content type. Editors can customize the layout and display of these articles based on their type, enabling them to show news items on a dedicated news page and blog posts on a blog page.
The Article content type also allows content editors to incorporate Layout Builder components directly within the page, providing enhanced control over content presentation.
Go to Admin > Content > Add Content > Article (Layout Builder).
Fill in the content fields:
Title (required): The title of the article.
Subtitle: An optional subtitle to provide additional context.
Type: Select “Blog”, “News”, or “Press Release”. Each type uses the same fields but enables administrators to group articles for display on different pages (e.g., Blog types on a Blog page, Press Releases on a Press Release page).
Header image: This image displays on the Article page and in listing views.
Tags: References terms from the Tags vocabulary. See
Taxonomy for more information. Tags provide a way to categorize and organize content.
Body (required): Add the main text of the article using the
WYSIWYG editor. The WYSIWYG editor allows for rich text formatting.
Locations: If the Article relates to a specific
Branch, select it here. This will display the Article in listings on the Branch page.
Published Date (required): Defaults to today’s date. This date displays on the Article page and is used for sorting and in listings.
Customizing Articles
After creating an Article, you can customize its layout using
Layout Builder. The following components are designed to work specifically with the Article content type:
Related Articles: Displays a list of related articles based on predefined criteria.
1.2.2 - Event (Layout Builder)
Updated Event content type that allows for Layout Builder components to be included within an event page.
Go to Admin > Content > Add Content > Event (Layout Builder)
Fill in the content fields:
Title (required)
Subtitle
Location info: Select the event location either by choosing from your list of locations or adding the address manually. You must either fill out the Event location OR Address fields.
Event Location: A list of Branch, Camp, and Facilities. Select any number of these.
Address: If your event does not happen at an existing location, you can add the address directly. Any content in this field will cause the Event Location to be overridden. To clear out the field, reset Country to “- None -”.
Directions: By default, a link with directions is auto-generated using the address field of either the Event Location or Address. Use this field to substitute your own directions link. You can substitute your own directions link in this field if desired.
Event Date(s): Add a start and end date and time for the event. If the event does not have an end time, choose the start time for both the start and end.
As of March 2023, this field supports recurring events.
To create a recurring event:
Set the Repeats option.
Choose the Number of recurrences and when to End.
Expand the Advanced options to select specific days.
Once you save the event, Manage Instance will allow you to customize or remove individual instances.
To select multiple dates for your event that do not fit a regular rule, use Add another item below the date selector.
Header image: This image is displayed on the Event page and in listing views.
Tags: References terms in the Tags vocabulary. See
Taxonomy for more information on tags.
Locations: If the event relates to a
Branch then select it here so that the event shows in listings on the Branch page.
Customizing Events
Once you create an Event you can customize the layout with
Layout Builder. These components are built specifically to work with the Event content type:
Format data from third parties (e.g. Daxko, Personify, or ActiveNet), for display in Activity Finder.
Content editors rarely, if ever, enter information directly into these content types on a day-to-day basis. However, it is important to know how they work and how they relate to manually-entered content.
Example - Swim Lessons
Swimming and Aquatics (Program Page, manually entered)
Youth Group Swim Lessons (Activity, mapped from CRM or custom automation)
Stage 3 (Class, mapped from CRM)
Monday/Wednesday/Friday 9:30-10 a.m. at Franklin Family YMCA (Session, mapped from CRM)
Note: This is an example only. Depending on your CRM and any customizations you make, your setup for Swim Lessons or any program may look different that the example listed above.
Activity
Often used as the top-level filter in Activity Finder and Repeat Schedules, Activity consists of the following fields:
Title: The name of the Activity (and the filter in Activity Finder).
Program subcategory: An entity reference to or tag for a
Program Subcategory. Maps the Activity to higher levels of user-entered content.
Description: A description for the Activity. Usually pulled from a description in a CRM through an API.
Class
A narrower selection of Program Offerings. Not an individual instance, but a smaller selection of instances.
Classes have three fields that map into Activity Finder and Repeat Schedules: a description, a title, and entity reference/tag to an Activity.
Class also contains Areas for content editors to add paragraphs; however, depending on how your CRM and the number of programs your Y runs, it may not be practical to use these fields.
Session
An individual program offering. Contains fields for pricing, session date/time, instructor, ages, and a registration link. These are the individual rows/instances in Repeat Schedules and
Activity Finder.
1.2.4 - Alert
Displays timely information in a thin banner across your site, just below the header or above the footer.
Unlike most content types in YMCA Website Services, you don’t use Alert to create pages. Instead, Alerts display as a rendered entity or a section of content on other pages.
Alerts also don’t use Paragraphs or Layout Builder. By design, the layout of Alerts is rigid; however, the text editor and the color options listed below allow content editors some flexibility.
When Should You Use an Alert?
Timely updates for centers, such as when your hours change or facilities close.
Marketing promotions, such as for membership campaigns or even promotions.
How to Use an Alert
Go to Admin > Content > Add Content > Alert (/node/add/alert).
Title: Displays as the headline for your alert.
Description: The main body of your alert. Sentences should be short and minimally styled in this section. Uses
the Text Editor.
Alert Style: Choose from the Classic Alert style which enables the Color Fields below or a set of styles that are pre-configured for you to match the YMCA colorways.
Urgent options use a colored background with dark or light text.
Info options use a grey background with colored text.
Color Fields: These three dropdown fields control different aspects of color in your alert. All three dropdowns reference the
color vocabulary.
Background Color: The color of your alert.
Text Color: Stick to using either black or white for accessibility.
Icon Color: Changes the appearance of the icon to the left of the title.
Link: Adds a button with a call to action to the alert on the right. The button color defaults to black.
Placement: Choose “Header” to show your alert above your main content or “Footer” to show below your main content.
Setting Visibility
Visibility pages: This is where you control where the alert displays on your site. In the large text field, you write the relative path of the pages where you want this to appear or not appear. Enter each path on a new line. Each path should start with a slash, /.
You also have the option to use an asterisk character * as a wildcard so you don’t have to enter a large number of relative paths. For example, if you wanted to add an alert to a /health-and-fitness section, you would enter /health-and-fitness* in the text area.
What is a relative path?
A relative path is the part of your URL after your domain name.
At https://example.com/community, for example, the domain name is example.com, while the relative path is /community.
Using the Alert visibility state radio buttons at the bottom, you can either show or hide your alert from the page paths listed in the text area above.
Location: This field provides additional flexibility for controlling where the Alert will display. Selecting a Location from this field will display the alert on the Location page and any related page (blog posts, news, landing pages) that has the corresponding Location selected.
Rearranging Alerts
Alerts can be rearranged to control the order in which they display if multiple appear on a page. The Alerts Rearrange page can be accessed via its link on the Content page or at Admin > Content > Alerts Rearrange (/admin/content/alerts-rearrange). The link might not appear in the Admin menu prior to version 10.3.1.
To rearrange alerts:
Go to the Alerts Rearrange page
Rearrange alerts with the drag handle () or the “Show row weights” option.
Save order when finished.
Alert Visibility Examples
Figuring out exactly how to show an alert on the right pages can be a challenge. The Visibility pages, Alert visibility state, and Location selectors work together to control where an alert is displayed. Here are some tips on how to get just what you want.
Related to a Location
To show an alert only on a single Location page:
Visibility pages: add the path to the Location, like /locations/downtown-ymca
Alert visibility state: “Show for the listed pages”
Location: “None”
To show an alert on a location and any related pages:
Visibility pages: Leave this field blank.
Alert visibility state: Select “Show for the listed pages.”
Location: select the Location, or select more than one using Shift or Command/Ctrl.
“Related pages” in this case means any page with a specific location selected in its Location field.
On Groups of Pages
The wildcard * can be used to specify any page in a section of the site.
To show an alert on every page on the site:
Visibility pages: *
Alert visibility state: “Show for the listed pages”
Location: “None”
To show an alert on every swimming page:
Visibility pages: /programs/swimming*
Alert visibility state: “Show for the listed pages”
Location: “None”
The position of the * wildcard is important. Consider /programs/swimming* versus /programs/swimming/*:
Show for /programs/swimming*:
✅/programs/swimming
✅/programs/swimming/drop-in
✅/programs/swimming/swim-lessons
Show for /programs/swimming/*:
❌/programs/swimming
✅/programs/swimming/drop-in
✅/programs/swimming/swim-lessons
On the Home Page
You can use / OR <front> to show an alert on the home page. <front> is a special token and should always be listed on its own line.
Visibility pages: / OR <front>
Alert visibility state: “Show for the listed pages”
Location: “None”
With Exceptions
Sometimes you want to show an alert on all pages except a few. Maybe you have an alert for a fundraising campaign but don’t want to show it on the “Join” or the “Give” page. The Hide for the listed pages option can help in this case.
To show an alert on all pages except “Join” and “Give”:
Visibility pages:
/join
/give
Alert visibility state: “Hide for the listed pages”
Location: “None”
1.2.5 - Blog Post
Timely content, articles, and news pieces tagged with one or more physical locations.
Blog posts in YMCA Website Services allow you the flexibility to create simple posts using only the text editor or more robust layouts with paragraphs. Blog posts utilize a two-column layout, with the content area on the left and the sidebar area on the right.
When Should I Use a Blog Post?
When you decide to use a blog post
depends greatly on your Association’s content strategy. However, blog posts are designed for publishing timely content and listing them throughout your site. Examples of blog posts may include:
Member Stories
Workouts and Recipes
Updates about a Center/Branch
Promotions and Contests
Press Releases
How Do I Use a Blog Post?
There are three fields that appear above the accordion tabs:
Locations: An option select field to tag a post with one or more locations (Camp or Branch). Use Ctrl+Click (Windows) or Cmd⌘+Click (Mac) to select multiple locations.
Each time you create a new Branch Page or Camp Page, it automatically populates into the locations field.
Category: An entity reference to
the Blog Category vocabulary. Type in the name of the category and select from the options that appear, or create a new category/term by typing in a new one.
Style
This dropdown changes the style of the post’s card when it appears in a listing format. This dropdown does not affect any layouts on the page itself.
Story Card
Carnation
Lily
Photo Card
Carnation
Lily
News Card
Color Card
When choosing the Color Card style, you are presented with two styling options in dropdowns. Both are entity references to
the Color vocabulary:
Background color: Changes the color of the card’s background.
Text color: Changes the color of the text. It’s recommended you only use white or black for optimal readability.
Carnation
Lily
Content Area
The content area is the main body of your page. You can use the default fields or build a more robust layout using paragraphs. The content area displays on the left side of the page.
Image: Displays above your description and inside a Photo Card. This field is optional. It uses the
media browser and image field.
Description: You can enter a brief summary or the entire body of your text by
using the text editor.
Sidebar Area
The sidebar area allows you to embed paragraphs below a section that links to the centers tagged in the post, the categories, and a Related Content field. The Related Content field allows you to promote other Blog Posts by tagging them with the autocomplete widget. The sidebar area displays on the right side of the page.
Layouts
Blog posts utilize a two-column layout. The Content Area displays on the left, while the Sidebar Area displays on the right. You can build layouts within these areas using paragraphs.
1.2.6 - Branch
One of the first places members go when they visit a Y website is to their local Y’s page.
Branch pages contain multiple data fields that work together to help members find the right location, hours, and amenities that fit their needs.
Title (required): This is the name of your branch which will display as your page title and the title on the location card. If your branch has a longer formal name we recommend using the shorter, more common name for readability.
Neighborhood: An optional reference to specify which neighborhood your Y is located in. Start typing and select from the list. To add a new neighborhood, add it to the “Area” vocabulary under Structure > Taxonomy (see
Taxonomy).
Coming Soon: This flag indicates a newly opening branch on the Locations page.
Temporary URL: Overrides the “Branch info” link on the Locations page, allowing you to link to a different internal or external page.
Contact Info
Address: The physical address of your location. Be sure to include all address fields.
Branch Coordinates (required): This field pins your branch on the locations map.
To copy the coordinates, left-click on the latitude and longitude.
Paste the lat, long into one of the fields, then cut and paste to separate them.
Phone (required): The main phone line for your branch. Will be displayed as it is entered and linked to allow mobile users to tap to call.
Fax: Optional.
Email: We recommend you use a main contact email, such as info@example.com, rather than the email for an individual staff member.
Directions: By default, a link with directions is auto-generated using the Address field. Use this field to substitute your own directions link.
Branch Hours
Add the main hours for your facility. These are displayed in the header and on the Locations page.
Custom hours label: The title that is displayed in the “All hours” dropdown. Clearing this field will hide the section from the Branch page.
Mon, Tue, …: Add the hours for each day of the current week.
Most formatting like <open time> <separator> <end time> should work, but we recommend something like 7am-5pm
Leaving a day empty will show the hours as “Closed” but you can enter any other text as well, like “Wednesday: ‘Temporarily closed’”
Branch Holiday Hours: Add special hours for any upcoming holidays. These will be displayed on the site when the holiday is less than two weeks away. Add as many holiday entries as you like.
Holiday Title: The displayed title of the holiday.
Holiday Hours: The displayed hours for the holiday.
Date: The date of the holiday. When this day is in the current week …
More Hours Link: A link to show additional location hours information, like another page or a PDF.
Header Area
This section is not displayed when “Use Layout Builder” is selected.
There is no image field for the Branch content type, so you will need to add one of the following paragraphs to add an image and title at the top of your page:
Type in and select which amenities are available or not available at your branch using the autocomplete field.
If you embed a Branch Amenities with the Icons paragraph or Branch Amenities block on your page, the amenities will be displayed in your content. The Amenities will also serve as filters for branches on your locations page.
If you don’t see an option available or would like to rename a branch amenity, go to Structure > Taxonomy > Amenities. See
Taxonomy for more info.
Menu
The Branch Menu is a single-level sub-menu that displays within a branch page (and sub-pages) that allows users to drill down to additional content specific to that branch. The Branch Menu always shows “Branch Home” as its first link.
Menu links: A list of menu links to be displayed in the menu. Allows unlimited items but we recommend a maximum of 6-8 depending on the Link text length.
Customizing with Layout Builder
Beginning in
Website Services 9.2.13 content editors have the option of customizing the Branch page with
Layout Builder. You can migrate from using Paragraphs to using Layout Builder on a branch-by-branch basis to ease the transition.
The Use Layout Builder checkbox on the Branch edit page non-destructively switches between Paragraphs and Layout Builder. If the checkbox does not appear, ensure the Y Branch (y_branch) module is installed at Admin > Extend (/admin/modules).
Layout Builder Blocks
Branch pages have several specialized components that utilize the structured data (fields) that already exist on your branch page in newly designed Layout Builder Blocks.
In addition to using many of the standard Layout Builder components, Branch pages also use several components that display the fields described above.
These blocks are available via All system blocks in Layout Builder:
Branch Hours: Combines the branch title, contact information, hours, and more into a dynamic page header.
Can be placed on a Landing Page to show the Branch Menu for a specific branch. Choose a branch in the Location field. This can be useful if you are creating sub-pages for a branch.
Added in the December 2024 release.
One additional component is available that requires additional information:
This feature allows users to select a single branch location as their home / preferred branch so that they can easily access branch-specific content across the site.
The Home Branch selector popup will appear to users who arrive at the site and:
are new to the site,
have not selected a Home Branch, and
have not checked the “Do not ask me again” checkbox in the modal.
Users can select a Home Branch by:
choosing a branch from the modal popup,
using the “Set Preferred Branch” link in the Utility menu,
choosing “My preferred branch” on a Branch page or in
Location Finder.
Users can remove a Home Branch by:
summoning the popup with the down arrow next to the set branch in the Utility menu, or
unchecking “My preferred branch” on a Branch page or in Location Finder.
Selecting a home branch will:
add a link to the Branch’s home page to the user’s utility menu,
show the Branch as the Home Branch on Branch Pages and Location Finder, and
populate the Branch options in other sections of the site like the
Membership Apps and
Schedules (coming soon).
Disabling the Home Branch Selector
If you want to completely remove the Home Branch selector from your site you will need to disable it via the command line. DO NOT disable the module via the admin UI as this will result in an error.
drush pmu ws_home_branch openy_home_branch
Migrating to Layout Builder
Migrating Branches to Layout Builder involves recreating some content on the page. The process is similar to
building a new Landing Page with Layout Builder but with a lot of the work done for you!
Once you are ready to migrate a Branch:
Either clone the page or open it in a separate tab so that it’s easier to compare content.
Prepare the Branch for Layout Builder:
Edit the Branch,
Add links in the Menu section if you’d like,
click Use Layout Builder,
if you’d like, uncheck Published while you migrate to hide the page temporarily, then
Save.
Your Branch will now display a set of default blocks: Hours (and header), Menu, Social Links, and Amenities.
From here, you can
use Layout Builder to move your old content from Paragraphs into Blocks. Review the
full list of designs or the
list of components if you need help deciding how to place things. Your old content will still be available to reference in the Edit tab in the old Header/Content/Footer sections.
When you’re finished, Save the layout and Publish the Branch!
1.2.7 - Camp
Physical locations where outdoor camp programming takes place.
The Camp content type is used for physical locations where outdoor camp programming takes place.
While
YMCA Branches may offer some form of summer day camp, they differ from facilities that primarily host programs related to outdoor camps. The Camp content type also enables editors to create sub-sites or “microsites” using a separate menu structure.
If you are an independent YMCA camp or you’re an Association with one or more locations dedicated to outdoor camp, the Camp Content Type serves well as a landing page for those locations. Camp teasers will also appear on the Location Finder page.
What about Branch Day Camps?
There are several considerations for Branches that host Day Camps in the center:
The Branch content type is intended to be the home page for branches.
Adding a Branch listing and a Camp listing for the same physical location creates duplicate listings for your center and could have search implications.
Camp pages don’t have fields for operating hours or amenities.
Branch Day Camps, unlike outdoor camps, tend to be listed in the same CRM as other branch-based programs and therefore could integrate into Activity Finder, provided the CRM’s compatibility.
Title (required): This is the name of your camp, which will display as your page title and the title in the location card.
There is no separate field for the full name of your facility (e.g., Joe C. Davis YMCA Outdoor Center) versus the common name (Camp Widjiwagan). The best practice would be to use the shorter, more common name for readability.
Menu Links (required): Add in the URL or name of the content you want to link your
Camp Menu to (you must use the Camp Menu paragraph for this to work). This field is not used with Layout Builder.
Address (required): The physical address of your location. Be sure to include all address fields.
Camp coordinates (required): This field pins your camp on the locations map.
See
Branch for details on how to find your camp coordinates.
Phone (required): The main phone line for your camp. Will be displayed as it is entered and linked to allow mobile users to tap to call.
Fax: Optional.
Email: We recommend you use a main contact email, such as info@example.com, rather than the email for an individual staff member.
Directions: By default, a link with directions is auto-generated using the Address field. Use this field to substitute your own directions link. You can use this field to substitute your own directions link.
Header Area
There is no image field for the Camp content type, so you will need to add one of the following paragraphs to add an image and title at the top of your page:
Beginning in Website Services 9.3, content editors have the option of customizing the Camp page with
Layout Builder. You can migrate from using Paragraphs to using Layout Builder on a camp-by-camp basis to ease the transition.
The Use Layout Builder checkbox on the Camp edit page non-destructively switches between Paragraphs and Layout Builder. If the checkbox does not appear, ensure the Y Camp (y_camp) module is installed at Admin > Extend (/admin/modules).
Camp Menus
The Camp page is often used as a landing page for a microsite with additional information, such as schedules, packing lists, and other camp-specific pages.
We have two camp-specific menus that help build this structure:
Camp Menus: Allow you to provide a two-level menu in the header of each Camp page and subpage.
Camp Quick Links: Provide a single-level utility menu for additional camp information.
Camp Quick Links
After enabling Use Layout Builder for your Camp page, navigate to the Layout tab. You need to configure the Camp Quick Links in two blocks for them to properly display on desktop and tablet/mobile devices.
Configure the first block
In the Configure Camp Header section, you will see placeholders for each of the menu blocks that say Please select the menu to display in this Camp Quick Links block.
Using the on the first Camp Quick Links block, click Configure.
In this menu, you can create a new menu or add an existing one that you’ve made in the Menus administration (/admin/structure/menu). To create a new menu, fill in these fields:
Title (required): The title of the Quick Links menu to be displayed in the Utility Navigation.
Display title: Must be checked in order for the Quick links to display properly.
Click Add new menu, then set up the new menu:
Menu Title (required): The administrative name of the menu. Like Camp Coleman Quick Links.
Menu Name (required): The machine name of the menu, using only lowercase letters, numbers, and hyphens. Like camp-coleman-quick-links.
Administrative summary: Is optional and only used in the menu admin.
Click Create menu, then click Edit links to add items to the menu.
In the Edit links popup you can add and reorder links in the menu.
For each new link:
Click Add new link
Menu link title is the text displayed.
Link is the internal page or external url that the link points to.
Enabled allows you to temporarily hide a menu item.
Show as expanded should be checked for any parent items. There is no harm in always checking this.
Other fields can be ignored.
Click Save when you are finished.
Use the drag handles to rearrange or nest menu items.
Note: Parent items must have Show as expanded checked in order to display child items.
When you are finished adding and rearranging menu links, click Save.
Finally, save all the changes with Update.
Configure the second block
Find the second place that says Please select the menu to display in this Camp Quick Links block in the Header Section.
Using the on this block, click Configure.
As before, configure the block:
Add the same Title as the first block.
Ensure Display title is checked.
Click Add existing menu, then start typing the name of the menu you created in the previous block and select it in the autocomplete dropdown.
Click Add menu to save the selection.
Once the existing menu has been added, you will see the Edit, Remove, and Edit Links options. Once you see those, you can click Update to save these changes.
Once you have completed the process you will see your Quick Links menu displayed in two sections of the Header. This will ensure that the menu is displayed properly across all displays.
Camp Menu
Find the final placeholder that says ... Camp Menu ...
Click Configure the block.
Create a new menu or choose an existing one using
the steps above.
Click Update, then Save Layout at the top of the page.
Now your Camp page is populated with all of its menus!
Camp Subpages
The Camp Subpage (formerly “Camp Landing Page”) content type allows you to create internal pages for your camp section or microsite. Once you’ve created the parent Camp page, you are ready to create additional Camp Subpage pages.
Go to Content > Add Content > Camp Subpage.
Set the Title.
In the Camp field, begin typing the name of the Camp page that will be the parent page, then select the item from the autocomplete dropdown.
Click Save and edit layout.
You will now see the Layout Builder editor with the menus from your Camp page pre-populated in the layout.
Add additional content using
Layout Builder, then click Save layout.
Note: The menu references on Camp Subpages are copied to the header when the page is created. Any updates to those menus (new items, reordering) will be reflected on all subpages. However, later changes to the blocks (removing the menu altogether, changing the linked menu) will need to be made on both Camp and Camp Subpage pages separately.
Camp Subpages are not automatically added to the Camp Menu of their corresponding Camp. Be sure to add the newly created Camp Subpage to the Camp Menu so that it’s properly linked.
Layout Builder Blocks
Camp pages have a number of specialized components that utilize the structured data (fields) that already exist on your camp page in newly designed Layout Builder Blocks.
In addition to using many of the standard
Layout Builder components, Camp pages also use a number of components that display fields described above.
Camp Info Block
The Camp Info Block is automatically added to the Body section of each Camp page. It displays content from the Contact Info section. It can be rearranged on the page but is not otherwise configurable.
Camp Header Layout
When you create a new Camp page or switch an existing one to use Layout Builder, it will come with a pre-set Camp Header Section, which enables the configuration steps above. If you find some of those blocks are missing, you can restore them manually.
To completely start over, use the x to the left of Configure Camp Header to delete the section. Add a new Section and choose the WS Camp Header layout. Then, add the following blocks by selecting Add block in the corresponding region.
The default configuration for a the Camp Header block should be:
Utility Menu
Left
All system blocks > Camp blocks > Camp Back Link
Right
Create custom block > Camp Quick Links
All system blocks > OpenY > Open Y Google Translate (optional)
Main Menu
Left
All system blocks > Common blocks > Site Logo Block
Right
Create custom block > Camp menu
Create custom block > Camp quick links
URL Pattern
The Camp content type uses the following URL pattern: /camps/[node:title]
1.2.8 - Facility
Locations that house YMCA programming outside of a Branch.
The Facility content type is used for locations where programming might take place that are not a full YMCA Branch. This might be a childcare facility, a shared-use space, or an office.
Designs:
Facilities share their design with the
Branch content type.
Title (required): This is the name of your facility, which will display as your page title and the title in the location card.
Neighborhood: If it is used, select an item from the Neighborhood
Taxonomy.
Type: Choose from a predefined list of types.
Facility Branch: Using autocomplete, select the
Branch that this facility is associated with. This establishes a relationship between the facility and its parent branch.
Contact Info
Address: The physical address of your location. Be sure to include all address fields.
If you do not set an address (or clear the address by resetting Country to “- None -”) then the facility will display the address of its associated Branch. (Added in version 10.3.1, December 2023.)
Facility coordinates (required): This field pins your facility on the locations map.
See
Branch for details on how to find your facility coordinates. These coordinates are used by the location finder and map views.
Phone (required): The main phone line for your facility. Will be displayed as it is entered and linked to allow mobile users to tap to call.
Fax: Optional.
Email: We recommend you use a main contact email, such as info@example.com, rather than the email for an individual staff member.
Directions: By default, a link with directions is auto-generated using the Address field. Use this field to substitute your own directions link.
Facility Hours: Set the hours for the Facility. (Added in version 10.3.1, December 2023.)
This field follows the same rules as Address - if it is empty, the associated Branch hours will be displayed.
See
Branch Hours for details on how to set the Facility Hours.
Sidebar area
For aside pieces of content, such as side navigations, promotional cards, and content related to the main part of your page. Use the Paragraphs described below to add content to this area only if “Use Layout Builder” is not selected.
Content
These sections are not displayed when “Use Layout Builder” is selected.
Use
Paragraphs to add content to your Facility page.
Sidebar Area
Content Area
Customizing with Layout Builder
Beginning in
Website Services 10.3.0 content editors have the option of customizing the Facility page with
Layout Builder. You can migrate from using Paragraphs to using Layout Builder on a facility-by-facility basis in order to ease the transition.
The Use Layout Builder checkbox on the Facility edit page non-destructively switches between Paragraphs and Layout Builder. If the checkbox does not appear, ensure the Y Facility (y_facility) module is installed at Admin > Extend (/admin/modules). This module provides the necessary integration with Layout Builder.
Flexible content types that use regions and paragraphs to build content.
Fields in Landing Page
Title (Required)
This is what you will see in your admin portal as your content’s name. It will also show as the page title in the Header unless you add a paragraph in the Header Area. The title will appear in the <title> tag of the HTML, which is important for SEO and accessibility.
Layout (Required)
Landing Pages come with four basic layouts for desktop. For mobile, all layouts display in a single column, with the Sidebar Area stacking below the Content Area.
One Column Layout
One Column (Full Width)
Two Columns
Two Columns (Fixed Sidebar)
Paragraph Areas
You can use any number of
Paragraphs in these fields. Paragraphs are reusable content components that can be added to various areas of your landing page.
Header Area: Used for inserting banners, small banners, and galleries. Date blocks are also great in this area for scheduled content. This area appears at the very top of the page.
Content Area: The main body of your content. This is where the primary information and messaging of your landing page should be placed.
Sidebar Area(Two Column Layouts Only): For aside pieces of content, such as side navigations, promotional cards, and content related to the main part of your page. This area is only visible when using a two-column layout.
Bottom Area: Add an anchoring element to your page, such as a promotional banner or webform. This area appears at the bottom of the page.
1.2.10 - Landing Page (Layout Builder)
A flexible content type that uses Sections and Blocks, managed with Layout Builder, to build content.
This page is the base for building pages with
Layout Builder.
Creating a Landing Page
Go to Admin > Content > Add Content > Landing Page (Layout Builder).
Fill in the content fields:
Title (required): The title of the page. This is for internal use, such as in the admin content list. It will not be displayed on the page itself unless you add it manually with a block in the
Banner section.
Metadata: This content is used to provide context to search engines and page previews. For the best user experience:
Meta description: A brief and concise summary of the page’s content, with a recommended maximum length of 160 characters.
Meta image: Choose or upload an image to be used as a thumbnail for social sharing and preview cards.
Meta tags: Advanced meta tag configuration. Caution: This section should not be edited unless you are familiar with meta tags and their impact on SEO.
Customizing a Landing Page
Once you create a Landing Page, you can customize its layout and content using
Layout Builder.
Landing Pages come with these pre-configured sections:
Header: Typically contains the site logo, site name, and navigation menus.
Banner: An edge-to-edge section, without margins (gutters), that is designed for visual impact. It works best with a single
Banner or
Carousel block.
Body: A section with left and right margins, designed to contain the bulk of your page content.
Footer: Generally includes copyright information, social media links, and secondary navigation menus.
You can
edit, reorder, or remove these sections to configure your page as desired. For specialized content, such as digital displays or embedded systems, you can even remove the header and footer altogether.
Blocks
Blocks are boxes of content rendered into a region of a web page. Blocks are placed and configured specifically for each theme. Blocks can contain a variety of content types, including text, images, menus, and forms.
Content blocks are blocks whose content you can edit. You can define one or more block types, and attach fields to each block type. Content blocks can be placed just like blocks provided by other modules.
The block description is an identification name for a block, which is shown in the administrative interface. It is not displayed on the site. The block title is the heading that is optionally shown to site visitors when the block is placed in a region.
1.2.11 - Membership Content Type
Membership items are the building blocks of the Membership Calculator and are only displayed within the Membership Calculator Paragraph.
Title: The title of the membership type to be displayed on the first step of the Membership Calculator.
Description: A short description to be displayed on the first step of the Membership Calculator. This can include information about the membership benefits or features.
Image: A reusable image field to be displayed on the first step of the Membership Calculator. Use an image that represents the membership type visually.
Membership Info
The Membership Info section lists detailed membership information per location. Add one “Membership Info” section for each location that your membership applies to. If a location does not offer a membership type, you can leave it out.
Location: A reference to an already-existing
Branch. If the branch does not exist, you’ll need to create it first.
Link: The URL to the membership signup page for the specified location.
URL: The link a member should be taken to to sign up for this membership at this location. See below for tips on finding this URL.
Link Text: This field is not used.
Join Fee: Dollar value for how much someone has to pay to join. Enter the amount without a currency symbol.
Monthly Rate: Dollar value for the monthly fee of the membership. Enter the amount without a currency symbol.
Finding your registration link
Every membership management system will have different ways of linking in for members to complete their registration. Here are a few we know about. If you have tips for a MMS not listed here, feel free to leave them in the comments.
Daxko Operations
Navigate to: Membership > Membership Types > Edit > Online Settings. This provides the deep link to the specific membership types.
1.2.12 - News Post
Designed for timely content, articles, and news pieces tagged with one or more physical locations.
News posts in YMCA Website Services allow you the flexibility to create simple posts using only the text editor and more robust layouts with paragraphs.
When Should I Use a News Post?
When you decide to use a news post
depends greatly on your Association’s content strategy. However, news posts are designed so you can post timely content and list them throughout your site. Examples of news posts may include:
Member Stories
Workouts and Recipes
Updates about a Center/Branch
Promotions and Contests
Press Releases
How Do I Use a News Post?
There are three fields that appear above the accordion tabs:
Title: The name of the news post. Displays in the header area on your news post and in
a list view of news posts.
Locations: An option select for you to tag a post with one or more locations (Camp or Branch). Use Ctrl+Click (Windows) or Cmd⌘+Click (Mac) to select multiple locations.
Each time you create a new
Branch Page or
Camp Page, that location’s name populates into the locations field automatically.
Category: An entity reference to
the News Category vocabulary. Type in the name of the category and select from the options that appear, or create a new category/term by typing in a new one.
Content Area
The content area is the main body of your page. You can use the default fields entered below for a simple block post or build a more robust layout using paragraphs.
Image: Displays above your description and inside a News Post listing. Not required. Uses the
media browser and image field.
Description:
Using the text editor, you can enter anything from a brief summary to the entire body of your text.
Sidebar Area
The sidebar area also allows you to embed paragraphs below a section that links to the centers tagged in the post, the categories, and a Related Content field that allows you to promote other News Posts by tagging them with the autocomplete widget.
Layouts
While you have the option to build layouts in news posts using paragraphs, all news posts are strictly two-column layouts. The Content Area displays on the left while the Sidebar Area displays on the right.
Other Settings
In the right column, ensure the “promoted to front page” item is checked, so it will appear in any listings.
1.2.13 - Program
A generic category page for program offerings.
The Program content type is a high-level page that directs people to more specific program offerings.
An example of a Program in YMCA Website Services would be a Swimming & Aquatics page that directs people to more specific offerings, such as swim lessons or clinics.
When Should I Use a Program?
Programs are pages that should link to more specific offering pages. Most often in YMCA Website Services sites, they are the main program pages in an YMCA Website Services mega menu setup.
How to Use Program
Header Area
Icon: An image field that displays an icon (jpg/png) inline with the title.
Image: An optional image field for a picture to display in the header.
Color: A background color for the header.
Paragraph Section: Area to enter paragraphs in the Header, such as a Gallery, Small Banner or Microsites menu. Paragraphs entered in this area replace the image/background color
Standard Title with Light Blue
Standard Title with Purple
Small Banner
Content Area
Description: Displays above the main body of your content and serves as a tease for your Program page when it’s displayed as part of a list on another page. Minimal styling and short lengths are recommended.
Content: The main body of your content. Use paragraphs to build your page layout. Designed to integrate
with the Categories Listing paragraph, but that is not required.
Sidebar Area
For aside pieces of content, such as side navigations, promotional cards and content related to the main part of your page.
Layouts
Similar to landing pages, Program pages are designed for flexible layouts, with a couple key differences:
There is no layout dropdown. How your content displays depends on your theme.
Lily/Rose will always display Programs in a two-column layout in desktop.
Carnation will display desktop in One Column without content in the Sidebar Area and in Two Columns with content in the Sidebar Area.
Carnation: Without Content in the Sidebar
Carnation: Desktop With Content in the Sidebar
The Description field always displays above the paragraphs you enter.
There is no bottom area for you to add an anchoring element.
Customizing with Layout Builder
Beginning in
Website Services 10.3.1.1 content editors have the option of customizing the Program page with
Layout Builder. You can migrate from using Paragraphs to using Layout Builder on a program-by-program basis to ease the transition.
The Use Layout Builder checkbox on the Program edit page non-destructively switches between Paragraphs and Layout Builder. If the checkbox does not appear, ensure the Y Program (y_program) module is installed at Admin > Extend (/admin/modules).
Layout Builder Blocks
Program pages can take advantage of the
Categories Listing block to list child Program Subcategory pages. To add the block:
Click the Layout tab at the top of your page.
Scroll to the location on the page where you want to add the block (usually the Body section).
Click Add block.
In the sidebar, expand All system blocks.
Search for “Categories Listing” or scroll to Lists (Views) > Categories Listing.
Click on Categories Listing.
Check Override title to add a title to the block.
Click Add block.
NOTE: As of version 10.3.1.1 (December 2023) the Categories Listing block styles have not been updated to be in line with the
Design System. They will be updated as of the March 2024 release. Keep an eye on
y_program releases for details.
Subcategory pages refine broad Programs into more concrete options.
A subset of a
Program, Program Subcategory pages list different types of program offerings, which can be grouped into
Activities.
Whereas a Program page would describe a Y’s Health & Fitness offerings in general, a Program Subcategory would break that down into subcategories such as:
Personal Training
Group Exercise Classes
Pilates
When Should I Use a Subcategory?
Most Ys have opted to use Program pages as the top-level categories in their Programs mega menu. Subcategories are then the items underneath each category.
Subcategories also appear as horizontal cards on Program pages.
How Do I Use the Program Subcategory Content Type?
Start by adding a Title for your Program Subcategory and tag it with a Program.
The Program tag will pull your Program Subcategory in as a horizontal card on a Program page. You can only tag a Subcategory with one Program.
Header Area
Image: Select an image from the media browser using the image field. It displays in the header and as a thumbnail in
Categories Listing.
Color: Use the dropdown to select a background color for your header.
Note: The background color does not display on desktop in Carnation unless you do not have an image selected.
You have the option to add paragraphs in the Header Area. However, these paragraphs display below the image and title you enter above.
For example, if you add a banner in the Header Area, it will display below the title and image entered in those Header Area fields.
Subcategory was originally designed to work with the Classes Listing Filters paragraph in the Header Area and the Classes Listing paragraph in the Content Area.
With the integration of Activity Finder into YMCA Website Services, Classes Listing and Classes Listing Filters are becoming less popular among YMCA Website Services sites.
Content Area
The Content Area includes a Description that displays full-width just below the Header Area.
When your Subcategory is showed in a Categories Listing on a Program page, the Description is the text inside the card.
You can embed content inside the Content Area, all of which will display below the Description.
YMCA of Greater Brandywine Example
Sidebar Area
The Sidebar Area will change the layout of the page into two columns once you enter content.
Beginning in
Website Services 10.3.1.1 content editors have the option of customizing the Program Subcategory page with
Layout Builder. You can migrate from using Paragraphs to using Layout Builder on a program-by-program basis to ease the transition.
The Use Layout Builder checkbox on the Program Subcategory edit page non-destructively switches between Paragraphs and Layout Builder. If the checkbox does not appear, ensure the Y Program Subcategory (y_program_subcategory) module is installed at Admin > Extend (/admin/modules).
Layout Builder Blocks
Program Subcategory pages do not utilize any specialized blocks. See
Layout Builder for the list of all components.
Flexible content that can be inserted into components as advertisements.
Promotions are timed pieces of content that allow content editors the flexibility to create a single item that can be placed in multiple locations on the site, without having to duplicate or manage content in multiple locations.
<iframewidth="560"height="315"src="https://www.youtube-nocookie.com/embed/hrFHguHoDNE?si=WN-h6H3QuYRQYMgA&start=218"title="YouTube video player"frameborder="0"allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"referrerpolicy="strict-origin-when-cross-origin"allowfullscreen></iframe>
Version 1 of the Promotion functionality was released in
version 10.3.1.1 (December 2023). This version supports swapping promos into:
Activity Finder
By enabling the ws_promotion_activity_finder module.
Cards
By enabling the ws_promotion_cards module.
Modals
By enabling the ws_promotion_modal module.
Creating a Promo
Go to Admin > Content > Add Content > Promotion (/node/add/promo).
Fill in the content fields:
Title (required)
Subtitle
Description: The body text of the promo.
Image (required): Choose an existing image from the library or upload a new one.
CTA/link: Add a call to action to your promo.
Promotion Category: Choose one item from the Activities
Taxonomy to link the promo with related components (see below).
Promotion Priority: Set how often the promo will appear. This setting will only have an effect if multiple promotions can appear on a page.
Visibility pages: This field is not yet in use.
Use the Scheduling options section in the sidebar to set a Publish on and Unpublish on time for your Promo (this requires cron to be running on your server - check with your hosting partner).
Placing a Promo
Version 1
In version 1, creating a Promotion and setting it as Published will automatically enable the promo in any available components (corresponding to the modules enabled above).
To filter a component to only a certain set of Promotions, edit a Layout Builder block and set the new Promotion Category field.
If Promotion Categoryis not set on a block, then the block will be overridden by any available (published) promo.
If Promotion Categoryis set on a block, then the block will be overridden by only matching promos that have the same category set.
1.3 - Blocks
Blocks allow content editors to reuse sections of content across multiple pages.
Understanding Blocks
Blocks are reusable content containers that can be placed in different areas, or regions, of a webpage. Think of them as building blocks that you can assemble in various ways to create different layouts.
Key Features:
Reusability: Create a block once and use it on multiple pages.
Flexibility: Different block types support different content formats.
Efficiency: Updates to a block are reflected everywhere it’s used.
A block works by selecting a paragraph, which prompts you to create or select an existing block. You then add content to that block.
You can then embed that block on another page by searching for it by its description and selecting it from the list of results.
Site-wide Blocks and Block Layout
Blocks can be configured on a site-wide level using the Block Layout. These blocks contain global elements such as menus.
Themes define Regions where blocks can be placed. In YMCA Website Services, these regions are typically static.
To view your site’s regions, go to Structure > Block Layout and click on Demonstrate block regions. It is generally not recommended to change the configuration in the Block Layout without proper training.
To change layouts on individual content pages, editors and website managers typically use Paragraphs or Layout Builder.
Paragraphs that support blocks will usually have two buttons: Add New Custom Block and Add Existing Custom Block.
Add New Custom Block: Creates a new block that can be reused later.
Add Existing Custom Block: Allows you to select a block that was previously created. Type the Block Description in the search field, and choose from the options that appear.
Block Descriptions
The block description field is required for all block types. This serves as the name for your block and is displayed in the administrative interface. Use clear and descriptive names to easily identify your blocks when embedding them onto pages. Block descriptions are not displayed on the site’s front end.
Block Types
YMCA Website Services supports different block types for different content needs:
Basic Block
A basic block provides a
basic text editor. It is suitable for simple text content, such as descriptions on cards across multiple pages.
Simple Block
The simple block is the block type you will likely use most often. It also provides a
basic text editor and is also great for embedding descriptions on cards across multiple pages.
This block allows you to use any type of HTML tag, making it useful for embedding scripts and iframes onto multiple pages. The code block provides more flexibility for technically-inclined content editors.
Layout Builder is a powerful page-building tool for your YMCA website. It allows content editors and site builders to quickly and easily create visual layouts for displaying content. You can customize how content is arranged on a single page, across types of content, or even create custom landing pages with an easy-to-use drag-and-drop interface.
Drupal’s Layout Builder allows content editors and site builders to easily and quickly create visual layouts for displaying content. Users can customize how content is arranged on a single page, across types of content, or even create custom landing pages with an easy-to-use drag-and-drop interface.
YMCA Website Services 9.2.12 introduces a new Content Type: Landing Page (Layout Builder). This new page will allow you to build pages using Sections with different Layouts that contain Custom Blocks. Please contact your development partner if you need assistance updating to the latest version.
Creating a new page
To use Layout Builder, you’ll first have to create a new page:
Choose any Layout Builder-enabled content type, or start with a basic
Landing Page.
Go to Content > Add Content > The Content Type.
Once you’ve saved, you will see an empty page. Click the Layout tab to enter Layout Builder or go directly there with Save and edit layout.
Updating an existing page
Navigate to the page you’d like to update, then click the Layout tab, like above.
Once you are in the Layout editor, you can create, edit, rearrange, and delete sections and blocks while viewing the page in a what-you-see-is-what-you-get preview mode.
Saving and publishing
Changes to the page are not displayed to site viewers until you Save Layout on the page and Publish it.
When in the Layout editor, you will have these options at the top of the page:
Save Layout will save your changes and return you to the main page view.
Save and edit layout will save your changes and keep you in Layout Builder.
Discard Changes
Revert to Defaults will reset your page to the default empty layout.
After saving your changes, be sure your page is published:
Click the Edit tab.
Check Published.
Save the page.
Fundamentals
In Layout Builder, you will see the page divided up into Sections and Blocks. Your page may already be populated with some sections to get you started building, and you can change or edit those to fit your page.
Sections
Sections create the structure of the page and contain blocks. You can drag and drop blocks between sections, but you cannot move sections themselves—you can only create sections above or below existing sections.
You can remove sections by clicking the small “X” link at the top left of the section. Click on “Configure ” to edit the section layout and other options.
Layouts
Layouts define the structure of a section. YMCA Website Services comes with 1-, 2-, 3-, and 4-column layouts, and each layout has additional configuration options once it’s created. See
advanced options for more details.
Then configure the advanced Layout, Styles, and Settings.
Some options in this configuration may not yet be fully supported.
Blocks
While Sections contain the page’s structure, Blocks contain its content. Blocks are boxes of content rendered into a region of a web page.
To create a block, click Add Block in any section of the page, then Create Custom Block.
Your YMCA website has a wide array of blocks to choose from. In this section, you will find detailed descriptions of those blocks.
Tips and Tricks
Get more space for writing
The Content Editing Pane—the sidebar where you edit blocks —can sometimes be too small to get all of your content in there nicely. Simply drag anywhere on its left border to expand the pane.
Rearrange blocks easily
When rearranging large blocks on the page it can often be challenging to drag them around. To make this easier, uncheck Show content preview at the top of the page. This will substitute the “WYSIWYG” preview for block titles, making the content much more compact.
An overview of all custom Layout Builder blocks and their designs.
The distribution has shipped with two generations of Layout Builder component designs. The first-generation “Pre-release” designs were included with versions
9.2.12 (December 2022) and
9.2.13 (March 2023). The refined and feature-complete “Design System” designs were released in June 2023.
Following the YMCA Brand Guide, the distribution offers four “colorways.” Content editors can use these to apply accessible, brand-compliant styles to all components within a Layout Builder-based page.
You can access each of these components on
Layout Builder pages via the Create custom block selector.
Component
Design
Accordion
Amenities
Article List
(Hero) Banner
Branch Hours
Branch Menu
Branch Preferred Branch
Branch Social Links
Breadcrumbs
Camp Menu
Camp Video Banner
Card
Card - Column Variations
Carousel
Donate
Event List
Forms
Global Footer
Global Header
Grid Content
Icon Grid
Icons and Logos
Locations
Menu and Search
Modal
Ping Pong
Promo Cards
Side Menu
Sponsors
Staff
Statistics
Table (Simple Content)
Tabs
Testimonials
Utility Menu
Pre-release
View the designs
Component
Mobile
Desktop
Accordion
Article (/News /Blog /Press Release)
Branch
Branch Amenities
Branch Hours
Branch Menu
Branch Social Links
Breadcrumbs
Cards
Carousels
Event
Grid Content
Hero Banner
Modals
Partners (/Sponsors)
Ping Pong
Promo Cards
Simple Menu
Staff
Statistics
Tables
Tabs
Testimonials
Webforms
1.4.2 - Advanced Options
Configuration for Layout Builder Sections and Blocks.
A wide range of configuration options are available for Layout Builder components using the contributed
Layout Builder Blocks module, which is included with the distribution. In addition to those configuration options, we provide an extra layer of “Y Styles” that help site builders customize their sites in an accessible and brand-compliant manner.
Y Styles
These options provide customizations for Layout Builder-enabled pages at the Content Type, Page, and Block level.
Styles inherit from content types, to pages, to blocks. Some styles can also be overridden at each level - block styles can override page styles, which can override content type styles.
flowchart
classDef ct fill:#5C2E9133;
classDef page fill:#92278F33;
classDef block fill:#C6168D33;
subgraph ct[Content Type]
direction LR
subgraph page[Page]
direction LR
subgraph block[Block]
blockStyles[Block Styles]
end
pageStyles[Page Styles]
end
ctStyles[Content Type Styles]
end
blockStyles -- override --> pageStyles
pageStyles -- override --> ctStyles
class ct ct
class page page
class block block
Content Type Styles
Note: This configuration may not be accessible to all content editors. Ask an administrator for assistance if necessary.
The default values for page-level Y Styles options are set in the Content Type display options.
To access them:
Go to Admin > Structure > Content types > Landing Page (Layout Builder) (or another LB-enabled content type) > Manage display
Ensure you’re acting on the Default display, then click Manage layout.
Expand the Y Styles section
Choose your default configuration options. These will set the defaults for every new node of this Content Type. Existing content will not be affected.
Click Save layout
Page Styles
Every Layout Builder-enabled page that you create will allow you to override the default settings. All of these settings will affect all items on a page, unless they are overridden at the block level.
Edit the Layout on a page
Expand the Y Styles section
Choose your configuration options.
Color scheme:The color scheme of all components on the page. Choose from four brand-compliant and accessible options:
Blue/Purple
Green/Blue
Purple/Red
Red/Orange
Border radius:The curvature of container corners.
0px (square)
10px (small curve)
20px (larger curve)
Border style:The style of container borders.
No border
1px border
Drop shadow
Text/Button alignment:The vertical placement of elements in containers.
Left
Center
Button position:Where buttons sit in containers.
Inside container
Overlapping container
Button fill:How buttons are colored.
Filled by default, outlined on hover
Outlined by default, filled on hover
Click Save layout
Y Block Styles
Some blocks have additional styles that can be configured per-block. For these blocks (e.g. Banner, Cards), look for the Y Styles section in the
block styles section and set the options accordingly.
Banner
Variant:Choose from five designs.
Standard
Overlay
Chevron
Frame
Small - This variant hides all but the title and description and does not use an image background.
Button fill: Override the page-level styles.
Card
Variant:Choose from four designs.
Standard
Overlay
Chevron
Color
Border style: Override the page-level styles.
Text/Button alignment: Override the page-level styles.
Button position: Override the page-level styles.
Button fill: Override the page-level styles.
Section Styles
When creating or editing a Section you have the option of configuring Layout, Style, and Settings.
Support for these options is a work in progress and may require involvement of your development partner. Feel free to experiment with the options. Be sure to follow proper brand guidelines and accessibility practices.
Layout Styles
In this section, you can control the container of the Section.
Container type
Boxed: Section is narrower than the header of the page. Good for text-heavy layouts.
Full: Section extends to the edges of the main content container.
Edge to Edge: Section extends to the edges of the page. Good for full-width components like Banners and Ping-Pong blocks.
Gutters
With Gutters: Section has left and right padding. Good for most non-full-width containers.
Without Gutters: Section has no left and right padding. Best for Edge to Edge containers.
Block Styles
When creating or configuring a block, you have the option of opening the Style tab to access additional style options including:
Background
Typography
Spacing
Borders
Animation
Support for these options is a work in progress and may require involvement of your development partner. Feel free to experiment with the options. Be sure to follow proper brand guidelines and accessibility practices.
After you have completed setting the Style options, click back to Content and Save or Update to commit your changes.
1.4.3 - Accordion
Expandable pairs of question/answer or header/section fields.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Displayed if Display title is checked; otherwise, this is for administrative use.
Section Subheading: The subheading of the accordion section.
Accordion Item: Add as many items as you like using the Add Accordion Item or Add new custom block button. When you are finished adding or editing each item, be sure to click Create/Update tab or Create/Update custom block to finalize the item. Each item contains:
Heading (required): The heading that will be used to expand/contract the accordion.
Body (required): The content of the accordion.
FAQ?: If this section contains Frequently Asked Questions, check this box to output them as structured data. Ensure the content contains individual sets of questions (e.g., “How old does my child need to be to swim at the YMCA?”) and answers (e.g., “The YMCA offers swim classes starting at age 3 and the pool is open to children of all ages with parental supervision”). Review
Google’s Content guidelines for FAQs for more information. 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.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Configuration
Configure the Activity Finder block after adding it to a Layout Builder page:
Edit the block within the Layout Builder.
Configure the available options. See
Activity Finder Block Configuration for field details. These configurations will affect what users see and can do on the front end.
Location & Category Filters: Restrict the block to show sessions from only certain Locations or Categories. Choose either “Limit” to show only the specified options or “Exclude” to remove the specified options. It’s generally recommended to choose either Exclude or Limit, but not both.
Limit by location: Only show sessions at specific locations in the results.
Exclude by location: Remove sessions at specific locations from the results.
Limit by category: Only show sessions related to specific Program Subcategories in the results.
Exclude by category: Remove sessions related to specific Program Subcategories from the results.
Legacy mode: Shows some data as it was in the previous version of Activity Finder (v3):
Disables bookmark functionality on the results screen.
Doesn’t display the age indicator in the result card of activities.
Changes the days + times wizard step. Displays only days of the week, but not times of each day (doesn’t support DaysTimes filter).
Weeks filter: Changes the Day/Time filter to use custom defined Week filters.
This requires setting the Weeks configuration in the Activity Finder settings (/admin/openy/settings/activity-finder).
Only sessions that have “Camp” in the title or room fields will return for this filter.
Additional filters: These filters are off by default, but can be enabled in the Block Configuration.
Start Month: Filters based on the month in the Session Time field.
In Membership: Shows Sessions that have In membership checked.
Duration: The length of the Session. This is configurable in the Activity Finder settings (/admin/openy/settings/activity-finder) and defaults to:
Single day
Multi-day (up to 5 days)
Weekly (up to 3 weeks)
Monthly (up to 5 weeks)
Season (up to 12 weeks)
School year (~9 months)
Full year
Hide Home Branch info block: Disables functionality related to the users selected home branch.
Background image: An image that’s displayed in the background of the banner above Activity Finder.
The distribution provides a few blocks to highlight articles:
Featured Articles
Articles Filter
Articles Listing
To use the blocks:
Click the Layout tab at the top of your page.
Scroll to the location on the page where you want to add a block.
Click Add block.
In the sidebar, click Create custom block.
Choose each block to add.
Featured Articles
Displays one or more articles in a large feature on the page.
Title (required): Displayed if Display title is checked; otherwise, this is for administrative use only.
Manual selection items: Select one or more articles to be featured on the page. Generally, it’s best to feature a single article.
Articles filter
Allows users to filter the Articles Listing by location, category, or text search.
Title (required): Displayed if Display title is checked; otherwise, this is for administrative use only.
This block has no other options.
Articles listing
Displays articles in a teaser view, filtered by the Articles filter block, with a “Show more” button.
Title (required): Displayed if Display title is checked; otherwise, this is for administrative use only.
Number of articles: The number of articles to show in the listing on first load. Defaults to 3.
Added in the December 2024 release.
Article type: Limit the articles to a specific type. Defaults to “All”.
Added in the December 2024 release.
When you are finished adding blocks,
Save and publish your changes.
1.4.6 - Banner
A full-width display with a header, description, and call to action overlaid on an image. Also known as a “Hero Banner”. The Banner block is used to draw attention to key content and promotions.
The banner block comes in several variations, including:
Standard: A basic banner with text and an optional image.
Overlay: Text is overlaid on the image.
Frame: The text appears within a frame.
Chevron: A banner with a chevron shape.
Small: A smaller banner variation.
Tall: A taller banner variation.
Promo: A banner designed for promotional content.
Sub Chevron: A variation with a sub-chevron design.
Sub Frame: A variation with a sub-frame design.
Some variations also have “Canada” specific styles in red, white, and black.
These variations can be selected during the block configuration process, allowing you to choose the most appropriate style for your content and design preferences.
Best Practices
Image Size: Use high-quality images that are appropriately sized for the banner area. Consult with your agency partner for recommended image sizes.
Text Length: Keep the banner title and description concise and engaging. Avoid lengthy text that could overwhelm the user.
Call to Action: Use a clear and compelling call to action to encourage user interaction.
Accessibility: Ensure that your banner content is accessible to all users, including those with disabilities. Provide alt text for images and use appropriate heading levels.
1.4.7 - Breadcrumbs
Secondary navigation that helps users understand their location within a website.
Scroll to the location on the page where you want to add the breadcrumbs (typically the bottom of the Header section or the top of the Content section).
Click Add block.
In the sidebar, expand All system blocks.
Search for “Breadcrumbs” or scroll to System > Breadcrumbs.
Click on Breadcrumbs.
Configuring the Breadcrumbs Block
After adding the block, you will need to configure it:
Title (required): This field is for administrative use only and will not be displayed on the front end. It is recommended to uncheck Display title.
The Breadcrumbs block might not display the correct path while editing the page layout. However, it will display correctly for site viewers.
Additional Information
What are Breadcrumbs? Breadcrumbs are a navigational aid used in user interfaces. They allow users to keep track of their location within a website or web application. The term comes from the Hansel and Gretel fairy tale.
Easy Breadcrumb Module: For more advanced breadcrumb functionality, consider using the
Easy Breadcrumb module. This module allows for customization of the breadcrumb trail, including:
Including/excluding the front page as a segment.
Including/excluding the current page as the last segment.
Using the real page title instead of deducing it from the URL.
Printing the page title segment as a link.
Using menu titles as a fallback.
Removing identical segments.
And more.
1.4.8 - Cards
Flexible card-style components that allow up to 4 cards to display across the page depending on the chosen layout.
The Cards block is similar to the
Grid CTA block, but has more fields and places the image behind the item content.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Section heading: Displayed as a heading above the cards.
Section subheading: Displayed below the heading.
Section link: A link button displayed below the list of cards.
# of columns: Allows 1 to 4 columns of cards.
Card items: Add up to 4. When you are finished adding or editing each item, be sure to click Create/Update tab or Create/Update custom block to finalize the item. Each card has:
Heading (required)
Image: Choose from the library or add a new image to be displayed behind the card text.
Description: A full text editor to add card content.
Link: A link at the bottom of the card.
As of the December 2024 release, Card links can use
link attributes such as id, target, and class.
Topic Tag: This is displayed at the top of the card and can be used to group cards visually.
The Cards block offers several variations that change the look and feel:
Standard: The default card style.
Overlay: Places the card content over the image.
Chevron: Adds a chevron graphic to the image area.
Color: Applies a background color to the card.
This block comes with
multiple styles. To choose an alternative style:
Click on the Style tab at the top of the Block Add/Update form.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): This title is for administrative purposes only and is never displayed, even if “Display Title” is checked.
Carousel heading: This heading is displayed above the carousel.
Carousel subheading: This subheading is displayed below the heading.
Carousel Item: You can add multiple items to the carousel by using the Add Carousel Item or Add new custom block button. Make sure to click Create/Update tab or Create/Update custom block to save each item after adding or editing. Each item includes the following fields:
Heading
Image: You can choose an existing image from the media library or upload a new image.
Description
Link: This creates a link that appears at the bottom of the carousel item.
Designs: This block provides no additional presentation outside of the embedded content. It renders the code you provide directly into the page. Ensure the code is properly formatted and safe for display.
To use the block:
Click the Layout tab at the top of your page
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Configuration
Fill in the following content fields:
Title (required): This field is for administrative purposes only. The title is never displayed, even if “Display Title” is checked. Use a descriptive title to easily identify the block in the Layout Builder.
Code: Paste the HTML, JavaScript, CSS, or other code to be embedded on the page.
!!! warning
Be extremely cautious when embedding code from untrusted sources. Unfiltered code can introduce security vulnerabilities and potentially compromise your site. Always validate and sanitize code before embedding it.
The Y Layout Builder - Donate (lb_donate) and YMCA Website Services Donation Embed Form (y_donate) modules work together to allow content editors to add an embedded donation form to the site and create a separate call to action to direct users there.
Embedded Form
The YMCA Website Services Donation Embed Form (y_donate) module provides a block that allows you to embed a donation form directly onto a page.
To get started:
Enable the YMCA Website Services Donation Embed Form (y_donate) module at Administration > Extend.
Navigate to the Layout tab of a Layout Builder-enabled page.
Select Add block on the page, then search or scroll to find Donation Form Embed Block.
Select the form type and enter the form ID from your donation provider.
Troubleshooting
If your embedded form does not work in your non-production environment, you may need to add a domain to the allow-list either on the provider-side or in your site’s Content Security Policy.
If your provider is not listed, you can add the form by selecting the Code Custom Block and pasting in your code. Alternatively, you can work with your development partner to
add a new donation provider. Refer to the
Information for Developers section of the y_donate project for details on how to implement a new provider.
Donate Block
The Donate Block (lb_donate) provides a call to action with donation amount buttons and a link to the embedded donation form page. This block can be placed in an
edge-to-edge container.
To use the block:
Click the Layout tab at the top of your page
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Section heading: Displayed as a heading above the items.
Section subheading: Displayed below the heading.
Giving amounts: Configure any number of buttons with preset donation amounts. An “Other” button will always be displayed after these buttons, allowing users to enter a custom amount.
Amount label: The amount to be displayed on the button, including the currency symbol (e.g., “$50”).
Form Element ID: This is usually a 4-digit number found in your donation platform’s backend. You may need to inspect the form using your browser’s developer tools to find this ID.
Donation page link: A link displayed below the buttons that directs users to the page containing the embedded donation form.
URL: This must link to the page where the embedded donation form is located for the donation buttons to function correctly.
Link text: The text to be displayed for the link (e.g., “Donate Now”).
Background image: Choose an image from the media library or upload a new image to be displayed behind the text and buttons.
The distribution provides a few blocks to highlight events:
Featured Events
Events Filter
Events Listing
To use the blocks:
Click the Layout tab at the top of your page.
Scroll to the location on the page where you want to add a block.
Click Add block.
In the sidebar, click Create custom block.
Choose each block to add.
Featured Events
Displays one or more events in a large feature on the page.
Title (required): Displayed if Display title is checked; otherwise, this is for administrative use.
Manual selection items: Select one or more events to be featured on the page. Generally, it’s best to feature a single event.
Events filter
Allows users to filter the Events Listing by location, category, or text search.
Title (required): Displayed if Display title is checked; otherwise, this is for administrative use.
This block has no other options.
Events listing
Displays events in a teaser view, filtered by the Events filter block, with a “Show more” button.
Title (required): Displayed if Display title is checked; otherwise, this is for administrative use.
Number of events: The number of events to show in the listing on first load. Defaults to 3.
Added in the December 2024 release.
When you are finished adding blocks,
Save and publish your changes.
1.4.13 - Grid CTA
Sets of content with a headline, description, and link displayed in 2 to 4-item wide rows, with the option to include icons or images.
The Grid CTA block is similar to the
Cards block, but allows for more flexible items with a slightly more freeform design. It is also similar to the
Icon Grid block.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Section heading: Displayed as a heading above the cards.
Section subheading: Displayed below the heading.
Grid CTA section link: A link button displayed below the list of items.
# of columns: Allows 2- to 4-columns of items.
Grid Item: Add up to 4. When you are finished adding or editing each item, be sure to click Create/Update tab or Create/Update custom block to finalize the item. Each item has:
Heading (required)
Description: A full text editor to add item content.
Media: Choose from the library or add a new image or icon to be displayed above the item text.
The header and footer on Layout Builder pages is composed of many complimentary blocks. The Header and Footer are special Sections that are pre-populated on each Layout Builder-enabled content type. If the Header or Footer do not already exist in your content, you can add them on your own.
Header Section
If a Header section does not already exist, add a new Section and choose the WS Header Layout. Then, add the following blocks by selecting Add block and then using the search box under All system blocks:
Utility Menu area
Left
Website Name Block
Right
Open Y Google Translate Block
Utility Menu
Main Menu area
Left
Site Logo Block
Center
Main navigation
Search Bar Block
Right
User account menu
Each block has some specific configuration recommendations:
Website Name Block
Configuration
Uncheck Display title.
Content
The Site Name is found under Configuration > System > Basic site settings.
Open Y Google Translate Block
Configuration
Uncheck Display title.
Content
The contents of this block are not configurable, but it may be omitted or removed if your site does not provide translation or uses another translation method.
Utility Menu
The option to add a Utility Menu was added in the December 2024 release. This menu is intended to give content editors an additional space for adding links in the top right of the header.
Configuration
Uncheck Display title.
Menu levels controls which and how many levels of menu are displayed. The Utility menu styles are designed for a single level of links.
Content
Menu items can be managed under Structure > Menus > Utility Menu.
Site Logo Block
Configuration
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
WS Site Logo: Choose which logo is displayed in the block.
Theme logo uses the logo defined by the active theme, in the Appearance > Settings > (The active theme).
Colorway logo uses a dynamic SVG that responds to the configured YMCA colorway. This option is recommended for the Header.
White logo uses a flat white logo. This option is recommended for the Footer.
Hide tagline in WS logo: (Added in the December 2024 release.) Check to hide the tagline (areas of impact) in the logo.
The areas of impact must appear on a website, but it is at the YMCA’s discretion whether to include them as the trademarked graphic paired with the logo or as a way of telling the story of our positive impact.
If you choose to hide the Areas of Impact in the logo, we recommend you include them elsewhere on the page.
Main navigation
The main navigation supports displaying up to three levels of menu items. When adding items, be sure to check Show as expanded for any parent item that should be expandable.
Menu levels controls which and how many levels of menu are displayed. We recommend using the default configuration.
Content
Menu items can be managed under Structure > Menus > Main navigation.
Tips
Refer to the Drupal User Guide for more information about
managing menus.
We recommend you limit the main menu to 6 items or fewer when using Layout Builder, as additional items can cause the menu to be wider than the supported area. Additional menu items can be added to the footer, if needed.
Search Bar Block
Configuration
Uncheck Display title.
Content
The contents of this block are not configurable.
User account menu
Configuration
Uncheck Display title.
Menu levels controls which and how many levels of menu are displayed. We recommend using the default configuration.
Content
Menu items can be managed under Structure > Menus > User account.
To show items with a button style, add the highlighted class to the menu item under Attributes > Class.
On mobile devices, only highlighted items from this menu will display.
Footer Section
If a Footer section does not already exist, add a new Section and choose the WS Footer Layout. Then, add the following blocks by selecting Add block and then using the search box under All system blocks:
Primary Footer
Site Logo
Footer Menu Left
Footer Menu Center
Footer Menu Right
Footer Social
Sub-footer
Copyright
Footer Menu
Site Logo
See above. The white logo is recommended for the footer.
Footer Menu Left, Center, Right
Each of these three blocks references a menu. The three menus can be used to split footer links across multiple columns.
Configuration
Display title: Uncheck to hide the title, or turn the menu title on to give each column a title.
Menu levels controls which and how many levels of menu are displayed. We recommend using the default configuration.
Content
Menu items can be managed under Structure > Menus > Footer Menu Left, Footer Menu Center, or Footer Menu Right.
Go to Structure > Block layout > Custom block library
Find the Footer Copyright Block
Edit the block, then Save when finished.
Footer Menu
This menu is typically for a limited number of links such as “Privacy Policy” or “Terms of Use”.
Configuration
Uncheck Display title.
Menu levels controls which and how many levels of menu are displayed. We recommend using the default configuration.
Content
Menu items can be managed under Structure > Menus > Footer.
Main Menu CTA Block
The
Main navigation has an additional feature that allows for adding a nested call-to-action that takes the place of the third level of the menu.
To use it:
Go to Extend (admin/modules) and enable the Web Services Main Menu CTA Block module (y_lb_main_menu_cta_block).
Edit a top-level menu item (like “Programs” or “Schedules”) via one of these methods.
CTA blocks will only be displayed on first-level menu items. Blocks on all other levels will be ignored.
Click the in the Main Menu section, then choose Edit menu.
Go to Admin > Structure > Menus > Main navigation then Edit a link.
In the CTA block section, click Add new custom block.
Fill in the fields:
Expand the Media section and choose or upload an image
Add a short Heading
Add a short 1-2 sentence Description
Add a link and display text for the Menu CTA Link
Add a Block description for administrative purposes only
Click Create custom block to save the block.
Save the menu item.
Go back to a Layout Builder page with the menu and refresh. The menu CTA should now appear when the corresponding menu dropdown is open.
Menu CTA items will not appear on pages that use Paragraphs-based layout. CTAs also ony show on desktop and not mobile displays.
1.4.15 - Icon Grid
A simpler version of the Grid CTA component. Displays sets of content, each with a title and description, arranged in rows of 2 to 4 items. Icons or images can be included with each item.
The Icon Grid block shares similarities with the
Cards and
Grid CTA blocks but offers a way to display more basic items with a slightly more constrained design. It is based on the lb_icon_grid block content type and uses icon_grid_item paragraphs.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): This field is for administrative purposes only and is never displayed, even if “Display Title” is checked.
Section heading: Displayed as a heading above the grid items.
Section subheading: Displayed below the heading.
Icon Grid section link: A link button displayed below the grid items. This uses the field_cta field.
# of columns: Determines the number of columns in the grid, allowing for 2 to 4 columns of items. This uses the field_icon_columns field.
Grid Icon Items: Add up to 4 items to the grid. This is managed by the field_grid_items field, which references icon_grid_item paragraphs. Each item has the following fields:
Title (required): The title of the grid item. This uses the field_title field.
Description: A full text editor to add content to the grid item. This uses the field_description field.
Icon: Choose an existing image from the media library or upload a new image or icon to be displayed above the item text. Circular icons are recommended, and all icons/images will be displayed with a circular crop. This uses the field_media field.
The Location Finder block provides search, filters, a map, and a listing of your YMCA locations.
Amenities Filters
Location Finder also now supports hierarchical amenities. That means you can arrange your list of amenities into categories instead of a simple alphabetical list.
The Amenities taxonomy is managed at Administration > Structure > Taxonomy > Amenities. See
Taxonomy, Vocabularies, and Terms for more info on managing Vocabularies.
Single-Level Amenities
If you leave the Amenities terms in a flat list on their configuration page, the Location Finder filters will display according to their configured weights. Drag terms up or down in the list to rearrange them in the filters.
Hierarchical (Parent/Child) Amenities
Y’s with many amenities may choose to group them in categories. Once any Amenities term is nested, the Location Finder filters switch to a hierarchical display.
To nest terms:
Go to the Amenities administration page at Administration > Structure > Taxonomy > Amenities.
Add term to create new parent terms if necessary.
Use the drag handle [✥] to arrange terms into nested groups.
NOTE:
Any terms more than two levels deep will be ignored. (That is, parents and children will be displayed, grandchildren will not.)
When nesting is enabled, any amenities that are not grouped will be hidden from the filter list.
Using Location Finder
The Location Finder block is best placed in an edge-to-edge Section with no gutters.
To use the block:
Click the Layout tab at the top of your page
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Note
The position on the page does not matter for the Modal block. It will always display as a popup in the center of the page and be completely hidden when dismissed.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Modal title: The displayed title of the popup.
Modal description: The text displayed in the body of the popup.
Modal CTA/Link (required): A link at the bottom of the popup.
Modal Dismissible:
If “Yes,” the modal will be shown to the user once on first load.
If “No,” the modal will be shown on every page load.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): This title is for administrative purposes only and is never displayed, even if “Display Title” is checked.
Section heading: Displayed as a heading above the partner items.
Section subheading: Displayed below the heading.
Partner tier: Click Create content block to add a new Partner tier. Add unlimited tiers. (Added in the December 2024 release. Prior to that, all partners were displayed in a single group.)
Block description: For administrative use only.
Partner’s Tier: The title of the tier (like “Platinum,” “Gold,” etc.). Leave this empty if you don’t want to display a tier title.
Partner items: Click Add new custom block to add a new Partner item or Add existing custom block to reuse an existing item. Items can be reused across pages. Add unlimited items. Each item has:
Heading: The name of the partner.
Image: The logo or image.
Link: An internal or external link.
After filling in the fields for an item, click Create custom block to save the item.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Section title: Displayed as a heading above the item.
Section subtitle: Displayed below the heading. This is the sub-heading of the Ping-pong section.
Item title: Displayed at the top of the ping-pong block.
Item description: Displayed below the title.
Item image: Choose from the library or add a new image to be displayed opposite the text.
Item image position: Places the image on the left/right side of the page in full-width (desktop) displays. Image will stack above text at narrow widths.
Item CTA/Link: Add up to two links. The first will be displayed with “primary” (solid) styling, the second will be “secondary” (outline) styling.
As of the December 2024 release, Ping-Pong links can use
link attributes.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): This field is for administrative purposes only and is never displayed, regardless of the “Display Title” setting. Use this to easily identify the block in the layout builder.
Card title: The main title displayed on the promo card.
Body: A rich text editor for adding the main content of the card.
Icon/Image: Choose an image from the media library or upload a new one to be displayed above the card text. The format of the image you upload affects how it will be displayed:
JPG/PNG: Images are cropped to a 3:2 aspect ratio.
SVG: Images are not cropped, and will retain their original dimensions. Using SVGs is the recommended approach for icons.
CTA: Configure the link and the text for the call to action button at the bottom of the card.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): This title is for administrative purposes only and is never displayed, even if “Display Title” is checked.
Section title (required): The heading for the related events section.
Link: An optional link to be displayed near the section title. This can be a link to a page with more events, for example. As of the December 2024 release, Related Events links can use
link attributes.
Type: Select how you would like to choose the related events in the block. Each type has different options:
Tags: Show upcoming events filtered by related tags.
Upcoming: Show upcoming events sorted by date.
Locations: Use the Locations field to filter related events.
Choose one or more Branch Locations to filter the list of events.
Manual: Directly specify the events to be listed.
Use the autocomplete field to add one or more events to be displayed.
Items count to display: The maximum number of items to display in the list: 3, 6, 9, or 12.
Note:
Related events will always be sorted by the event date unless Manual filtering is selected. When using manual filtering, events are displayed in the order in which they appear in the configuration.
The current page will not display in the list of related events once published, although it may appear in the preview.
For Tags, Upcoming, and Locations, “Sticky” events that match the filter criteria will show up first.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Displayed if Display title is checked, otherwise, this is for administrative use. This title will serve as the block description in the Block Layout interface.
Icon: Optional icon (or small image) to be displayed to the left of the menu title.
Links: An unlimited number of internal or external links.
The Simple Menu block is a useful way to display a list of links in a sidebar. Menus are a collection of menu links that are used for site navigation. You can create new menus and menu links, reorder links, and disable links provided by modules. For more information about managing menus, refer to the
Drupal User Guide.
To further customize the appearance of the menu, you can adjust the theme settings or use CSS to style the block. The administrative toolbar also provides a way to manage menus and their associated links. You can access it under Structure > Menus.
1.4.25 - Simple Schedule
A calendar-based schedule.
The Simple Schedule block pulls content that is added via the
Simple Schedules module, along with other Sessions on the site, displaying them in a calendar format. It’s crucial to configure your schedules using the Simple Schedules module before adding this block to your site to ensure content is displayed correctly. This block leverages existing session data and presents it in a user-friendly, calendar-based view.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Location (required): Select the location for which you would like to display scheduled events. This setting determines which sessions are included in the schedule.
Allows users to add simple content and responsive tables within a page.
The Table block allows users to add simple content and responsive tables to Landing Pages (Layout Builder content type). It utilizes the
Tablesaw library for responsive table functionality.
To configure the Table block, fill in the following content fields:
Title (required): This title is for administrative purposes only and is never displayed, even if Display Title is checked.
Section title: This title is displayed as a heading above the table and other content.
Section subtitle: This subtitle is displayed below the heading.
Body: This field provides a full text editor for adding tables, text, images, and other content to the page.
Adding a table: Click the Table icon in the editor toolbar. Configure the table options (number of rows/columns, headers, etc.) in the popup window.
Editing table properties: Right-click inside the table and select an option from the context menu to modify table properties such as row/column insertion/deletion, cell formatting, and other table-specific settings.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Section heading: Displayed as a heading above the items.
Section subheading: Displayed below the heading.
Staff items: Click Add new custom block to add a new Staff item, Add existing custom block to reuse an existing item from another block, or click Duplicate to reuse an entry from the same block. Items can be reused across pages. Add unlimited items. Each item has:
Image: Image of the staff member.
First name (required)
Last name (required)
Job title (required)
Email: Email address of the staff member.
After filling in the fields for an item, click Create custom block to save the item.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): This title is for administrative purposes only and is never displayed to users, even if “Display Title” is checked.
Section heading: Displayed as a heading above the statistics items.
Section subheading: Displayed below the heading.
Media: Choose an existing image from the media library or upload a new image. The image will be displayed to the left of the statistics.
Section link: Add a link to be displayed below the statistics items.
Statistics items: Add as many statistics items as needed by using the Add Statistics Item or Add new custom block button. After adding or editing each item, remember to click Create/Update tab or Create/Update custom block to save your changes. Each item includes the following fields:
Number value: The numerical value of the statistic. This field accepts a prefix (e.g., “$100”) and/or a suffix (e.g., “100M”).
Gives users the ability to switch page views by selecting in-page tabs. This component is built using the Paragraphs module and Entity Reference Revisions module.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Section heading: Displayed as a heading above the item.
Section subheading: Displayed below the heading.
Tab Item: Add as many Tabs as you like using the Add Tab or Add new custom block button (depending on your version). When you are finished adding or editing each item, be sure to click Create/Update tab or Create/Update custom block to finalize the item. Each item contains:
Heading: The heading that will be used to select the tab. This corresponds to the field_title field of the tab_item block content type.
Body: The content of the tab. This corresponds to the field_description field of the tab_item block content type.
Scroll to the location on the page where you want to add a block
Click Add block
In the sidebar, click Create custom block
Choose the block to add.
Fill in the content fields:
Title (required): Never displayed, even if “Display Title” is checked. For administrative use only.
Section title: Displayed as a heading above the cards.
Section subtitle: Displayed below the heading.
Item: Click Add new custom block to add a new Testimonial item, or Add existing custom block to reuse an existing item. Testimonial items can be reused across pages. Add up to 4 items. Each item has:
Block Description: A label for the Testimonial for administrative use only.
Name: The attribution of the testimonial. May get trimmed on mobile after about 20 characters.
Testimonial text: The body of the testimonial. May get trimmed on mobile after about 70 characters.
Image: An image related to the testimonial. Will use a placeholder image if not used.
After filling in the fields for an item, click Create custom block to save the item.
Embed text, images, blocks, and interactive components using Paragraphs, the layout-building component of YMCA Website Services.
YMCA Website Services content editors use Paragraphs to create flexible and unique layouts for their pages. Each Paragraph is a self-contained section of content with its own styling, functionality, and fields. Paragraphs are based on the
Paragraphs Drupal module.
You can add a Paragraph to a page when you see the Paragraphs field. These Paragraphs are typically placed within one of the four main “Areas” of a content type:
Header Area - Used for adding images, page titles, and other introductory content.
Content Area - The primary area for your main content.
Sidebar Area - Used for related information, such as promotions or links to other content.
Bottom Area - Often used for calls to action or other “anchoring” elements at the end of the page.
Not all content types use all four areas. Some content types might use fields directly to populate the Sidebar Area, while others might use an Image field instead of a dedicated Header Area.
Two Ways to Add Paragraphs
Content editors can add Paragraphs to a page using either the inline editor or the admin portal.
Admin Portal
To add a Paragraph to an Area:
Open the desired Area.
Select a Paragraph type from the dropdown. The button is typically labeled “Add [First Paragraph in List]”.
Helper text is usually provided above the dropdown.
The video below provides an example of the functionality of Paragraphs; however, the specific layouts demonstrated are not YMCA Website Services layouts.
Inline Editor
If you’ve upgraded to YMCA Website Services 2.4 or later, you can add a Paragraph from the front-end:
Click the Plus icon in the desired region.
Select a Paragraph type from the pop-up window.
Note: Not all Paragraph types are available for inline editing yet. More Paragraphs will be added to the inline content editor in future releases.
Rearranging Paragraphs
If the initial layout doesn’t meet your needs, you can easily rearrange sections:
Click the cross icon to the left of the Paragraph.
Drag the Paragraph to its new position.
Editing Paragraphs
To correct a typo or update content, click the edit button next to the Paragraph. This will open the Paragraph for editing.
Deleting Paragraphs
To remove an unwanted section, click the remove option from the dropdown menu next to “Edit.”
Choosing the Right Paragraph Type
YMCA Website Services offers over 50 Paragraph types out of the box, and customizations by your partner might add even more. This documentation focuses on the standard Paragraph types available with YMCA Website Services and how to use them.
1.5.1 - 1 Column
Embeds a single column of content into a container, with an option to embed reusable content.
Examples
Rose - Without Block
Rose - With Block
Carnation - With Custom Block
Areas 1 Column Should Be Used
Content Area
Sidebar Area
Bottom Area
How to Use 1 Column
After selecting “1 Column” from the paragraphs dropdown, you will notice the following fields:
Paragraph title (optional)
Checkbox (optional, for horizontal rules)
Description (required)
Details on each field are below.
Paragraph title adds an all-caps heading at the top of your paragraph. This is optional.
The checkbox adds dual horizontal rules. Check this only if you’re planning on using the paragraph title.
Description (required) - Adds simple text
through a text editor. Font color defaults to purple in Lily and Rose.
Custom Block Feature
While the paragraph can be used only with the fields above, 1 column also supports custom blocks of content. For this paragraph type, it’s recommended that users stick with “Simple block” types.
When adding your custom block, use the font-awesome icon class instead of the custom icon image field. In Carnation, the image option tends to get too large.
Content editors who want to edit this CSS can ask their developers to install the
CSS Editor module and edit their styles directly from the User Interface.
Add two equal-width, reusable blocks of content, side-by-side. The left side stacks on top of the right side for mobile. In the Lily theme, the left column is 8 units wide and the right column is 4 units wide.
Examples
Carnation
Lily
Rose
Areas it Can Be Used
Content Area
Bottom Area
How it Works
Select “Two Columns” from the paragraphs dropdown.
Insert a custom block into the Left and Right Column.
There is an optional checkbox to display a horizontal rule above the two columns.
If you want to add multiple rows of content with 2 columns, add a new 2 columns paragraph for each set of two you want (e.g., if you have five blocks of content, add three 2 columns paragraphs).
Add three equal-width, reusable blocks of content side-by-side. Columns stack top to bottom on mobile devices for optimal viewing.
Examples
The 3 Columns paragraph provides a way to display content in a visually appealing and organized manner. Here are a few examples of how it looks in different themes:
Carnation
Lily
Rose
Areas It Can Be Used
The 3 Columns paragraph can be used in the following areas:
Content Area
Bottom Area
How It Works
The 3 Columns paragraph allows you to create a row with three custom blocks of content. Here’s how to use it:
Select 3 Columns from the Paragraphs dropdown.
Title: Add an optional title. The title will appear in all caps at the top of the 3 columns section.
Add custom blocks to the Left Column, Center Column, and Right Column fields.
Out of the box, the Title field in each custom block renders as plain text. To work around this, add your headers directly within the text editor of the custom block.
See the Advanced section for details about how to address this with CSS.
If you want to add multiple rows of content with 4 columns, add a new 4 Columns paragraph for each row. For example, if you have seven blocks of content, add two 4 Columns paragraphs (the second one will only have 3 columns populated).
In all three themes currently in YMCA Website Services (Lily, Rose and Carnation), the Title field’s default styling may appear similar to the body copy. To override this and apply a more prominent style, target the .field-sb-title CSS class in your theme’s stylesheet.
Carnation: Columns Stacking on Desktop
By default, the 4 Columns paragraph may not render correctly in the Carnation theme, with columns stacking vertically instead of horizontally on desktop. To fix this, the .wrapper containing the column elements needs to be changed to .row using CSS.
This paragraph type embeds a block. The specific block used determines the functionality and appearance of the Activity Finder. Multiple Activity Finder block types exist, including:
Activity Finder Block: (deprecated) Original Activity Finder
Activity Finder Search Block: (deprecated)
Activity Finder v4: Latest Activity Finder, uses Vue.js.
This paragraph type requires an integration into a CRM. See
Program Activity Framework for a list of existing integrations. Any other CRM will require custom developer work.
How you use these paragraphs will depend on how your Association has structured its program data on the CRM and on how you decide to get people to program results.
To start, add the Activity Finder Paragraph or Block to a page.
Warning: This paragraph is deprecated and provides similar functionality to the “Location filter by amenities” paragraph. It is no longer recommended for use by the YMCA Website Services Core Team. Consider using the “Location filter by amenities” paragraph instead.
What It Does:
Shows a list of branches with icons indicating the amenities available at each branch. Includes a checkbox field to filter branches by amenities. This is implemented via the lb_branch_amenities_blocks module.
Areas Where It Can Be Used:
Content Area
Bottom Area
How to Use It
After selecting “All Amenities” from the paragraphs list, you can change the title that displays above the search checkboxes by entering text in the Title field.
Styling can differ greatly based on the theme. Use of this paragraph in Rose is not recommended.
Add large, full width images to the top of your page, along with a title, optional description and optional link.
How to Use a Banner
To add a banner, select Add Banner from the paragraphs dropdown in the Header Area of your content. Then, fill out the following fields:
Title (required): This field adds a headline to your banner. The placement of the title will depend on your theme and customization, but it will typically appear as large, all-caps text.
Color (required): The background color for your banner. You typically will not see this color in Lily or Carnation, but in Rose, it will display behind your text. Choose from the list of available options. This references the Color vocabulary.
Description (optional): Displays beneath your Title. You have the option to style your text using the text editor, but it’s not as consistent as other places where you typically see the editor.
Recommendation: Just enter basic text and don’t do anything beyond basic styling, such as bold or underline.
Image:
Use the image library to embed an image. You can upload a new image from your computer or reuse an existing image from your library. The image field is optional, but recommended.
For recommended image sizes for your YMCA Website Services site, talk to your agency partner.
How to add/edit images >
Link/Button: Add a URL and a link to the button on the page. The button on your banner cannot be styled without custom CSS/code. [Using link/button fields ⇒](../../text-editor/building-buttons)
Note: If you know a little CSS, you can have your agency partner [install the CSS Editor](
https://www.drupal.org/project/css_editor) module, and you can target .btn.banner-btn to change the default button.
Add a section with teaser cards that link to blog posts. Includes optional dropdown search fields.
Examples
Carnation
Lily
Rose
Areas it Should Be Used
Content Area
Bottom Area
How to Use Blog Posts Listing
From the paragraphs dropdown, add Blog Posts Listing.
Enter a header title for the section in the text field.
Hit Save.
This paragraph allows you to display a listing of blog posts with optional search and filtering capabilities. The appearance and available options might vary based on the theme (Carnation, Lily, Rose).
Add a horizontal menu beneath the Header Area on a camp page.
Examples
Carnation
Lily
Rose
Areas It Can Be Used
Header Area
How It Should Be Used
Before adding the paragraph, create the menu you want to use. You can create a new menu at Admin > Structure > Menu > Add menu (/admin/structure/menu/add).
After creating the menu, add links to it by navigating to Admin > Structure > Menu > [Your Menu] > Add link (/admin/structure/menu/manage/[your-menu-name]/add).
To add additional links to your menu, click on the Add Another Item button.
Once you’re done adding your menu links, scroll down to the Header Area and add the Camp Menu block via Layout Builder. Click Save.
Note - While it is technically possible to position the Camp Menu above your banner image, it is not recommended. The Camp Menu has layout issues on desktop in the Carnation theme, and in all themes it can be hard to distinguish the Camp Menu from your main navigation.
Mobile Considerations for Camp Menu
When a user views your Camp Menu on mobile, the menu doesn’t collapse; it merely shrinks. Menu items either disappear or wrap onto a new line if they do not fit the space.
It’s recommended you limit your menu items to no more than 3 or 4 unless you opt to customize the styling.
Embed horizontal cards for program subcategories on a programs page.
Examples
Carnation
Desktop
Mobile
Lily
Rose
Areas It Should Be Used
Content Area
How To Use It
On a
Programs page, go to the content area and click to open it.
Select Categories listing.
This paragraph can only be used on programs pages that have
subcategories tied to them. If a program has no subcategories tied to it or if it’s used on another content type, it will not work.
Unformatted, unrestricted text that supports any HTML tag and can be embedded anywhere. Great for embedding iframes, third-party scripts, and other custom HTML.
Examples
YMCA of Central Kentucky / Daxko Schedules iframe
YMCA of Middle Tennessee / GroupEx Pro Script
Areas It Should Be Used
Content Area
Sidebar Area
Bottom Area
How to Use Code
Select “Add Code” from the paragraphs dropdown.
You will see two options: “Add Custom Block” to create a new code block, or an autocomplete field to search for and embed an existing custom block.
To search for an existing custom block, type the name of the block in the autocomplete field and click on an option that appears to embed that block.
To add a new block, click the “Add New Custom Block” button.
When you add your block, you will see a blank, unformatted text field. Type your HTML text into this field.
Important Considerations When Using Code Blocks:
To use code, you must add HTML tags.
Hard returns will be ignored, and text will be printed out in one long string. Use HTML line breaks (<br>) or paragraph tags (<p>) to format your text.
Code will not highlight or color-code your HTML. To display code snippets with syntax highlighting, consider using a different paragraph type or a dedicated code highlighting library.
There is an option to change to a “Full HTML” text editor within the block configuration, which will allow you to make use of the default text editor. However, using this may strip “faulty” or disallowed HTML out of your block and may prevent you from using certain tags. Exercise caution when using the “Full HTML” editor for code blocks.
Once you’re done, click the button that either says Add custom block or Update custom block, depending on the option you had selected at first.
Schedule different sections to show or hide on your pages based on date and time.
Areas Where Date Blocks Can Be Used
Header Area
Content Area
Sidebar Area
Bottom Area
How to Use Date Blocks
In the desired content area, choose Add Date Block from the list of paragraphs in the dropdown menu.
You will then see two options: Add New Custom Block or Add Existing Custom Block.
Add New Custom Block
If you are using Date Block for the first time or want to create a new, unique date block:
Choose the Add New Custom Block option.
Enter a descriptive Label for your date block in the Block description field.
This label is for administrative purposes and will help you identify the block when reusing it on multiple pages. It is not displayed on the front end of the site.
Enter a Start Date and End Date for your block.
The content within the date block will only be visible between these dates, similar to how content types can be scheduled for publishing and unpublishing.
Add paragraphs to the designated areas to display content Before, During, and After your scheduled dates.
Use the corresponding fields and add paragraphs as you normally would.
If you do not want content to display before, during, or after your specified time period, leave the corresponding field blank.
Click Create custom block to save your date block.
Add Existing Custom Block
To reuse a date block that you have previously created:
Click the Add Existing Custom Block button.
Enter the Label of your block into the autocomplete field.
Select your block from the options to add it to the content area.
Editing a Date Block
To edit a Date Block:
Click Edit next to the paragraph where the Date Block is located.
Click the second Edit button that appears next to the name of your date block.
Make the desired changes within the block.
Click Update Custom Block to save your changes.
Any changes made to a date block will be applied to every page where that block has been added.
To add another Question and Answer, click the Add another item button at the bottom of your paragraph.
Structured Data for SEO
If your FAQ contains Frequently Asked Questions, consider enabling the “FAQ?” option within the paragraph to output them as structured data. This can improve your site’s visibility in search engine results. Ensure the content contains individual sets of questions and answers.
Display a curated list of blog posts on a page. This paragraph allows you to hand-pick the blog posts you want to highlight.
Examples
This paragraph is rendered differently depending on the theme. Here are some examples:
Carnation
Desktop
Mobile
Lily
Desktop
Mobile
Rose
Desktop
Mobile
Usage
When to Use
The Featured Blog Posts paragraph is ideal for:
Highlighting specific blog posts that are particularly relevant.
Creating a curated resource page of top blog content.
Drawing attention to older blog posts that are still valuable.
Areas It Can Be Used
This paragraph can be used in the following areas:
Content Area
Bottom Area
Configuration
Adding Featured Blog Posts
Add a Featured Blog Posts paragraph to the desired content type.
In the Headline field, add a title for the featured blog posts section. This is optional; if left blank, a default title of “Latest news & Updates” will be used.
In the autocomplete field, begin typing the name of the blog post you want to feature.
Select the desired blog post from the suggestions that appear.
Repeat steps 3 and 4 to add additional blog posts.
To add more blog posts, click the Add another item button.
Click the blue Save button at the bottom of the page to save your changes.
Available Fields
Field
Machine Name
Required
Description
Headline
field_prgf_headline
No
Title of the featured blog posts section.
Blog Posts
field_fblog_posts
Yes
References to the blog posts you want to feature. Supports multiple blog posts.
Supported Content Types
The “Featured Blog Posts” paragraph can be added to the following content types:
Select the number of columns you would like to have in each row using the style dropdown.
Carnation: Due to the card styling in Carnation, this field does not limit the number of cards that will display in a single row. A recommended workaround is to add multiple rows of featured content or
use the Grid Content paragraph type.
Advanced users: You can clear the confusion for content editors in Carnation by making the style field an optional field and hiding it in the form display in the UI.
Additionally, you can limit the number of columns to four in the Featured Content’s paragraph settings.
Finally, add content for each column of content using the text editor. To add additional columns click the “Add Another Item” button.
Lily/Rose: Adding more columns than what you selected in the “Style” dropdown will create additional rows. Aligning each column’s content is not recommended unless you are not using any other field.
Below the link field, you will add your images. Click on the Add images button to select the pictures for your gallery. You can upload an image to the media library, or select multiple images from your library.
Once you’ve uploaded/selected your images, click that blue Add images button at the bottom.
To order your images, hover your mouse over the thumbnail in the “Images” section, and then drag them to reorder. You will see a cross-arrow icon when you’re dragging them around, similar to what you see when you reorder paragraphs.
To delete a photo from the gallery, click the delete button below the image.
Embed one or more rows of up to four columns of content - each with a title, icon, description, and link.
Examples
Carnation
Lily
Rose
Areas It Should Be Used
Content Area
Bottom Area
How to Use Grid Content
Note on Grid Content: This paragraph’s style will vary greatly depending on your theme. The docs outline how to use the fields.
First, choose Grid Content from the Paragraphs dropdown. You will then see a dropdown with options under Style, determining the number of items per row:
2 items per row
3 items per row
4 items per row
Select a style to choose how many sections/cards you want to display in a row; the more items per row, the narrower they will be.
Examples
2 Items Per Row
3 Items Per Row
Next, you will see a button that says Add Grid Columns. Click this button to add individual sections/cards.
For each item you add, you will have the following fields:
Headline (optional) - A title for your section. The size will vary depending on your selected style and theme.
Icon (optional) - An image to display inline with your headline. Upload a new image or use one in your image library.
Icon Class - A
Font Awesome icon CSS class. Type the name of the class, and the system will generate the icon.
Description - A standard text editor field. Because of how each grid content item is styled, it’s recommended that the text in this field be shorter than 200 characters.
Embed a listing of blog posts with optional filtering by Branch or Camp.
These paragraphs embed a listing of blog posts, sorted by the most recent, in a card design. They utilize a dynamic paragraph that renders blog posts.
Latest Blog Posts: Shows the most recent blog posts across your entire site.
Latest Blog Posts (Branch): Filters the most recent blog posts by the branch the paragraph is embedded on. For example, if placed on a “Downtown YMCA” page, only “Downtown YMCA” blog posts will be displayed. If placed on a non-branch page, only the headline will be shown.
Latest Blog Posts (Camp): Filters blog posts by the camp the paragraph is embedded on. For example, if placed on a “Camp Widjiwagan” page, only “Camp Widjiwagan YMCA” blog posts will be displayed. If placed on a non-camp page, only the headline will be shown.
Areas it Should Be Used
Content Area
Bottom Area
How to Use Latest Blog Posts
From the paragraphs dropdown, add Latest Blog Posts, Latest Blog Posts (Branch), or Latest Blog Posts (Camp).
Enter a header title for the section in the text field.
Save the paragraph.
Unlike the related
Blog Posts Listing, this paragraph does not include filters for searching blog posts.
Embed a listing of news posts with optional filtering by Camp/Branch.
These paragraphs embed listings of news posts, sorted by the most recent, in a row/listing design. There are three variations:
Latest News Posts: Displays all the most recent news posts across your entire site.
Latest News Posts (Branch): Filters news posts by the branch on which the paragraph is embedded. For example, if placed on a “Downtown YMCA” page, only “Downtown YMCA” news posts will be shown. If placed on a non-branch page, only the headline will be displayed.
Latest News Posts (Camp): Filters news posts by the camp on which the paragraph is embedded. For example, if placed on a “Camp Widjiwagan” page, only “Camp Widjiwagan YMCA” news posts will be shown. If placed on a non-camp page, only the headline will be displayed.
Examples
Carnation
Rose
Areas to Use
Content Area
Bottom Area
How to Use Latest News Posts
From the paragraphs dropdown, add the desired “Latest News Posts” paragraph type. Enter a header title for the section in the text field, and save.
Add an anchoring element to the bottom of a page, similar to a small banner. Best for promotional offers.
Example
Areas Where It Can Be Used
Bottom Area
How to Use Limited Time Offer
Go to the Bottom Area and select Limited Time Offer. Fill in the Title field for your main headline, and if you would like to add a subheader below the title field, use the Subtitle field.
The Membership Calculator paragraph adds an interactive “membership wizard” to a YMCA Website Services site, allowing users to explore membership options and pricing.
The Membership Calculator paragraph can be added to these areas of a content page:
Content Area
Bottom Area
How to Use the Membership Calculator Paragraph
When editing a page, locate the paragraphs dropdown within the desired area (Content or Bottom).
Select Membership Calculator from the dropdown.
No additional configuration is typically needed on the page itself. The calculator pulls its data from configured
Membership Content Type items.
1.5.24 - News Posts Listing
Add a filterable section of news posts to a page.
Areas it Should Be Used
Content Area
Bottom Area
How to Use News Posts
From the paragraphs dropdown, add the News Posts Listing. Enter a header title for the section in the text field and hit Save.
Note: Advanced users can make changes to the exposed fields using the Views module and the paragraphs settings. This requires advanced knowledge of Drupal’s Views and Paragraphs modules.
It is generally not recommended to use the News Post Listing on Branch, Camp or Facility pages due to the availability of the Latest News Posts/(Camp)/(Branch) paragraph.
Add a small individual card to the sidebar of a page with evergreen promotional content, such as links to join pages.
Examples
The Promo Card comes in three default color variations: Carnation, Lily and Rose.
Carnation
Lily
Rose
Areas It Should be Used
Sidebar Area
How to Use the Promo Card
In your sidebar area, select Add Promo Card from the paragraphs list.
The Promo Card has the following fields:
Title: (Optional) A large title that appears at the top of the card. (Machine name: field_prgf_title)
Headline: (Required) A smaller headline that appears below the title. (Machine name: field_prgf_headline)
Description: (Optional) A WYSIWYG text editor field for entering content. Standard text editor options are available. (Machine name: field_prgf_description)
Display programs in a schedule view with an optional PDF export.
Sometimes called “Group Exercise” or “Group Schedules”, the Repeat Schedules block provides a similar view to Activity Finder, but focused more on recurring, often drop-in classes.
Add a bottom area element with two columns of reusable content for anchoring a page.
Warning: This element does not work properly in the Carnation theme and is considered deprecated. It may be removed in a future update.
Overview
The Secondary Description and Sidebar paragraph type provides a two-column layout in the bottom area of a page. It allows you to insert reusable content blocks into a left and right column.
Fields
Name
Machine Name
Required
Description
Left Column
field_prgf_left_column_block
No
Block reference to: Basic Block, Code Block, Date block or Simple Block. Create a new one or pick up an existed block. Content placed here typically serves as a secondary description for the page.
Right Column
field_prgf_right_column_block
No
Block reference to: Basic Block, Code Block, Date block or Simple Block. Create a new one or pick up an existed block. Content placed here typically serves as a sidebar with related information or calls to action.
Example
Carnation
Lily
Rose
Areas it Should Be Used
Bottom Area
How to Use Secondary Description and Sidebar
Insert the paragraph from the dropdown menu into the Bottom Area of your page.
You will see two fields: Left Column and Right Column.
Within each column, you can select from one of four different custom block types:
Basic Block
Code Block
Date Block
Simple Block
You can either add a new custom block or reuse an existing block.
Note: When reusing blocks in this paragraph type, the icon field may not render correctly. Font Awesome icons might display as plain text. If you need icons, consider using inline images.
1.5.28 - Simple Content
Add a section of basic text onto a page.
Areas It Should Be Used
Content Area
Sidebar Area
Bottom Area
How to Use Simple Content
The Simple Content paragraph allows you to add and format text using the WYSIWYG editor. This provides a flexible way to add basic content to your pages.
From the paragraphs dropdown within the desired area (Content, Sidebar, or Bottom), select Add Simple Content.
A text editor will appear. You can style your text using the editor’s toolbar. This toolbar typically includes options for:
A wide, short image with fields for a title, background color, description, and image.
Examples
Carnation
Desktop
Mobile
Lily
Desktop
Mobile
Rose
Desktop
Mobile
Areas It Can Be Used
Header Area
Content Area (1 column only)
Bottom Area
How to Use a Small Banner
Select Add Small Banner from the paragraphs dropdown.
Fill out the following fields:
Title (required): This field adds a headline to your banner. The placement of the title depends on your theme and customization, but it typically appears as large, all-caps text. The character limit for this field is 255.
Color (required): The background color for your banner. In Lily and Rose, this background color displays behind your title and description.
In Carnation, you will not see the background color unless you add an image.
Description (optional): Displays beneath your Title. You can style your text using the text editor; however, it’s not as consistent as other places where you typically see the editor.
Image (optional, but recommended): Use the image library to embed an image. You can upload a new image from your computer or reuse an existing image from your library. For best results, consult with your agency partner regarding recommended image sizes for your YMCA Website Services site.
Note: Image Upload does not work in Rose.
Note: Unlike
the Banner, Small Banners don’t have a specific Link field for buttons without customization.
To add a button to a small banner, use the
Text Editor button tool to create a button in your description field.
Add a simple card to the sidebar with a title, headline, and call to action.
The Story Card Paragraph works best with the Lily and Rose themes. It is available, but not themed with a border in Carnation.
Areas it Can Be Used
Sidebar Area
How to Use It
In the sidebar area of a content page, select Story Card.
Add a Title and Headline. The Title will be larger than the Headline and display above it.
Add your link in the Link field. Unlike most paragraph types, the link field does not create a button or standalone link; the entire card becomes the link. The link text is required. The link will not stand out like a typical call to action.
To work around this, add a > or another special character to indicate to users that they are clicking on a link.
Recommendations for use with Carnation
While this component is available to use in Carnation, it is not themed with a border as in Lily or Rose. The best practice is to use this paragraph sparingly and only in the following content types:
Facility
Event
In Carnation, the Story Card works best inside the News Post, Event, and Blog Post paragraphs.
Advanced
Note: In the headline area on Lily and Rose, a large quotation mark will display to the left of your headline. This can be easily disabled using the following CSS:
Add a wide feature with an image, text, and a call to action.
Overview
The Teaser paragraph is a versatile component designed to highlight key content. It typically includes an image, a title, a brief description, and a call-to-action link. It can be used to promote specific programs, services, or events.
Examples
The appearance of the Teaser paragraph can vary depending on the theme:
Carnation
Lily
Rose
Areas It Should Be Used
Content area
How to Use the Teaser Paragraph
Insert the paragraph: From the content area, select “Add Teaser” from the paragraph dropdown menu.
Fill in the content fields:
Title: Enter the title of the teaser. This should be concise and engaging.
Image: Select an image from the
image library or upload a new one. Use high-quality images that are relevant to the content.
Description: Add a brief description using the
Text Editor. Keep the description concise and focused on the key benefits or information.
Link: Add an internal or external link. This is the call to action. Use a clear and direct call to action in the link text (e.g., “Learn More,” “Register Now,” “View Details”). The Link field supports adding attributes:
URL: The destination URL
Title: The link text for the button.
Target: Open in a new window.
Rel: “Nofollow” or “Sponsored”.
Class: Add custom classes if needed.
Save: Save the page to view your Teaser.
Best Practices
Use compelling imagery that is relevant to the content.
Write concise and engaging titles and descriptions.
Use a clear and direct call to action in the link text.
Ensure that the linked page provides more detailed information related to the teaser content.
1.5.33 - Webform
Add an existing Webform to a page.
Areas it Should be used
Content Area
Sidebar Area
Bottom Region
How to Use Webform
Prerequisite: You must have your web form created before embedding it onto a page. You can continue to revise and edit your form after embedding, but this process will NOT create a webform for you.
Once you’ve selected Webform from the paragraphs dropdown, select the name of the webform you want to embed onto your page.
Next, you will have the option to open, close, or schedule open/close dates for your webform.
The “Default submission pairs” field allows you to pre-populate certain fields in your webform with default values if users leave them blank. Unless you have advanced knowledge of YAML, it is not recommended to configure this field.
Group pieces of related content together for tagging, filtering, sorting, and grouping.
Taxonomy, in YMCA Website Services, is a system for classifying and organizing website content. It uses organized lists of categories to group content, create folders for Images (
in YMCA Website Services 2.4 and later), and create standard options for dropdown fields. Think of it as a way to tag, filter, sort, and group your content.
Each list of categories is called a Vocabulary, and each individual category within a vocabulary is called a Term. Terms consist of a Term Name and can include additional data or settings specific to that vocabulary (see Vocabularies in YMCA Website Services for details). Taxonomy terms are an entity type
How to Edit Vocabulary Lists
Go to Structure > Taxonomy.
Find the Vocabulary you want to edit.
Click List Terms.
You can rearrange your terms by hovering your mouse over the cross icon and dragging them. This determines the order in which they appear on your website. By default, terms are displayed alphabetically if no specific order is set.
Moving a term to the right will “nest” it underneath another term, creating a parent-child relationship. The nested term becomes a “child” of the term above it. This allows you to create hierarchical taxonomies.
Adding/Editing Terms
To edit an existing term, click Edit.
To add a new term, click Add Term.
On the next page, you can add a Name for your vocabulary and an optional Description.
Below those two fields, you can add additional information unique to your vocabulary. The available fields will depend on how the vocabulary is configured.
Term Example - Grey Color
The Color Vocabulary provides a standard list of color options across your website, such as for a background color for your header.
To change the shade of grey:
Go to Structure > Taxonomy > Color.
Click List Terms.
Click Edit next to Grey.
Below the name of the Grey term, you’ll find a color widget where you can change your standard shade of Grey across your site.
In this example, you can change the color of the Grey term in the Color Vocabulary using a Color widget.
Vocabularies in YMCA Website Services
Vocabularies are lists of categories. How they are used and displayed depends on the specific vocabulary. Here are some common vocabularies in YMCA Website Services:
Amenities
Used for tagging
branches with amenities (e.g., “Pool,” “Sauna,” “Gym”). Amenities are displayed on the branch page and can be used as filters on a locations page.
Color
The Color vocabulary provides a list of colors for use across your site, primarily in page headers,
small banners,
galleries, and
banners. Using a standardized color vocabulary ensures brand consistency.
Blog/News Category
These vocabularies are used to tag blog and news posts. Categories are often displayed in the sidebar and as filters in the
Blog Post Listing and
News Posts Listing paragraphs, respectively.
Media Folders
This vocabulary creates folders for organizing images in the media browser.
This vocabulary creates tags for filtering images (YMCA Website Services 2.3.3 and earlier), documents, and videos in the media browser. Using tags helps you organize and find media assets more easily.
The media library stores images and files, allowing you to have custom cropping, focal pointing, folders, and image styles.
Media Items and the Media Library
Core media items include audio, images, documents, and videos. You can add other media types, such as social media posts, through contributed modules. Media items may be files located in your site’s file system or remote items referenced by a URL. Media items are content entities divided into media types (which are entity sub-types); media types can have fields. The media library is a visual user interface for managing and reusing media items. Add media items to content using Media reference fields and the Media library field widget.
An image style is a set of processing steps, known as effects, that can be applied to images. Examples of effects include scaling and cropping images to different sizes. Responsive image styles can associate image styles with your theme’s size breakpoints. This allows serving images sized for the browser width.
Modules that provide media-related functionality include:
The core Media module manages media items and media types.
The core Media module provides a Media reference field to add media to content entities. The core File and Image modules also provide reference fields. It is recommended to use the Media reference field because it is more versatile.
The core Media Library module provides the media library and the Media library field widget. With this module installed, the Media library field widget becomes the default widget for editing Media reference fields.
The core Image module provides a user interface for defining image styles. The core Responsive Image module provides responsive image styles. Using the core Breakpoint module and a breakpoint-enabled theme, these responsive styles can serve images sized for the browser.
Video Tutorials
Learn more about media management in the distribution. Some of these videos use older versions of the distribution.
Your YMCA website has the ability to upload media (images, documents, videos) in bulk (since
9.2.12 - December 2022).
You can batch/bulk upload from Admin > Content > Media (/admin/content/media) or Media Browser (/admin/content/browser). After uploading media, it will be available from the Media list and browser in any component on your site.
From the Media list
Go to Admin > Content > Media (/admin/content/media)
Click Upload media in bulk
Choose your media type
Drag or choose the media to upload
Fill in the required fields in the resulting form.
From the Media browser
Admin > Content > Media Browser (/admin/content/browser)
Click Add media
Choose your media type in the sidebar, then use the Choose Files button to choose or drop files.
Fill in the required fields in the resulting form.
1.8 - Webforms
Beyond just a basic contact form, Drupal’s robust webforms features allow you to build interactive webforms with logic-based questions, built-in animation fields, and a submissions manager.
Because this is one of the most well-documented applications in the Drupal community, we recommend using the documentation provided by the maintainer of the Webform module, Jacob Rockowitz.
Virtual YMCA allows members and other authorized users to enjoy exclusive content from their local Y.
After members log in to your website, they can browse a diverse selection of gated content—on-demand videos, written content, and live events—from any device.
Below are links to various videos and documents providing basic setup and management information for your new Virtual Y environment. Choose the format that best suits your learning style.
1.9.1 - Building Blocks & Basics
Virtual YMCA (VY) is based on Open Y and was originally built as an extension for Open Y sites. Therefore, it shares many of the same underlying functionalities and concepts.
Virtual YMCA utilizes the same content editing tools as Open Y. However, the pre-configured features and modules available “out-of-the-box” may differ from a standard Open Y installation. It’s best to review the specific modules enabled in your VY instance, such as the ones provided by the ws_small_y module collection (see below), to understand its capabilities.
Content Types
Virtual YMCA comes with several content types designed for delivering exclusive member experiences. These content types are typically accessible behind a login.
Virtual Y Video
Reach your members even when they’re away from the physical Y. Provide on-demand classes, kids’ activities, and other engaging video content. This is an excellent option for health seekers, families, and active older adults.
Stream your popular classes and events to members in real-time. Live Streams are well-suited for events where audience interaction is minimal.
Live Streams can be added individually or scheduled on a recurring basis. Unlike Virtual Events, Live Streams are embedded directly within the Virtual Y site.
Integrates with: YouTube and Vimeo
Virtual Events
Host interactive group fitness classes and other live events with member participation. Virtual Events are ideal for classes with Y instructors and personal or small group training sessions.
Virtual Events can be added individually or on a recurring basis. Unlike Live Streams, users are directed to an external video link for Virtual Events.
Integrates with: Any URL/link, including GoToMeeting, Google Meet, Microsoft Teams, Zoom, Instagram Live, and Facebook
Blog Posts
Provide members with written workouts, recipes, activity suggestions, and other engaging content. Blog Posts are perfect for members who prefer self-guided activities and need inspiration.
Virtual Y Blog Posts can be added via the standard Add Content list or menu within the Drupal interface.
No integrations required.
Small Y Module Collection
The ws_small_y module and its submodules provide a collection of features that customize the appearance and functionality of smaller Y associations. These modules can include enhanced article displays, staff directories, and customized styling. Review the list of enabled modules within the ws_small_y collection on your site to understand the features available.
1.9.2 - Authentication Providers
The authentication options available for gating your content depend on your Customer Management System (CRM). Currently, the following options can be used to control access to content within the Virtual Y website.
Personify
Single Sign-On (SSO)
Requires members to log in using their existing Personify CRM credentials.
Daxko
Single Sign-On (SSO)
Requires members to log in using their existing Daxko CRM credentials.
Note: Daxko API access is required and may incur API usage fees from Daxko. Contact Daxko for details on API access and associated costs.
Barcode Validation
Requires members to enter their barcode. The Virtual Y site validates the barcode against the Daxko system before granting access.
Requires members to log in using their existing ReClique CORE CRM credentials.
CSV File Uploads
Allows associations to upload a CSV file containing membership information to grant access. Two options are available:
CSV Upload without Email Verification
Upload a CSV file containing member email addresses. The Virtual Y site validates the entered email address against the uploaded list before granting access.
CSV Upload with Email Verification
Upload a CSV file containing member email addresses. The Virtual Y site sends a verification email to the address provided. The member must click the link in the email to gain access.
1.9.2.1 - Daxko Barcode Authentication
Open Y Gated Content (Virtual Y)
release 0.13 includes a new authentication provider to support Daxko Virtual Areas. This allows associations using Daxko to set up Virtual Areas that enable members to access Virtual Y content using only their member barcode.
Instructions for setting up Virtual Areas are in
Daxko’s documentation. If you need assistance configuring Virtual Areas, Daxko’s support team can assist you with setup:
support@daxko.com.
Configuration
Enable Daxko Barcode Virtual YMCA integration.
OPTIONAL (but highly recommended): Configure reCaptcha settings at /admin/config/people/captcha/recaptcha.
Add your validation secret and form URL, and check the help messages at /admin/openy/virtual-ymca/gc-auth-settings/provider/daxkobarcode.
Save your settings.
Set Daxko Barcode as your main authorization plugin in the Virtual YMCA settings: /admin/openy/openy-gc-auth/settings.
Once enabled, the module allows granular configuration of messages that users will receive on the page. You can change “Barcode” to something different, like “Member ID”, and add help text to assist members in finding their ID. It also allows for global help text to direct members to help channels if they’re unable to log in.
Once the module is enabled, members will be presented with the appropriately titled field to log in to Virtual Y.
Upon success, the user will be logged in to Virtual Y. Upon failure, the failure state will be returned along with a help message provided by the association.
Notes
Members with a Balance Due
Anyone with a balance due in Daxko doesn’t have access to Virtual Y [via Daxko Barcode]. A lot of the accounts with balances are families with memberships who receive state scholarships for child care. The balance in Daxko is the portion the state pays, so it’s a bit of a “fake” balance. Is there any way to allow any ACTIVE member to use [Virtual Y], regardless of whether they have a balance or not?
The fix:
There’s a setting on the Daxko Operations virtual area at Membership > Virtual Area > Virtual Y > Edit that you can check/uncheck for “Block access when balance due.” Unchecking that should let the member access the virtual area.
1.9.2.2 - ReClique SSO Configuration
The ReClique Core API enables check-in access by specifying a member’s email address. The following steps are necessary to fully configure the ReClique Provider for your Virtual Y site.
Acquire ReClique Core API Access
To get started, you will need to perform the following steps in the ReClique CORE portal, while logged in as a YMCA super admin user:
Locate and note your YMCA association’s YMCA ID, known within the ReClique CORE documentation as the “Association Slug”.
Create a separate user for executing the ReClique CORE authentication API and grant this user API-level access.
In Detail:
Log into the ReClique Core portal using a user with the YMCA super administrator role.
Click Profile in the top-right corner of the CORE portal.
The YMCA ID is the non-numeric part of the “Association Slug” in front of the numeric user ID. Note this value for use in the Verification URL. In this example, the text midtn is the association slug value and is needed for the YMCA ID.
Click Users from the navigation menu (Users > Add New User).
Select the + Add User / Staff button.
Create a stand-alone user for the purpose of executing API calls only. A suggested name is virtual_y, but any suitable name can be used.
Assign this user the API Access role by selecting Use Core API in the Other list of role options.
Configure the Virtual Y ReClique Provider
To enable the Virtual Y site to communicate with the ReClique Core API, you’ll need to configure the ReClique provider.
Navigate to the Gated Content Auth Setting Page at Manage > Virtual Y > Virtual YMCA Settings > GC Auth Settings.
The GC Auth Settings page, when loaded, will look like this:
Find the ReClique Provider option and click the Edit Action.
Enter Your ReClique Provider Settings.
The ReClique Provider configuration page allows the specification of permission mappings, settings for accessing the ReClique CORE authentication API, and Email Verification settings.
Specify Permission Mappings
This is used for User Segmentation. User Segmentation will allow YMCAs to segment content to particular Virtual Y roles based on membership types. Refer to documentation from the Open Y Community for more information about
Setting up user segmentation.
Add ReClique CORE API settings
Add the values needed to connect to the ReClique Core API.
Field
Value
Verification URL
The API endpoint provided by ReClique to verify member logins. It takes the form https://{Y_ID}.recliquecore.com/api/v1/members/virtual_y/?Email= (This is the Production verification URL).
Authentication login
The login for the dedicated user created with ‘Use Core API’ access in the ReClique Core portal.
Authentication password
The password for the dedicated user created with ‘Use Core API’ access in the ReClique Core portal.
ID field text
The text to be displayed on the Virtual Y login form. The default value is “Enter your Email:”.
Specify the Email Verification options
This enables a one-time login link to be sent to the member’s email for verification. Here, you can configure the length of time the login link will last before needing to generate another, email verification text, and a message displayed to the member with instructions on how to proceed with logging into the Virtual Y site.
Specify the Verification Message
This is the message the member will see when logging in if they are inactive. The phone number must be added at the very least.
After configuring the ReClique provider, click Save.
From the GC Auth Settings page, ensure only ReClique Provider is selected and click Save.
Your ReClique Provider is now fully configured and ready for use.
To test, log out from the admin portal. You should now see your new login form configured and ready to accept input from the Home Page.
If a valid email address is entered and the member is active, the member will be allowed access to your gated content (videos, blog posts, virtual meetings).
1.9.3 - Video Support & Hosting
Virtual Y supports embedding videos from the following sources. The supported source depends on the content type:
On-demand Video
YouTube
Vimeo
Live Stream
YouTube
Vimeo
Virtual Meeting
As a “Join” button
Any external link, including Facebook
Zoom meetings (embedding is no longer supported)
Video Provider Specifics
Each video provider has its benefits. We’ve provided this list to help you decide where to start.
YouTube videos smaller than 1280x720px (aka “720p”) may not display a thumbnail properly in Virtual Y. If you upload a larger (greater than 1280x720px) thumbnail using YouTube’s video editor, that should resolve this issue on Virtual Y (until
this issue is resolved).
Setting up a
Brand account for your Y is a good first step in using YouTube for your videos.
The requirements for embedding YouTube Live Streams may change often. Previously, this has required having more than 1000 subscribers on your channel or turning on “Monetization”. It may, at times, be more expedient to use Vimeo for Live Streaming.
Upload and bandwidth limits based on account type.
Truly gated videos with
domain-level privacy. Domain restrictions are NOT RECOMMENDED if you plan on sharing your content with other Y’s using Virtual Y’s “Shared Content” feature.
To facilitate content sharing, we recommend using the Hide this video from vimeo .com privacy option combined with Enable people to embed this video on any site.
Review all of Vimeo’s privacy options.
Most associations have purchased the
“Premium” level to get access to unlimited live streaming.
Vimeo private videos do not allow thumbnails to be generated for your site. If you use private videos on Vimeo, you’ll need to upload a thumbnail using the Teaser Image field on the content.
Facebook
Facebook is not recommended for Virtual Y content, as any meeting there will also be listed publicly.
If you choose to host virtual meetings on Facebook, they will need to be publicly listed; otherwise, it is not possible to create a direct link to the event. To get the link to a public video:
Click the three dots on the bottom right of the video.
Select “Copy Link”.
Zoom
A few notes:
If you are creating a recurring Virtual Meeting, please be sure your Zoom meeting recurrence matches the recurrence on the Virtual Y meeting.
If your Zoom meeting requires a password, we recommend generating a link with the password embedded in it. This usually looks something like ?pwd=... in the link. Please review
Zoom’s updated security settings for more information.
Through many tests, we determined that Zoom embeds are unreliable, and support for that feature has been disabled. Zoom links now display as a “Join” button, which should make for a much smoother user experience.
1.9.4 - Go-live Checklist
Here are some things you should check before you go live with your Virtual Y site:
Ensure that you’ve disabled links to those sections in your Main Navigation.
Review and click through Main Navigation and
Footer links to ensure they’re all valid.
Visit /admin/content and ensure any demo content is deleted or unpublished. This is important to ensure a clean and professional launch.
Visit Virtual Y > Event Series and ensure any demo content is deleted.
Ensure that Virtual Y content is displaying as you expect.
If some content is not displaying, check to ensure all required fields are filled in. While the Description field is not technically required, leaving it empty can sometimes prevent content from displaying.
Review Your Authentication
Review and test your Virtual Y Authentication provider.
If you’re using the Daxko Barcode provider, ensure you’ve set the Message for login failures at Virtual Y > Virtual YMCA Settings > GC Auth Settings > Edit Daxko barcode provider. This message will be displayed to users if their barcode is invalid.
Final Clean-up
If you’re using it, ensure you’ve set up Google Analytics at Configuration > System > Google Analytics.
If you’re using any basic authentication to protect the site before it goes live (what Y Cloud calls “Site Lock”), ask your hosting partner to turn it off. Leaving it on will prevent public access to your site.
If you’d like to share content with other Ys, review
Shared Content and initiate a connection to the Open Y Shared Content server. This allows you to leverage content created by other Ys and share your own.
1.9.5 - FAQs
For up-to-the-minute conversations and info on Virtual Y and its content, join us in the YUSA Slack.
Request access to Slack
Join the
#virtual_ymca Slack channel where you can talk with other Y associations, the YMCA Website Services team, and partners on how to quickly get your Virtual Y experience launched.
The Virtual Y code is free, but using it is not. Your costs come with having a developer configure Virtual Y as well as from hosting. Time estimate: <30 hours if you stick close to the default implementation and don’t make customizations. The more you deviate, the higher the cost. Costs will include:
Implementation
CRM SSO integration
Domain name and hosting
Training and support (will vary based on team’s comfort working with Drupal)
I’m not on YMCA Website Services
Can I use it if I’m not on YMCA Website Services? Yes!
Our website is built in WordPress. Will Virtual YMCA integrate with WordPress?
Virtual Y is built on YMCA Website Services (Drupal). You would build a stand-alone instance of Virtual Y (see agency partner next steps) that could be linked to from your current site. You can work with an agency of your choice or talk with one of our core partners if your current partner does not develop on Drupal. Time estimate is <30 hours if you stick close to the distribution and don’t customize.
What is my next step for Virtual Y if I’m not on YMCA Website Services?
Have a conversation with your current developer or contact one of our featured partners. You may work with your current web developer if they know Drupal. If not, one of our partners or Y-USA will likely be more economical.
How does my internal developer or agency use Virtual Y?
Here are the Agency Partner/Internal Developer Steps:
The login is the same as for the standard YMCA Website Services sandboxes so
let us know if you need that information.
Committed to VY - Initial Technical Set-Up
I already have an YMCA Website Services site, do I need to upgrade to get Virtual Y?
Nope, unless you’re more than a couple of upgrades behind. Our incredible developer team established a structure to allow Ys to obtain Virtual Y without undergoing a full site upgrade, saving both time and $$$. If it has been 12+ months since your last upgrade, we recommend you proceed to keep your site current with the latest features and security. This will reduce future upgrade costs (it’s more expensive to update a site that is multiple versions behind) and help prepare you for Drupal 9, which was released in February 2021.
If your CRM is not listed, we have a workaround solution where you can upload a CSV file of your active members’ email addresses into your Virtual Y site to grant your Virtual Y visitors access to your content. As long as you can export a basic spreadsheet of your active members, your data is likely compatible with Virtual Y.
Will there be impacts to the domain?
There should not be any impact from your domain if you already use YMCA Website Services. If you do not use YMCA Website Services, you can create a subdomain of your choosing, such as virtualy.yourassociationname.org where virtualy is the subdomain.
What Web Browsers are compatible with Virtual Y?
Virtual Y supports the most recent versions of all modern web browsers such as
Edge,
Firefox,
Chrome,
Safari, and
Opera
Internet Explorer 11 and earlier are not supported due to the inability of that browser to play videos from services such as
https://youtube.com. Here is
YouTube’s official statement on not supporting Internet Explorer.
There is demo content for you to test with, but you need to create and post your own content via the platforms mentioned in the next question. Some Ys have shared their content for all to use.
Which platforms can I use to host my content for Virtual Y?
Virtual Y works* with:
YouTube - hosted and livestream
Vimeo - hosted and livestream
Zoom - livestream
Zoom, GoToMeeting and Teams - video conferences
Blogs - any content you post
*Note: “Works with” means technically functional. Each video provider service, such as YouTube, manages its own terms of use, which will guide what’s okay and what’s not.
For Vimeo, is a specific account level needed to host videos to stream/pass through Virtual Y?
Many associations have been buying the Premium level to get access to unlimited livestreaming. Again, the YMCA Website Services Team has no control over Vimeo’s terms of use, and Vimeo’s terms of use are subject to change at any point without prior notice.
Can we keep our YouTube videos unlisted on our channel but still have them play in our Virtual Y?
Yes.
Can we use Facebook video links?
No. Due to restrictions/limitations enforced by Facebook, private videos or videos from a private group cannot be embedded on an external (non-Facebook) site. This means the only option would be to use publicly-facing Facebook Live video within Virtual Y, which can be seen by anyone on Facebook, not just your members. This weakens the case for paying for exclusive access to Virtual Y as a member, and YMCA associations were not interested in YMCA Website Services pursuing this type of Facebook integration.
Can I host Les Mills classes on our Y’s YouTube channel?
Unfortunately, Les Mills licensing does not cover recording the class for rebroadcasting.
Can we use Y360 videos?
Y360 videos are owned exclusively by Y360 and then licensed by Ys. A Y would need to obtain explicit permission from them for usage within Virtual Y. Additionally, YMCA Website Services would first have to build a new integration to accept those videos as on-demand content, because Y360 uses a video hosting service other than YouTube or Vimeo.
Music Licensing
How does music licensing work with this platform?
Music licensing copyrights and restrictions originate with the video platform used (e.g., YouTube, Vimeo) so you need to follow those guidelines. Be very careful to investigate whether the music you use within your branches is OK on livestream workouts.
I’m a live-streaming novice. How do I learn about it?
We’ve got your back. It’s technically possible to do a reasonably good stream with just a smartphone camera. Some associations have opted to invest in more professional technology.
I just heard Y-USA is building a Virtual Y platform. What if I’m already building this with a developer?
Virtual Y is open source software built by the YMCA Website Services. Because this software is open source, it is free for any YMCA to download and use. The Y-USA’s Y Cloud platform uses the Virtual Y module as a plug-and-play standalone micro-site that YMCA Website Services created. Y-USA’s Y Cloud provides Virtual Y as Software-as-a-Service (SaaS) that includes hosting, maintenance and general support of the Virtual Y stand-alone microsite for a low monthly fee. Y-USA provides this as an opt-in option to any YMCA that may be interested. For any further questions, you can contact Y-USA at
ycloud@ymca.net
What’s the difference between Y-USA’s work on Virtual Y and what other partners are doing?
There is no significant customer-facing difference between Y-USA’s Virtual Y SaaS solution and other partners’ hosting solutions. The functionality should work as expected in both deployment models.
Marketing
Will there be an opportunity for shared content?
Yes. Cross-association content sharing is available now, both for use and for you to contribute your content.
Do associations have access to analytics for Virtual Y?
Yes, there is a tracking log within the admin menu that displays when a user logs in, as well as which pieces of content they view. This allows you to gauge what is most popular with your members. The information can be sorted and exported for ease of use.
Will there be a marketing toolkit?
Ys are responsible for marketing virtual offerings. We encourage associations to share helpful tips on what marketing tactics have worked best for them on the
YMCA Website Services message board, and YMCA Website Services Slack
Enable direct, secure, scheduled person-to-person calls inside your Virtual Y site.
This module is distributed as part of the YCMA Virtual Experience Platform (Virtual Y). Review
the README for more technical information.
Initial Configuration
Go to Admin > Extend (/admin/modules) and enable the Virtual Y 1on1 Meeting (openy_gc_personal_training) module.
Go to Admin > Virtual Y > 1on1 Meeting > Settings (/admin/virtual-y/personal_training/settings) and enter signals.cibox.tools:8091 as the Signaling PRL. This is the address of the signaling server that facilitates the connection between participants.
Go to Admin > People (/admin/people) and add the Virtual YMCA Editor role to the user profile of any users who will create meetings.
NOTE: The admin user will also need to have this role set. This role grants the necessary permissions to manage 1-on-1 meetings.
Also at Admin > People (/admin/people), add the Virtual trainer role to at least one user. This role identifies users as trainers within the system.
If you are starting a new site, log in as a Virtual Y member at least once. This ensures that member accounts are properly initialized.
Go to Admin > Virtual Y > 1on1 Meeting (/admin/virtual-y/personal_training) and you should be able to see a dashboard with links to add a 1on1 meeting.
If you receive an Access denied error, be sure to check that you have the Virtual YMCA Editor role as noted in step 3. This is the most common cause of this error.
The community-maintained server, signals.cibox.tools, will work for most sites at small to medium levels of 1-on-1 traffic. If you are planning to scale up this service you may need to maintain a separate
signaling server. A dedicated signaling server provides better performance and reliability for high-volume usage.
Creating a 1on1 Meeting
Go to Admin > Virtual Y > 1on1 Meeting (/admin/virtual-y/personal_training). This is the central management interface for 1-on-1 meetings.
Choose to add a single 1on1 meeting or a series and fill in the form. When creating a series, be sure to configure the recurrence options appropriately.
Joining a 1on1 Meeting
Once a 1on1 meeting is created, the customer and trainer will see a card for the call in the Virtual Y dashboard. The dashboard provides a convenient overview of upcoming meetings.
Both the Trainer and Customer should open this card, join the meeting, provide their names, and proceed with the call. Ensure that both participants have a stable internet connection and working audio/video devices for the best experience.
There are multiple ways to add a new video, depending on the type of site you’re working with:
Y Sites: Navigate to “Content” and click the blue “Add Content” button. Select “Virtual Y Video.”
Standalone Virtual Y Sites: Go to “Virtual Y” -> “Videos” -> “Add Video.”
From the Main Content Tab: You can also add a new video directly from the main “Content” tab.
Video Details
Title and Description: Add a title and description for your video. These will be displayed below the video player.
Media Tab
Selecting Your Video: In the “Media” tab, click “Select videos.”
New Videos (Default): This option is for uploading new videos.
Video Name: Name your video file the same as your content title for easy identification.
Video URL: Copy and paste your video URL into the “Video URL” field.
Supported Platforms: This field supports Vimeo and YouTube URLs.
URL Format: Use the main URL from your browser’s address bar. You do not need embed code or special URLs.
Other Fields: The “Media Tags,” “Directory,” “Revision Log Message,” and “URL Alias” fields can usually be ignored.
Previously Uploaded Videos: If you are reusing a video you’ve already uploaded, go to the “Select Videos” tab and choose the desired video.
Additional Options
Level (if applicable): Select a level for your video, such as for an on-demand class.
Add/Edit Levels: You can add or edit the default levels by going to “Structure” -> “Taxonomy” -> “Virtual YMCA Level” -> “List terms.”
Instructor Name (if applicable): Type in the instructor’s name.
Category: Choose a category for your video by typing it in and selecting from the dropdown. Only one category can be assigned per video.
Equipment: If your video features the use of equipment (e.g., exercise equipment in a workout video), type the name of the equipment and select it from the list. To add multiple items, click “Add another item.”
Configure Equipment List: You can configure the available equipment options by going to “Structure” -> “Taxonomy” -> “Virtual YMCA Equipment” -> “List terms.”
Duration: Add your video’s length in seconds in the “Duration” field.
Featured Video: To feature your video on the Virtual Y homepage, click the “featured” checkbox.
Saving
Click the blue “Save” button to save your video.
1.9.8 - How to change the Login page photo
Please follow these steps if you wish to customize the photo users will see when they log into the Virtual Y site.
To update the image before the user logs in:
Log into the site as a Site Owner.
Go to Manage > Content (click directly on Content, not one of its sub-menus).
In the content grid, find “Virtual YMCA Login” and click the Edit button for that row.
Expand the “Header Area”.
Click the Edit button next to the “Banner” row.
Expand the “Image” section. Locate the current image and click the Remove button underneath it (not the Edit button).
Re-expand the “Image” section and click the Select Images button.
If the desired image is not already in the system, click the Upload images link to add it.
If the image is already in the system, select it and click Select media.
Scroll to the bottom of the page and click Save.
If you also want to modify the image the user sees after they log in, repeat the steps above, but in step #3, find “Virtual YMCA” instead of “Virtual YMCA Login”.
1.9.9 - Image Guidelines
Virtual Y uses Drupal’s
Image Styles concept to allow you to upload a single image but display it in several ways. Image Styles automatically resize, crop, or otherwise manipulate images on display. This allows for consistent image presentation across the site, regardless of the original image dimensions. Because of this, there are no strict image dimensions required for images in your Virtual Y site.
We can, however, provide guidance on what images work best with the image styles used on the site:
Use high-resolution images if possible, but compress them using a tool like
TinyJPG or
ImageOptim to ensure they are no more than 1-2MB. Large image files will slow down page load times.
Use landscape-orientation images with a 4:3 or 16:9 ratio. These are common formats, so often no cropping is necessary.
Square images are NOT recommended, as they are often cropped in unexpected ways.
Images are sometimes cropped from the top and bottom, so ensure faces or other focal points are in the vertical center of the image. This will help prevent important content from being cropped out.
When including images for “Meta” (preview) purposes, such as for social media sharing, images should be at least 1080px in width.
1.9.10 - Live Chat
Enable group chat functionality on your live stream events.
This module is distributed as part of the YCMA Virtual Experience Platform (Virtual Y). Review
the openy_gc_livechat README for more technical information.
Initial Configuration
Go to Admin > Extend (/admin/modules) and enable the Virtual Y Livechat (openy_gc_livechat) module.
Go to Admin > Virtual Y > Virtual YMCA Settings > Livechat Settings (/admin/openy/virtual-ymca/gc-livechat-settings). Review the settings and modify them if necessary.
Go to Admin > People > Roles > Add role (/admin/people/roles/add) and add a role entitled Virtual Trainer if it does not exist.
Assign this role to any user who should have the ability to disable chat.
NOTE: The admin user will also need to have this role set.
Joining a Live Chat
Visit any Live Stream event. At the time that the event starts, a Live Chat button will appear below the video.
The button will not be visible before the event start time. To allow attendees to join before the meeting, set the start time to a few minutes before your actual start.
All participants can enter the chat, set their name, and chat throughout the entire Live Stream event.
Moderating a Live Chat
At any point during a chat session, users with the Virtual Trainer role have the ability to disable the chat using the Disable Chat button.
Users will see a message saying “Instructor disabled chat for users”.
Chat can be restarted using the Restart Livechat button on the event page, next to the chat icon.
Disabling chat will remove the history of that chat from the server.
Chat History
Each Livestream saves its history for a certain amount of time.
The default is 30 days and can be configured in the Live Chat Settings (/admin/openy/virtual-ymca/gc-livechat-settings).
Chat history is saved and can be viewed at Admin > Virtual Y > Virtual Meeting Chat Logs (/admin/virtual-y/chats).
Troubleshooting
If the chat button is not appearing, or the dialog displays “Chat is not available” or “Chat is not working at the moment,” you will need to check with your development partner to ensure the
Livechat service is properly configured on your server.
1.9.11 - Logging
Introduced in
Virtual Y 0.7, the “Open Y Virtual YMCA Log” module generates logs to record user behavior on Virtual Y sites. This module is part of the Open Y distribution and helps track user activity for reporting and analysis.
To enable the module, visit the Extend page on your site (/admin/modules), or ask your partner for assistance. You will need appropriate administrative permissions to access the Extend page.
Once the Log module is enabled, you’ll see two new items in the Virtual Y menu (/admin/config/virtual-ymca):
Logs
The Virtual Y Logs page (/admin/config/virtual-ymca/logs) displays searchable and filterable individual user activity. Additionally, individual log items can be removed. This allows administrators to review and manage user activity data directly within the Drupal interface.
Activities that are currently being tracked include:
User login
User views content
The Open Y team is working to add additional logging functionality as they gather requirements. If you have additional logging requirements for your reporting, please
contact the YMCA Website Services team with as much detail about your requirements as possible. Providing detailed use cases helps the team prioritize and implement relevant logging features.
Logs Archives
As of
Virtual Y 1.1, log archives can be generated on-demand via Virtual Y > Logs > Export Log Records (/admin/config/virtual-ymca/logs/export).
While logging begins immediately, log archives (prior to VY 1.1) should appear on the first day of the month following when logging is enabled. Log archives will be available as .gz files. The archive stores data indefinitely, but the log itself then deletes out the previous month’s info out of the database to start collecting data for the current month. This ensures efficient storage and data management.
Virtual Y > Logs stores ONLY the current month’s records
Virtual Y > Logs > Logs Archives keeps monthly archives indefinitely, in the format virtual-y-logs-2021-01.csv.gz
The log archive process depends on Drupal’s cron task, so you’ll need to ensure that cron is running periodically on your site. The cron task is responsible for automatically generating and archiving the log files. You can configure cron jobs through your hosting provider or using Drupal modules like
Automated Cron.
To extract .gz files:
Extracting files on Mac:
The system’s Archive Utility should work to extract files. If that fails…
(Easy) Download
Keka or
The Unarchiver, install, and use it to extract the file.
(Advanced) Open a Terminal window and navigate to the directory where the .gz file is located, then run gunzip my_log_file.csv.gz. Replace my_log_file.csv.gz with the actual name of your archive file.
Your Virtual Y log archives may include times in the created column that look like 1606839555. This is a format called “Unix epoch time”, representing the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT). You can convert it to a human-readable format in a few ways:
Use the formula = (A1/86400) + DATE(1970,1,1), substituting the correct cell for A1. This formula divides the Unix timestamp by the number of seconds in a day (86400) and adds it to the base date of January 1, 1970.
Right-click on the column, select “Format Cells”, then choose a Date format. This will display the converted timestamp in a readable date and time format.
1.9.12 - Managing Footer Links
Your standalone Virtual Y site may have a block with social media links at the bottom of the page. These links can be customized for many social media services.
Getting to the Block Editor
Your site may have a “Quick Edit” icon (a tiny pencil) that appears when you hover over the section with the links. If so, click the pencil, then Edit.
OR
If you don’t see the Quick Edit option, you can navigate to the Block editor via the admin menu at Structure > Block Layout > Custom Block Library > Edit Footer Social Block.
Editing the Block
In the Block editor, you will see a Content field containing links to your social media sites.
Adding a Link
Add a new item to the bulleted list.
Select the text you want to use for the link.
Click the link icon.
Editing Links
Select the text you want to link, or double-click an existing link to modify it.
In the URL field, add the complete URL to the social media site.
Edit the Title field to something more descriptive; this will be used as the title attribute for accessibility.
Open the Advanced section and update the CSS classes field to select the correct icon. Be sure to copy the entire code snippet below for the icon you want. These CSS classes use Font Awesome icons.
Released in 0.12, Virtual Y’s Shared Content module allows Y’s to share their content with other associations/branches and to pull shared content to use on their own site.
Requirements
Open Y Gated Content Module
While Shared Content is supported in Open Y Gated Content >=0.12, we recommend that you use
version 1.0 or greater for the best support.
Hosted Videos
Any YouTube video that works in Virtual Y will be sharable.
Vimeo videos that use the “Only on sites I choose” privacy setting should not be shared. Please review the
Vimeo Privacy Settings Overview for full details. If you plan to share content on Vimeo, we recommend:
Who can watch? - “People with the private link” OR “Hide this video on vimeo.com”
Where can this be embedded? - “Anywhere”
Getting Started
To start sharing content, you need to get your site ready.
Enable the modules
On the Drupal Extend page (/admin/modules), enable Virtual Y Shared Content. If your site is hosted on a managed hosting environment, this step is either already done for you or will need to be done by your hosting partner.
Accept any other required modules if asked.
Connect your site to the Open Y server
In order to share content, you’ll first need to register your site with the Open Y shared content server:
Go to Virtual Y > Shared Content > Source Servers (/admin/virtual-y/shared-content/server)
Use the List additional actions arrow (▾) under Operations then Edit
On the following page, simply Save the form. Once you’ve saved the form and your site is able to contact the server, the Source Token will be populated.
New connection requests are reviewed periodically and are approved by the Open Y team to prevent abuse. Please allow up to two business days for approval, or email
ycloud@ymca.net with the URL of your site to request approval.
Fetching Shared Content
Once you are connected to the server you may, at any point, Fetch content from the server:
Go to Virtual Y > Shared Content > Source Servers (/admin/virtual-y/shared-content/server)
Fetch content from the Open Y server.
Your site will fetch Virtual Y blog posts and Virtual Y Videos from the server. In each list you may:
Preview content using the button on the right.
Check the box to the left of any content you’d like to use on your site.
Fetch to my site to download the new content.
As of Virtual Y 1.6.1 (released in December 2021) the fetched content list will show items in different states:
Bold items are new to the server since your last visit.
Greyed out items have already been added to your site.
Also in VY 1.6.1, content can be fetched directly from the preview.
Publishing Shared Content
You can share your own content to other Y’s in the Movement too!
Create your Video or Blog post as usual.
To share a single item:
expand the Shared Content options on the sidebar of the content edit page,
then check “Available to share”.
To share multiple items, visit the Content list (/admin/content) then:
Check the Update this item checkbox.
In the Action dropdown, select Share to Virtual Y.
Use the Apply to selected items button.
FAQ
Why can’t another Y see my shared content?
New connection requests are reviewed periodically and are approved by the Open Y team to prevent abuse. Please allow up to two business days for approval, or email
ycloud@ymca.net with the URL of your site to request approval.
Can I share content before my site is live?
If your site is in a “pre-live” mode and is somehow restricted from being publicly accessible (sometimes called “Site Lock” or “HTTP Auth”) you will not be able to share content. Please wait until your site is live to share content.
1.9.14 - Software Requirements
Open Y Sites
Open Y version 2.0 or newer.
The ability to install Virtual YMCA modules.
Virtual Y Standalone Site
Hosting
Tech stack required:
Ubuntu Server (local or Cloud environment) with 2CPU and 2GB of RAM minimum.
Server configured with LAMP stack (Linux/Apache/MySQL/PHP).
Digital Ocean – Cost-effective. For self-installs.
OneEach Technologies – Mid-range. For Ys with developer partners.
Acquia/Pantheon/Platform.sh – Enterprise. For large YMCAs.
SSL (Security Certificate)
A security certificate authenticates that you own your website and displays a lock icon in the user’s web browser. Most modern browsers require SSL certificates. SSLs are widely available from a large number of reputable providers.
Domain Name (Website Address)
Only required for standalone Y sites. Can be set up with its own unique web address (i.e., virtualymcatn.org), a unique directory within your existing site (ymcamidtn.org/virtual) or as a subdomain of your existing site (virtual.ymcamidtn.org).
Requirements for each of these setups are unique. Contact your developer partner or the Open Y community for help with your setup.
Sign-In Integration
CRMs with Full Integration:
Daxko
Personify
Salesforce (Coming Soon)
Other CRMs:
Upload a .csv file of emails to your server to use the manual sign-in experience.
1.9.15 - User Segmentation
User segmentation is a feature within Virtual Y that allows you to categorize your users. This enables you to:
Diversify your membership strategy.
Organize your Virtual Y content into categories such as fitness, wellness, and family enrichment.
Set Up User Segmentation
In your Drupal toolbar, hover over Virtual Y and click Virtual YMCA Settings.
Click the AUTH Settings tab. A list of authentication method options appears. If your desired authentication method isn’t listed, install it from the Extend menu.
Click Edit on the authentication method you want to use. User segmentation settings are located in the Permissions Mapping field at the top of the page.
In the membership field, carefully type or paste the name of a membership type from your CRM that you want to grant access to Virtual Y. Then, use the dropdown to select the appropriate access level for users with that membership type.
To add more membership types, click the Add one more button until all desired membership types are listed.
To remove a membership type: Delete the membership name from the field and select None as the Virtual Y role. Then, scroll to the bottom of the page and click the blue Save button. The empty line should then disappear from your mapping list.
Add a New Role
You might need to add roles beyond the default three included in Virtual Y. While you can, keeping the number of roles to five or fewer is recommended, as managing content and avoiding fragmentation becomes more difficult with more roles.
If you’re unfamiliar with Drupal roles, consult with your agency partner for help customizing your Virtual Y roles.
Click People in the Drupal toolbar.
Select the Roles tab.
Click the blue Add Role button.
Enter the name of your new role in the field.
Note: The Machine Name for your role must begin with virtual_y_, or it won’t be included in the permissions mapping table. To ensure this, either name your official role “Virtual Y [Desired Role Name]” or click the small Edit button link next to the Machine Name and edit the text.
1.10 - Content Editing Basics
Adding New Content
To add new content:
Select the Content tab in the administration toolbar at the top of the page.
A text field with a circle on the right that’s used for searching content, blocks, or taxonomy terms.
Type what you want to enter.
Select from the options that appear below the field. The results narrow as you type.
Links/Button Fields
These typically appear as a single box with two fields inside and add a link onto a page, often as a button:
URL: The link destination.
Link Text: The call to action that’s displayed.
The URL field supports relative URLs for links on your site (e.g., /join for http://myymca.org/join) and full URLs for links on other sites (e.g., http://someotherymca.org/join). You can also search for content by title and select it, like in other autocomplete fields.
Link Attributes
Some link fields contain an Attributes section that you can expand to add attributes to your link:
ID: Identifies the link in the page’s HTML and can be targeted by anchor links.
More on anchor/jump links.
Target: Determines how the link opens:
New Window _blank: Opens the link in a new tab or window.
Same Window _self: Opens the link in the same tab or window.
Class: Applies a CSS class to the link for styling.
Image Fields/Image Library
You can add, edit, and upload images any time you see a tab with “Image” in the title. To use the media browser, click the button in the image field.
You can clone content using the Clone button on many pages:
or on the Content list in the site administration:
After selecting Clone, you’ll see a screen asking which entities you want to clone. Generally, you can leave the checkboxes as they are, as changing the options could cause unintended consequences.
At the bottom of the options, select Take ownership if you want your user account to own the new content, then click Save.
1.11 - Demo Content
The distribution comes with demo content to help kick-start your site building.
Two sets of demo content are available for the distribution:
These modules also contain significant boilerplate migration code that a developer would need to migrate content from an older Drupal site or different CMS into the distribution.
Guide prospective members through the join process.
The distribution offers a couple of ways to present membership options to visitors and direct them to the appropriate membership management system (MMS) for signup.
Methods for Informing Visitors
The two primary methods for informing visitors about membership options involve:
Membership Content Type: This content type allows you to create individual pages detailing specific membership offerings. These pages can be linked to from other areas of your site.
Membership Calculator Paragraph: This paragraph type, when added to a page, creates an interactive wizard that guides users through selecting a membership. See
Membership Calculator Paragraph and
Membership Content Type for more information.
Finding Your Registration Link
Every membership management system will have different ways of linking for members to complete their registration. Here are a few we know about. If you have tips for an MMS not listed here, feel free to leave them in the comments.
Daxko Operations
Navigate to: Membership > Membership Types > Edit > Online Settings. This provides the deep link to the specific membership types.
1.12.1 - Membership Calculator
This application provides an interactive “membership wizard” with location and pricing options. It is the default membership experience for attracting new members.
The Membership Calculator is bundled with the distribution in the
openy_calc module.
As of August 2024, the Membership Calculator has
an updated design with improved functionality and user experience. The improved design also responds to the selected
colorway and page styles.
Configuring the Calculator
The Membership Calculator uses
Membership content items. These must be created for the Membership Calculator to function.
Create a Membership node for each membership type your Branch or Association offers.
Inside each Membership node, add a Membership Info Paragraph with the details of that membership at each of your Locations. This paragraph includes fields for:
Location: A reference to an existing
Branch content type.
Link: The URL a member is directed to for signing up for the membership at the selected location.
Join Fee: The one-time fee to join.
Monthly Rate: The recurring monthly membership fee.
The Membership Calculator presents a three-step process:
Membership Type
Primary Location
Summary
Membership Type
This step displays the Title, Image, and Description of each published Membership node. This information is pulled directly from the corresponding Membership content items.
Primary Location
This step shows a map with radio buttons, enabling members to select their preferred primary location. All locations listed in the YMCA Website Services Location Filter Settings (see the Troubleshooting section below) are included in the list.
Summary
This final page displays a link for members to continue their registration or a message stating that the selected membership is unavailable at the chosen location. The summary includes:
The selected branch location.
The selected membership type.
The monthly rate and join fee, if applicable.
A button to proceed to the registration link, if a membership is available at the selected location.
Placing the Calculator on a page
Once configured, the Membership Calculator can be placed on a page using:
If the second step of the Membership Calculator does not display any locations, navigate to Administration > YMCA Website Services > Settings > YMCA Website Services Location Filter Settings. Ensure that all Branches you want to include in the location search are selected.
1.12.2 - Membership Framework
This application is built on Drupal Commerce and provides advanced options for building a membership journey.
The Membership Framework is distributed in the
openy_memberships repository and must be
added and installed on top of the base distribution. We recommend working with your development partner if you wish to go this route.
To get started with the Membership Framework, you will first need to create a number of landing pages.
The examples below use Paragraphs. Similar pages can be created using
Layout Builder blocks and the Membership Framework custom block.
Membership Builder
Go to /node/add/landing_page
Title: Membership Builder
Layout: Two Columns with left sidebar
Header Area: Add a “Small banner” paragraph and fill in the fields.
Content area: Add a “Memberships” paragraph (it has pre-filled fields).
Sidebar Area: Add a “Block Container” paragraph with the “Memberships Desktop Sidebar” skin.
Block_ref: Choose “Paragraph container” with the “Memberships Menu Container” title.
Sidebar Area: Add “Simple content” with the “Memberships Button” skin and link to the builder:
<p><aclass="btn btn-primary"href="/membership-builder"><spanclass="text">JOIN THE Y</span></a></p>
Sidebar Area: Add a “Sidebar Menu” with the “Memberships Sidebar Menu” skin to create your Memberships Menu with these items:
Membership Types
Member Benefits
Discounts
Corporate Wellness
Free Trial
Sidebar Area: Add a “Block container” with the “Memberships Feature card” skin. Use the “Feature Card” block type with any content allowed in this block.
Save the landing page.
Membership Types
Go to /node/add/landing_page
Title: Membership Types
Layout: Two Columns with left sidebar
Header Area: Add a “Small banner” paragraph and fill in the fields.
Content Area:
Add a “Simple content” paragraph with the “Membership Simple Content” skin and text.
Add a “Membership Types Listing” with the “Membership Types” skin.
Sidebar Area: Follow the same steps for the “Membership Builder” page.
Save the landing page.
Member Benefits
Go to /node/add/landing_page
Title: Member Benefits
Layout: Two Columns with left sidebar
Header Area: Add a “Small banner” paragraph and fill in the fields.
Content Area: Fill the area with content. An example is shown in the next screenshot.
Sidebar Area: Follow the same steps for the “Membership Builder” page.
Save the landing page.
Discounts
Go to /node/add/landing_page
Title: Discounts
Layout: Two Columns with left sidebar
Header Area: Add a “Small banner” paragraph and fill in the fields.
Content Area: Fill the area with content. An example is shown in the next screenshot.
Sidebar Area: Follow the same steps for the “Membership Builder” page.
Save the landing page.
Corporate Wellness
Go to /node/add/landing_page
Title: Corporate Wellness
Layout: Two Columns with left sidebar
Header Area: Add a “Small banner” paragraph and fill in the fields.
Content Area: Fill the area with content. An example is shown in the next screenshot.
Sidebar Area: Follow the same steps for the “Membership Builder” page.
Save the landing page.
Free Trial
Go to /node/add/landing_page
Title: Free Trial
Layout: Two Columns with left sidebar
Header Area: Add a “Small banner” paragraph and fill in the fields.
Content Area: Add “Simple content” with a description.
Content Area: Add a “Webform” with the “Memberships Free Trial Webform” skin and the “Memberships Free Trial” webform.
Sidebar Area: Follow the same steps for the “Membership Builder” page.
Membership Products
Go to /admin/commerce/products
Click on + Add product, then choose Membership.
You’ll see these fields:
Title
Description
Add-ons (used in specific cases, skip for default setup)
Total Available
Subfields:
Related Add-on (skip for default functionality)
Age groups (select age groups, usually Adults, Youth, Seniors)
Total Available (number of people allowed for the age group selected above for the membership product. You can add multiple groups by clicking “Add another item” for Family memberships)
Total Free (designed for cases where extra people are allowed in the membership, but with an additional fee. Fill with the same value as Total Available for default functionality)
Branches in the product: Use if a membership is specific to a branch. If “None” is selected, the membership will appear for all branches.
A typical setup is shown in the following screenshot:
Click on the “Save and add variations” button (or go to the “Variations” tab if editing a previously created product).
A typical setup for variations of a membership is shown in the following screenshot:
1.13 - Schedules
The distribution provides two applications for managing schedules at your YMCA.
Out-of-the-box, YMCA Website Services’s Activity Finder integrates with
Daxko,
ActiveNet, and
Personify. Configuring these integrations is mostly user-friendly, but often is supported by a partner development team. Any other CRM will require custom developer work.
When you add the Activity Finder block to a page, you have a number of options. These are in addition to the configuration at Admin > YMCA Website Services > Settings > Activity Finder Settings (/admin/openy/settings/activity-finder). See
the Activity Finder module README for more information.
Location & Category Filters - Restrict this block to show sessions from only certain Locations or Categories. ‘Limit’ will show only the specified options. ‘Exclude’ will remove the specified options. Generally, you should choose either Exclude or Limit, not both.
Limit by location - Only show sessions at specific locations in the results.
Exclude by location - Remove sessions at specific locations from the results.
Limit by category - Only show sessions related to specific Program Subcategories in the results.
Exclude by category - Remove sessions related to specific Program Subcategories from the results.
Legacy mode - Shows some data as it was in the previous version of Activity Finder (v3):
Disables bookmark functionality on the results screen.
Doesn’t display the age indicator in the result card of activities.
Changes the days + times wizard step. Displays only days of week, but not times of each day (doesn’t support DaysTimes filter).
Weeks filter - Changes the Day/Time filter to use custom defined Week filters.
This requires setting the Weeks configuration in the Activity Finder settings (/admin/openy/settings/activity-finder).
Note: Only sessions that have “Camp” in the title or room fields will return for this filter.
Additional filters - These filters are off by default, but can be enabled in the Block Configuration.
Start Month - Filters based on the month in the Session Time field.
In Membership - Shows Sessions that have In membership checked.
Duration - The length of the Session. This is configurable in the Activity Finder settings (/admin/openy/settings/activity-finder) and defaults to:
Single day
Multi-day (up to 5 days)
Weekly (up to 3 weeks)
Monthly (up to 5 weeks)
Season (up to 12 weeks)
School year (~9 months)
Full year
Hide Home Branch info block - Disables functionality related to the user’s selected home branch.
Background image - An image that’s displayed in the background of the banner above Activity Finder.
Schedules - Filters by a number of facets, which are configurable in the Block Configuration or Activity Finder settings.
Age(s) - Filters based on the Min Age and Max Age. Age ranges are configurable in the Activity Finder settings (/admin/openy/settings/activity-finder).
Day(s) & Time(s) - Filters by the time of date on specific days of the week. This filter has no configuration.
Weeks - Replaces date/time filter when Weeks filter is selected in the Block Configuration. See configuration requirements above.
Activities - Program Subcategory filters grouped by Program.
Locations - Location filters grouped by Content type.
The filtered results in the Activity Finder app are a list of Sessions that meet the given filter criteria.
Each row of results contains:
The Session Title.
The Session Time, which contains a date, days of the week, and times.
The Session Location.
The Session Min/Max Age.
The Member Price and Non-member price.
An indication of the number of spots available, from the Initial Availability field.
Clicking on the row will bring up a pop-up with further details:
The Session Description.
A “Learn more” link and “Register” button which both go to the URL in the Session Registration Link field.
Additional topics
Allowing UTM codes in Activity Finder
UTM codes can be used to track the effectiveness of marketing campaigns. Activity Finder uses query strings as filters, but as of
version 4.2.0 it will also maintain UTM codes in the URL.
Activity Finder begins with a number of preset arguments, and those can be modified at Admin > YMCA Website Services > Settings > Activity Finder Settings (/admin/openy/settings/activity-finder) in the Allowed Query Arguments field.
Once those settings are saved, you can visit an Activity Finder page with UTM codes attached, for example:
and see that the codes are maintained as the filters are changed.
1.13.2 - Group Schedules
Displays daily group exercise classes with filters and a PDF download.
Sometimes called “Group Exercise” or “Group Schedules”, the Repeat Schedules block provides a similar view to Activity Finder, but focuses on recurring, often drop-in classes. You can see
an example of this on our sandbox site.
As of August 2024, the Schedules have
an updated design with improved functionality and user experience. The improved design will also respond to the selected
colorway and page styles.
Available with openy_repeat2.2.0 and above via the Repeat (Group) Schedules (lb_repeat_schedules) module.
Block Configuration
After you add the Paragraph or Block to a page, configure the options:
PDF Schedule link - a link to a manually generated PDF as an alternative to the automatically generated one.
Clear All link - where the user is directed when they use the “Clear all” link.
Limit by category - choose categories with autocomplete to only show certain categories.
Filters - choose the filters that show up in the sidebar.
The available filters are:
by category
by class name
by instructor name
Limit by Location - choose a location to only show events from that location.
Display instructor - controls whether the instructor’s name is displayed.
Display end time
Categories Exclude - exclude any programs that are tagged with specific categories.
PDF only view - only show the PDF link and not the schedule.
Front-end
Data from Sessions, Classes, and Activities are all used to form the Repeat Schedules. Here’s what shows up where. Fields are noted with their relationships, so session.class.activity.title means “the title of the Activity referenced by the Class referenced by the Session”.
Fields used in the table view:
Fields used in the popup view:
1.13.3 - Simple Schedules
The PEF Schedules module allows Ys to create and manage schedules with a simple, calendar-based view powered by FullCalendar.
flowchart LR
subgraph "PEF Relationships"
direction LR
Session -- requires --> Class
Class -- references --> Activity
Activity -- references --> PS
PS -- requires --> Program
PS["Program Subcategory"]
end
You will need to create at least a Class and Activity to start adding events to the calendar. Go to Admin > Content > Add Content (/node/add) to start adding items.
If you have preexisting content for any of these content types you can use them here. You may first need to configure the Activity Color for existing Activities.
Activity colors
PEF Schedules adds a new Color field to Activities which is used to style the categories on the calendar.
The Color field takes a hex value (#XXXXXX where X is a hexadecimal character (0-9, a-f)). We recommend using colors from the
Brand Standard Color Wheel. The default color is configurable in the Calendar Settings. We recommend selecting dark tones from the color wheel as the item titles are displayed with white text.
Calendar settings
Settings for the calendar are configurable at Admin > YMCA Website Services > Settings > Schedules calendar settings (admin/openy/settings/schedules-calendar). This form is managed by the \Drupal\y_pef_schedule\Form\FullCalendarSettingsForm.
Options include:
Slot settings - These relate to creating events on the calendar.
Slot Duration - The default length of each time slot. This setting defines the length of each time slot in the calendar (e.g., 00:30:00 for 30 minutes). Must be in the format of HH:MM:SS.
Snap Duration - The default granularity to which events “snap” when clicking and dragging on the calendar. This setting determines the granularity of time slot selection and event dragging (e.g., 00:30:00 for 30 minutes). Must be in the format of HH:MM:SS.
Slot Label Interval - The interval between time labels on the calendar’s time axis. This setting specifies the interval between time labels displayed along the calendar’s axis (e.g., 01:00 for every hour). Must be in the format of HH:MM.
Time Settings - These help make the calendar display more relevant to your user’s needs.
Min Time - The earliest time that is visible on the calendar view. Enter the earliest time in HH:MM:SS format that you want to be visible in the calendar’s view. This setting helps to limit the view to specific hours, making the calendar more relevant to the user’s needs.
Max Time - The latest time that is visible on the calendar view. Enter the latest time in HH:MM:SS format that you want to be visible in the calendar’s view. This time represents the cutoff point at which the calendar view will stop displaying events for the day.
Default Color - Enter the default color for activities in the calendar. Enter the color in hexadecimal string format #XXXXXX where X is a hexadecimal character (0-9, a-f).
Manage schedules
Once everything is configured, you can start managing schedules. See a list of available schedules at Admin >
Content > Schedules Calendar (admin/openy/branch-schedules). Click on one of the options to open the editable schedule.
When in the schedule, you can:
Click Download PDF to download a PDF of the current display.
Click Legend to open the legend, then click items in the legend to filter the view.
Use the Week/Day buttons to filter and change the view or page between weeks/days.
Click anywhere in the calendar to add a session.
Click on an existing item to view its details and edit.
Drag from the middle of an item to change its time.
Drag from the bottom of an item to change its duration.
Create sessions
When creating a session from the schedule, you’ll see a simplified version of the Add Session (/node/add/session) form.
Enter a Title (required).
Select a Class from the dropdown (required).
Enter a Room and/or Instructor (optional).
Choose a Location (required).
Add a Session Description (optional).
Set a Start date/time and End date/time (required). The time values will determine when on each day the session happens. The dates will determine the start and end of its recurrence if it happens across multiple days.
Set the Days on which the Session recurs during the duration of the dates set above (required).
Display schedules
Once content is added to the schedule, you have several options for showing it to users:
Place the
Simple Schedule block on any Layout Builder page. This block adds a calendar view of a Branch schedule to a page. Configure the block by selecting the desired schedule.
All items added via the Simple Schedule will be shown in
Activity Finder or
Group Schedules. Follow the directions on those pages to configure the respective components and add them to a page.
Download the schedule PDF and upload it somewhere on your site.
2 - How-to
These guides will help you quickly accomplish common tasks.
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.
Our guides are always evolving. If you have a request for a guide, or if you find an issue with an existing guide, please
get in touch.
These guides provide step-by-step instructions to accomplish specific tasks within the system. They are designed to be practical and goal-oriented, helping you quickly achieve your desired outcome.
The following formatting conventions are used in How-to guides:
Numbered lists: Indicate sequential steps.
Code snippets: Display code or configuration examples.
Screenshots: Provide visual guidance.
Callouts: Highlight important information or warnings.
2.1 - How to Avoid Outdated Configuration
Managing configuration across versions of a module can result in unexpected challenges.
Sometimes, in the process of making successive configuration changes, we need to maintain old configuration files so that outdated update hooks can still run successfully for sites that 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. This can also happen when configuration schema changes.
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 often involves creating a new directory to house the older configuration files.
Overview
This process results in a configuration directory that looks like this:
When you encounter this error, follow these steps:
Identify the culprit: Find the version of the module where the failing update hook was committed.
Isolate the code: Checkout or download the old version of the module to a separate working directory.
Preserve the config: Copy all the configuration files that are being imported in that update hook into a new directory, such as config/outdated/x.x.x. Name the directory to clearly indicate the module version that the configuration pertains to. Consider creating a README.md file inside this directory to document its purpose and the specific module version it supports.
Adapt the path: Modify the $path line in the failing update hook, changing /config/optional to /config/outdated/x.x.x.
Test thoroughly: Commit these changes and test them thoroughly to ensure the update hook now runs successfully and doesn’t introduce regressions.
Warning Signs
While the error message described above is the most direct indicator of an issue, it’s better to prevent these errors proactively.
Consider also using the
Configuration Update module to identify configuration changes between the default configuration and the active configuration on your site.
Adding or removing major features or fields can also lead to this type of error. Be particularly cautious when:
Removing configuration entities.
Changing configuration schema (e.g., renaming properties, changing data types).
Introducing dependencies on new modules in configuration.
2.2 - How to customize your locations map
YMCA Website Services includes robust mapping functionality defined in the
openy_map subproject. Maps are typically displayed on the /locations page using the
Location Finder component and are highly customizable.
Here 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 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.
Set the map icon.
Edit each content type as needed, then Save the form.
Reload /locations to 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. The Field UI module must be 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.
2.3 - How to install Cachet (the official Y Font)
Cachet, the Y’s primary font, should be used for all internal and external materials whenever possible.
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).
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.
These steps leverage the @fontyourface module. Ensure this module and the @fontyourface - Local Fonts module are enabled before proceeding.
Visit Admin > Extend and ensure the “@fontyourface” and “@fontyourface - Local Fonts” modules are enabled.
Click + Add Custom Font and add each of the Cachet font files you downloaded above with the following settings:
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
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.
2.4 - How to integrate with social media
Embedded social feeds or posts can help share your message with users.
Social media is a great platform for communicating with your 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 on your website
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:
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 Block to 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 allows your site to import social media content for syndication. This module fetches social feeds from Facebook, Twitter, and Instagram, and aggregates them into a content type.
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.
The Social Feed Fetcher module includes the following features:
Social Post Content Type: A content type specifically designed for social media posts, including fields for the post text, link, image, and platform.
Views Integration: Provides a pre-configured View to display and administer social post content at /admin/social-posts.
Field Mapping: Maps fields from social media APIs to the Social Post content type fields.
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.
AddToAny is the perfect drop-in replacement for AddThis.
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)
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.
Layout Builder components for YMCA Website Services were developed and released throughout 2023. The initial plan was to support Paragraphs-based components for one year after the Layout Builder components were completed, after which they would no longer be supported. Site owners can begin migrating their content at any time. After the deprecation of Paragraphs components, they will not “disappear”, but the YMCA Website Services core team will no longer support them.
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 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 manageable pieces and spread out over 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, or 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 can 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. Note that available Layout Builder components may vary based on your specific YMCA Website Services configuration.
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
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.
2.6 - How to perform a content audit
Content audits help get an overview of how your site is structured and can assist with migrations, SEO analysis, and more.
Doing a content audit is a useful first step in planning a migration or a larger content strategy initiative. A content audit helps you understand the current state of your website, identify areas for improvement, and make informed decisions about your content.
List all current website pages in a spreadsheet, organized by menu section or information architecture.
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 or deleted!
Review
Visit each page and review the content.
Identify key pages and content types.
Locate content that is outdated, duplicated, needs further review, or could benefit from consolidation.
Find content gaps and identify what might be missing.
Identify commonly used page components (i.e., Cards, Carousels, Accordions).
Note the text formats being used. Text formats are managed by the core Filter module and define how text is filtered and displayed. See the
Managing text filters and text formats help topic for more information.
Additional Resources
For more information on content audits, check out these resources:
If you are starting with an internal toolchain, run composer require ycloudyusa/yusaopeny at the root of the project.
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 might 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:
To install only selected modules: Go to Admin > Extend (/admin/modules) and enable only the components that you choose to use.
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.
When building Landing Pages, you will override the Default Layout for every page by placing content blocks. For this reason, it is important that you configure the desired defaults before building 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:
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.
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:
2.8 - How to set up a site with the Small Y template
The Small Y template is a set of modules and themes tailored to the needs of Small YMCAs.
What is the Small Y template?
The Small Y template is a pre-configured set of modules and themes designed to meet the specific needs of Small YMCAs. It provides a lightweight and user-friendly solution for small organizations requiring a simple and effective website. The Small Y template is based on the
YMCA Website Services distribution and built using
Y Layout Builder.
The Small Y template incorporates updates to the Layout Builder design system, a collaborative effort between VML and the YMCA of the USA. A visual representation of the new theme is available as a
mockup in Figma.
Essential Modules
The Small Y template is built with a curated selection of modules that are essential for a basic YMCA website. This streamlined approach simplifies setup and maintenance while minimizing the website’s overall footprint.
Alerts feature a new set of styles aligned with the colorway color scheme.
Small Y Specific Features
The Small Y template includes features tailored to simplify setup and maintain content consistency for small organizations:
Limits have been implemented on the number of items for the main menu and various components.
Breadcrumbs are automatically enabled on all pages.
The
Banner block offers additional variants, each compatible with the colorway color or a grey background:
Tall - Designed for use as the primary hero banner on a page.
Sub-page chevron - Suitable as a secondary banner.
Sub-page chevron (no media) - A secondary banner option without media.
Sub-page frame - A secondary banner that uses dark text on a white background.
Promo - A smaller banner option for use on pages needing a call to action with no media.
Ping-pong blocks can be added to sections using the Ping-pong Section content block. This simplifies adding alternating content blocks with section-level formatting, rather than formatting each block individually.
When adding a Ping-pong Section, two sets of options can be configured under Styles > Y Styles:
Image Alignment - Choose whether the image starts on the left or right.
Background colors - Select a colorway, white, or grey background for items within the section.
Statistics blocks have been redesigned, and include the option for grey or colorway backgrounds.
Grid CTA blocks now have CTA buttons positioned between the subheading and the items.
Icon Grid blocks position the CTA below the items.
Install the Small Y template
The Small Y template can be installed using either the YMCA Website Services Installation wizard or the command line.
Installation Wizard: This web-based tool provides a guided, step-by-step process for setting up a new YMCA website.
During the installation process, select “Small Y” as the Installation Type.
After installing the Small Y template, you can begin building your site by adding content and configuring the layout. Refer to
How to set up a Layout Builder site for detailed instructions.
2.9 - 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. The Google Analytics module adds a JavaScript tracking code to every page.
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.
The Google Analytics module settings include:
Web Property ID: Your Google Analytics account number.
What are you tracking?: Options include “Single domain”, “One domain with multiple subdomains”, and “Multiple top-level domains”.
List of top-level domains: Only relevant if you are tracking “Multiple top-level domains”.
Visibility: Settings for adding tracking to specific pages and/or roles.
Links and downloads: Options for tracking outbound links, mailto links, telephone links, and file downloads.
File extension list: A comma-separated list of file extensions to track as downloads.
Privacy: Options for anonymizing visitor IP addresses.
Custom variables: Settings for custom dimensions and metrics.
Custom code snippets: Allows you to add custom JavaScript code snippets.
Cache: Options for locally caching the Google Analytics JavaScript file.
Debug: Loads the debugging code of Google Universal 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.
Search Tracking with Google Analytics
Prerequisites
A Google Analytics account to track your site should be created.
The Google Analytics contrib module should be enabled and configured to use an existing GA account.
Steps
Log in to the Google Analytics account configured to track your YMCA Website Services site.
Click the Admin button in the bottom right corner of the main screen.
Click View Settings.
Scroll to the “Site Search Settings” section and enable the “Site Search Tracking” switch.
Fill the query parameter field with q, query values and click Save.
Reports about the search tracking can be found on the main screen in Behavior → Site Search Section.
Attention: Data processing latency for search tracking reports is 24-48 hours (see
Google’s support doc).
The Data Layers module outputs 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 the use of hook_datalayer_meta().
Altering which properties will be output can be done via hook_datalayer_meta_alter().
/**
* Implements hook_datalayer_meta_alter().
*/functionmy_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(['my_bundle','my_nodetype'],$obj->type)){// Remove author names on some content type.
if($key=array_search('name',$properties,TRUE)){unset($properties[$key]);}}elseif($type==='my_entity_type'){// Remove some property on some entity type.
if($key=array_search('my_property',$properties,TRUE)){unset($properties[$key]);}}}}
Adding additional data can be done using datalayer_add().
/**
* Add data to the data layer.
*/function_my_module_myevent_func($argument=FALSE){if($argument){datalayer_add(['drupalMyProperty'=>$argument,'userAnotherProperty'=>_my_module_other_funct($argument),]);}}
To alter the data to be output use hook_datalayer_alter().
/**
* Implements hook_datalayer_alter().
*/functionmy_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=.....
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 how 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
Enable the “YMCA Website Services Cross-domain Tracking (XDT)” module at Administration > Extend, or via Drush:
drush en openy_xdt
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.
2.10 - How to leverage structured data
Structured data helps the machines reading your site - search engines, AI models, and more - understand your content.
Adding structured data can enable search results that are more engaging to users and might encourage them to interact more with your website
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).
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.
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. See
Google’s Content guidelines for FAQs for more information.
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). Refer to the
Metatag module documentation for more information.
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.
Go to /admin/config/search/metatag/front
Scroll to the bottom of the form.
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.
2.11 - How to use the Canadian Colourway for Layout Builder
With a few clicks, Canadian YMCAs can use their own set of brand-compliant, accessible styles.
YMCA of the USA has partnered with
YMCA Canada to create a brand-compliant and accessible colorway for use by Canadian YMCAs. This allows Canadian YMCAs to easily implement their specific branding requirements within the YMCA Website Services platform.
Designs
The colorway is packaged as the
Canada Layout Builder Colorway module on Drupal.org and is included with the full
YMCA Layout Builder package. The ws_colorway_canada module provides colorways, logos, and banner styles approved by YMCA Canada. It also depends on the y_lb (YMCA Layout Builder) and responsive_favicons modules.
The Canada Layout Builder Colorway includes the lb_hero_canada submodule, which provides helper functionalities for the Canada variations of the Hero Banner block type.
The Canadian Colorway package includes four options for content type or page-level colorways: Y Canada Blue, Y Canada Purple, Y Canada Green, and Y Canada Black. Each colorway 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
Warning
Enabling ws_colorway_canada immediately changes the site logo from the Y-USA logo to the Y Canada logo. It is strongly recommended to perform this action on a development environment first.
To enable the Canadian colorway:
Visit Admin > Extend (admin/modules).
Enable the following modules (search for Canada):
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, follow these steps to ensure the new colorways are used across your site:
Y Canada site developers may want to hide the existing YUSA styles to prevent unintentional usage. While there isn’t a configuration option for this, custom CSS can achieve this:
Enhance your site’s security by enabling multi-factor authentication (MFA) for user roles.
Multi-factor authentication (MFA), also known as two-factor authentication (2FA or TFA), provides an extra layer of security for your site. It can be enabled for specific roles, such as administrators, while allowing other users to log in with just a username and password.
The community-contributed
TFA module is the recommended way to implement MFA.
Requirements
The TFA module requires the PHP OpenSSL extension, which is typically included in modern PHP stacks. You can verify its installation by running:
php -i | grep openssl
To install the TFA module and its soft dependency, use Composer:
composer require drupal/tfa drupal/real_aes
Installation and Configuration
Install the module: Use the command-line instructions above, or install via the Extend page /admin/modules.
Encryption Key and Profile: Follow the instructions in the TFA module’s README file for your branch:
These files will walk you through setting an encryption key and an encryption profile.
Enable TFA: Go to Admin > Configuration > People > TFA (/admin/config/people/tfa) and enable the module.
Configure Roles: After enabling TFA, you can require it for specific roles on your site.
Basic Authentication and MFA
It is important to note that enabling TFA does not disable basic username/password authentication. Users without the roles required to use TFA will continue to log in as normal. Users with roles that do require TFA will first enter their username/password, and then will be prompted for their MFA code.
Security Considerations
Basic Authentication for Web Services: Be aware that modules like
Basic Authentication use HTTP Basic Authentication, which transmits usernames and passwords in plain text (though base64 encoded). While Basic Authentication provides a way for web services to authenticate, it is crucial to secure the connection using HTTPS (SSL/TLS) to encrypt the transmission and prevent eavesdropping. Consider using other authentication methods, like OAuth, for improved security where possible.
Permissions: The core User module allows users to register, log in, and log out, and administrators to manage user roles and permissions. The core Ban module allows administrators to ban certain IP addresses from accessing the site. Ensure that permissions are properly configured for each role to maintain a secure environment. Grant permissions only to trusted roles, especially those with security implications. Periodically review the permissions assigned to each role at Admin > People > Permissions (/admin/people/permissions).
3 - Content Structure
Welcome to the Content Structure documentation.
Here you can find technical descriptions of content entities and fields used by YMCA Website Services site builders. The YMCA Website Services core team has established specifications for fields and created naming conventions to help developers maintain and upgrade their sites alongside the YMCA Website Services development timeline.
Key Concepts
Content Entity: A fundamental unit of content, such as a page, article, or block.
Field: A specific data element within a content entity, like a title, body, image, or date.
Content Type: A pre-defined structure for content entities, specifying the available fields and their configuration.
Module: A collection of code that extends Drupal’s functionality, potentially introducing new content types, fields, or other features. See
Extending and Altering Drupal.
Small Y: Refers to a specific set of modules within the YMCA Website Services ecosystem designed for smaller YMCA branches, as detailed in the
Small Y module README.
Content Entities
Content entities are the building blocks of your website’s content. Each content type has a defined set of fields. Here are some commonly used content entities in YMCA Website Services:
Article: Used for news, announcements, and blog posts. Often includes fields for title, body, image, and publication date. (See also: ws_small_y/modules/small_y_articles/small_y_articles.info.yml)
Landing Page: Designed for creating visually appealing and informative pages. Offers flexible layouts and various content areas. (See also: openy_node_landing.info.yml)
Promotion: Used to highlight special offers, events, or campaigns. Typically includes fields for title, description, image, and link. (See also: ws_promotion.info.yml)
Branch/Facility: Represents a physical YMCA location, including address, hours, amenities, and social links. (See also: ws_small_y/modules/small_y_branch/small_y_branch.info.yml, y_facility.info.yml)
Camp: Content type for YMCA Camps, including integration with Layout Builder. (See also: y_camp/y_camp.info.yml)
Fields
Fields store specific data within content entities. Here are some common field types used in YMCA Website Services:
Text: Stores text content, with options for plain text, formatted text, and summaries.
Image: Uploads and stores images, with options for alt text and display settings.
Link: Stores URLs and link text.
Date: Stores dates and times.
Entity Reference: Establishes a relationship between one entity and one or more other entities. For example, a “Related Articles” field can link an article to other relevant articles.
Boolean: Stores true/false values (e.g., a “Featured” checkbox).
List (Options): Allows users to select a value from a predefined list.
Modules and Content Structure
Several modules contribute to the content structure of YMCA Website Services:
Y Layout Builder (y_lb): Provides a base for layout building functionalities.
Small Y (ws_small_y): Offers customizations for smaller YMCAs. See
Small Y module README.
Layout Builder Restrictions: Allows administrators to restrict the available blocks and layouts within the Layout Builder.
Branch Modules (lb_branch_*_blocks): Provide specific block types for displaying branch-related information, such as amenities, hours, and social links.
Staff Members (lb_staff_members_blocks & ws_small_y_staff): Modules for displaying staff members.
Configuration Management
Configuration is managed through YAML files, which define the structure, data types, and translatability of content. See the
Configuration API for details.
Blocks are boxes of content rendered into a specific area, or region, of a web page. Blocks are placed and configured specifically for each theme, allowing for customization of content display and layout. Think of them as reusable content containers.
What are Content Blocks?
Content blocks are a specific type of block, where you can edit the content directly through the administrative interface. You can define one or more block types and attach fields to each block type, enabling structured content creation for blocks. Content blocks can be placed just like blocks provided by other modules.
What is the Block Description?
The block description is an administrative label for a block, which is displayed in the administrative interface to help identify the block. It is not displayed to site visitors on the live website.
What is the Block Title?
The block title is the heading that is optionally displayed to site visitors when the block is placed in a region. The visibility of the title can be configured within the block’s settings.
Managing Blocks
The Block module allows you to place existing blocks in regions of your installed themes and configure various block settings, such as title visibility, and user roles. The Block Content module allows you to manage custom block types and create/edit their content.
Refer to the related topics listed below for specific tasks.
3.1.1 - Basic
A simple block with a description. This block type is commonly used for displaying basic content on a website. It offers a single WYSIWYG field for content creation.
Fields
Name
Machine name
Required
Description
Content
field_block_content
Yes
WYSIWYG field without summary. Allows rich text formatting.
3.1.2 - Block Menu
The Block Menu implements a custom block type with links. Blocks are boxes of content rendered into a region of a web page. Content blocks are blocks whose content you can edit, placing them like blocks provided by other modules. The block description is an identification name for a block, shown in the administrative interface but not displayed on the site. The block title is the heading optionally shown to site visitors when the block is placed in a region.
Fields
Name
Machine name
Required
Description
Menu Links
field_menu_block_links
Yes
The menu links to be displayed in the block.
Color
field_menu_block_color
Yes
Select the background gradient color for the menu block.
Text color
field_menu_block_text_color
Yes
Select the text color for the menu block.
3.1.3 - Branch Amenities
A block displaying a list of amenities for the current branch.
Fields
Name
Machine name
Required
Description
Branch amenities
field_branch_am
Yes
Uses a custom formatter to display a list of amenities within a Paragraph block. This field is a boolean to indicate if the amenity is available. Hidden from content managers by default.
Link
field_sb_link
No
A link to display at the bottom of the block. Allows for adding attributes like target, rel, and class.
Title
field_sb_title
No
A title to display at the top of the block.
Icon class
field_icon_class
No
A Font Awesome icon name, e.g., flag, car, or info. This overrides the image icon. See
Font Awesome for available icons.
Section Title
field_section_title
No
Section heading
Section Subtitle
field_section_subtitle
No
Section subheading
Image
field_image
No
Image for the block. Uses the amenities_image image style.
3.1.4 - Custom Simple
A simple block with a body, title, icon and link.
Fields
Name
Machine name
Required
Description
Icon
field_icon
No
Icon for the block.
Icon class
field_icon_class
No
Provide a “Font Awesome” icon name, e.g. flag, car, info. Overrides image icon. See available icons
here.
Body
field_sb_body
No
Enter the main body text for the block. Supports basic HTML.
Link
field_sb_link
No
Add a link to the block. Provide a full URL.
Title
field_sb_title
No
Title to display at the top of the block. If left blank, no title will be displayed.
3.1.5 - Flexible
The Flexible block provides a way to display content from a referenced node.
Fields
Name
Machine name
Required
Description
Node reference
field_node_ref
Yes
Provide a reference to a Node. The content of the referenced node will be displayed in the block.
3.2 - Content Types
Welcome to the YMCA Website Services Content Types documentation.
In terms of YMCA Website Services, content types are “bundles” of a “node” entity within the Drupal Framework. For more low-level documentation, refer to
drupal.org.
YMCA Website Services ships with a set of content types to simplify site usage. While the number of content types isn’t restricted and developers can add more, the goal is to ensure that the shipped list of content types is covered by the YMCA Website Services upgrade path.
Understanding Content Types
Content Entity: A content entity is an item of content data like text, images, or files. Content entities are grouped into entity types, which are further divided into entity sub-types to allow for variations in how the entities are used and displayed.
Fields: Data within content entities is stored in individual fields. Each field holds a specific data type (formatted text, plain text, images, etc.) Fields can be single or multiple-valued.
Reference Field: A reference field stores a relationship between one entity and one or more other entities.
Formatter: A formatter determines how a field is displayed.
Widget: A widget determines how a field is edited.
Managing Content Structure
Several core modules are used to manage content structure:
Node, Comment, Content Block, Custom Menu Links, User, File, Image, Media, Taxonomy, and Contact modules: Provide content entity types.
Field UI module: Provides a user interface for managing fields and their display on entities.
Layout Builder module: Provides a user interface for configuring the display of entities.
Filter, Responsive Image, and Path modules: Provide settings and display options for entities and fields.
3.2.1 - Activity
The Activity content type is used for adding Activities to the site. Activities are typically associated with Programs and Classes.
Fields
Name
Machine name
Required
Description
Title
drupal's default
Yes
Title of the activity item. This is the standard Drupal title field.
Program Subcategory
field_activity_category
Yes
A reference field for selecting the program subcategory to which the activity belongs. This field connects the Activity to a specific subcategory within the broader program structure.
Content Area
Field group
A field group to organize the main content of the Activity.
Description
field_activity_description
No
Textarea for the description/body of the activity. This field uses a WYSIWYG editor (like CKEditor) for rich text formatting, but does not support a summary field.
/programs/: Indicates that this is part of the Programs section of the site.
[node:field_activity_category:entity:field_category_program:entity:title]: This part of the URL is dynamically generated from the title of the Program to which the activity subcategory is associated.
[node:field_activity_category:entity:title]: This is dynamically generated from the title of the Activity Category.
[node:title]: This part is dynamically generated from the title of the Activity node itself.
3.2.2 - Alert
The Alert content type is used for displaying timely information in a banner across the site. Unlike most content types, you don’t use Alert to create pages. Instead, Alerts display as a rendered entity, as a section of content on other pages, either just below the header or above the footer.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the alert, which will display as the headline.
Background color
field_alert_color
Yes
Reference field for choosing a term from the “Color” vocabulary.
Text color
field_alert_text_color
Yes
Reference field for choosing a term from the “Color” vocabulary. For accessibility, stick to using either black or white.
Icon color
field_alert_icon_color
No
Reference field for choosing a term from the “Color” vocabulary. Leave empty to hide the icon.
Placement
field_alert_place
Yes
Select list field (singular) for choosing placement:
Header
Footer
Description
field_alert_description
Yes
Textarea for the main body of the alert with WYSIWYG (What You See Is What You Get) editor, without summary. Sentences should be short and minimally styled in this section.
Link
field_alert_link
No
Internal or external link. Adds a button with a call to action to the alert on the right. The button color defaults to black.
Reference
field_alert_belongs
No
Entity reference with autocomplete to any node. Reference to a node (branch, camp, landing page, etc.) where the alert will be displayed.
URL pattern
Content type uses the following pattern: /alert/[node:title].
3.2.3 - Article
The Article content type is used for creating blog posts, news items, and press releases on the site.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the article item. This field utilizes the core text field type. See
TextItem.php for more information.
Sub-title
field_article_subtitle
No
Sub-title of the article item.
Locations
field_article_location
Yes
Reference field to branch and camp nodes. Allows multiple values.
Category
field_article_category
No
Reference field for choosing terms from the “Blog Category” vocabulary. Allows multiple values.
Meta Tags
field_meta_tags
No
A meta tags field that allows providing structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites. This utilizes the
Metatag module.
Type
field_article_type
Yes
Select list field with the following options for choosing the article type:
- News Item (default)
- Blog Post
- Press Release
Image
field_article_image
No
Image field for the article item. Entity reference to a Media bundle.
Body
body
No
Text area for the main content of the article. This field uses a WYSIWYG editor and does not include a summary field.
Content
field_content
No
Filter list of available
Layout Builder components. This field enables the arrangement of content using configurable layouts.
Related Content
field_article_related
No
Reference field for selecting related Article nodes. Allows multiple values.
URL patterns
The Article content type uses the following URL patterns:
/blog/[node:title]
/news/[node:title]
/press-release/[node:title]
3.2.4 - Blog
The Blog Post content type is used for adding blog posts to the site.
Fields
Name
Machine name
Required
Description
Title
Drupal’s default
Yes
Title of the blog item.
Locations
field_blog_location
Yes
Reference field to branch and camp nodes. Allows multiple values, enabling association with multiple locations.
Category
field_blog_category
No
Reference field for choosing terms from the “Blog Category” vocabulary. Allows multiple values, categorizing blogs under several topics.
Meta Tags
field_meta_tags
No
Allows providing structured metadata and Open Graph meta tags for social networking sites like Facebook, Pinterest, and LinkedIn, enhancing SEO and sharing.
Styles
Field group
Style
field_blog_style
Yes
Select list field with multiple options for choosing a style:
- Story Card
- Photo Card
- News Card (default)
- Color Card
Background color
field_blog_color
No
Background color for the teaser, used when the “Color Card” style is selected.
Text color
field_blog_text_color
No
Text color for the teaser, used when the “Color Card” style is selected.
Content Area
Field group
Image
field_blog_image
No
Image field for the Blog item. Entity reference to a Media bundle, allowing selection of pre-uploaded images.
Description
field_blog_description
No
Textarea for the description/body with WYSIWYG editing capabilities and no summary field.
Content
field_content
No
A Paragraph embed field that allows adding various flexible content modules from a predefined list of paragraph types.
Sidebar Area
Field group
Related content
field_blog_related
No
Reference field for choosing related Blog nodes. Allows multiple values for cross-linking content.
Content
field_sidebar_content
No
A Paragraph embed field that allows adding various flexible content modules to the sidebar, from a predefined list of paragraph types.
URL pattern
This content type uses the following URL pattern:
/blog/[node:title]
3.2.5 - Branch
The Branch content type is used for adding and managing branch locations on the site. Each branch can have detailed information, including address, contact details, hours of operation, and associated content.
Fields
Name
Machine name
Required
Description
Title
Drupal’s default
Yes
Title of the branch item. This is the main identifier for the branch.
Neighborhood
field_location_area
No
A taxonomy reference field using the “Area” vocabulary. This allows you to categorize branches by geographical area or neighborhood.
Coming Soon
field_location_state
No
A checkbox field to indicate if the branch is still in development or not yet open to the public.
Temporary URL
field_location_temp_url
No
A link field to provide a temporary page URL (e.g., a blog post or announcement) if the branch is coming soon and doesn’t have a permanent page yet.
Meta Tags
field_meta_tags
No
A meta tags field allows you to provide structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites. This helps with SEO and social sharing.
Contact
Field group
Address
field_location_address
Yes
An address field that allows you to add detailed location information. This field stores:
Address
City
State
Zip Code
Branch Coordinates
field_location_coordinates
No
Input for providing the latitude and longitude information.
Phone
field_location_phone
Yes
Input for providing the branch’s phone number.
Fax
field_location_fax
No
Input for providing the branch’s fax number (if applicable).
Email
field_location_email
No
Input for providing the branch’s email address.
Directions
field_location_directions
No
A link field for adding a directions link (e.g., to a Google Maps page or other online mapping service).
Branch Hours
Field group
Branch Hours
field_branch_hours
Paragraph
A paragraph field to indicate the branch’s hours of operation. This allows for flexible scheduling, including different hours for different days.
Day of the week
field_branch_hours_day
No
A select list with the following values:
sunday|Sunday
monday|Monday
tuesday|Tuesday
wednesday|Wednesday
thursday|Thursday
friday|Friday
saturday|Saturday
Start/End Time
field_branch_hours_time
No
A text field with a description “e.g. 9am - 5pm, closed.” This field stores the opening and closing times for a specific day.
Header Area
Field group
Content
field_header_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This allows you to customize the header area of the branch page.
Content Area
Field group
Content
field_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This is the main content area of the branch page.
Bottom Area
Field group
Content
field_bottom_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This allows you to add content to the bottom area of the branch page.
URL pattern
The Branch content type uses the following URL pattern:
/locations/[node:title]
3.2.6 - Camp
The Camp content type is used for adding camp information to the site.
Fields
Name
Machine name
Required
Description
Title
Drupal’s default
Yes
Title of the camp item.
Menu links
field_camp_menu_links
Yes
Link field with multiple values, that should have the Title and Link field. Based on it, we will complete the Camp Menu.
Meta Tags
field_meta_tags
No
A meta tags field allows us to provide structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites.
Contact
Field group
Address
field_location_address
Yes
An address field that will provide the ability to add details about the locations. Details to be completed:
- Address
- City
- State
- Zip Code
Camp Coordinates
field_location_coordinates
No
Input for providing the latitude and longitude information.
Phone
field_location_phone
Yes
Input for providing the phone information.
Fax
field_location_fax
No
Input for providing the fax information.
Email
field_location_email
No
Input for providing the email information.
Directions
field_location_directions
No
A link field for adding the directions link.
Header Area
Field group
Content
field_header_content
No
A paragraph embed field that will allow us to add various flexible content modules from the predefined list of paragraph types.
Content Area
Field group
Content
field_content
No
A paragraph embed field that will allow us to add various flexible content modules from the predefined list of paragraph types.
Bottom Area
Field group
Content
field_bottom_content
No
A paragraph embed field that will allow us to add various flexible content modules from the predefined list of paragraph types.
URL pattern
This content type uses the following URL pattern:
/camps/[node:title]
3.2.7 - Class
The Class content type is used for adding Classes to the site.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the class item.
Activity
field_class_activity
No
A reference field for selecting the activity the class belongs to. This field references a taxonomy term from the “Activity” vocabulary.
Meta Tags
field_meta_tags
No
A meta tags field that allows you to provide structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites. This helps with SEO and social sharing.
Header Area
Content
field_header_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This allows for rich and structured content within the header.
Content Area
Description
field_class_description
No
Text area for the class description/body, using a WYSIWYG editor. A summary is not available for this field.
Content
field_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This is the main content area for the class.
Sidebar Area
Content
field_sidebar_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This is for content that will appear in the sidebar of the class page.
Bottom Area
Content
field_bottom_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This is for content that appears at the bottom of the class page, often used for calls to action or related links.
Note: Fields marked as “Field group” are not actual fields but are used to group the fields in the table for better readability.
URL pattern
The Class content type uses the following URL pattern:
[program-category]: The title of the program category, derived from the field_class_activity reference field to the Activity taxonomy term, which in turn references the Program taxonomy term: [node:field_class_activity:entity:field_activity_category:entity:field_category_program:entity:title].
[activity-category]: The title of the activity category, derived from the field_class_activity reference field to the Activity taxonomy term: [node:field_class_activity:entity:field_activity_category:entity:title].
[class-title]: The title of the class node: [node:title].
/class-times: A fixed suffix for the class times page.
3.2.8 - Event
The Event content type is used for adding and managing events on the site.
Fields
Label
Machine Name
Required
Description
Field Settings
Notes
Title
drupal’s default
Yes
Title of the event.
Sub-title
N/A
No
Subtitle of the event.
Plain text
Locations
field_event_location
Yes
Reference field to branch and camp nodes. Allows multiple values.
Address for the event; can be either a branch or a non-branch location.
Category
field_event_category
No
Reference field for choosing terms from the “Event Category” vocabulary. Allows multiple values.
Meta Tags
field_meta_tags
No
Allows providing structured metadata and Open Graph meta tags for social networking sites like Facebook, Pinterest, and LinkedIn.
Image
field_event_image
No
Image for the event. Entity reference to a Media bundle.
Media
Date
field_event_date
Yes
Uses Drupal’s built-in date/time fields.
Add to Calendar
field_add_to_calendar_link
No
Link to add event to calendar.
Link
Body
body
No
Textarea for the event description with WYSIWYG editor, without summary.
Content
field_content
No
Filter list of available layout builder components.
Related Content
field_event_related
No
Reference field for choosing related Event nodes. Allows multiple values.
URL pattern
The Event content type uses the following URL pattern:
/event/[node:title]
3.2.9 - Facility
Facility content type is used for adding facilities on the site.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the facility item.
Neighborhood
field_location_area
No
A taxonomy reference field using the Area Vocabulary(area).
Type
field_facility_type
No
A taxonomy reference field using the “Facility Type” vocabulary.
Facility Branch
field_facility_loc
No
An entity reference field to reference the related Branch node.
Meta Tags
field_meta_tags
No
A meta tags field allows us to provide structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites.
Contact
Field group
Address
field_location_address
No
An address field that will provide the ability to add details about the locations. Details to be completed:
Address
City
State
Zip Code
Facility Coordinates
field_location_coordinates
No
Input for providing the latitude and longitude information.
Phone
field_location_phone
Yes
Input for providing the phone information.
Fax
field_location_fax
No
Input for providing the fax information.
Email
field_location_email
No
Input for providing the email information.
Directions
field_location_directions
No
A link field for adding the directions link.
Facility Hours
field_branch_hours
No
The facility hours.
Facility Holiday Hours
field_branch_holiday_hours
No
Any special holiday hours for the facility.
Content Area
Field group
Content
field_content
No
A paragraph embed field that will allow us to add various flexible content modules, from the predefined list of paragraph types.
Sidebar Area
Field group
Content
field_sidebar_content
No
A paragraph embed field that will allow us to add various flexible content modules, from the predefined list of paragraph types.
URL pattern
Content type is using the following pattern:
/facility/[node:title]
3.2.10 - Landing Page
The Landing Page content type is used for creating landing pages on the site.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the landing page item.
Layout
field_lp_layout
Yes
Select list with the options:
one_column_clean|One Column - Full width
one_column|One Column
two_column|Two Columns
two_column_fixed|Two Columns with fixed sidebar (sticky at the top)
Meta Tags
field_meta_tags
No
A meta tags field allows us to provide structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites.
Header Area
Field group
Content
field_header_content
No
A paragraph embed field that allows you to add various flexible content modules from the predefined list of paragraph types.
Content Area
Field group
Content
field_content
No
A paragraph embed field that allows you to add various flexible content modules from the predefined list of paragraph types.
Sidebar Area
Field group
Content
field_sidebar_content
No
A paragraph embed field that allows you to add various flexible content modules from the predefined list of paragraph types.
Bottom Area
Field group
Content
field_bottom_content
No
A paragraph embed field that allows you to add various flexible content modules from the predefined list of paragraph types.
URL pattern
The content type uses the following pattern:
[node:title]
3.2.11 - Landing Page (Layout Builder)
Landing Page content type is used to add Landing Pages to your website using Layout Builder widgets.
This page is managed with Layout Builder. You may want to uncheck “Published” before creating a page, use the “Layout” tab to build the content, then Publish when the page is complete. See our
User Guide for help. You can also use the “Save and edit layout” button to stay in Layout Builder after saving.
Fields
Label
Machine Name
Required
Description
Field Settings
Notes
Title
title
Yes
Title of Landing Page
This is used as the administrative title and may also be displayed on the page, depending on your Layout Builder configuration.
Metadata
Field group
Meta description
field_meta_description
No
Short text used for metatags and cards
Text (plain, long)
A brief and concise summary of the pages content that is a maximum of 160 characters in length.
Meta image
field_meta_image
No
Media image reference for use in metatags and cards
Entity reference (Media image)
Choose or upload an image to be used as a thumbnail for social sharing and preview cards.
Meta tags
field_meta_tags
No
Provided by Metatag module. Advanced meta tag configuration.
This section should not be edited unless you are familiar with meta tags.
URL pattern
This content type uses the following pattern by default: [node:title]
3.2.12 - Membership
The Membership content type is used for adding membership information to the site.
Fields
Name
Machine name
Required
Description
Title
Drupal’s default
Yes
Title of the membership item.
Description
field_mbrshp_description
Yes
Textarea for the description/body with WYSIWYG, without summary.
Image
field_mbrshp_image
Yes
Media field to upload the image.
Membership info
field_mbrshp_info
Paragraph
Paragraph to indicate the location where the membership is available and the URL.
Location
field_mbrshp_location
No
Select list with locations (branches). Single value.
Link
field_mbrshp_link
No
Link field to provide the membership redirect URL.
Join Fee
field_mbrshp_join_fee
No
Dollar value for how much someone has to pay to join.
Monthly Rate
field_mbrshp_monthly_rate
No
Dollar value for the monthly fee of the membership.
URL pattern
The content type uses the following pattern for its URLs:
/membership/[node:title]
3.2.13 - News
The News Post content type is used for adding news posts to the site. News posts are typically displayed in a list or grid format, with the most recent posts appearing first.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the news item. This field is a standard Drupal title field.
Locations
field_news_location
Yes
Reference field to branch and camp nodes. Allows multiple values, enabling you to associate the news item with multiple locations.
Category
field_news_category
No
Reference field for choosing a term from the “News Category” vocabulary. Allows multiple values, enabling categorization of the news item.
Meta Tags
field_meta_tags
No
A meta tags field that allows you to provide structured metadata and Open Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites.
Content Area
Field group
Image
field_news_image
No
Image field for the News item. Entity reference to a Media bundle. This allows you to select an existing image from the media library.
Description
field_news_description
No
Text area for the description/body with WYSIWYG (What You See Is What You Get) editor, without summary option.
Content
field_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types.
Sidebar Area
Field group
Related content
field_news_related
No
Reference field for choosing related News nodes. Allows multiple values to link to other relevant news items.
Content
field_sidebar_content
No
A paragraph embed field that allows you to add various flexible content modules to the sidebar from a predefined list of paragraph types.
URL pattern
This content type uses the following URL pattern:
/news/[node:title]
The [node:title] token is replaced with the title of the news item, with spaces replaced by hyphens. For example, a news item with the title “New Branch Opens” would have the URL /news/new-branch-opens.
3.2.14 - Program
The Program content type is used for adding Programs to the site.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the program item.
Meta Tags
field_meta_tags
No
A meta tags field allows us to provide structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites.
Header Area
Field group
Icon
field_program_icon
No
An image field, supporting .svg for uploading the program icon.
Image
field_program_image
No
An image field, for uploading the program image.
Color
field_program_color
No
Reference field for choosing a term from the “Color” vocabulary.
Content
field_header_content
No
A paragraph embed field that allows adding various flexible content modules from a predefined list of paragraph types. If this field is not empty, the image and icon are not displayed on the page.
Content Area
Field group
Description
field_program_description
No
Text area for the description/body with WYSIWYG, without summary.
Content
field_content
No
A paragraph embed field that allows adding various flexible content modules from a predefined list of paragraph types.
Sidebar Area
Field group
Content
field_sidebar_content
No
A paragraph embed field that allows adding various flexible content modules from a predefined list of paragraph types.
URL pattern
This content type uses the following URL pattern:
/programs/[node:title]
3.2.15 - Program Subcategory
The Program Subcategory content type is used for adding program subcategories to the site.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the program subcategory item.
Program
field_category_program
Yes
A reference field for selecting the program. This establishes the parent program for the subcategory.
Meta Tags
field_meta_tags
No
A meta tags field that allows you to provide structured metadata and Graph meta tags for Facebook, Pinterest, LinkedIn, and other social networking sites. This helps with SEO and social sharing.
Header Area
Field group
Image
field_category_image
No
An image field for uploading the category image. This image is typically displayed in the header area of the subcategory page.
Color
field_category_color
No
Reference field for choosing a color term from the “Color” vocabulary. This allows you to visually distinguish subcategories.
Content
field_header_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This allows for rich and dynamic content within the header area.
Content Area
Field group
Description
field_category_description
No
A textarea for the description/body of the subcategory, using a WYSIWYG editor and without a summary field.
Content
field_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This is the main content area of the subcategory page.
Sidebar Area
Field group
Content
field_sidebar_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This is the content that will appear in the sidebar of the subcategory page.
Bottom Area
Field group
Content
field_bottom_content
No
A paragraph embed field that allows you to add various flexible content modules from a predefined list of paragraph types. This allows you to add content to the very bottom of the subcategory page. This could be calls to action, related content, or other supplemental information.
This means that the URL will be constructed using the title of the parent program and the title of the subcategory itself. For example, if the parent program is “Youth Programs” and the subcategory is “Summer Camp”, the URL would be /programs/youth-programs/summer-camp.
3.2.16 - Promotion
Promotions are timed pieces of content that allow content editors the flexibility to create a single item that can be placed in multiple locations on the site, without having to duplicate or manage content in multiple locations. This content type is typically not displayed on its own page.
Fields
Name
Machine name
Field type
Required?
Description
Title
title
Text (plain)
Yes
The main title of the promotion.
Subtitle
field_subtitle
Text (plain)
No
A secondary title or short description displayed below the main title.
CTA / link
field_link
Link
No
A call-to-action link that directs users to a specific page or external resource.
Description
field_promo_description
Text (formatted, long)
No
A longer description providing more details about the promotion. This field supports rich text formatting (e.g., bold, italics, lists, links).
Image
field_promo_media
Entity reference
Yes
An image associated with the promotion. This is an entity reference to a media item.
Pages
field_promo_visibility_pages
Text (plain, long)
No
A list of internal page paths where the promotion should be displayed. Use relative paths. One path per line. Use <front> for the front page.
Promotion Category
field_promo_category
Entity reference
No
A category that classifies the promotion (e.g., “New Product,” “Sale,” “Event”). This is an entity reference to a taxonomy term.
Promotion Priority
field_promo_priority
List (text)
Yes
Determines the order in which promotions are displayed. Options might include “High,” “Medium,” and “Low.”
Promotion visibility state
field_promo_visibility_state
List (text)
Yes
Controls whether the promotion is visible or hidden. Options may include “Published”, “Unpublished”.
URL pattern
Promotions are generally embedded within other pages and do not have their own dedicated URL. Therefore, no URL pattern is defined for this content type.
3.2.17 - Session
The Session content type is used for adding Sessions to the site. Sessions typically represent events, classes, or other scheduled activities.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the session item.
Class
field_session_class
Yes
A reference field for selecting the program subcategory or type of session. This allows you to categorize sessions.
Session Info
Field group
-
-
Description
field_session_description
No
Textarea for the description/body of the session. Uses a WYSIWYG editor (like CKEditor) without a summary field.
Gender
field_session_gender
No
Select List with Gender options: Coed, Male, Female. This allows you to specify if the session is intended for a specific gender or is coeducational.
Online registration
field_session_online
No
Boolean field (checkbox) that determines if a “Register Now” button/link is displayed for the session.
Ticket required
field_session_ticket
No
Checkbox field to indicate that a ticket is required to attend the session.
Min Age
field_session_min_age
No
Input field for adding the minimum age allowed to participate in the session.
Max Age
field_session_max_age
No
Input field for adding the maximum age allowed to participate in the session.
Registration link
field_session_reg_link
No
A link field containing the URL for session registration. This is used if online registration is handled by a third-party system.
Membership
Field group
-
-
In membership
field_session_in_mbrsh
No
Boolean field (checkbox) that indicates whether the session is included in a membership package.
Member price
field_session_mbr_price
No
Input field for specifying the price for members.
Non Member Price
field_session_nmbr_price
No
Input field for specifying the price for non-members.
Location
Field group
-
-
Location
field_session_location
Yes
A reference field for selecting the branch or camp where the session is held. This should link to a location content type.
Physical Location
field_session_plocation
No
A reference field for selecting the specific facility (e.g., room, gym) within the branch or camp where the session takes place. This should link to a facility content type.
Time
Field group
-
-
Exclusions
field_session_exclusions
No
A date field that identifies specific dates on which the session will not be held, even if it’s normally scheduled. Supports multiple values. Should be a single date field with the ’end date’ option enabled. Its widget should be adjusted to not show period end date, but show period end time (to keep period start/end date equal).
Time
field_session_time
Paragraph
Session schedule defined using a Paragraph content type.
Date & Time
field_session_time_date
No
A Drupal date/time field. Should be a single date field with both ’end date’ and ’end time’ options enabled.
Days
field_session_time_days
No
Checkboxes with the following values:
sunday|Sunday
monday|Monday
tuesday|Tuesday
wednesday|Wednesday
thursday|Thursday
friday|Friday
saturday|Saturday
Supports multiple values, allowing you to select all days on which the session occurs.
URL pattern
No dedicated URL pattern is defined for the Session content type by default. The intention is that this content type may not be directly accessed by end-users via a dedicated URL.
3.2.18 - Social Post
The Social Post content type is used for adding social media posts to the site. Social Posts are typically fetched from social networks using a module like the
Social Feed Fetcher.
Fields
Name
Machine name
Required
Description
Title
drupal’s default
Yes
Title of the social post content item.
ID
field_id
Yes
Post ID in the social network. This is a system field used by the post fetcher to identify the social post.
Image
field_sp_image
No
Image field for saving the post image. Supports jpg, png, and gif formats.
Link
field_link
No
Contains the link to the original post on the social network.
Platform
field_platform
Yes
The name of the platform where the post was imported from (e.g., Facebook, Twitter, Instagram).
Post
field_post
Yes
The text content of the post. May contain HTML markup.
Posted
field_posted
Yes
The date and time when the post was originally posted on the social network.
URL pattern
The content type uses the following URL pattern:
/social_post/[node:title]
3.3 - Layout Builder
These custom block types exist to support page building with Layout Builder. Blocks are boxes of content rendered into a region of a web page. Content blocks are blocks whose content you can edit.
Global Fields
These fields are reused across many of the below components.
Core media items include audio, images, documents, and videos. You can add other media types, such as social media posts, through the use of contributed modules. Media items may be files located in your site’s file system or remote items referenced by a URL. Media items are content entities, and they are divided into media types (which are entity sub-types); media types can have fields. Refer to the
Content Structure documentation for more information on content entities and fields.
What is the Media Library?
The media library is a visual user interface for managing and reusing media items. Add media items to content using Media reference fields and the Media library field widget.
What is an Image Style?
An image style is a set of processing steps, known as effects, that can be applied to images. Examples of effects include scaling and cropping images to different sizes. Responsive image styles can associate image styles with your theme’s size breakpoints. This allows serving images sized for the browser width.
Overview of Managing Media
The following modules provide media-related functionality:
Media items and media types are managed by the core Media module.
The core Media module provides a Media reference field to add media to content entities. The core File and Image modules also provide reference fields. It is recommended to use the Media reference field because it is more versatile.
The core Media Library module provides the media library and the Media library field widget. With this module installed, the Media library field widget becomes the default widget for editing Media reference fields.
The core Image module provides a user interface for defining image styles. The core Responsive Image module provides responsive image styles. Using the core Breakpoint module and a breakpoint-enabled theme, these responsive styles can serve images sized for the browser.
See the related topics listed below for specific tasks.
The following view modes are available for embedding media assets within a WYSIWYG editor, such as CKEditor 5. These view modes offer different display options for media assets, allowing content creators to choose the most appropriate presentation for their content.
View Modes
Name
Machine name
Description
Full
embedded_full
Displays the media asset at its full width within the available container.
Half
embedded_half
Displays the media asset at half its original width, typically with alignment options (left or right) to control its placement.
Link
embedded_link
Displays a simple link to the media asset, directing the user to the original file.
Bundle Details
The display of each media asset type (Image, Video, Document) varies depending on the selected view mode. The following outlines the specific rendering for each bundle:
Image
Full & Half View Modes: Images are displayed using the <img> tag with appropriate CSS classes applied for styling and responsiveness. The specific classes may vary depending on the theme and styling configuration.
Link View Mode: A hyperlink (<a> tag) is generated, pointing to the original image file. The link includes target="_blank" to open the image in a new tab or window.
Video
Full & Half View Modes: Videos are displayed as embedded video players, likely using the <video> tag or an <iframe> to embed from a video hosting platform. Appropriate CSS classes are applied for styling.
Link View Mode: A hyperlink (<a> tag) is generated, pointing to the original video file. The link includes target="_blank" to open the video in a new tab or window.
Document
Full & Half View Modes: Documents are displayed using an <iframe> tag. The src attribute of the <iframe> points to a service like Google Docs Viewer, which renders the document within the iframe. Replace URL with the actual URL of the document. Appropriate CSS classes are applied for styling.
Link View Mode: A hyperlink (<a> tag) is generated, pointing to the original document file. The link includes target="_blank" to open the document in a new tab or window.
3.5 - Paragraphs
Welcome to YMCA Website Services Paragraphs.
Paragraphs are content components, aligning with
component-based design principles. Within the YMCA Website Services architecture, paragraphs are based on the
Paragraphs Drupal module. This module enables the creation of Paragraphs entities.
The core idea is to provide a user-friendly widget for adding predefined content blocks directly within a page or other content item, without needing to reference external entities. It’s important to note that paragraphs are not intended as reusable content types. For reusable content, consider using blocks or other entities within Drupal.
Paragraphs enhance the user experience by offering a convenient and structured way to build content. They allow content editors to create unique layouts for their pages. Each paragraph represents a distinct content section, complete with its own styling, functionality, and fields.
Here’s a breakdown of key aspects:
Paragraphs Module: Facilitates the creation of paragraph entities within Drupal.
Component-Based Design: Paragraphs align with the principle of building interfaces from independent, reusable components.
User Experience (UX): Paragraphs are designed to make content creation more intuitive and efficient.
Non-Reusable Types: Paragraphs are not designed to be reused across multiple content items. Instead, look at Drupal blocks or entities.
Paragraphs Types: Paragraphs are pre-defined sets of fields that are made available to the content editors. These are configured under Structure > Paragraphs Types.
To get started with Paragraphs:
Install the Paragraphs module.
Create Paragraphs types.
Add a Paragraph field to a content type.
Begin creating content and adding paragraphs.
3.5.1 - 1 Column
The 1 Column paragraph type allows you to create a single-column layout within your content.
Fields
Name
Machine name
Required
Description
Notes
Line Above
field_prfg_display_line_above
No
Display a line above the column.
Column
field_prgf_1c_column
No
Enter the main content for the single column. This field typically supports rich text.
Paragraph Title
field_prgf_1c_title
No
Enter a title to display at the top of the 1-column paragraph.
Paragraph Description
field_prgf_1c_description
No
Enter a description to display below the paragraph title.
3.5.2 - 2 Columns
The 2 Columns paragraph type allows you to create a paragraph with two columns for content. This is useful for displaying related information side-by-side or creating visually appealing layouts.
Fields
Name
Machine name
Required
Description
Notes
Line Above
field_prfg_display_line_above
No
Display a horizontal line above the columns.
Left Column
field_prgf_2c_left
No
Content for the left column.
Supports text, images, and other embedded content.
Right Column
field_prgf_2c_right
No
Content for the right column.
Supports text, images, and other embedded content.
3.5.3 - 3 Columns
The 3 Columns paragraph type allows you to create a paragraph with three distinct columns of content. This paragraph type is useful for displaying information in a structured and visually appealing manner.
Fields
Name
Machine name
Required
Description
Notes
Line Above
field_prfg_display_line_above
No
Display a line above the column.
Left Column
field_prgf_3c_left
No
Enter the content for the left column.
Center Column
field_prgf_3c_center
No
Enter the content for the center column.
Right Column
field_prgf_3c_right
No
Enter the content for the right column.
Paragraph Title
field_prgf_title
No
Enter a title to display at the top of the 3 columns paragraph.
3.5.4 - 4 Columns
The 4 Columns paragraph type allows you to create a content block with four columns of information. This is useful for displaying related content side-by-side.
Fields
Name
Machine name
Required
Description
Notes
Line Above
field_prfg_display_line_above
No
Display a line above the column.
Use this to visually separate this paragraph from the content above it.
First Column
field_prgf_4c_1st
No
Enter the content for the first column.
Supports text, images, and other embedded content.
Second Column
field_prgf_4c_2nd
No
Enter the content for the second column.
Supports text, images, and other embedded content.
Third Column
field_prgf_4c_3rd
No
Enter the content for the third column.
Supports text, images, and other embedded content.
Fourth Column
field_prgf_4c_4th
No
Enter the content for the fourth column.
Supports text, images, and other embedded content.
Button
field_prgf_4c_button
No
Button with link to display under the 4-column paragraph.
Use this to add a call to action or link to more information related to the content.
Paragraph Title
field_prgf_title
No
Enter a title to display at the top of the 4-column paragraph.
This provides a clear heading for the entire paragraph.
Paragraph Description
field_prgf_description
No
Enter a description to display under the 4-column paragraph title.
Use this to provide context or an overview of the content within the four columns.
3.5.5 - All Amenities
This paragraph displays a list of amenities, typically in a table view. It’s useful for showcasing available features or services.
Fields
Name
Machine name
Required
Description
All amenities
field_field_prgf_amnts_view
No
Predefined reference to a view that displays all amenities. Configure this view to control which amenities are shown and how they are formatted.
Title
field_prgf_title
No
Enter the title that will be displayed at the top of the paragraph. This provides context for the list of amenities.
Important Considerations:
View Configuration: The “All amenities” field relies on a pre-existing view. Ensure this view is properly configured to display the desired amenity information.
Paragraph Usage: This paragraph type is generally intended for use within a larger page structure, like a landing page or a branch details page.
Alternative: Consider using “Branch Amenities” block if you want to show the amenities for the current branch.
3.5.6 - Banner
The Banner paragraph type is used to display eye-catching content, often at the top of a page or section. It typically includes a headline, description, image, and a call to action link.
Fields
Name
Machine name
Required
Description
Notes
Headline
field_prgf_headline
Yes
The main heading of the banner. This should be concise and attention-grabbing.
Plain text, maximum 255 characters
Color
field_prgf_color
Yes
A reference field that allows you to select a color from the “Color” vocabulary. This color is often used as a background or accent color for the banner.
Choose a term from the “Color” vocabulary
Image
field_prgf_image
No
An entity reference to a media image. This image should be visually appealing and relevant to the banner’s content.
Single value
Description
field_prgf_description
No
A WYSIWYG field where you can add descriptive text to the banner. Use this to provide more context or details about the banner’s topic. It is recommended to avoid using a summary for this field.
Link
field_prgf_link
No
A link field that stores both internal and external links. Use this to direct users to relevant pages or resources. This can be a call to action.
Use for internal and external links
3.5.7 - Blog Posts Listing
This paragraph is dynamic and renders the latest blog posts, utilizing exposed filters for enhanced content discovery. It’s based on the openy_prgf_blog_listing module.
Key Features:
Filtering: Allows users to filter blog posts based on:
Location
Category
Text (Search Keywords)
Sticky at Top: Supports the “sticky at top” functionality to highlight important posts.
Ordering: Orders blog posts by published date, displaying the newest posts first.
Views Integration: Leverages Drupal’s Views module for flexible content display and filtering. The exposed filters are part of the View configuration.
Infinite Scroll: Supports the views_infinite_scroll module for a better user experience.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block that provides the blog post listing. It should have a default value and ideally be hidden in the form display to prevent accidental modification. The view should be configured to use exposed filters for Location, Category, and Text.
This dynamic paragraph renders the locations selection popup, based on the current node. It’s typically used to allow users to select a branch or location from a popup window. This selection can then influence other elements on the page, such as filtering schedules or classes.
Relates to:
[Schedule search list](Schedule search list.md)
[Classes Listing](Classes Listing.md)
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block that provides the location selection options. It should have a default value configured and is typically hidden in the form display to prevent direct user modification. This field is the key to connecting the paragraph to the actual location data.
Usage
This paragraph is often used in conjunction with other paragraphs and blocks to create a location-aware experience. For example, it might be used on a page with a schedule search to allow users to filter the schedule by location.
The openy_branch_selector module is often used to provide the functionality for selecting and saving a user’s preferred branch. The selected branch can then be used to pre-populate location filters and customize the user’s experience.
The specific appearance and behavior of the popup are determined by the view/block referenced in the field_prgf_block field. This allows for a high degree of customization to match the specific needs of the site.
3.5.9 - Branches Popup (Class)
This dynamic paragraph renders the location selection popup based on the current node. It’s typically used to allow users to select a location from a list of branches.
Relates to:
[Class Sessions](Class Sessions.md)
[Class Location](Class Location.md)
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to a View or a Block plugin. This field should have a default value configured and is typically hidden in the form display for content editors.
3.5.10 - Categories Listing
This is a dynamic paragraph that renders all published categories associated with the current program page.
It typically includes a “sticky at the top” option and orders items based on their published date (newest at the top).
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block. This field should have a default value and is typically hidden in the form display.
Note: The Categories Listing paragraph type displays taxonomy terms. Taxonomy terms are categorized under: plain text, number, reference, date and time and general.
3.5.11 - Class Location
This dynamic paragraph renders the location’s “class location” view mode based on the location URL query parameter with a valid ID. This paragraph is typically used on class pages to display location-specific information.
Context:
This paragraph is used to display location information, such as address, phone number, and hours, for a specific class.
The “class location” view mode defines how the location information is displayed.
Relates to [Branches Popup (Class)](Branches Popup (Class).md).
When the page has a location parameter, the Branches Popup paragraph will make an “Edit” link on this paragraph visible. That link triggers the Branches Popup to open, allowing the user to select a different location.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block. Should have a default value and should be hidden in the form display. This field determines which block is rendered within the paragraph. The referenced block provides the actual content and formatting for the location information. Consider using a view block to display dynamic content related to the location.
3.5.12 - Class Sessions
This dynamic paragraph renders class session instances based on the URL query parameter location with a valid ID.
Relates to [Branches Popup (Class)](Branches Popup (Class).md).
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block. Should have a default value and should be hidden in form display.
Displayed Table
The following fields are displayed in a table format:
Location: Displayed unless &location=% is present in the URL, in which case it is hidden.
Time + Date
Registration: A link to the registration page.
Details:
Online registration information
Ticket requirement status
Membership eligibility
Age: Minimum and maximum age range for the class.
Use Cases
These use cases describe the behavior of the Class Sessions paragraph in different scenarios, specifically regarding location filtering.
Class Page WITHOUT Location Popup
Use case 3: Class page WITHOUT location popup
Location Specified in URL
1 Location in specified URL
When a Class page without a location popup is opened.
And the URL contains location=%.
The system skips any existing cookie values.
The class session results are filtered based on the location specified in the URL.
A location teaser is displayed in the sidebar.
Preferred Branch Empty or Selected, No Location in URL
2 Preferred branch is empty and no location in URL or Preferred branch is selected and no location in URL
When a Class page without a location popup is opened.
And either:
No preferred branch is selected.
A preferred branch is selected, but the URL does not contain location=%.
The class session results include all branches.
“All locations…” is displayed in the sidebar.
Class Page WITH Location Popup
Use case 4: Class page WITH location popup
Location Specified in URL
1 Location in specified URL
When a Class page with a location popup is opened.
And the URL contains location=%.
The system skips any existing cookie values.
The class session results are filtered based on the location specified in the URL.
A location teaser is displayed in the sidebar.
The location teaser in the sidebar includes an “Edit” link that opens the location popup.
Preferred Branch Empty or Selected, No Location in URL
2 Preferred branch is empty and no location in URL or Preferred branch is selected and no location in URL
When a Class page with a location popup is opened.
And either:
No preferred branch is selected.
A preferred branch is selected, but the URL does not contain location=%.
The class session results include all branches.
“All locations…” is displayed in the sidebar.
The location popup is displayed, unless only one location is associated with the class.
3.5.13 - Classes Listing
Displays published classes and provides filtering options.
The Classes Listing paragraph displays all published classes, grouped by activity.
The Classes Listing Filters provide a filter form with the following fields:
Location
Program
Sub-program
Activity
Relates to [Branches Popup (All)](Branches Popup (All).md).
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block. A default value should be set, and this field should be hidden in the form display.
Use Cases
Use case 1: Classes Listing paragraph on a Program subcategory page WITHOUT location popup paragraph
1.1 Preferred branch is selected and no location in URL
When I open a Program subcategory page with the Classes Listing paragraph WITHOUT a location popup on the page.
And I have a preferred branch set (via cookie).
And I don’t have location=% in the URL.
Then the filter by location should be pre-defined based on the cookie value.
And the results should be filtered accordingly.
1.2 Preferred branch is empty and no location in URL
When I open a Program subcategory page with the Classes Listing paragraph WITHOUT a location popup on the page.
And I don’t have a preferred branch set (cookie is empty).
And I don’t have location=% in the URL.
Then the filter by location should show “All”.
And the results should be shown for all branches.
1.3 Location specified in URL
When I open a Program subcategory page with the Classes Listing paragraph WITHOUT a location popup on the page.
And I have location=% in the URL.
Then the preferred branch cookie should be ignored, regardless of its value.
And the filter by location should show the branch from the URL.
And the results should be filtered accordingly.
Use case 2: Classes Listing paragraph on a Program subcategory page WITH location popup
2.1 Preferred branch is selected and no location in URL
When I open a Program subcategory page with the Classes Listing paragraph WITH a location popup on the page.
And I have a preferred branch set (via cookie).
And I don’t have location=% in the URL.
Then the location popup shouldn’t be shown.
And the filter by location should be pre-defined based on the cookie value.
And the results should be filtered accordingly.
2.2 Preferred branch is empty and no location in URL
When I open a Program subcategory page with the Classes Listing paragraph WITH a location popup on the page.
And I don’t have a preferred branch set (cookie is empty).
And I don’t have location=% in the URL.
Then the filter by location should show “All”.
And the results should be shown for all branches.
And the location popup should be shown.
2.3 Location specified in URL
When I open a Program subcategory page with the Classes Listing paragraph WITH a location popup on the page.
And I have location=% in the URL.
Then the preferred branch cookie should be ignored, regardless of its value.
And the location popup shouldn’t be shown.
And the filter by location should show the branch from the URL.
And the results should be filtered accordingly.
3.5.14 - Code
The Code paragraph type allows you to embed code snippets, or even embed content from other websites such as YouTube videos. It leverages the Code block type for its functionality.
Fields
Name
Machine name
Required
Description
Code
field_prgf_code_block
Yes
Block reference to a Code block. You can create a new Code block directly from the paragraph edit screen, or select an existing one from the library. The Code block will determine the actual content displayed.
3.5.15 - Featured Blog Posts
The “Featured Blog Posts” paragraph type displays a listing of featured blog posts. It utilizes the openy_prgf_featured_blogs module.
Fields
Name
Machine Name
Required
Description
Headline
field_prgf_headline
No
Headline of the banner. This is a simple text field.
Blog Posts
field_fblog_posts
Yes
Multiple values. A reference field that links to Blog posts. The blog posts are sourced from nodes of the “Blog” content type.
Module Information
Module:openy_prgf_featured_blogs
Description: Provides a dynamic paragraph that renders a featured blog posts listing.
Dependencies:
drupal:field
drupal:node
openy_node_blog:openy_node_blog
openy_prgf:openy_prgf
paragraphs:paragraphs
Templates
The appearance of this paragraph can be customized via Twig templates. The following templates are used by default, and can be overridden in your theme:
The Featured Content paragraph type is used to create dynamic listings of content with various grid layouts. It’s part of the openy_prgf_featured_content module.
Fields
Name
Machine name
Required
Description
Headline
field_prgf_headline
No
Headline of the featured content.
Description
field_prgf_description
No
Text area for the description/body with WYSIWYG, without summary.
Link
field_prgf_link
No
Link field that supports internal and external URLs.
Style
field_prgf_grid_style
Yes
Select list defining the number of items per row: 2: 2 items, 3: 3 items, 4: 4 items.
Column description
field_prgf_fc_clm_description
No
Multiple values. Text area for column descriptions with WYSIWYG, without summary.
3.5.17 - Featured Highlights
The Featured Highlights paragraph type provides a way to display specific content blocks in a grid layout, with options for 2, 3, or 4 blocks per row.
Fields
Name
Machine name
Required
Description
Title
field_prgf_title
No
Optional paragraph title displayed above the grid of blocks.
Style
field_prgf_grid_style
Yes
Determines the number of blocks displayed per row. A select list with the following values: 2: 2 items per row, 3: 3 items per row, 4: 4 items per row.
Featured Highlights block
field_prgf_block_ref_unlim
Yes
References blocks to be displayed in the grid. You can create a new block or select an existing block. Allowed block types: Featured Highlight Block, Basic Block, Simple Block, and Date block. The “Featured Highlight Block” provides a title, link, image, and description for each item.
3.5.18 - Featured News Posts
The Featured News Posts paragraph type displays a set of news articles. It allows content editors to highlight timely and relevant news items on a page. This paragraph leverages the openy_prgf_featured_news module.
Fields
Name
Machine name
Required
Description
Headline
field_prgf_headline
No
Headline for the featured news section. This will appear above the linked news posts.
News Posts
field_fnews_posts
Yes
Multiple values. References existing News posts (nodes of type “News”). The referenced news posts will be displayed in this section.
Usage
When creating or editing a page or content type that supports paragraphs, select the “Featured News Posts” paragraph type.
Enter a “Headline” for the section (optional).
In the “News Posts” field, select one or more existing News posts. Use the autocomplete functionality to search for news posts by title.
Save the paragraph and the parent content.
The selected news posts will now be displayed on the page, under the specified headline. The display of each news post will use the “teaser” view mode.
3.5.19 - Gallery
The Gallery paragraph type is used to display a collection of images, often with accompanying text and links.
Fields
Name
Machine Name
Required
Description
Headline
field_prgf_headline
Yes
Headline of the gallery. Plain text.
Description
field_prgf_description
No
WYSIWYG field without summary. Allows for rich text formatting to describe the gallery.
Link
field_prgf_link
No
Link field for internal and external URLs. Can be used to link to more information.
Images
field_prgf_images
No
Entity reference to media images. Supports multiple images in the gallery.
3.5.20 - Grid columns
This paragraph type is used for the field_grid_columns within the Grid Content paragraph. It defines the structure and fields for individual columns within a grid layout.
Fields
Name
Machine name
Required
Description
Description
field_prgf_grid_clm_description
No
Textarea for the column’s description or body content. Supports WYSIWYG editing, but does not include a summary field.
Headline
field_prgf_clm_headline
No
Headline for the grid content within the column.
Icon
field_prgf_clm_icon
No
Entity reference to a media asset, typically an image. Recommended to allow uploading of SVGs for scalability.
Icon class
field_prgf_clm_class
No
Input field for adding
Font Awesome icon classes (e.g., flag, car, info). Overrides the image specified in the Icon field.
Link
field_prgf_clm_link
No
Link field that supports both internal and external URLs.
3.5.21 - Grid Content
The Grid Content paragraph type is used to create grid layouts within stories.
Fields
Name
Machine name
Required
Description
Style
field_prgf_grid_style
Yes
Select list with the following values: 2: 2 items per row, 3: 3 items per row, 4: 4 items per row. This determines the number of columns in the grid.
Content
field_grid_columns
Paragraph
Grid columns. This field references the Grid columns paragraph type, allowing you to add individual columns to the grid.
Description
field_prgf_grid_clm_description
No
Textarea for the column description/body. Supports WYSIWYG editing, but without a summary option.
Headline
field_prgf_clm_headline
No
Headline for the grid content column.
Icon
field_prgf_clm_icon
No
Entity reference to a media asset, typically an SVG image. Allows uploading of new SVG files.
Icon class
field_prgf_clm_class
No
Input field for adding
Font Awesome icon classes (e.g., flag, car, info). This will override the image Icon.
Link
field_prgf_clm_link
No
Link field that supports both internal and external URLs.
3.5.22 - Group Schedules
This is a dynamic paragraph that renders group schedules from the GroupEx Pro system. It leverages the openy_prgf_group_schedules module. This paragraph type allows content editors to embed schedules directly within content, providing users with up-to-date class and activity information.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block that displays the GroupEx Pro schedule. A default value should be set and is configurable in the form display.
3.5.23 - Latest Blog Posts
This paragraph is a dynamic element that displays the most recent blog posts. It’s designed to showcase content that is promoted to the front page.
Key features:
Sticky at the top: This ensures the most important blog posts remain visible.
Order: Items are ordered by published date, with the newest posts appearing first.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
This field holds a block reference to the view/block that provides the blog post listing. It is intended to have a default value set and is typically hidden from the form display to simplify content creation and prevent accidental modification of the listing source.
3.5.24 - Latest Blog Posts (Branch)
This dynamic paragraph renders the latest blog posts associated with a specific branch. It displays posts in chronological order, with the newest posts at the top, and utilizes the “sticky at the top” option to highlight important content.
Functionality
This paragraph type automatically filters and displays blog posts based on the branch context in which it is placed. For example, if this paragraph is added to a “Downtown YMCA” branch page, it will only display blog posts associated with the “Downtown YMCA” branch. If placed on a non-branch page, only the headline will be visible.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block. This field should have a default value and be hidden in the form display. It determines the view or block used to render the blog posts.
3.5.25 - Latest Blog Posts (Camp)
This paragraph dynamically renders the latest blog posts associated with a specific camp. It displays posts in reverse chronological order (newest first).
Functionality
Filtering: Displays only blog posts associated with the current camp. If placed on a non-camp page, only the title will render.
Ordering: Blog posts are ordered by published date, with the newest posts appearing at the top.
Styling: Blog posts are displayed in a card format.
Usage
This paragraph is typically used in the content area or bottom area of a Camp page to showcase relevant blog content. To use it, select “Latest Blog Posts (Camp)” from the paragraphs dropdown, and enter a header title.
This paragraph type dynamically renders the latest news posts. It is typically used to display news promoted to the front page, ordering them by published date with the newest at the top. The “sticky at the top” option can be used to highlight certain posts.
This paragraph leverages a block reference to display content.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
A block reference to a view or block. A default value should be configured, and the field should be hidden in the form display. This block will contain the actual list of news posts.
3.5.27 - Latest News Posts (Branch)
The “Latest News Posts (Branch)” paragraph type is a dynamic element that displays the most recent news articles associated with a specific branch location. It’s designed to highlight timely and relevant information, ensuring that users are presented with the newest content first.
This paragraph automatically orders news items by their published date, with the most recent articles appearing at the top. Additionally, it utilizes a “sticky at the top” feature, which can be configured in the associated View to keep specific, important news posts prominently displayed.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
This field is a block reference to a View block that lists news posts. The View should have a default value set and is typically hidden in the form display to simplify content editing. The view should filter by branch.
Module Dependencies
This paragraph type is provided by the openy_prgf_news_branch module, which has the following dependencies:
field: Part of Drupal core.
node: Part of Drupal core.
openy_loc_branch: Open Y Branch Location module.
openy_node_news: Open Y News Node module.
openy_prgf: Open Y Paragraphs base module.
paragraphs: Paragraphs module for creating structured content.
plugin: Part of Drupal core.
user: Part of Drupal core.
views: Part of Drupal core.
views_infinite_scroll: Views Infinite Scroll module for paginating results.
3.5.28 - Latest News Posts (Camp)
This paragraph type dynamically renders the latest news posts associated with a specific camp. It displays news articles in reverse chronological order (newest first) and can utilize a “sticky” option to highlight certain posts at the top of the list.
Functionality
This paragraph is designed to be placed on a Camp page. When placed on a Camp page, it will display only news posts associated with that specific camp. If placed on a non-Camp page, it will display only the title (if one is configured).
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block that displays the news posts. A default value should be configured for this field, and it should typically be hidden in the form display to prevent accidental modification.
3.5.29 - Limited Time Offer
This Paragraph type is used to add a limited-time offer section to a page, often the home page, and is based on a Landing Page Content Type.
Fields
Name
Machine name
Required
Description
Subtitle
field_lto_subtitle
No
Enter the subtitle for the limited-time offer.
Link
field_lto_link
No
Add a link for the limited-time offer.
Title
field_lto_title
Yes
Enter the title for the limited-time offer.
3.5.30 - Location finder
This paragraph describes the Location finder paragraph type, which renders a block.
The Location finder block displays locations such as branches, camps, and facilities using a map and associated views. It may also include a filter block. For the Location finder block and Location finder filter block, see the
Open Y Map documentation.
Fields
Name
Machine name
Required
Description
Location finder
field_prgf_location_finder
No
Block reference to the location_finder block. It should have a default value and be hidden in the form display. This block renders the location map.
3.5.31 - Location Finder Filters
This paragraph renders the Location Finder map with pins and filters. It allows users to filter locations displayed on the map based on tags or other criteria.
Fields
Name
Machine name
Required
Description
Location Finder
field_prgf_location_finder
No
Block reference to the location_finder block. This field should have a default value and be hidden in the form display to prevent direct user modification.
Tags Style
field_prgf_lf_tags_style
Yes
Determines the style of tags used for the map tags filter. Options include: - Checkboxes (default) - Multiselect widget with checkboxes.
3.5.32 - Membership Information Paragraph
This document describes the “Membership Information” paragraph type, which is used to display membership details such as location, link, fees, and rates. This paragraph is intended for use in the Membership content type.
Fields
Name
Machine name
Required
Description
Location
field_mbrshp_location
No
Select list with locations (branches). Single value.
Link
field_mbrshp_link
No
Link field to provide the membership redirect URL.
Join Fee
field_mbrshp_join_fee
No
Dollar value representing the one-time fee to join.
Monthly Rate
field_mbrshp_monthly_rate
No
Dollar value representing the recurring monthly membership fee.
3.5.33 - Microsites Menu
This paragraph type provides a microsites menu block.
Fields
Name
Machine name
Required
Description
Menu Block
field_prgf_block_ref
Yes
Block reference to the view/block. Create a new one or select an existing menu block. See the
Blocks documentation for more information.
Hide Main Menu
field_prgf_ms_menu_hide_menu
No
Determines whether to hide the main website menu when this microsites menu is displayed.
3.5.34 - News Posts Listing
This dynamic paragraph renders the latest news posts and utilizes exposed filters, allowing users to refine the displayed content.
The available filters are:
Location
Category
Text
The News Posts Listing also features a “sticky at the top” option, ensuring important news remains visible. Items are ordered by published date, with the newest posts appearing first. This functionality relies on the Views module.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the View block. This should have a default value configured in the Paragraph type and hidden in the form display.
3.5.35 - Program Registration (Daxko)
This paragraph renders the Programs Search Block.
The Programs Search Block provides a form to search programs from Daxko.
Important: The Daxko and Program Registration (Daxko) configurations must be set up before the Program Registration paragraph will work.
Configuration settings are located at /admin/config/development/daxko/programs-search. You must have the administer daxko permission to configure these settings. See the
Daxko settings documentation for more information on configuring the connection to Daxko.
Fields
Name
Machine name
Required
Description
Program registration block
field_prgf_reg_block
No
Block reference to the programs_search_block block. Should have a default value and should be hidden in the form display.
3.5.36 - Promo Card
The Promo Card is a Paragraph type used to create promotional content. It is often used in sidebars or other secondary areas of a page.
Fields
Name
Machine name
Required
Description
Title
field_prgf_title
No
Optional title for the Promo Card. Displayed above the Headline.
Headline
field_prgf_headline
Yes
Headline of the Promo Card. Displayed below the Title.
Description
field_prgf_description
No
A WYSIWYG field for the main content of the Promo Card. Does not support summaries.
Link
field_prgf_link
No
A link field for internal and external links. Supports a call to action.
3.5.37 - Schedule search form
This paragraph renders the session instance filters for the [Schedule search list](Schedule search list.md). It provides a dynamic form allowing users to filter session instances based on various criteria. The form is rendered using the SchedulesSearchFormBlock plugin, which utilizes the SchedulesSearchForm form.
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block. This field stores a reference to a block, typically a view or another block, that provides the search form. It should have a default value and should be hidden in form display. The default value should be the schedules_search_form_block plugin.
Usage
This paragraph is typically used in conjunction with the [Schedule search list](Schedule search list.md) paragraph to provide a filtering mechanism for session instances. It is rendered using the SchedulesSearchFormBlock plugin.
This dynamic paragraph renders the session instances based on URL parameters and/or filters from the [Schedule search form](Schedule search form.md).
Relates to [Branches Popup (All)](Branches Popup (All).md).
Fields
Name
Machine name
Required
Description
Block
field_prgf_block
Yes
Block reference to the view/block. Should have a default value and should be hidden in the form display.
Use Cases
Use Case 1: Schedule search list paragraph on a page WITHOUT a location popup paragraph
1.1 Preferred branch is selected and no location in URL
When I open the Schedule search list page WITHOUT a location popup on the page
And I have a preferred branch
And I don’t have location=% in the URL
Then the filter by location should be predefined based on the cookie
And the results should be filtered
1.2 Preferred branch is empty and no location in URL
When I open the Schedule search list page WITHOUT a location popup on the page
And I don’t have a preferred branch
And I don’t have location=% in the URL
Then the filter by location should show “All”
And the results should be shown for all branches
1.3 Location specified in URL
When I open the Schedule search list page WITHOUT a location popup on the page
And I have location=% in the URL
Then we skip the cookie, whether it is empty or exists
And the filter by location should show the branch from the URL
And the results should be filtered
Use Case 2: Schedule search list paragraph on a page WITH a location popup
2.1 Preferred branch is selected and no location in URL
When I open the Schedule search list page WITH a location popup on the page
And I have a preferred branch
And I don’t have location=% in the URL
Then the location popup shouldn’t be shown
And the filter by location should be predefined based on the cookie
And the results should be filtered
2.2 Preferred branch is empty and no location in URL
When I open the Schedule search list page WITH a location popup on the page
And I don’t have a preferred branch
And I don’t have location=% in the URL
Then the filter by location should show “All”
And the results should be shown for all branches
And the location popup should be shown
2.3 Location specified in URL
When I open the Schedule search list page WITH a location popup on the page
And I have location=% in the URL
Then we skip the cookie, whether it is empty or exists
And the location popup shouldn’t be shown
And the filter by location should show the branch from the URL
And the results should be filtered
3.5.39 - Secondary Description and Sidebar
The Secondary Description and Sidebar paragraph type is designed for content layouts featuring a left column (secondary description) and a right column (sidebar). Both columns utilize blocks for flexible content placement.
Fields
Name
Machine Name
Required
Description
Left Column
field_prgf_left_column_block
No
A block reference field for the left column, often used for a secondary description. You can select from existing blocks or create a new one. Supported block types: Basic Block, Code Block, Date Block, or Simple Block.
Right Column
field_prgf_right_column_block
No
A block reference field for the right column, typically used as a sidebar. You can select from existing blocks or create a new one. Supported block types: Basic Block, Code Block, Date Block, or Simple Block.
Note: Blocks provide a modular way to organize and display content within the columns. Consider using Basic Blocks for standard text and media, Code Blocks for displaying code snippets, Date Blocks for event dates, and Simple Blocks for streamlined content elements. You can create these blocks in the “Blocks” section of the administrative interface. The “Block Content” module allows you to manage block types and content blocks. The block description is an identification name for a block, which is shown in the administrative interface and not displayed on the site. The block title is the heading that is optionally shown to site visitors when the block is placed in a region.
3.5.40 - Session Time
The Session Time paragraph is used within the Session content type to define the schedule for a session. It allows you to specify the date and time range, as well as the days of the week the session repeats.
Fields
Name
Machine name
Required
Description
Date & Time
field_session_time_date
No
This field uses the Datetime Range module to create a date/time field with start and end date/time options. This defines the period when the session is active. For example, January 1, 2024, to January 1, 2025.
Days
field_session_time_days
No
Checkboxes to select the days of the week the session repeats. Available options: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. If a date range and a day are selected, the session will occur on that day of the week within the specified date range.
Session time override
field_session_time_override
No
Use this field to override the session time to text.
3.5.41 - Simple Content
The Simple Content paragraph type is used for adding formatted text to pages. It provides a WYSIWYG editor for rich text input.
Fields
Name
Machine name
Required
Description
Content
field_prgf_description
Yes
WYSIWYG editor for formatted text content.
3.5.42 - Small Banner
The Small Banner paragraph type is used to display banner content in a compact format.
Fields
Name
Machine name
Required
Description
Notes
Color
field_prgf_color
Yes
Reference field for choosing a color from the “Color” vocabulary.
Used for the banner’s background color.
Headline
field_prgf_headline
Yes
Headline of the Small Banner.
Plain text, maximum 255 characters.
Image
field_prgf_image
No
Entity reference to a media image.
Single value. Recommended image dimensions: [TBD].
Description
field_prgf_description
No
WYSIWYG field for the banner’s description, supports rich text formatting.
No summary option. Use sparingly to maintain a clean banner appearance.
3.5.43 - Social Post Listing
This paragraph type renders the latest social posts imported from social networks and displays them in a masonry grid. It leverages a View block to select and format the posts.
Fields
Name
Machine name
Required
Description
Title
field_prgrf_sl_title
No
Title for the social posts block. This is a plain text field.
Description
field_prgrf_sl_description
No
Description for the social posts block. This field supports longer text and can be used for introductory content.
Social List
field_prgrf_sl_block
No
Reference to a View block. This block is configured to select social posts and display them.
Details about the Social List (field_prgrf_sl_block) View Block:
View:social_posts_view
Block Display:social_posts_block
This view selects nodes of the social_post content type.
The view provides an administrative interface at admin/social-posts to manage social posts.
The view displays the platform, ID, post content, and posted date for each social post.
3.5.44 - Social Share Icons
This paragraph type was used to add social media share icons, leveraging the AddThis service.
Important: The AddThis service has been deprecated as of May 31, 2023. This paragraph type no longer functions. See
Using AddToAny for its replacement.
You can add text here if your block needs a title.
Description
field_prgrf_sl_description
No
Block Description.
You can add text here if your block needs a description.
Block
field_prgrf_sl_block
Yes
Select a social sharing plugin.
3.5.45 - Story Card
The Story Card is a Paragraph type designed for use in sidebars, featuring a title, headline, and a link that turns the entire card into a call to action. This paragraph type is commonly used to highlight specific information or direct users to related content.
Fields
Name
Machine name
Required
Description
Title
field_prgf_title
No
Title of the Story Card.
Headline
field_prgf_headline
Yes
Headline of the Story Card. A quotation mark will be displayed to the left of your headline in the Lily and Rose themes.
Link
field_prgf_link
No
Link field that stores an internal or external URL. The entire card becomes the link, so use link text that encourages users to click.
Usage Notes
Themes: The Story Card Paragraph renders with specific styling in the Lily and Rose themes, including a border. It may not have the same visual emphasis in other themes like Carnation.
Best Practices: To enhance usability, consider adding a > or other special character to the link text to visually indicate it’s a clickable link.
Content Types: Story Cards are primarily designed for use in the sidebar region of content types, including:
Landing Page
News Post
Blog Post
Facility
Program
Program Subcategory
Advanced
Custom CSS: To disable the quotation mark in the headline area (Lily and Rose), use the following CSS:
.story-card.quotesvg{display:none;}
3.5.46 - Teaser
The Teaser paragraph type is used to create visually engaging previews of content, often linking to more detailed information. It typically includes a title, image, short description, and a link.
Fields
Name
Machine name
Required
Description
Title
field_prgf_title
No
The title of the teaser. This is often displayed prominently.
Image
field_prgf_image
No
A reference to a media image. This field accepts a single image to visually represent the teaser content.
Description
field_prgf_description
No
A WYSIWYG field (What You See Is What You Get) allowing formatted text input for a brief description of the teaser content. A summary is not supported for this field.
Link
field_prgf_link
No
A link field that stores internal and external URLs. This allows the teaser to link to other content within the site or external resources.
Usage
Teaser paragraphs are commonly used on landing pages, content hubs, and in listing pages to promote specific articles, products, or sections of a website. They provide a concise overview and encourage users to explore further. The field_prgf_link will take the user to the page that the Teaser is promoting.
Best Practices
Image Dimensions: Use appropriately sized images to ensure optimal display and page load times.
Concise Descriptions: Keep descriptions brief and focused on highlighting the key benefits or features of the linked content.
Clear Call to Action: The link text should clearly indicate the destination and encourage user interaction (e.g., “Read More,” “Learn More,” “View Details”).
3.5.47 - Webform
This is a paragraph type used for embedding webforms within content. It allows you to add existing webforms to a page.
Prerequisites
You must have already created your webform using the Webform module before embedding it. This paragraph type does not create a new webform.
Add the Webform Paragraph: Select “Webform” from the available paragraph types when editing a content item.
Select the Webform: Choose the desired webform from the “Embedded Webform” field. This field displays a list of available webforms created using the Webform module.
Configure Webform Status: Use the “Webform status” field to control the webform’s availability:
Open: Allows users to submit the webform.
Closed: Prevents new submissions. Existing submissions remain accessible.
Scheduled: Set open and close dates for the webform.
Default Webform Submission Data (Optional): The “Default webform submission data (YAML)” field allows you to pre-populate webform fields with default values.
Enter YAML code to define the default values.
This is useful for providing guidance or setting common values for users.
The Area vocabulary is used to categorize location areas on the site. This vocabulary is used by the Location Branch and Facility content types to classify the areas they serve. Areas can represent neighborhoods, regions, or any other relevant geographical or logical division.
Machine name: area
Details:
This vocabulary is implemented as a taxonomy.
Terms within this vocabulary are referenced by the field_location_area field on the Location Branch and Facility content types.
Consider using a hierarchical structure for your Area taxonomy to allow for more granular categorization (e.g., Continent > Country > Region > City > Neighborhood).
When creating terms, ensure that the names are clear, concise, and representative of the area they describe. Use title case for term names (e.g., “Downtown”).
This is a vocabulary that will be used for adding blog categories on the site. A vocabulary is a set of taxonomy terms. Taxonomy terms are used to classify website content.
Machine name: blog_category
Definition: A vocabulary for categorizing blog posts. Individual categories are known as terms.
This is a vocabulary used for adding colors. It is typically used as a reference field in other content types, such as Paragraphs.
Machine name: color
Fields
Name
Machine name
Required
Description
Name
drupal's default
Yes
Color name.
Color
field_color
Yes
Color selector. This usually provides a color picker interface.
3.6.5 - Facility Type
This is a vocabulary used for categorizing facilities on the site, specifically for the Facility content type.
Machine name: facility_type
3.6.6 - Media Tags
This vocabulary is used for adding media tags, which allow you to structure your media assets library. These tags are crucial for organizing, searching, and managing your media files effectively within the system.
Machine name: media_tags
Media tags, when applied correctly, enhance the discoverability and reusability of your media assets. They provide a controlled vocabulary for categorizing different types of media, such as images, videos, audio files, and documents. This categorization enables efficient filtering and sorting within the media library.
Consider the following benefits of using media tags:
Improved Search: Users can quickly locate specific media assets by searching for relevant tags.
Enhanced Organization: Media assets are neatly categorized, making it easier to browse and manage the library.
Content Relationships: Tags can define relationships between different media items, showcasing related content.
Workflow Automation: Automate media processing tasks based on assigned tags.
Best Practices
Consistency: Use consistent tagging practices across all media assets.
Specificity: Choose the most specific tags that accurately describe the media.
Relevance: Ensure that tags are relevant to the content of the media asset.
Hierarchy: When creating tags, it’s important to have a hierarchy so that filtering and searching can find all of the related tags.
By implementing a well-defined media tagging strategy, you can significantly improve the usability and effectiveness of your media asset library.
3.6.7 - News Category
This vocabulary is used for categorizing news articles on the site. Taxonomy terms are grouped into vocabularies. This vocabulary provides a predefined set of categories for news content, ensuring consistency and facilitating content organization and filtering.
Machine Name:news_category
Description:
Used to classify news content.
Terms within this vocabulary can be used to create lists of related articles, filter news feeds, and improve site navigation.
Allows content editors to assign one or more categories to each news item.
Usage:
The news_category vocabulary is used with a “Taxonomy term” reference field attached to the “News” content type.
When creating or editing a news article, users can select relevant categories from the available terms in this vocabulary.
Welcome to the development corner of the YMCA Website Services distribution. This section contains resources and guidelines for developers, QA engineers, and YMCA associations involved in the development and maintenance of YMCA Website Services.
Getting Started with YMCA Website Services Development
Whether you are just getting started with YMCA Website Services or need to test a feature in a stable environment, the YMCA Website Services Core Team maintains a number of
Sandboxes that you can use.
To get a copy of the latest development version of the distribution, follow the steps in the
YUSA OpenY README.
YMCA Website Services has a modular structure. If you plan changes to a specific component, create a Pull Request/Merge Request in the respective project or repository, based on the component’s composer.json data.
To test a specific component, create a PR to
yusaopeny and add a reference in composer.json of YMCA Website Services so the build system starts using the updated component.
QA sandboxes for YMCA Website Services
The YMCA Website Services core team manages
sandboxes for various configurations of the distribution. These sandboxes facilitate evaluation, QA, and issue investigation.
YMCA Website Services’s system requirements generally track
those of Drupal with some occasional more opinionated recommendations. YMCA Website Services leverages many other open source frameworks including, but not limited to, the ones listed below. These dependencies are reviewed periodically for new features and deprecations.
General Requirements
Supported versions may differ based on your Drupal version. Refer to Drupal’s documentation for specific version compatibility.
YMCA Website Services is a large distribution with a significant number of modules, components, subsystems, and business processes. Therefore, we must take appropriate steps to ensure the stability of major functionality during development.
For automated tests, we have created a
General Checks template on GitHub. Every developer should follow this template to get review approval from the YMCA Website Services core team. However, General Checks are for testing functionality related to the current proposed change only and are not intended for Regression Testing.
For regression testing,
Behat tests are provided automatically on each build by the YMCA Website Services community.
Every pull request should include a testing plan before being released into YMCA Website Services. This plan should cover the testing of all workflows and functionality to ensure they continue to work with any new code or changes implemented. Conflicts can occur between elements of YMCA Website Services, Drupal modules, and Drupal core. Pull request testing plans increase productivity and decrease the effort required for manual Acceptance Testing of upcoming releases. The testing plan should cover specific features and functionality that are likely to cause regression issues post-release or post-upgrade to the latest version of YMCA Website Services after the new code is implemented.
Example of a testing plan: If the Drupal core is updated, gather all Drupal core Release Notes since the last core upgrade for YMCA Website Services and analyze the important issues fixed.
For example, if you are upgrading from version 8.4.0 to 8.4.4:
This means that the following systems should be tested:
Multilingual
PostgreSQL support
Migration
Taxonomy
CKEditor
Composer
This list can be extended by analyzing the YMCA Website Services distributions’ important parts that depend on the subsystems listed above. Spending time on every module with a taxonomy dependency is not required, but testing at least one impacted module to ensure it is still working post-implementation is essential. If a Behat test is already created for the subsystem in a list, a manual test can be skipped if the build is not failing due to the module or element covered in the associated Behat test.
How to choose which modules to test: Modules can be randomly selected from the list of impacted systems, or one of the oldest modules in an impacted system. Older modules that have not received recent or regular updates are more likely to have regression issues caused by a minor change.
The oldest modules (contrib modules) with dependencies from the above list should also be updated. However, to improve productivity, initiate these updates only if there is a security issue or a module has stopped working because the subsystems are being updated within an upcoming release. If a module update creates more issues than the older version of said module, it is better to keep the old module and fix the associated regression bug.
Tip: A new module version usually contains a bug fix, so adding a patch from Drupal.org to the YMCA Website Services distribution’s composer.json is preferred to releasing the distribution. Remember to create a follow-up task for updating the module after the release.
After creating a list of modules that could introduce regression issues, following the Quick-start section of the modules’ README files (usually shipped with modules) is highly recommended.
If a module has no Quick-start or Acceptance testing section in its README, testing at least one place where the module’s functionality should be working is essential. Adding these manual test steps as a follow-up task (
new issue) or creating a Pull Request with changes to the README in the YMCA Website Services repository is highly recommended. For performance, adding step-by-step how-to instructions to the respective modules’ README.md file is highly recommended. Writing a couple of lines of documentation takes only a few minutes and will greatly help others with future contributions and changes.
Optionally, adding a Drupal tour for the how-to instructions created in the README will benefit future YMCA Website Services users and developers. Having a tour for the business functionality is highly recommended to ship with the component, creating in-site visual guided documentation and helping to decrease the time for Acceptance testing.
Lastly, adding Behat tests to the system will ensure functionality is tested on every pull request and every CI build in the future.
Rule
Every release of YMCA Website Services since 8.1.9 should include a list of subsystems changed in the release for the community to be aware of possible regressions on their end.
4.4 - Anti-spam Protection
To protect YMCA Website Services customers, anti-spam protection based on CAPTCHA and Google reCAPTCHA is included in the YMCA Website Services core. This solution leverages the
CAPTCHA and
reCAPTCHA Drupal modules.
Understanding CAPTCHA and reCAPTCHA
CAPTCHA: A challenge-response test used to determine whether the user is human. It blocks form submissions by spambots, which are automated scripts that post spam content. The CAPTCHA module provides this feature to virtually any user-facing web form.
reCAPTCHA: A free service from Google that protects your website from spam and abuse while letting real people pass through with ease. It uses an advanced risk analysis engine and adaptive CAPTCHAs to keep automated software from engaging in abusive activities on your site.
Configuration
Install and Enable Modules: Install both the
CAPTCHA module and the
reCAPTCHA module. Enable them in the Extend administration page (/admin/modules).
reCAPTCHA Settings: Configure reCAPTCHA settings at /admin/config/people/captcha/recaptcha. You’ll need a Site key and a Secret key.
Get API Keys: Register your website at the
reCAPTCHA Admin console to obtain your Site key and Secret key.
Enter API Keys: Input the Site key and Secret key into the reCAPTCHA settings form.
CAPTCHA Settings: Configure where you want the CAPTCHA/reCAPTCHA to appear on your site at /admin/config/people/captcha.
Additional Spam Protection
In most cases, the above configuration protects you from most spam. However, human-entered spam may require additional protection.
Blacklist Logic: Implement blacklist logic to block email domains frequently used in spam messages.
Protected Submissions Module: Consider using the
Protected Submissions module to harden all submissions on a site with a list of stop words and per-language settings.
Virtual Y Use Case
For Virtual Y, the
simple_recaptcha module is used to address caching issues and may be suitable in similar cases. The standard CAPTCHA + reCAPTCHA module combination has sometimes presented reliability issues. Replacing those modules with “Simple reCAPTCHA” may resolve those issues.
4.5 - Code of Conduct and Best Practices
The YMCA Website Services community aims to build from the methods and best practices of other open-source projects, such as the
Drupal community and the
Drupal Ukrainian community.
This document supplements our
Code of Conduct and Best Practices. It provides technical and in-depth guidelines for specific cases discussed during code quality reviews by the YMCA Website Services team. All code should be reviewed by 1-2 developers before being merged into the YMCA Website Services codebase.
General Rules
Components in YMCA Website Services (modules, themes, or other code structures) should be reusable and atomic whenever possible. Bundle all features, content types, settings, and styles to create cohesive components.
Module naming conventions - Choose the name from this list, depending on the context:
${project_name|abbr}_${business_name|abbr} - when the code looks like legacy and has specifics that are not ready to be open-sourced.
openy_${business_name|abbr} - when the code is ready to be extracted to an OpenY package.
${business_name} - when the code is so abstract that it has no connection to OpenY and is ready to be hosted on Drupal.org as an independent project.
Code Sharing
To support community reuse, the MODULE-NAME should relate to the module’s business logic. Avoid creating modules by abstracting them out of the business context. Modules shared to Drupal.org from past projects were shareable because they represented a feature tied to a business need. For example:
personify - module for SOAP related methods for working with Personify API
acrypt - Asymmetric crypt algorithm
and so on.
PHP
Return Early Pattern
To improve readability in functions and methods, return early if simple conditions can be checked at the beginning of a method:
<?phpfunctionfoo($bar,$baz){if($foo){// logic goes here
return$calculated_value;}else{returnnull;}}?>
Returning early reduces indentation and cognitive load.
<?phpfunctionfoo($bar,$baz){if(!$foo){returnnull;}// logic goes here
return$calculated_value;}?>
Define Early Pattern
When a condition aims to change a variable’s value without additional logic, define the variable early and change it based on conditions, avoiding if else elseif structures.
Before:
<?phpif($a=='hello'){$text='Welcome to site';}else{$text='Register please';}?>
After:
<?php$text='Register please';if($a=='hello'){$text='Welcome to site';}?>
Null Checks with isset()
isset() verifies if a variable is set and not null. Additional verification against NULL is unnecessary.
<?php...if($type=='program'){if($feed['profile_media_videos']!=NULL||$feed['profile_media_images']!=NULL){\Drupal::logger('form_import')->notice("FORM IMPORT: type is $type");...?>
Maintaining an Upgrade Path
Add all configuration changes to appropriate hook_update_N functions to update existing environments. We suggest using the
Config Importer and Tools package for working with hook_update_N.
Install Files
openy.install in Profile
Place updates related to the distribution in general and not specific to any feature in this file.
Enable/Disable module
General configs
openy_*.install in Modules
If you update a configuration for a specific feature, put the updates in the appropriate module’s install file.
Config Management
Revert Only Specific Property from Config
This is the preferred method for updating configurations, resulting in fewer conflicts when upgrading customized YMCA Website Services instances.
What goes into making the selectable colorways in Layout Builder.
CSS Variables
Base Variables
We start by defining a base set of colors based on the “Y Color Wheel and Neighbored Color Zones” from the “Websites & Platforms Style Guide”, available in the
YMCA Brand Resource Center. These colors are used to create the color palettes available in the Layout Builder.
Note: RGB variable values are not complete color definitions and must be wrapped in rgb{a}(), like background-color: rgb(var(--ylb-color-rgb-red-dark), 0.5);. This allows you to control the opacity of the color.
Each colorway is built upon four core colors derived from the base color palette:
PrimaryColor: The main color for the colorway.
SecondaryColor: A complementary color to the primary.
TertiaryColor: Another complementary color, providing additional visual interest.
PartnerColor: A contrasting color, often used for buttons and calls to action.
These four colors are used to style the majority of page elements. Each variable is prefixed with ws to denote “Website Services”. RGB versions of these colors are also provided for use with rgba() styles.
In addition to the main colors, five more variables are used to define the YMCA logo gradients:
LogoChevronDark
LogoChevronMid
LogoChevronLight
LogoTriangleDark
LogoTriangleLight
Important: These Logo variables should only be used for styling the YMCA logo. They are not intended for use in other page components. The Canadian Y logo does not change colors, and therefore these extra colors are not needed for Canadian colorways.
To ensure consistency and minimize code duplication, the YMCA logo is divided into six distinct sections, each styled individually:
the
chevron
ymca
triangle
registeredtm
areas-of-impact
The chevron and triangle sections use radialGradient elements, taking advantage of the wsLogo variables mentioned above. The other sections are styled using the standard colorway variables. Each section is a path element with a unique id and a color defined using the fill property.
#logo-the uses --wsSecondaryColor
#logo-chevron uses a gradient composed of (from top to bottom) --wsLogoChevronLight, --wsLogoChevronMid, and --wsLogoChevronDark
#logo-ymca uses --wsPartnerColor
#logo-triangle uses a gradient composed of (from left to right) --wsLogoTriangleLight and --wsLogoTriangleDark
It’s crucial to keep your composer.lock file synchronized with your composer.json file. Here’s how:
After any changes to composer.json: Ensure you update the composer.lock file.
Update a specific package: Use the composer update command, which automatically updates the composer.lock file.
composer update drupal/metatag
Force update the composer.lock file: Use composer update --lock to regenerate the composer.lock file based on the dependencies defined in composer.json. This is useful if you suspect the lock file is out of sync.
composer update --lock
For comprehensive information, refer to the official Composer documentation:
4.9 - Composer Version Constraints for YMCA Website Services
In 2020, due to changes in Drupal core release management and demand from YMCA Website Services customers to improve upgrade path flexibility and stability, the YMCA Website Services team added extended composer version constraints to our composer.json. This allows for greater flexibility and stability when upgrading the YMCA Website Services platform.
"drupal/ckeditor_bootstrap_buttons": "^1.2 || ^2.0.0", - This line means the project is compatible with version 1.2 and any subsequent 1.x versions starting from 1.2. It also indicates that version 2.0.0 has been tested and that any stable 2.x versions starting from 2.0.0 are allowed.
"drupal/custom_formatters": "^3.0 || ^3.0@beta", - This indicates testing with the 3.0 beta of custom_formatters and allows any 3.x version starting from 3.0 once it is released as stable.
By having multiple OR (||) conditions, we provide developers with information on which versions can be used for upgrades. In some cases, the latest stable version of a dependency might be incompatible with other functionalities. Using older versions is a valid strategy while other functionalities are being upgraded to be compatible.
For example, if custom_formatters version 3.0 is incompatible with any YMCA Website Services dependencies at the time of its release, a developer can select an older beta version to proceed with the upgrade.
To select a specific version of a dependency during an upgrade of YMCA Website Services, add the dependency and its version alongside YMCA Website Services in the composer require step.
You can change any dependency version without upgrading YMCA Website Services by running the composer require command for specific dependencies and then running the Drupal Update DB routines.
It’s important to note that many YMCA Website Services modules and themes specify core version requirements in their .info.yml files. These constraints define the compatible Drupal core versions for each component.
For Example:
core_version_requirement:^10 || ^11
This example indicates that the module is compatible with Drupal 10 and 11. When managing dependencies with composer, you must ensure that the version constraints defined in the .info.yml files are respected.
4.10 - Contributing
The YMCA Website Services distribution is open source, and we welcome contributions from the YMCA Movement, the Drupal community, and beyond. Be sure to check our
Community Resources for how to get in touch and our
Roadmap to see if your request is already in progress.
Issues
If you have a support request, you’ve found a bug, or you have a feature request, you can start in our primary repository,
YCloudYUSA/yusaopeny:
If you are able to pinpoint the issue to a specific piece of functionality, you can open an issue on
the appropriate module.
When submitting issues, please refer to the
CONTRIBUTION.md file in the Blazy module for guidelines on submitting issues and bug reports.
Pull Requests
We use the GitHub
“Fork and pull model” for community contributions. If you have some time to make a contribution to the project, here are the steps that will help you:
Write steps for review. In this way maintainers can go through steps on build to verify your fix/feature.
Ensure steps for review added to README.md file in a module’s/project’s directory if it makes sense to check them on regular basis. Often this is needed for crucial parts of the system which is main business functionality of the component. Example of super simple steps for review
see in Quickstart section of location_finder module, please.
Wait for a CI build and ask maintainers for review.
Important: make sure your git email is associated with account on drupal.org, otherwise you won’t get commits there.
When submitting patches, please refer to the
CONTRIBUTION.md file in the Blazy module for guidelines on submitting patches.
Merge Requests
Modules on Drupal.org follow their Merge Request process. The Drupal Wiki has in-depth documentation on these processes:
Configuration setting at /admin/config/development/daxko
Account configuration must be set up before the Program Registration paragraph will work.
GroupEx Pro
There are three methods of integrating GroupEx Pro with your YMCA Website Services site, ordered from most to least complex/customizable:
API integration
Embedded schedules
Responsive schedule link
GroupEx PRO APIs
Deprecation Notice
On February 28, 2023, Daxko planned to sunset the GroupEx PRO Public API in favor of their Daxko Group API v1.
YMCA Digital Services, with the help of YMCA of the North, has developed and adopted a Syncer for Repeat Application, which helps migrate from the GroupEx PRO Public API to the Daxko Group API v1 and pulls data from GroupEx PRO to the Program Event Framework.
Embed code for GroupEx Pro schedules can be found in your GroupEx Pro admin interface.
Look for the “New embed” toggle.
Expand the options and choose any filters or colors that you prefer.
Disable the “Fixed Header” option.
Copy the resulting code. It will look similar to the following, substituting 000 for your own account number and adding any location or category filters as needed:
If the pasted code does not appear on the page, ensure your site is updated with
this change to enable direct copy/pasting of embed codes.
While the incoming code is controlled by Daxko/GroupEx Pro, many changes can be made with CSS. Try the
CSS Editor module (≥2.0.1), which is bundled with the distribution, or work with your development partner to make customizations.
Responsive schedule link
GroupEx Pro also provides direct links to the schedule page. These can be found in the “New Embed” section. Simply copy the link and add it to any link field or button on your site.
4.13 - Decoupled (external) projects
Inventory of external modules available via Composer
Check all GitHub for the tag
openy-decoupled to discover more decoupled projects.
YCloudYUSA/yusaopeny_loc_finder - Extended Location Finder. Note: The repository name (yusaopeny_loc_filter) does not match the link text (yusaopeny_loc_finder). Please verify that this is the correct repository.
ynorth-projects/openy_prgf_session_table - if you need to present couple of Sessions in a table view without using any complex app like Schedules or Activity Finder
drupal/openy_autocomplete_path - YMCA Website Services Autocomplete Path. Works in Drupal 8 only. Removed from 9.* YMCA Website Services releases.
Decoupling Mind-Map
4.14 - Decoupling components as independent modules
History
In 2019, the YMCA Website Services team started decoupling major components to streamline distribution and simplify support. This involved separating components into independent modules, making them easier to manage and update.
Communication started in the Community Board - Ejecting modules from OpenY distro as independent projects.
GitHub should be used when there is no strategy to make a component or project available for the wider Drupal community; that is, when it is tied to YMCA business and unlikely to be leveraged by somebody else.
Drupal.org should be used when the component could be useful to projects outside of YMCA Website Services. This allows for broader community contribution and usage.
Process
Creating a new decoupled component
Create a new GitHub/Drupal.org repository.
Work on getting an initial release with at least beta version stability. This ensures the component is reasonably tested and ready for use.
Create a composer.json file for the component to be able to start using it via composer. See
Virtual Y for an example. The composer.json file defines the dependencies and other metadata for the component.
Make it available for the public via
packagist.org or Drupal.org as a release. Ensure podarok is added as a co-maintainer to the respective system. This allows others to easily find and use the component.
Suggest adding to YMCA Website Services by
opening an issue. This initiates the process of including the component in the main distribution.
If approved, create a Pull Request adding it as a dependency in
composer.json.
Ensure this component is enabled in any of the packages maintained in the
YMCA Website Services profile installation. This makes the component active by default in new installations.
Ask for review and release, according to the
release plan. This ensures the component is properly integrated and released to the community.
Decoupling an existing component of YMCA Website Services
Follow the steps above, but with these additional considerations:
After creating the repo, filter the selected component by running git filter-branch --subdirectory-filter ... from the latest development branch of the YMCA Website Services profile. This keeps credits of work done for this component as a part of the
Code of Conduct.
After separating the code, ensure the ejected code is not duplicated in the YMCA Website Services profile. Remove duplicated code in the same Pull Request in which you add the new dependency. This avoids redundancy and potential conflicts.
Examples
Updating a module on Drupal.org
Use git filter-branch to get a history of changes.
Change the git origin to the Drupal.org project.
Create a new branch and push the code to Drupal.org.
Create and push a tag to Drupal.org. Create a release on Drupal.org.
Update composer.json in this distribution with a new tag.
In order to generate composer.json files for Drupal projects, Drupal.org uses specific rules defined in a module’s info.yml file. These dependencies are used to manage the module’s external libraries and Drupal core module requirements.
Declaring Dependencies
If your module depends on another Drupal module, you should declare it in your module’s info.yml file using the following format:
dependencies:- drupal:webform
This tells the packager to include drupal/webform as a Composer dependency for your module. The Drupal.org packaging system resolves drupal:webform to the correct package name and version.
You can find the correct Drupal.org project shortname to use for dependency declarations on the project page near the bottom. For example, the
Webform project is webform. The corresponding composer package name is drupal/webform.
Incorrect Dependency Declaration
If you were to specify a dependency like this:
dependencies:- whatevernameyouwish:webform
The Drupal.org packaging routine will automatically correct it to drupal:webform during the packaging process.
Soft Dependencies (Drupal Core Only)
There may be situations where you want to express a dependency for Drupal core to manage during module installation and enabling, but not require Composer to manage it. This is sometimes referred to as a “soft dependency”. In such cases, you can use the simplified format:
dependencies:- webform
In this scenario:
Composer will not include any dependency.
Drupal core will require that the webform module be present in the codebase before your module can be enabled. Drupal will check for the existence of the module when resolving dependencies during module installation.
This approach is useful when a module’s functionality degrades gracefully if another module is not present, but is enhanced if it is.
4.16 - Deprecating and removing components
Occasionally, old code is deprecated from the YMCA Website Services codebase. To minimize disruption to existing sites, we use the following process:
Decide: Before removing components from the distribution, we gather feedback from the community to protect active projects from having components accidentally removed. We accomplish this via messaging in the YMCA Website Services Slack channel and discussion on monthly calls.
Deprecate: Once a decision is made, we notify users that the feature will be removed soon. The deprecated component is moved from the YMCA Website Services package group to the YMCA Website Services (Deprecated) package group. For example, see
Deprecate Daxko Program Registration Paragraph. Deprecation notices are posted in point and quarterly releases of YMCA Website Services.
Uninstall: Before removing code, components should be uninstalled via an update hook in the distribution, and any hard dependencies should be removed. Uninstalls must occur at least one point (fix) release after the deprecation notice.
Remove: Complete removal of the component from the codebase or composer.json should happen at least one quarterly (feature) release after the deprecation notice.
Additionally, the following housekeeping steps should be taken when deprecating a component:
Add the release where the deprecated component has been uninstalled to the
important versions document in the Wiki.
Decouple the code to external GitHub repositories with all history of commits, marked as openy-decoupled, and archive the repository.
UX/CX for deprecated components
To deliver a high-quality upgrade path and keep the distribution on the leading edge of technologies, we occasionally replace old and aged components with new ones for a better User Experience (UX) and Content Experience (CX).
To achieve deprecations, we have a policy that aims to provide a comfortable migration path for all components of the distribution.
When we create a component that will replace an old one, we must introduce a period of overlap when both components are available in the system for some time (typically 6-18 months). This allows users time and resources to migrate from the old component to the new one before it is removed from the distribution. See the
Activity Finder v3 to v4 migration.
Deprecated components are moved to the deprecated modules group in the list of modules at Admin > Extend. Also, we add
lifecycle and lifecycle_link to the documentation in every deprecated module to provide enough information for the community. See
Deprecate openy_gxp.info.yml.
All titles of deprecated components in the Content Editing interface should be renamed to add the suffix (deprecated) to help Content Managers daily avoid choosing an old component and using a new one.
For most content components, an automated migration path is expensive and sometimes impossible. Therefore, we have a “lazy migration” practice in our community, which puts the responsibility of migration on Content Managers and Strategists. Once new components are available in the distribution, all editors should start using them and rebuild old pages by replacing old components with new ones. After the communicated timeframe (6-18 months), old components are removed from the distribution. However, if an association needs it, the component will be available as an independent—but unsupported—project. A 3rd-party agency or developer can support it as long as needed.
After the communicated timeframe (6-18 months), the Core team will remove the component from the distribution and keep it in an independent project for archival reasons. Usually, the project is marked as archived/obsolete to clarify that it is not supported and is possibly insecure.
If the normal timeframe (6-18 months) is not achievable due to unforeseeable circumstances, the Core team will add proper notifications and tutorials for the community to help migrate comfortably in a shorter time. See the
GroupEx Pro API deprecation notice.
4.17 - Development FAQ
YMCA Website Services Developer FAQ
Local Development
Getting started with a local environment
To start developing, you need to obtain the latest YMCA Website Services codebase. See the
openy-project repository for the full process. This includes instructions for setting up your local environment and configuring your development tools.
This video tutorial will walk you through how to initiate a local development environment.
The YMCA Website Services team has pre-built environments and walkthroughs using either
Vagrant and VirtualBox or
Docker and Docksal. Choose the method that you’re most comfortable with and get started!
Gathering information about your local environment
To best troubleshoot issues, it’s helpful for the YMCA Website Services team to have as much information about your environment as possible. Before you ask for help, watch this tutorial on
how to gather that information. This video explains how to collect relevant details about your setup, such as operating system, software versions, and configuration settings.
Debugging with Xdebug in your local
The Docksal project maintains detailed information for
using Xdebug with VSCode, PHPStorm, and more. This documentation covers installation, configuration, and usage of Xdebug with popular IDEs for efficient debugging of your code.
Contributing
Who should I specify for review?
We have a best practice to get at least 2 independent reviews before merging code. Please request a review from the YMCA Website Services Lead Technical Architect (Andrii Podanenko, @podarok) and somebody else (from your team or another YMCA Website Services partner).
Who is responsible for merging?
The YMCA Website Services Lead Technical Architect (Andrii Podanenko, @podarok) is responsible for final approval, merging, and release management on the YMCA Website Services project.
What labels in PRs should I use?
[Link to Labels documentation]
What milestone should I specify?
[Link to Milestones documentation]
Why I can’t add labels or specify milestones?
All of these require you to be granted Contributor access to the YMCA Website Services GitHub repository. Contact the YMCA Website Services Lead Technical Architect (Andrii Podanenko, @podarok) to get access. Labels are usually set by the YMCA Website Services Core Team.
Why are the steps for review in Pull Requests so important?
When you send your code for review our team must know both how to review the code and what to test to verify the functionality. You are the only source of truth for how to check functionality. Adding steps for review will help the reviewer and QA team to verify that the issue is resolved.
Why should I add a reference to the GitHub issue in my PR description?
As we are a community-led project, there may be a long time between creating an issue and resolving it in a Pull Request. The reviewer should be able to understand the context and possible discussion around the issue to be resolved with your PR. The more context we have, the better and faster we can review the request.
In what format should I add commits, should I add internal Jira task ID or GitHub issue?
It is important to make commit messages with some sort of sense for the human to read them when digging back in history. Adding any task identifications from the project management system is allowed.
What is the “DeepCode” bot?
The DeepCode bot is an automated, machine learning code review system that analyzes a large number of GitHub repositories. It can be useful for finding common issues before human reviews. It is helpful, but not always necessary to fix issues found by the DeepCode bot because sometimes it flags false positives. If you see a comment, be sure to read the report. If the report makes sense, then fix the issue suggested by the bot.
Build Automation & CI
What CI processes does YMCA Website Services have in place?
To get a fully working YMCA Website Services site for the code change you are about to push for review there is a build generating system installed for the YMCA Website Services GitHub repository that automatically generates a dedicated temporary website with your changes applied.
Why are some builds created automatically and some not?
By default, builds are configured for trusted users, so if you are getting a message from the bot like
“Can one of the admins verify this patch? Use “o+k to test” or ‘’t+est this please” for manual build execution."
then your username is not in the allowlist and somebody from the YMCA Website Services Core Team can comment to initiate a build for you. Contact @podarok to get your build generated or your name added to the allowlist.
How do I create a build for my PR?
If you are on the allowlist then simply create a Pull Request from your fork to the YMCA Website Services repository. After up to 30 minutes you’ll receive comments with links to the generated site builds.
When are builds deleted from the server?
Usually, you have a day for the build to be wiped out from the server. If there is an upcoming deadline and many PRs are coming in, the lifetime could be significantly shorter, down to a couple of hours.
Who should I contact to get logs from the build server?
Andrii Podanenko @podarok or Dima Danylevskyi @danylevskyi
What should I do if tests fail?
If you have any concerns with reports generated by the code checkers that are used in YMCA Website Services ask YMCA Website Services Lead Technical Architect Andrii Podanenko to get them resolved. The majority of these systems are works-in-progress and it is helpful to have feedback on them.
How do I install YMCA Website Services on Pantheon hosting
Occasionally, configuration will get removed or otherwise go missing in the upgrade process. For instance, the list of colors could go missing in the Layout Builder styles pane.
Usually, these changes are resolved by update hooks that import new config, but on occasion, these too can fail or break. In that case, we have a few options for resolving the issue:
Re-run the most recent related update hook.
Import the config with drush.
Import the config with the Drupal UI.
The first step in any of this troubleshooting is to try to find the offending config. In this case, searching your codebase for “text-color” might lead you to
this config file in y_lb. Now, we can try a few things…
NOTE: These methods could damage your site if not tested. Please take a backup before proceeding.
Re-run an update hook
Often, searching an adjacent .install file can get you an existing
update hook to import the missing configuration. In our example case,
y_lb_update_9001 imports the one settings file that we’re looking for. It doesn’t matter that the hook is old, if we re-run it, it will import the file in its current state in our file system.
y_lb_update_9001(); runs the individual function from the file.
Import config with drush
Suppose the target config exists mostly on its own, or you wish to import the entire config of a module (due to a failed install, for instance). In that case, you can use
drush config:import with --partial and --source pointing to a module directory, relative to the Drupal root. In this case:
Be aware that all configs in that directory will be imported. Targeting a single config file with drush is impossible, although you could also temporarily move the config to its own directory.
Import config with the UI
Another way to import a single configuration file is with the Drupal “Config Synchronization” admin pages. To import a single item:
Go to Admin > Configuration > Development > Config Synchronization > Import > Single item (admin/config/development/configuration/single/import).
Choose the Configuration type (if you are unsure, choose “Simple Configuration”)
Paste in the configuration from the file and click Import.
4.18 - Drupal 10 update
The update from Drupal 9 to 10 is easier than some, but still comes with some challenges.
The distribution core team has gone through these steps to ensure as smooth of a transition as possible. If your site is up-to-date and using no additional dependencies you may be able to skip right to the update, but otherwise you’ll want to review these steps.
Step through the distribution’s
important versions until you reach 9.2.13.0. You should be running the latest Drupal 9.5.x before you begin the upgrade to 10.
Pre-checks
CKEditor
If any custom/contrib modules are used, CKE5 should likely be done AFTER your D10 upgrade
Contrib checks will NOT be found in the next step, be sure to check these manually
Dependency cleanup
Modules not installed, but in composer.json should be cleaned up to prevent unwanted dependency issues in trying to update.
Admin theme
If your website uses a
deprecated admin theme, you should migrate to the Claro theme and test the admin experience. If necessary you can keep the deprecated theme as a contrib package but that is not recommended and won’t be supported by the distribution.
Upgrade Report
Install Upgrade Status
fin composer show drupal/core | grep versions
fin composer require --dev drupal/core-dev:[copy version above] --update-with-all-dependencies
Search for hook_field_widget_form_alter, hook_field_widget_multivalue_form_alter, hook_field_widget_WIDGET_TYPE_form_alter and hook_field_widget_multivalue_WIDGET_TYPE_form_alter. These hooks have been deprecated in Drupal 9.2 and not available anymore in Drupal 10.
Streamline field widget hooks
Patches
Review patches in composer.json. Review any that are no longer applying or may be duplicated by the distribution.
Carefully review and re-roll custom patches.
Update
At this point you should be ready to update to the latest version of the distribution:
Edit the ycloudyusa version in your project root composer.json: "ycloudyusa/yusaopeny":"^10.3",
Run composer update
If errors occur, review the conflicts, check out the
known issues, and attempt to resolve them.
Re-run the previous steps until they complete successfully
Run drush updb, review the updates, and run them.
Smoke Tests
We recommend reviewing critical functionality after the update to ensure any custom functionality still works.
Troubleshooting
Composer Issues
Composer can be … tricky. To resolve composer conflicts:
If specific modules conflict, try requiring them directly to get more information about the conflict.
> [error] Configuration core.entity_view_display.node.lb_event.featured depends on the core.entity_view_mode.node.featured configuration that will not exist after import.
you may be able to resolve it yourself.
Breaking down the error message:
core.entity_view_mode.node.featured is missing, which is blocking
y_lb_update_9011 from installing core.entity_view_display.node.lb_event.featured
We need to figure out where core.entity_view_mode.node.featuredshould be coming from, so we can search our code for that.
Use the “Find in files” command in your IDE to search docroot/modules, or
// This goes in mymodule.install as the next update hook.
// Increment the number accordingly.
functionmymodule_update_9000(){$path=\Drupal::service('extension.list.module')->getPath('ws_event').'/config/optional';/** @var \Drupal\config_import\ConfigImporterService $config_importer */$config_importer=\Drupal::service('config_import.importer');$config_importer->setDirectory($path);$config_importer->importConfigs(['core.entity_view_mode.node.featured',]);}
// This also goes in mymodule.install.
functionmymodule_update_dependencies(){$dependencies['y_lb'][9011]=['mymodule'=>9000,];}
Re-run drush updb.
If you run into other missing configs, add them to the list to be imported in update hook and re-run updb.
Consider backporting your customization which led to the challenge of doing this upgrade in order for it to be covered and tested by distribution developers.
4.19 - Drupal Core Dependencies Version Flexibility
:::caution
This document is no longer actively maintained. The information it contains may be outdated.
:::
To update the version of Drupal being used on your site independently of YMCA Website Services, see the official Drupal documentation:
Updating Drupal Core via Composer.
Important: The openy/composer.json file may set
Drupal core version constraints. Always review these constraints before updating Drupal core. These constraints define the compatible Drupal core versions for the YMCA Website Services distribution.
Working with Drupal Core Versions (Example: Drupal 9)
In the February 2021 release, YMCA Website Services tagged Drupal core versions 9.0.x and 9.1.x as allowed dependencies.
Composer, by default, installs the latest stable version that satisfies the defined constraints. Therefore, executing the following command:
will typically install YMCA Website Services with the latest stable 9.1.x Drupal core version (subject to the constraints in composer.json).
Pinning to a Specific Drupal Core Version
If you need to stay on a specific Drupal 9.0.x stable core version (e.g., for compatibility reasons), use the following commands:
composer create-project YCloudYUSA/yusaopeny-project:dev-9.2.x-development OPENY --no-interaction
cd OPENY
composer require drupal/core:~9.0.7
In this example, 9.0.7 represents the specific Drupal core version you want to use for your YMCA Website Services instance. Replace this with your desired version number.
Module Version Constraints
Refer to
Composer-version-constraints-for-Open-Y for information about module version constraints within the Open Y distribution. This document provides guidance on how module versions are managed and constrained within the YMCA Website Services ecosystem.
4.20 - Drupal-SA-CORE-2018-004 Security Update
This document is archived but may contain useful information for troubleshooting future updates. For updated upgrade steps, visit
How to upgrade YMCA Website Services.
This document provides instructions for applying the security fix described in Drupal core’s
SA-CORE-2018-004 security advisory to your OpenY site.
The OpenY team suggests two options:
Apply a patch: Use this method for a quick resolution.
Upgrade Drupal core (or OpenY): This is a more comprehensive solution but may require more planning and testing.
Applying the patch is recommended to address the security issue promptly. You can then schedule a Drupal core or OpenY upgrade for a later date.
How to Apply the Patch
The following instructions are for patching OpenY releases 8.0.1 - 8.1.10, which correspond to Drupal cores 8.2.x, 8.3.x, and 8.4.x.
Access your server via SSH:
Log in to your production server environment via SSH and navigate to the docroot folder of your site codebase. If you followed a standard OpenY installation tutorial, your site is likely located in either /var/www/html or /var/www/openy.
If your site is located in /var/www/html:
ssh -l root YOUR_SERVER_DOMAIN_NAME
cd /var/www/html
If your site is located in /var/www/openy:
ssh -l root YOUR_SERVER_DOMAIN_NAME
cd /var/www/openy
If the output is different, stop and seek assistance. A failed dry-run indicates a problem applying the patch, and applying it anyway could break your site.
Apply the patch:
If the dry run was successful, apply the patch with the following command:
patch -p1 < SA-CORE-2018-004.patch
You should see the same output as in the dry run. Your site is now patched.
Important: Clear all caches after applying the patch. This can be done via the Drupal UI or using Drush: drush cr
(Optional) Commit changes to your Git repository:
If you are using Git for version control, add the patched files to your repository and commit the changes.
If you installed OpenY on a DigitalOcean server (droplet) using a tutorial, these steps provide a simplified patching method.
Log in to the Drupal admin UI:
Access your site’s admin interface by navigating to /user/login.
Access the DigitalOcean console:
Log in to the DigitalOcean cloud console at digitalocean.com and find the “Access Console” option in the dropdown menu for your OpenY droplet.
Log in to the console:
A popup window with a black screen will appear, prompting for login credentials. Use root as the username and the password generated during droplet creation.
Run the one-line script:
Execute the following command in the console. This script automatically applies the patch:
After the script completes, you should see the message OpenY was patched.
Important: Clear all caches after applying the patch. This can be done via the Drupal UI or using Drush: drush cr
4.21 - Google Custom Search Configuration
YMCA Website Services release 8.2.4 introduces Google Custom Search (aka Google Programmable Search Engine) for the website. This feature allows you to integrate a custom search engine powered by Google, providing enhanced search capabilities for your website.
Enabling the module
Fresh installations
The search feature is automatically included in the Extended installation type. If you chose the Standard installation, refer to the Existing websites section for instructions on enabling the search feature.
During a fresh YMCA Website Services website installation via the web interface, the third-party integration step allows you to specify a Google Search ID. Providing the ID during this step configures the search feature to be up and running immediately.
Existing websites
If you are upgrading an existing YMCA Website Services website, the search feature is not automatically enabled. You must manually enable it.
To enable the search feature:
Log in as an administrator (or a user with the administrator role).
Navigate to the YMCA Website Services Extend page (Admin menu > YMCA Website Services > Extend > Install, or /admin/openy/extend/list).
Locate the YMCA Website Services Google Search package.
Tick the checkbox next to the package name.
Submit the form to install the package.
After installation, the necessary modules are enabled, and a search field should appear in the website header. During installation, the module automatically creates a Landing page for search results and configures the header search form to point to this page.
Configuring the Google Search module
After enabling the module, you need to configure it with your Google Search Engine ID:
Access the Google Search settings form (Admin menu > YMCA Website Services > Settings > Google Search settings, or /admin/openy/settings/google-search).
Locate the Google Search ID field.
Enter your Google Search ID (refer to the following section for instructions on obtaining your Search Engine ID).
Register for an account if you don’t already have one, and log in.
Create a new Search Engine. Google provides detailed instructions on how to do this in their official documentation. The basic steps are:
Click “New Search Engine”.
Specify the domain of your website (e.g., www.example.com).
Specify a name for the Search Engine (e.g., example.com).
Click “Create”.
Once the Search Engine is created, you will be redirected to its configuration page. The Search engine ID is displayed on this page. Copy this value.
Paste the Search engine ID into the YMCA Website Services Google Search configuration form.
Configuring the Search Engine look and feel
To configure the look and feel of your Search Engine:
Go to the Look and feel section of the Search Engine in the Google Programmable Search Engine control panel.
In the Layout tab, select the Full width option and click Save.
If you do not select the Full width option, the search results may display in a popup window on your website.
Dealing with Ads
New Google Programmable Search Engines use the Free Edition (with ads) by default. As YMCAs are non-profit organizations, you can switch to the Non-profit Edition of the CSE, which allows you to disable ads.
If you are already registered as a Non-profit in Google:
You can configure the custom search engine to include multiple domains, which is useful if your association manages multiple websites (e.g., different websites for different camps).
You can also restrict the search to specific parts of a website by using URL patterns like example.com/blog/*. For more information, see
Update sites in your search engine.
Refinements allow users to filter search results based on predefined categories.
Refinements are displayed as tabs on the search results page. You can configure the content of each tab in the “Search features > Refinement” section of the Custom Search Control Panel.
Example: Creating a “Blog” tab:
In the Control panel, go to Search features > Refinements.
Click Add.
Set the name of the refinement to Blog.
Select Search only the sites with this label for How to search sites with this label?.
Click Ok.
Go to Setup.
Find Sites to search, click Add.
Add example.org/blog/* in the text field.
Select Blog in the Label dropdown.
Select Include just this specific page or URL pattern I have entered.
Click Save.
This configuration adds a “Blog” tab to the search results page, displaying only blog entries related to the search term.
The openy_third_party_services.google_search_engine_id parameter sets the Search Engine ID (01234567890123456789:abcdefgh in the example). Replace the example ID with your actual Search Engine ID.
To set the Search Engine ID on an already installed website, use the following Drush command:
Replace 01234567890123456789:abcdefgh with your actual Search Engine ID.
4.22 - GroupEx PRO quick start
This document has been moved to
ynorth-projects/openy_pef_gxp_sync. This repository contains the code to synchronize data between GroupEx Pro and the Open Y platform.
4.23 - How to Contribute Large Features (Back-porting, etc.)
These are our best practices for back-porting large features into YMCA Website Services and contributing code for others to use.
Summary
The YMCA Website Services core team is excited for you to contribute to the distribution for all to benefit from.
There’s a lot that goes into back-porting your code – details below.
These steps ensure that we are collaborating while continuing to support YMCA Website Services in a sustainable way.
Before getting started, please keep these notes in mind:
Back-porting requires a process called decoupling. This is where your developers remove any hard-coded variables or dependencies on any integration from your website code. This makes it so the feature you wish to contribute can work for anyone in the broader Y movement. For example, anything that ties into Personify APIs will have to have those hooks replaced with Program Event Framework so that it could function with any CRM source that a YMCA Website Services site might be using.
This decoupled code will then need to be thoroughly tested to ensure it can function when not relying on any fee-based, or non-secure, technology or systems.
Once the decoupling is complete, the YMCA Website Services core team will need to review every line of code before it goes into the distribution. This helps us ensure it won’t break any of the other elements of YMCA Website Services and that the code is 100% secure. As of 2019, we have 3 templates in YMCA Website Services that work across mobile, desktop, and tablet breakpoints. We need to test new features/code across all these templates to make sure nothing breaks across hundreds of possible use-case scenarios. For example, adding a schedule block to a location landing page using the Carnation template when on the mobile breakpoint that is powered by ActiveNet through Program Event Framework.
Once a feature is in YMCA Website Services, someone must pay to maintain that code. Does this code rely on any other Drupal modules to function? What if there’s an update to that module? That update needs to be tested to ensure it’s compatible with the now contributed code – and if it breaks, we have to write new code to fix it. What if there’s a security patch that involves the contributed code? We would then have to spend time applying the patch, etc.
Is your customization a new feature or a replacement of existing YMCA Website Services functionality/UX? We prefer you have A/B testing data demonstrating that your customization is a clear improvement over the current YMCA Website Services experience. There are many ways to run AB tests, so please consult with the YMCA Website Services team on your hypothesis, method, and success criteria to ensure that the results are valid and reliable.
Steps/process for back-porting code into YMCA Website Services:
Most problems have at least a generic component and can be approached in part through abstracted development.
We recommend beginning development with an eye toward
these “abstracted” solutions - providing configuration instead of static templates, solving root causes instead of using local patches, using generic language instead of client specific. This will ensure that your features are easily contributed even before you begin this process.
List each customization/feature you want to contribute to YMCA Website Services.
It’s plausible that there are portions of your code that it might not make sense to put into the distribution, either because it’s duplicative to what YMCA Website Services already has, or it might be cost-prohibitive to decouple it from your site for back-porting.
In the early days of YMCA Website Services, we were less stringent on this step. As long as there was no security or technical risk, we accepted any contribution into YMCA Website Services. This led to some problems, such as having two nearly identical paragraph types called Blog Post and News Post. These were contributed by two different associations. This caused significant confusion until we resolved the issue with the launch YMCA Website Services 2.0, where we deprecated some of this functionality.
You can start this process by taking an inventory of all your customizations that you feel would be good to backport into the distribution.
The deliverable of this step is a list of each independent feature you think it makes sense to contribute.
Prioritize your list.
Rather than taking a ‘big bang’ approach of decoupling and back-porting all your features into YMCA Website Services, it is a better practice to take a bite-size approach, doing one feature at a time. This is because it can be cost and time intensive and expensive to decouple and backport your code into the distribution if you do it all at once.
As a guide, YMCA Website Services uses the following prioritization method: Demand for feature (1 to 3 with 1 being high), Impact/Benefit to Ys and visitors (1 to 3 with 1 being high), Effort to build/maintain (1 to 5 with 1 being extra low and 5 being extra high). The sum of these gives us a ‘score’ for each feature which helps us prioritize.
This will also help you decide how much, or little, of your back-porting you want to fund as you’ll be able to get a clear feature-by-feature time estimate for the work required.
The deliverable will be a prioritized list of the features that you want to contribute.
Share your prioritized list with YMCA Website Services, and align roadmaps before spending money and time on decoupling.
There might be things the YMCA Website Services core team is already working on that are similar and would be finished before your decoupling would be complete, thus it would not be the best use of your funds to decouple/backport that feature.
There may be information the YMCA Website Services team has based on talks with other Ys that influence your demand/impact scores and thus your prioritization.
We might have technical knowledge that influences your effort scores as well.
This is when timelines will start to emerge on when your code would be available in the distribution.
Decoupling.
Your developers and the YMCA Website Services team should align on best practices for code. At a high level, our best practices can be reviewed here:
Development FAQ and
How we release code.
When you are ready to begin the decoupling work, let us know, and we can either talk to you here, on Slack, or even set up a conference call if it would be helpful for you.
You would then start the technical/dev work of decoupling the features you wish to contribute back into YMCA Website Services.
You would test all of your decoupled code to ensure that these features work when no longer reliant on any paid or non-secure technology or partners.
The deliverable from this step is code that works in your own dev environment independent of any other Y association-specific code/technology.
Contribute your code: Pull Requests (PRs).
Code gets submitted to YMCA Website Services for review via a process called a Pull Request.
The YMCA Website Services lead technical architect sees the code, runs it through automated test cases, and provides feedback on any issues detected that may cause problems for other portions of YMCA Website Services code.
Sometimes, the feedback from the YMCA Website Services lead technical architect requires re-work from the original developer making the PR before the code is accepted into the distribution. See
Submitting Patches or Issues in the Blazy module documentation for tips on how to write good pull requests.
Release.
The features contributed from you get scheduled into one of the YMCA Website Services quarterly releases, and we make sure you get ample credit for your contribution.
The movement then benefits from your contribution!
Ongoing improvements, maintenance, etc.
Over time, you might want to make enhancements to your site due to analytics or other data inputs from customers and team members.
It would be great if you made those same enhancements to the now-decoupled version of your code that exists in YMCA Website Services if you feel it makes sense.
If you identify any bugs or issues over time on your site that involve code that was contributed to YMCA Website Services, it would be awesome if you fixed that code and contributed the fix via a Pull request (step 5 above).
To be clear, all of the above is only required if you want to get your code into the core YMCA Website Services distribution. You could always take your code as is, ensure any PII or secure information is scrubbed, and post it to your own GitHub repository – however it would be difficult for others to use this code as is if it hasn’t at least been decoupled. If you take this approach, please be sure to remove references to OpenY from the code so that the GitHub search engine does not confuse it with core YMCA Website Services. Further, please review the YMCA Website Services license agreement to make sure you are in alignment with GPL and Open Source sharing best practices.
4.24 - How to Develop Themes in YMCA Website Services
Developing Themes
Each YMCA Website Services theme was developed independently, either by the YMCA Website Services Core Team or by a partner for a specific Y and then contributed back. You can see demos of each theme on the
Sandboxes.
Each theme has its own dependencies and build processes. Refer to the README file within each theme’s project for specific instructions.
Theme Inventory
As of December 2021, themes have been decoupled from the YMCA Website Services profile and exist as independent projects on Drupal.org.
YMCA Website Services development moves quickly. This document highlights important versions that should not be skipped when upgrading your sites. Understanding the upgrade path ensures a smoother transition and avoids potential issues.
Determining your upgrade path
Example: If you are on YMCA Website Services 8.1.2 and want to upgrade to YMCA Website Services 8.2.8.5, you should follow these steps:
Upgrade 8.1.2 to 8.1.13.1
Upgrade 8.1.13.1 to 8.2.2.1
Upgrade 8.2.2.1 to 8.2.7.3
Upgrade 8.2.7.3 … and so on.
These supplemental documents provide more detailed information for specific upgrade scenarios:
The following versions are crucial milestones in the YMCA Website Services upgrade path. Pay close attention to the notes for each version to ensure a successful upgrade.
8.1.13.1 - Optional, use this version if you have a lot of customized code and encounter issues with 8.2.2.1.
8.2.2.1 - Critical. This is a mandatory step for all sites. After upgrading to this version, drush entup will no longer function. This version marks the migration to the core media subsystem. Upgrading your site to this version first is essential for proper media management in later versions.
8.2.7.3 - Recommended. This is a very stable Drupal 8-based YMCA Website Services release with numerous updates to contributed modules. It’s one of the final Drupal 8-based versions before the upgrade to Drupal 9 core. From versions 8.2.7.0 and 8.2.7.1, multiple version constraints were introduced in composer.json, allowing developers to select between minimum or latest dependency versions for a more secure and flexible upgrade path.
9.2.8.0 - A Drupal 9 version that is required in the upgrade path before moving to 9.2.8.1+. This version includes Drupal Core 9.0-9.1 and disables deprecated components.
9.2.10.0 - This version removes several unused modules from the distribution, streamlining the codebase.
9.2.11.3 - Last Open Y release based on Drupal core 9.3.*.
9.2.11.4 - A technical release of YMCA Website Services with no functional differences compared to 9.2.11.3.
9.2.13.0 - Important pre-Drupal 10 release. This is the last Drupal 9 release. Before upgrading to Drupal 10 and entering the Layout Builder era, it is highly recommended to uninstall the geysir, openy_inline_editing, quickedit, and rdf modules as a best practice.
10.2.14 - A Drupal 10/9 release. When upgrading to this version, consider the following recommendations:
Upgrade to the latest Drupal 9 core using version 10.2.14 of the distribution (released in June 2023):
10.2.14 Release.
Upgrade all contributed modules and libraries to their latest Drupal 9-compatible versions using composer update.
Utilize tools like
drupal-rector,
drupal-check, and PHPCS to prepare custom modules and themes for Drupal 10 compatibility.
Upgrade to Drupal 10 and perform thorough regression testing to identify and resolve potential bugs. Update drupal/core-* projects in composer.json, then run composer update.
Upgrade all contributed modules on the Drupal 10 site to their latest versions using composer update.
10.3.0.1 - Drupal 10/9 release that precedes the introduction of new demo content and the initial replacement of Paragraphs with Blocks for a native Layout Builder experience.
10.3.1 - Drupal 10/9 release that introduces new demo content and initiates the replacement of Paragraphs with Blocks for a native Layout Builder experience. A significant number of dependencies were also updated in this release.
10.3.2 - Introduced
recurring event support in the Event Content Type, which necessitates an automated migration between date_range and smart_date fields. If possible, update to this version during the upgrade process.
10.3.2.3 - Introduced before 10.1 and 10.2 Drupal core. Also upgraded openy_map. This version ensures we support removed modules pre 10.1 for contrib modules.
If you encounter an issue where composer installs an incorrect version of drupal/core for your chosen YMCA Website Services version, use the following command to downgrade:
composer require drupal/core-recommended:9.5.9
Run this command from your docroot. Replace 9.5.9 with the correct core version you need.
4.26 - Install Solr site search
YMCA Website Services leverages
Apache Solr for a few features:
A running Apache Solr server, version 6.4 or higher is recommended (refer to
Apache Solr for installation instructions).
The YMCA Website Services Search API module installed and enabled.
Administrative access to your Drupal site.
Quick Start / Upgrade path
Log in as admin.
Go to admin/modules and enable the YMCA Website Services Search API module.
Approve the next step for enabling Database Search.
Go to the Search API configuration page admin/config/search/search-api.
Verify that the “OpenY Database Search” server is enabled.
Visit “Search content” index.
TIP: Admins can enable the Solr search and switch the index between servers.
Index content by clicking “Index now”.
Go to the homepage and search for any keyword.
Verify search results are displayed correctly.
Starting from the YMCA Website Services installer
Find the Select search service step displayed during the YMCA Website Services installation.
Choose from one of these options during installation:
None
Nothing happens if the user chooses this option; search modules are displayed after installation.
YMCA Website Services Google Custom Search
Google Custom Search configuration form is displayed if the user chooses this option.
The YMCA Website Services Google Search module is enabled after installation and ready to use.
YMCA Website Services Search API
Search API backend options are displayed in this case with the following options:
Database
The YMCA Website Services Search API module is enabled after installation. The database search API server is enabled. The search is ready to use after content indexation.
Solr
Additional installation step with Solr configuration form is displayed in this case and user can specify all params for Solr connection. The YMCA Website Services Search API module is enabled after installation, Solr search API server is enabled. The search is ready to use after content indexing (if the correct Solr settings were used).
Switch from database search backend to Solr backend
Watch a
video tutorial on how to switch an existing site from the database backend to a Solr server. This requires a Solr server to be configured in your environment.
Edit the “Solr search” server from the Search API configuration admin/config/search/search-api.
Add the configuration information for your Solr server. Refer to Drupal’s
Search API Solr project for troubleshooting connection information.
Save the server and observe that Search API has successfully connected to your server.
Edit the “Search content” index and change the “Server” field to the newly configured “Solr Search” index.
Visit the “Search content” index and click “Index now” to re-index the content.
Layout Builder and Solr search
Solr search can be used with
Layout Builder, and requires a few extra steps.
Configure Solr to index the new content types
In order for Solr to index the new content types, they need to be added to the index.
Enable the YMCA Website Services Search API (openy_search_api) module if not already enabled.
Go to Admin > Configuration > Search and metadata > Search API, then Edit the Search content index. (/admin/config/search/search-api/index/search_content/edit)
Configure Solr to index the Layout Builder content types:
Scroll down, expand Configure the Content datasource, and check the content types that should be indexed for search.
Save the form.
Configure how Solr indexes the Layout Builder content types:
From the Search API configuration, open the dropdown for the Search content index and choose Fields.
To the right of the Rendered HTML output field options, choose Edit.
For each newly added content type, switch “Don’t include the rendered item” to the right view mode.
In general, new Layout Builder specific content types will use the “Default” view mode, while older Layout Builder-compatible content types should use the “Full content” view mode.
Content type
View mode
Article (LB)
Default
Branch
Full
Event (LB)
Default
Camp
Full
Camp Subpage
Full
Facility
Full
Landing Page (LB)
Default
Program
Full
Program Subcategory
Full
Save the page.
Once your changes have been saved, re-index the content to see the changes reflected in search results.
Set up a Layout Builder search page
If you have an existing site, disable the old search page:
Go to /search.
Remove the URL alias by unchecking Generate automatic URL alias in the sidebar then deleting /search.
Uncheck Published and Save to un-publish the page.
Create a new Landing Page (Layout Builder) (node/add/landing_page_lb):
Set the Title to “Search”.
Ensure Generate automatic URL alias is unchecked in the sidebar and set the alias to /search.
If that alias results in an error, you can remove the old one at Admin > Configuration > Search and metadata > URL aliases
Check Published then Save and edit layout.
Add a
Small Banner to the header with a title for the page, like “Search”.
Add the search results block to the page:
In the Body section, Add block, then expand All system block and choose Content search block from the Paragraph Blocks section.
Optionally, choose to hide the title or change the number of items to display.
Save layout and check your page.
Change the Search API config to use your new page:
Go to Admin > YMCA Website Services > Settings > Search API settings (/admin/openy/settings/search-api) and set the Search page id to the node id of your new page.
Test the search box in the Layout Builder page header to ensure the new configuration works as expected.
Legacy Solr Support
The contrib
Search API Solr module supports a broad swath of Solr versions, but occasionally old versions are dropped from support in the main module. If, when enabling YMCA Website Services Search API, you encounter errors that your version of Solr is out of date, you may need to enable the
Search API Solr Legacy module. As of January 2022, Search API Solr Legacy supports Solr 3.6 through 6.4.
The error message when using an old version of Solr may look something like this:
Notice: Undefined index: 4.x in Drupal\search_api_solr\Controller\SolrConfigSetController->getConfigFiles()
4.27 - Install SSL Certificate
Web Security and YMCA Website Services
As many parties have moved to
Encrypt the Web, https sites and SSL certificates have shifted from a “nice to have” to a necessity.
If you’re running YMCA Website Services on a managed platform, you most likely have SSL already configured. If you choose to manage YMCA Website Services on your own, you’ll have to install a certificate.
Let’s Encrypt is “a free, automated, and open certificate authority (CA), run for the public’s benefit. It is a service provided by the
Internet Security Research Group (ISRG).”
Certbot is “a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS.”
Certbot maintains detailed documentation for installing SSL certificates on a variety of systems. Simply
visit Certbot’s instructions wizard and follow the instructions to configure your server.
4.28 - Installation With Drush
You can use the
drush site-install command to quickly set up the OpenY distribution.
openy: Specifies the installation profile to use (OpenY).
--account-pass=password: Sets the administrator password. Replace "password" with a secure password.
--db-url="mysql://user:pass@host:3306/db": Defines the database connection details.
user: Database username.
pass: Database password.
host: Database host.
3306: Database port (default MySQL port).
db: Database name.
--root=/var/www/docroot: Specifies the Drupal root directory. Adjust this to the correct path on your server.
openy_configure_profile.preset=extended: Selects the “extended” installation preset.
openy_theme_select.theme=openy_rose: Selects the “openy_rose” theme.
4.29 - Module Development
Module Content Removal
When deleting an entity where plugins or services of the removing module are used, content removal should be done in the hook_uninstall() function of that module. This ensures that no orphaned data or references remain in the system after the module is uninstalled.
Example:
See openy_prgf_camp_menu.install for an example of how to implement this. The hook_uninstall() function in this file removes paragraphs before the module uninstall to avoid errors related to missing services used in the camp menu block.
Creating a New Module
When creating a new module on Drupal.org, ensure the following:
Add all current maintainers: Properly credit and involve all individuals actively contributing to the module.
Add a module template: This template provides essential information and resources for users. Use the following HTML snippet and customize it for your module:
<tableclass="views-view-grid"bgcolor="#d4efcc"><tr><td><h2>🇺🇦</h2></td><td> This module is maintained by Ukrainian developers. Please consider
<ahref="https://supportukrainenow.org">supporting Ukraine</a> in a fight for their freedom and the safety of Europe.
</td></tr></table><!-- Edit this section with a short intro to the module -->This component/module allows you to ... when using the
<ahref="https://github.com/YCloudYUSA/y_lb">YMCA Layout Builder</a> package.
<!-- Leave this section as is --><ul><li> Read our
<ahref="https://github.com/YCloudYUSA/yusaopeny#installation">instructions for getting started</a>.
</li><li><ahref="https://ds-docs.y.org/docs/">Search our documentation</a> for
assistance.
</li><li><ahref="https://ds-docs.y.org/community/">Review our Community Resources</a> for more information.
</li></ul><h3id="project-requirements">Requirements</h3>This project is meant to be used with the
<ahref="https://www.drupal.org/project/openy">YMCA's Website Service distribution</a>.
4.30 - One-Click Install How-To
This walkthrough is outdated and is in the process of being updated. Consider using the resources below instead.
Installing YMCA Website Services on a DigitalOcean Droplet
These steps outline how to install YMCA Website Services on a DigitalOcean droplet.
Create a new Ubuntu 16.04 LTS x64 droplet. Choose a region close to your location.
Use a 2GB droplet or more powerful option, if needed. Do not use the 1GB option as YMCA Website Services may fail on it.
Log in to the droplet via SSH.
Execute the one-click install script. Run the following command as the root user:
curl -Ls http://bit.ly/initopeny | bash -s
This command will run for approximately 10 minutes.
Access the installation URL. Upon completion, you should see a message similar to:
Open http://127.0.0.1/core/install.php to proceed with OpenY installation.
Open the provided URL in your browser. Access this link from your droplet’s IP address, not from this document. Then proceed with the YMCA Website Services installation.
For example, if your droplet’s IP address is 192.0.2.0, you would access http://192.0.2.0/core/install.php.
Enjoy!
Installing the Latest Beta Release
To install the latest beta release of YMCA Website Services 2.0, modify the command in step 3:
curl -Ls http://bit.ly/initopeny | bash -s beta
Troubleshooting
If you encounter any issues, please report them in the issue queue:
On January 28, 2020, the Open Y initiative introduced an anonymous analytics module,
openy_analytics. This module was designed as a free, opt-in/opt-out solution, allowing the Core Team to gather statistics from Open Y sites regarding the usage frequency of various components.
The primary goal was to collect data that would inform decision-making and enhance our understanding of component demand within the Open Y ecosystem.
Recently, the Open Y Core Team decided to sunset this functionality and remove both the openy_analytics and openy_update modules from the Open Y distribution due to low usage. This sunsetting reduces the server load on Open Y instances and allows us to archive the analytics server.
How to Opt-Out of the Analytics Subsystem
To opt-out, navigate to YMCA Website Services -> Terms and Conditions within your YMCA Website Services site instance and uncheck the Optional Permissions checkbox.
After submitting the form, your site will no longer transmit anonymous data. If the checkbox was already disabled, no action is needed, as you had not previously opted in.
Deprecation Details
The uninstall and deprecation process was implemented in
Pull Request #2537.
Related Packages
The openy_analytics module was part of the Analytics package. This package, as described in openy.packages.yml, aimed to “integrate the website with analytic systems and capture website statistic.” It included modules like google_tag and google_analytics to configure integrations with Google Analytics or Google Tag Manager.
4.32 - Participant Agreement
YMCA Website Services PARTICIPATION AGREEMENT
This YMCA Website Services Participation Agreement (this “Agreement”) is between YMCA of the USA (“YUSA”), and participating YMCA member associations in the United States (“Member Associations”). YUSA has received license rights from the National Council of Young Men’s Christian Associations of the United States of America, an Illinois not-for-profit corporation (“National Board”) to provide the Platform (as defined below) to you.
The purpose of the YMCA Website Services community is to collectively advance YMCA web and online experiences to better serve the YMCA mission. The terms of this Agreement govern your use of YMCA Website Services’s open-source digital content management system. This system facilitates the sharing of National Board brand-compliant website templates, tools, applications, and related digital assets (“Platform”). The community provides a collaborative environment for individuals to positively interact and participate in the Platform. These guidelines address the standards and expectations of those contributing to and participating in the YMCA Website Services community. They are meant to help our YMCA community grow and thrive. Your participation in YMCA Website Services means that you agree to the following guidelines and to the YMCA Website Services
Terms of Use.
YMCA BRAND ASSETS
No right is granted by this Agreement to use or license the YUSA brand assets. YMCA brand assets, which include, but are not limited to YMCA trademarks, trade dress, logos and other indicia of origin, are owned and controlled by YUSA. YUSA provides the Platform to you under license from YUSA. Accordingly, neither YUSA nor any Member Association shall, either directly or indirectly, at any time do any act or thing contesting the validity of YUSA’s trademarks or its rights thereto.
Only Member Associations in the United States will have access to use any YUSA brand assets included in YMCA Website Services. All use by Member Associations must be in compliance with YUSA brand standards and guidelines as established by the National Board. YUSA is a third party beneficiary to this Agreement, with the right to enforce each of the terms of this Agreement with respect to YMCA Website Services and you. YMCA Website Services shall send copies of all notices due to you under this Agreement to each of you and YUSA.
BEING A MEMBER OF OUR COMMUNITY
Participation: YMCA Website Services will be at its best if each member participates in the community. There are many different ways you can participate, including through using the platform, presentations, forums, summits, emails, calls, etc. We encourage your active participation to the extent you feel you are able and willing. YUSA may publicly disclose your participation in the project.
Contribution: YMCA Website Services encourages Members to contribute to the enhancement, editing, and building of YMCA Website Services. To ensure valuable contributions to the community, YMCA Website Services encourages Members to stay familiar and up-to-date with the YMCA Website Services roadmap, as well as new features in active development. When you make changes that improve YMCA Website Services features, please contribute those back to the community by ensuring they are re-useable and decoupled.
Collaboration: YMCA Website Services encourages Members to collaborate across the YMCA community to share costs and efforts on building new capabilities.
Transparency: Customizations of code provided by YMCA Website Services for your website will likely increase the initial fees, support, and upgrade costs for your website. When modifying or redistributing code, you must include a notice giving credit to YMCA Website Services for the portion of the YMCA Website Services code you use.
Promotion: YMCA Website Services encourages Members to share their expertise and YMCA Website Services experience to expand its reach and accessibility to experienced and new members alike. There will be many opportunities for members to support YMCA Website Services and its marketing and messaging initiatives.
Reporting Problems
If you believe someone has violated the YMCA Website Services Community Guidelines, or have any questions or concerns, please contact YUSA through the
YMCA Website.
4.33 - Patch YMCA Website Services
Here you can find instructions on how to patch a YMCA Website Services distribution used in your project.
When to Patch YMCA Website Services
If you’ve found a bug and created a patch for YMCA Website Services on GitHub.
If you’ve developed a new feature that would benefit YMCA Website Services and created a Pull Request (PR) to the YMCA Website Services repository.
If you want to use a feature that has been added to YMCA Website Services but isn’t yet included in a released version.
Patch description: A brief description of what the patch does. This helps you remember the purpose of the patch later.
https://...XXX.patch: The patch link created in step 1.
Run composer update:
This command applies the patch to your project.
Verify the Changes:
Check that the changes from the patch are present in your YMCA Website Services installation.
Enjoy!
4.34 - Profile custom configuration
The distribution supplements the Drupal install process with a number of custom additions.
There are many
YAML configuration files at the root of the profile. Some are standard Drupal configuration, and others are YMCA Website Services specific.
Basic .yml files
The following files are very common and can be found in many Drupal modules:
openy.info.yml (
documentation) - Defines YMCA Website Services as a profile and defines its name and dependencies. See openy.info.yml file located in the /docroot/profiles/contrib/yusaopeny/ directory.
openy.permissions.yml - Defines global YMCA Website Services permissions.
openy.services.yml (
documentation) - If you are introducing a service that is needed by all (or the majority of) YMCA Website Services modules, add it here and store the service class file in the openy/src directory.
YMCA Website Services specific .yml files
There are also a few configurations related to the YMCA Website Services installation process and the YMCA Website Services package system:
openy.installation_types.yml
openy.themes.yml
openy.packages.yml
YMCA Website Services packages
The YMCA Website Services package system introduces a new level of abstraction, shifting from the Drupal standard module level to packages. Packages represent complete YMCA Website Services features, which could include multiple modules. A package is a declaration of a group of several modules. You can enable and disable a package, which means the whole set of the associated Drupal modules are enabled or disabled.
This approach provides a convenient way of managing YMCA Website Services features.
The YMCA Website Services system module provides a page where the enabled and available packages are listed and can be installed/uninstalled. See the YMCA Website Services Extend page (at /admin/openy/extend).
YMCA Website Services Installation types
When an YMCA Website Services site is installed, there is also another abstraction level - the installation type - which groups packages.
The hierarchy is as follows:
installation type
package
module
module
package
module
module
module
package
module
installation type
package
module
openy.installation_types.yml
openy.installation_types.yml defines the high-level presets available during website installation.
Each installation type has a machine name which is a key of the top-level items.
Properties of installation types:
name (required) - A human-friendly name of the installation type.
packages (required) - A list of YMCA Website Services packages that are associated with the installation type. The packages are listed when a website is installed via the web-interface.
hidden (optional) - If the installation type must be hidden when a website is installed via the web interface.
If an YMCA Website Services site is installed using the web interface, there is a step where the installation type can be selected.
If an YMCA Website Services site is installed using Drush, then the installation type can be specified by an optional argument for the drush site-install command (
Installation with Drush):
Packages are defined in openy.packages.yml. This file is placed in the root of the profile, and it’s automatically detected and used by the YMCA Website Services installation process.
File structure
blog:name:"Blog"description:"Blog package provides a set of modules to maintain and create different blog post listings."help:'<p>Using Blog package you can create and maintain blog posts and create flexible listings of blog posts. Watch a video below to learn more about blog anatomy.</p>
<iframe width="560" height="315"
src="https://www.youtube.com/embed/Vg1fy29DhdQ"
frameborder="0" allow="autoplay; encrypted-media"
allowfullscreen></iframe>'modules:- openy_node_blog- openy_prgf_blog_listing- openy_prgf_featured_blogs- openy_prgf_blog_branch- openy_prgf_blog_camp- openy_prgf_blog_latest- openy_txnm_blog_categorycamps:name:"Camps"description:"Camps package provides a set of modules to maintain camps and add them to the location finder page."help:'<p>Using Camps package you can create and maintain Camps and extend location finder page to include them.</p>'modules:- openy_prgf_camp_menu- openy_loc_camp
Each package has a machine name which is a key of the top-level items.
Properties of packages:
name (required) - A human-friendly name of the package.
description (required) - A short description of the package features to show up on the YMCA Website Services Extend page.
help (required) - An HTML markup for the installation via web interface. It contains a help message that pops up when the package name is clicked on the Select installation type step.
modules (required) - A list of Drupal modules that are associated with the package. When the package is installed/uninstalled, the associated modules are installed/uninstalled respectively. When a website is installed via the web interface, all the available packages are listed there but split into two groups - the ones that are to be installed (associated with the selected package) and all the rest.
openy.theme.yml
The file defines which YMCA Website Services themes are available for installation when a website is being installed.
If an YMCA Website Services site is installed using Drush, then the theme can be specified by an optional argument for the drush site-install command (
Installation with Drush):
A robust set of content types and syncer modules that build interactive tools to help members find and book activities.
“Program Event Framework” (PEF) refers to the entire ecosystem of content and modules in YMCA Website Services that work together to build Activity Finder, Group Schedules, and more. PEF provides a structured approach to managing program-related content, ensuring consistency and ease of use.
Content Types
These content types provide the containers for PEF content in Drupal:
Program - Represents a high-level program (e.g., “Swimming”, “Camps”).
Program Subcategory - Represents a specific subcategory within a program (e.g., “Lap Swimming” within “Swimming”).
These modules provide integrations to pull content from external systems into the content types listed above. They automate the process of importing data from various platforms into the YMCA Website Services ecosystem.
Out-of-the-box, YMCA Website Services’s Activity Finder integrates with
Daxko,
ActiveNet, and
Personify. Configuring these integrations is mostly user-friendly, but often is supported by a partner development team. Any other CRM will require custom developer work.
When you add the Activity Finder block to a page, you have a number of options. These are in addition to the configuration at Admin > YMCA Website Services > Settings > Activity Finder Settings (/admin/openy/settings/activity-finder). See
the Activity Finder module README for more information.
Location & Category Filters - Restrict this block to show sessions from only certain Locations or Categories. Limit will show only the specified options. Exclude will remove the specified options. Generally you should choose either Exclude or Limit, not both.
Limit by location - Only show sessions at specific locations in the results.
Exclude by location - Remove sessions at specific locations from the results.
Limit by category - Only show sessions related to specific Program Subcategories in the results.
Exclude by category - Remove sessions related to specific Program Subcategories from the results.
Legacy mode - Shows some data as it was in the previous version of Activity Finder (v3):
Disables bookmark functionality on the results screen.
Doesn’t display the age indicator in the result card of activities.
Changes the days + times wizard step. Displays only days of week, but not times of each day (doesn’t support DaysTimes filter)
Weeks filter - Changes the Day/Time filter to use custom defined Week filters.
This requires setting the Weeks configuration in the Activity Finder settings (/admin/openy/settings/activity-finder).
Note: Only sessions that have Camp in the title or room fields will return for this filter.
Additional filters - These filters are off by default, but can be enabled in the Block Configuration.
Start Month - Filters based on the month in the Session Time field.
In Membership - Shows Sessions that have In membership checked.
Duration - The length of the Session. This is configurable in the Activity Finder settings (/admin/openy/settings/activity-finder) and defaults to:
Single day
Multi-day (up to 5 days)
Weekly (up to 3 weeks)
Monthly (up to 5 weeks)
Season (up to 12 weeks)
School year (~9 months)
Full year
Hide Home Branch info block - Disables functionality related to the users selected home branch.
Background image - An image that’s displayed in the background of the banner above Activity Finder.
Schedules - Filters by a number of facets, which are configurable in the Block Configuration or Activity Finder settings.
Age(s) - Filters based on the Min Age and Max Age. Age ranges are configurable in the Activity Finder settings (/admin/openy/settings/activity-finder).
Day(s) & Time(s) - Filters by the time of date on specific days of the week. This filter has no configuration.
Weeks - Replaces date/time filter when Weeks filter is selected in the Block Configuration. See configuration requirements above.
Activities - Program Subcategory filters grouped by Program.
Locations - Location filters grouped by Content type.
The filtered results in the Activity Finder app are a list of Sessions that meet the given filter criteria.
Each row of results contains:
The Session Title.
The Session Time, which contains a date, days of the week, and times.
The Session Location
The Session Min/Max Age
The Member Price and Non-member price
An indication of the number of spots available, from the Initial Availability field.
Clicking on the row will bring up a pop-up with further details:
The Session Description
A Learn more link and Register button which both go to the URL in the Session Registration Link field.
Additional topics
Allowing UTM codes in Activity Finder
UTM codes can be used to track the effectiveness of marketing campaigns. Activity Finder uses query strings as filters, but as of
version 4.2.0 it will also maintain UTM codes in the URL.
Activity Finder begins with a number of preset arguments, and those can be modified at Admin > YMCA Website Services > Settings > Activity Finder Settings (/admin/openy/settings/activity-finder) in the Allowed Query Arguments field.
Once those settings are saved, you can visit an Activity Finder page with UTM codes attached, for example:
and see that the codes are maintained as the filters are changed.
4.35.1.1 - Adding Activity Finder to your site
Both v4 and v3 can coexist as independent applications on your site, displaying the same data sourced from the Program Event Framework within Open Y.
The screenshot above illustrates the Open Y components listed for both Activity Finder v3 and v4.
Activity Finder v3 (Deprecated)
To implement the v3 Activity Finder, you’ll need to create two interconnected landing pages: one for the Activity Finder itself (deprecated) and another for the Activity Finder Search (deprecated).
4.35.1.2 - Bootstrap version support for Activity Finder
The Carnation theme utilizes Bootstrap v4.6. To accommodate this, the Activity Finder v4 module includes a “Bootstrap version” setting located at /admin/openy/settings/activity-finder.
The Rose and Lily themes use Bootstrap v3, while the Carnation theme is built with Bootstrap v4. Setting the “Bootstrap version” to “4” ensures that the Activity Finder v4 result page displays correctly on tablet screens within the Carnation theme.
4.35.1.3 - Configuring Solr for Activity Finder
To install Open Y with Activity Finder v4, use the following command:
This command retrieves the latest stable version of Open Y (Drupal) along with the latest stable version of Activity Finder v4. Proceed with the standard installation, ensuring you enable demo content as outlined in the provided tutorials. For streamlined setup, choose either the Extended or Custom installation profile (Custom via Drush).
Once YMCA Website Services (formerly Open Y) is installed, enable Activity Finder v4 with these Drush commands:
# Solr 8.8.1, Activity Finder v4drush en -y search_api_solr_legacy openy_prgf_activity_finder_4 ||truedrush en -dvy openy_prgf_af4_demo ||true
After enabling the modules, visit /admin/config/search/search-api to download the config.zip file. This ZIP archive contains the pre-configured Solr server settings for Open Y.
Hint: The Open Y module infrastructure is compatible with Solr versions 8 up to 8.8.1. Activity Finder v4 is specifically tested against Solr 8.8.1. Refer to the
Drupal.org documentation for instructions on installing Solr. Note that Solr versions prior to 7.7 are End of Life (EOL). The Open Y team is actively working on upgrading support for newer Solr versions.
Install the downloaded configuration as a separate core on your Solr 8.8.1 server. Extract the contents of config.zip into the conf directory of your new Solr core.
After extracting the configuration, verify that the core name defined in the core.properties file matches the Solr Server configuration within Open Y.
You can find the Solr server configuration dropdown at /admin/config/search/search-api.
Alternatively, you can configure Solr via Drush. Replace ${SOLR_CORE_IS_HERE} with the actual name of your Solr core in the commands below:
After executing these commands, confirm that the Solr server is enabled and indexed at /admin/config/search/search-api.
If you installed Open Y with demo content, create a landing page featuring the Activity Finder v4 component. The openy_prgf_af4_demo module automates this process. Enable it using Drush:
# Solr 8.8.1, Activity Finder v4drush en -dvy openy_prgf_af4_demo ||true
Enabling this module automatically creates the /activity-finder-v4 landing page.
Visiting /activity-finder-v4?step=results or clicking the suggested buttons displays activities, filters, and other features included in Activity Finder v4.
With the Open Y demo content, the Activity Finder v4 page should resemble the following:
mkdir solr8
sudo chown 8983:8983 solr8
docker run -v "$PWD/solr8:/var/solr" -p 8984:8983 --name d9_sandbox_rose_custom solr solr-precreate d9_sandbox_rose_custom
# stop docker and remove created container# unpack solr_8.x_config.zip into data/d9_sandbox_rose_custom/conf/docker run -v "$PWD/solr8:/var/solr" -p 8984:8983 --name d9_sandbox_rose_custom solr solr-precreate d9_sandbox_rose_custom
To configure Open Y to use Solr 8.x, change the address port to 8984.
Rebuild and reindex the index information. Verify that Activity Finder v4 functions correctly.
4.35.2 - PEF Schedules
The PEF Schedules module allows Ys to create and manage schedules with a simple, calendar-based view. It leverages the FullCalendar library for a rich, interactive experience.
The “PEF Schedules” module provides a calendar-based interface for creating and managing branch schedules. It integrates with the Open Y platform, allowing for seamless schedule creation and display.
Key Features:
Calendar-Based Interface: Utilizes the FullCalendar library for an intuitive drag-and-drop scheduling experience.
Branch Schedules: Allows administrators to create and manage schedules for different branches.
Configuration Options: Settings include configurable time intervals for calendar slots, event snapping granularity, and slot label intervals.
Integration with Open Y: Works with existing Open Y content types like Activities and Classes.
Display Options: Schedules can be displayed using the Simple Schedule block, Activity Finder, or Group Schedules.
PDF Export: Option to download schedules as PDF documents.
Configuration
The module provides settings for customizing the calendar’s appearance and behavior:
Slot Duration: Defines the length of each time slot (e.g., 00:30:00 for 30 minutes).
Snap Duration: Determines the granularity of time slot selection and event dragging (e.g., 00:15:00 for 15 minutes).
Slot Label Interval: Specifies the interval between time labels displayed along the calendar’s axis (e.g., 01:00:00 for every hour).
Min Time: The earliest time visible on the calendar (e.g., 04:00:00).
Max Time: The latest time visible on the calendar (e.g., 23:00:00).
Default Color: Sets the default color for activities displayed on the calendar, using a hexadecimal color code (e.g., #3788d8).
These settings can be accessed at Admin > YMCA Website Services > Settings > Schedules calendar settings (/admin/openy/settings/schedules-calendar).
Block Content Type
The module introduces a new block content type:
Simple Schedule: Provides a calendar view of a branch schedule.
Menu Links
The module adds the following menu links:
Schedules Calendar: Located under Admin > Content, allows administrators to select a branch and view its schedule.
Schedules calendar settings: Located under Admin > YMCA Website Services > Settings, provides access to the module’s configuration settings.
Dependencies
drupal:openy_repeat
drupal:colorapi
Repeat Schedules Paragraph
The “Repeat Schedules” paragraph type provides additional configuration options for displaying schedules:
Display instructor: A boolean field to show or hide the instructor’s name in the schedule display.
Display end time: A boolean field to show or hide the end time in the schedule display.
Categories exclude: Allows excluding specific activity categories from the schedule display.
Filter: Allows filtering content by category, class name, or instructor name.
Templates
branches-list.html.twig: Template for displaying a list of branches with links to their respective schedules.
block--lb-simple-schedule.html.twig: Template for rendering the Simple Schedule block.
Additional Information
For installation instructions and usage details, refer to the following resources:
The Y PEF Schedule module provides a calendar functionality for scheduling events.
It includes a Vue.js component, fullcalendar-app, to display and interact with the calendar.
composer require ycloudyusa/y_pef_schedule
drush en y_pef_schedule lb_simple_schedule
Install as you would normally install a contributed Drupal module. For further information, see
Installing Drupal Modules.
Enable the module by navigating to Admin > Extend (/admin/modules) in your Drupal admin interface, then enabling "Y PEF Schedules Admin tool" and "LB Simple Schedule".
Configuration
Configure the calendar settings at Admin > YMCA Website Services > Settings > Schedules calendar settings (/admin/openy/settings/schedules-calendar)
Go to Admin > Content > Schedules Calendar (/admin/openy/branch-schedules) and select a branch.
After choosing a branch, you can view the calendar. The calendar features include:
Viewing events in weekly or daily format.
Viewing the main information of the event (by clicking on the event).
Creating a new event (using the Session Content Type).
Updating existing events.
Downloading the schedule in PDF format.
Filtering results by categories.
Showing the calendar on a page
Once you have added sessions to a calendar, you can add the calendar block to a Layout Builder page to display on the site. Ensure the "LB Simple Schedule" is enabled first.
Edit the Layout of a Layout Builder page (Branch, Landing Page, etc).
Create or find a section, then Add Block.
Choose Add custom/content block then Simple Schedule.
Add a Title and choose a Branch to populate the calendar.
Save the block and the page.
Customization
A few options are available for advanced customization of the calendar.
Retrieving Events
The module provides controllers to handle AJAX requests for fetching events. To create a custom request, use the following route in your JavaScript code:
axios.get('/fullcalendar-api/get-event-data-date-range/{location}/{start}/{end}/{category}').then(response=>{constevents=response.data;// Process the received events as needed
}).catch(error=>{console.error('Errorfetchingevents:',error);});
Replace {location}, {start}, {end}, and {category} with the appropriate values.
Creating Events
The fullcalendar-app component allows users to create events interactively. When a date is clicked, a modal form is displayed for users to enter event details such as title, category, time, and date.
To customize the form or extend the functionality, refer to the
Vue.js component documentation and customize the handleDateClick and createEvent methods in the fullcalendar-app component.
Troubleshooting
Known issues
After creating a series of events, it is created, but only one event is displayed in the calendar, the page must be refreshed to see the correct data
The color is fixed to the session and not to the category
PDF format is A3
4.35.3 - Traction Rec Integration
Instructions for configuring and importing data from Traction Rec into the Program Event Framework.
The
Traction Rec Integration module (ycloudyusa/openy_traction_rec) facilitates data synchronization between Traction Rec and the Program Event Framework (PEF). This integration allows you to import program and event data from Traction Rec into your Drupal website.
Create a new private key and X509 certificate, customizing the subj options in the command to suit your organization. (See
the manual for openssl-req to understand the options here.)
The email address in the certificate does not need to match the email on the Connected App.
The certificate must be renewed yearly (or after the set number of --days). We recommend you set a reminder in order to prevent unwanted failures.
In Salesforce > Setup > App Manager, create a New Connected App.
Set a Name and Email.
The Contact Email is not used for authentication.
Check Enable OAuth Settings
Set the callback url as the base URL of your site
Check Use digital signatures and upload the X509 certificate (.crt) created above.
Ensure the app has the following Selected OAuth Scopes
Full access (full)
Manage user data via APIs (api)
Manage user data via Web browsers (web)
Perform requests at any time (refresh_token, offline_access)
Check these options:
Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows
Issue JSON Web Token (JWT)-based access tokens for named users
Uncheck all other options in the OAuth section.
Save the Connected App
Once the app is saved, you will need to get the Consumer Details:
In the "My Connected App" screen that appears once you save (or via Setup > App Manager), click Manage Consumer Details.
Save the Consumer Key and Consumer Secret for the next step.
Create a Profile OR Permission Set to assign permissions to your app. We recommend using a Permission Set as those are the option recommended by Salesforce.
Your Traction Rec support team should be able to deploy the Traction Rec Activity Finder Permission Set from their dev1 instance. If this Permission Set is deployed, proceed straight to the User creation step. To create a Permission Set from scratch:
Setup > Users > Permission Sets > New
Fill in the Label as you wish, and leave License as --None--
In the new Permission Set, open Object Settings.
In the very long list of Object Settings, do the following for each of the 10
Objects listed below:
Find the object and click to open it. In the configuration screen for each Object:
Under Object Permissions, mark Read as Enabled.
Under Field Permissions, mark Read Access on the header field to provide access to all fields.
Save the Object Settings and search for the next one.
Finally, review the summary of access permissions and ensure Read access is provided for each of the necessary objects.
Create a Profile:
You must do this before creating a user.
Setup > Users > Profiles > New
When asked what Existing Profile to clone from, select Standard User or Standard Platform User. Be sure to note the User License connected to the target profile.
In the very large configuration screen, click Edit, then:
Under Connected App Access, add access to the Connected App you created above.
Create a new User with the new Profile or Permission Set:
Setup > Users > New User
User License - The option under which you created the Profile in the previous step, or Salesforce.
Email - A working email that you will use to receive login verifications.
Username - This is not your email and must be unique across all Salesforce Organizations. This is the name that will be used in the Drupal connection below. If you enter a preexisting username, you will receive this error:
> Error: Duplicate Username.
> The username already exists in this or another Salesforce organization. Usernames must be unique across all Salesforce organizations. To resolve, use a different username (it doesn't need to match the user's email address).
Assign the User to the Profile you created above, or a Permission Set that has the
necessary permissions.
Under Permission Set Assignments, click Edit Assignments
Find the Permission Set you created in the prior step, select it, click Add, then Save.
Confirm your Connected App, Profile, and User are connected:
Go to Setup > Apps > Connected Apps > Manage Connected Apps and choose your new app. Assign the Profile or Permission Set that contains your new user if it does not already show under the relevant section.
Click Manage Profiles or Manage Permission Sets
Search for your Profile or Permission Set and Save.
In the Connect App Detail, click Edit Policies:
Under OAuth Policies > Permitted Users choose Admin approved users are pre-authorized.
Check Issue JSON Web Token (JWT)-based access tokens.
Save the Connected App details.
When the process is complete, you should have the following relationships between the User, Permission Set OR Profile, and Connected App:
the API User should be assigned the Permission Set OR Profile.
the Connected App should be assigned the same Permission Set OR Profile.
Review all of these steps carefully. Missing any of them can result in an inability to query the API.
Salesforce permissions
The Salesforce integration Permission Set OR Profile should have read access to all fields in the following objects:
Course Options
Courses
Course Session Options
Course Sessions
Locations
Products and Discounts
Program Categories
Program Category Tags
Programs
Sessions
If using a Profile, it should also have the following Systems Permissions:
Apex REST Services
View Restriction and Scoping Rules
Update Consent Preferences Using REST API
Configure the connection in Drupal
Go to Admin > Configuration > System > Keys (/admin/config/system/keys) and create a new key to store the private key created above.
Add key
Add a Key name and Description
Choose Key Type: "TractionRec JWT Private Key"
Choose the Key provider depending on your configuration. See
Managing Keys for details.
Configure the chosen provider then Save the key.
Go to Admin > YMCA Website Services > Integrations > Traction Rec > Traction Rec auth settings (/admin/openy/integrations/traction-rec/auth) to configure the keys & secrets provided by Traction Rec.
Add the Consumer key and Consumer Secret from Manage Consumer Details in Salesforce.
Add the User connected to the Connected App.
This is the Username of the User, not the Contact email.
Enter a Login URL.
This will most likely be https://login.salesforce.com
Set the Services base URL and REST API Base URL as per their descriptions.
Ensure the REST API Base URL responds to curl -I with a 200 response. Replace URLs like *.lightning.force.com with *.my.salesforce.com because the lightning url may result in a redirect, which will cause an authentication error, like ([@"message":"Session expired or invalid","errorCode":"INVALID_SESSION_ID"]).
Set the Community URL based on the publicly accessible registration links.
This may be something like https://my-ymca.my.site.com
The URL can be found in Salesforce under Setup > Digital Experiences > All Sites.
Maps to both Activities and Classes. Since TREC does not have this distinction, information in the resulting Activities and Classes in Drupal is duplicated.
locations.json - from Locations
This file is unused, but Locations map to Location via the Session import.
program_categories.json - from Program Category Tags
Maps to Program.
programs.json - from Programs
Maps to Program Subcategory.
sessions.json - from Course Options
Maps to Session.
Note: Traction Rec's labels for "Programs" and their child groupings are different:
Traction Rec: "Program Category" is the parent of "Program".
Drupal: "Program" is the parent of "Program Subcategory".
Mapping to Drupal fields
Those files are then imported into Drupal content via
importers (in config items that start with migrate_plus.). The import goes as follows:
> - Drupal Content Type (bundle)
> - Salesforce/TractionRec source field → Drupal destination field
Program - from programs.json / TREC Program Categories
Id → id
Name → Title
Available → Published (status)
Program Subcategory - from program_categories.json/ TREC Programs
Id → id
Name → Title
Program → Program (field_category_program) via a lookup to the Programs import
Available → Published (status)
Activity - from classes.json / TREC Courses
Id → id
Name → Title
Program/Id → Program Subcategory (field_activity_category) via a lookup to the Program Subcategory import
Available → Published (status)
Class - from classes.json / TREC Courses
Id → id
The Class Id will also be used to set the Activity (field_class_activity)
If a Rich Description is set, it will be used, otherwise the Description field will be used.
Available → Published (status)
Session - from sessions.json / TREC Sessions
Course_Option/Name → Title
Course_Option/ID → id
Also used to generate the Registration link URL using the Community URL set in Traction Rec auth settings (/admin/openy/integrations/traction-rec/auth).
Location ID is used to attempt to match a location in the Location mapping in the Traction Rec importer settings (/admin/openy/integrations/traction-rec/importer)
Course_Option/Instructor → Instructor (field_session_instructor) trimmed to 255 characters
Course_Session/Id → Class (field_session_class) via a lookup to the Class import
Data Model
This module assumes a Traction Rec "standard" data model in its queries. Any deviations from this model will require overriding the queries in src/TractionRec.php.
This model contains a subset of the fields in Traction Rec that are relevant to our usage. All entities have more fields than listed.
Field types are taken from Salesforce's Setup > Object Manager > {Entity} > Fields & Relationships.
Number field options are: number(length_decimal places)
erDiagram
Program_Category__c {
id Id
text(80) Name
}
Program__c {
id Id
text(80) Name
checkbox Available__c
textArea(255) Description__c
}
Program_Category_Tag__c {
id Id
autoNumber Name
lookup(Program) Program__c
lookup(Program_Category) Program_Category_c
}
Course__c {
id Id
text(80) Name
checkbox Available__c
text(128) Code__c
longTextArea(640) Description__c
lookup(Program) Program__c
richTextArea Rich_Description__c
}
Course_Session__c {
id Id
text(80) Name
checkbox Available__C
text(128) Code__c
lookup(Course) Course__c
longTextArea(640) Description__c
number(18_0) Num_Option_Entitlements__c
lookup(ProductAndDiscount) Product__C
richTextArea Rich_Description__c
sum Total_Option_Capacity__c
formula(number) Total_Option_Capacity_Remaining__C
sum Total_Option_Registrants__c
count Total_Options_Available__c
}
Course_Option__c {
id Id
text(80) Name
number(3_1) Age_Max__c
number(3_1) Age_Min__c
checkbox Available__c
number(18_0) Capacity__c
picklist(multiSelect) Day_of_Week__c
date End_Date__c
text(8) End_Time__c
text(128) Instructor__c
lookup(ProductAndDiscount) Product__c
number(18_0) Registration_Total_c
longTextArea(3500) Setup_Notes__c
number(3_0) Setup_Time_Required___c
date Start_Date__c
text(8) Start_Time__c
longTextArea(3500) Tear_Down_Notes__c
number(3_0) Tear_Down_Time_Required__C
}
Course_Session_Option__c {
id Id
autoNumber Name
lookup(CourseOption) Course_Option__c
masterDetail(CourseSession) Course_Session__c
checkbox Option_Available__c
number(18_0) Option_Capacity__c
number(18_0) Option_Registration_Total__c
}
Program_Category__c ||--|{ Program_Category_Tag__c : ""
Program__c ||--|{ Program_Category_Tag__c : ""
Program__c ||--|{ Course__c : ""
Course__c ||--|{ Course_Session__c : ""
Course_Session__c ||--|{ Course_Session_Option__c : ""
Course_Option__c ||--|{ Course_Session_Option__c : ""
The YMCA Website Services Core Team adheres to the same standards set for the community across all development areas and technologies, as outlined in the YMCA Website Services documentation.
The YMCA Website Services Core Team reserves the right to deviate from these standards only in the following situations:
Emergency: A critical defect or security vulnerability requiring immediate and drastic measures for resolution.
When standards are not met, the YMCA Website Services Core Team is responsible for explaining the reasons behind the deviation and defining the updated standards moving forward.
This explanation will be communicated via the YMCA Website Services message board, Slack, and the documentation on GitHub, reflecting the new standards.
Requirements for Pull Requests
Code in Pull Requests must adhere to our established
best practices.
Submitters’ profiles on GitHub or Drupal.org should include a name and organization.
Pull Request Template
To ensure high-quality Pull Requests, a
PR template is automatically applied to new Pull Requests on GitHub.
The template includes the following requirements:
Issue Link: A link to the original issue addressed by the PR.
Coding Standards: Confirmation that all coding styles are followed, and no issues are reported by CodeSniffer. Refer to the
Code of Conduct.
Documentation Updates: Verification that
documentation has been updated to reflect the PR changes.
Review Steps: Detailed
steps for review based on the PR changes.
Upgrade Path Support: Inclusion of all necessary hook_update_N functions to
support the upgrade path.
Drupal.org Email Association: Confirmation that your Git email is associated with a Drupal.org account to ensure commit attribution.
Drupal.org Credits: If you want credits on drupal.org, consult the
documentation.
4.37 - Release processes
Repositories Involved in Releases
The following repositories are involved in the release process for YMCA Website Services:
YMCA Website Services Drupal Profile Distribution:YCloudYUSA/yusaopeny - This repository contains the core Drupal profile distribution for YMCA Website Services.
YMCA Website Services Project:YCloudYUSA/yusaopeny-project - This repository is used to initiate a new YMCA Website Services instance. It typically includes the composer.json file and installation scripts.
Continuous Integration/DevOps for YMCA Website Services:YCloudYUSA/yusaopeny-cibox-build - This repository manages the CI/CD processes for rebuilding and installing YMCA Website Services.
CIBox Development Environment:YCloudYUSA/yusaopeny-cibox-vm - This repository contains the configuration for the CIBox development environment, which uses Virtualbox, Docker, and Vagrant.
Docksal Development Environment:YCloudYUSA/yusaopeny-docksal - This repository provides a Docksal-based development environment using Docker and VirtualBox.
Release Management Process
The Lead Architect follows these steps when tagging a new release of YMCA Website Services:
Update the Project Repository: Review, merge, and update the
YCloudYUSA/yusaopeny-project repository. This usually involves updating the composer.json file or the one-line installation script. Tag a new release in this repository.
Review and Merge Pull Requests: Review and merge all pull requests in the
YCloudYUSA/yusaopeny repository that are planned for the release.
Update the Distribution Version: Change the YMCA Website Services version in the openy.info.yml file located in the yusaopeny repository. The file path is
openy.info.yml.
Update Module Versions: If there were changes to major modules (e.g., Activity Finder, PEF), update the YMCA Website Services version in those modules as well.
Create Changelog Release Notes: Create a draft changelog with release notes. Include a list of contributors and major issues fixed or introduced in the release.
Regression Testing: Spin up a copy of an YMCA Website Services site and check top-priority functionality for regressions.
Core Team Review and Approval: Send the release candidate to the Core Team for review and get their approval.
Update Development Version: After approval, change the YMCA Website Services version in
openy.info.yml to the next version with the -dev suffix for developers.
Refresh Private Mirror: Refresh the YMCA Website Services private mirror on the openy.cibox.tools CI server.
Verify Version in Site Info: Ensure the version of YMCA Website Services is correct in the site information page (admin/reports/status).
Announce Release - Developers: Publish an announcement in the #developers YMCA Website Services Slack channel.
Announce Release - General: Publish an announcement in the #general YMCA Website Services Slack channel.
4.38 - Release Schedule and Guidelines
YMCA Website Services Release Guidelines
YMCA Website Services releases major releases of the base project
YMCA Website Services and
Virtual Y quarterly. Minor releases and sub-project releases occur as needed. These releases impact the base theme openy_lily and modules like ws_small_y.
Major Releases (Quarterly)
Major releases are scheduled for the second Tuesday of the second month of each quarter (February, May, August, November). They are numbered 2.x and may consist of:
This document is archived but may contain useful information for troubleshooting future updates. For updated update steps, visit
How to upgrade YMCA Website Services.
To update your OpenY site with the security fix from Drupal core
SA-CORE-2018-002, the OpenY team suggests two options: applying a patch or upgrading Drupal core (or upgrading OpenY). While a Drupal core or OpenY upgrade isn’t always immediately feasible, security issues should be addressed as soon as possible. Therefore, consider applying the patch and planning an OpenY upgrade for later.
How to Apply the Patch
Before you begin, it is crucial to identify the OpenY release version you are using. This will determine the correct patch to apply. You can find your OpenY version in the openy.info.yml file located in the root of your OpenY installation (e.g., /docroot/profiles/contrib/yusaopeny/openy.info.yml). The version key in that file indicates your OpenY version.
For older OpenY releases, it’s highly recommended to upgrade to the latest version of OpenY or at least to a version between 8.1.1 and 8.1.6 (Drupal core 8.3.x) and then upgrade Drupal core to 8.3.9 (
Drupal 8.3.9 Release Notes). If an immediate upgrade isn’t possible, follow these steps:
Log in to your production server: Access your server environment via SSH and locate the docroot folder of your site’s codebase. If you followed an OpenY installation tutorial, you should:
ssh -l root YOUR_SERVER_DOMAIN_NAME
cd /var/www/html
wget https://raw.githubusercontent.com/YCloudYUSA/yusaopeny-project/8.1.x/scripts/patches/8.2.x.patch
Back up the file to be patched: Before applying the patch, create a backup of DrupalKernel.php:
Apply the patch: If the dry run was successful, apply the patch with the following command:
patch -p1 < 8.2.x.patch
You should see the same output as the dry run, indicating that your site is now patched.
If the patch fails with an error message like “Hunk #1 FAILED at 123”, this means the file has been modified since the patch was created. You will need to manually resolve the conflicts or revert to a clean version of the file before applying the patch.
Common causes for patch failures include:
The file has been previously patched with a different patch.
The file has been customized or modified.
The patch is for a different version of Drupal core.
If you encounter issues, consult the Drupal documentation on patching or seek assistance from the OpenY community.
After successfully applying the patch, clear the Drupal cache to ensure the changes take effect:
drush cr
Tip: If you’re using a Git repository for your site, run the following commands to commit and push the patched core:
For these OpenY releases, upgrading to the latest version or at least to one of the 8.1.7-8.1.10 releases (Drupal core 8.4.x) with a Drupal core upgrade to 8.4.6 (
Drupal 8.4.6 Release Notes) is highly recommended. If that is not currently possible, follow these steps:
Log in to your production server: Access your server environment via SSH and locate the docroot folder of your site’s codebase. If you followed an OpenY installation tutorial, you should:
ssh -l root YOUR_SERVER_DOMAIN_NAME
cd /var/www/html
wget https://raw.githubusercontent.com/YCloudYUSA/yusaopeny-project/8.1.x/scripts/patches/8.3.x.patch
Back up the file to be patched: Before applying the patch, create a backup of DrupalKernel.php:
For these OpenY releases, it is highly recommended to upgrade to the latest version (8.1.10 or later) or at least to version 8.1.10 (Drupal core 8.4.x) with a Drupal core upgrade to 8.4.6 (
Drupal 8.4.6 Release Notes). If that is not currently possible, follow these steps:
Log in to your production server: Access your server environment via SSH and locate the docroot folder of your site’s codebase. If you followed an OpenY installation tutorial, you should:
ssh -l root YOUR_SERVER_DOMAIN_NAME
cd /var/www/html
wget https://raw.githubusercontent.com/YCloudYUSA/yusaopeny-project/8.1.x/scripts/patches/8.4.x.patch
Back up the file to be patched: Before applying the patch, create a backup of DrupalKernel.php:
to store your patched core into your own repository.
==========================
How to Patch Your DigitalOcean OpenY Install
If you followed a tutorial to install OpenY on DigitalOcean, your OpenY installation should be located in a predictable folder. This section provides a simplified method for patching your OpenY site, designed for users who are not technical experts.
Log in to your site: Log in to your site’s administrative interface as an administrator by visiting the /user/login URL.
Check Drupal Version: Go to /admin/reports/status after login and search for Drupal Version string. It should be something like 8.2.x, 8.3.x or 8.4.x (x - some number too, like 8.4.2, for example). Based on your finding follow the steps below to your version
Access the DigitalOcean Console: Log in to your DigitalOcean cloud console at digitalocean.com and find “Access Console” in the dropdown menu for the droplet you’re using for OpenY.
Log in to the Console: A popup window with a black screen will appear, prompting you for login credentials. Use root as the username and the password generated for you when the droplet was created.
Run the Patch Script: After logging in to the console, run the command corresponding to your Drupal core version.
One-Line Script to Patch 8.2.x Drupal Core for OpenY
YMCA Website Services Sandboxes for Evaluation and QA
The YMCA Website Services core team manages sandboxes for various configurations of the distribution. These sandboxes facilitate evaluation, assist with QA, and enable investigation of issues.
To test the content editor experience or explore the Drupal configuration, request login access by
emailing us or contacting a project team member on the Y-USA Slack. Please include the specific sandbox you need access to and a brief explanation of your testing goals.
Stable sandboxes are based on the latest
stable release of YMCA Website Services. They rebuild completely overnight and clear their database and files every 2 hours. This ensures a clean testing environment.
These sandboxes are based on the
latest development version of YMCA Website Services or other branches as necessary. They rebuild daily but are not guaranteed. If one isn’t working, try another.
These sandboxes use the YMCA Website Services stable Standard profile and the
Virtual Experience Platform (aka “Virtual Y”, aka “Open Y Gated Content”) project.
This article primarily applies to long-term users of YMCA Website Services. YMCA Website Services supports Composer 2 as of version 8.2.7, released in November 2020. New installations of YMCA Website Services use Composer 2 by default. You can find the release notes
here.
Composer was upgraded to version 2.x on October 30, 2020. An older Composer version (1.x) might accidentally auto-update to version 2.x, potentially causing instability. Issues might include Composer failing to run commands, which would block OpenY upgrades or maintenance. This instability would occur in the developer environment, not within YMCA Website Services or Drupal itself.
The YMCA Website Services team prepared an avoidance plan for the community to take action before the release, while YMCA Website Services verified that Composer 2.x caused no issues or regressions.
If you use Docksal or Vagrant local environments, your Composer version will not update automatically, so you are currently safe from inadvertent updates. Instructions for updating these environments will be included with any necessary YMCA Website Services updates at a later date.
If you are on Composer 1.x before October 30, 2020
With Composer 2 on the horizon, older versions of Composer 1.x may display the following message:
Composer 2.0 is about to be released and the older 1.x releases will self-update directly to it once it is released. To avoid surprises update now to the latest 1.x version
If you see this message, ensure your environments have updated Composer to the latest 1.x version by running:
composer selfupdate --1
To verify that the command updated to version 1.x, check the Composer version:
composer --version
You should see output similar to the following:
MacBook-Pro-Andrii:www podarok$ composer --version
Composer version 1.10.15 2020-10-13 15:59:09
If you accidentally upgrade to Composer 2.x before upgrading to the latest 1.x version (before October 30, 2020)
If Composer has updated to version 2 and you are experiencing issues, downgrade Composer to the latest 1.x version by running:
composer selfupdate --1
If you encounter any issues, connect with the YMCA Website Services team on GitHub (
create issue) or the #developers channel on
Slack.
4.42 - Server Requirements
If you need to prepare a server for the YMCA Website Services instance, the information below outlines the necessary software and configurations.
Requirements
Operating System: Ubuntu LTS (Long Term Support) versions 14 or 16 are preferred. CentOS is also acceptable. Other Linux distributions may work, but have not been fully tested by the YMCA Website Services team.
Drupal 8/9/10 Requirements: Meet the server requirements specified by Drupal.
PHP: PHP 7.4 or higher is strongly recommended for performance and security reasons. Refer to the specific Drupal version’s documentation for supported PHP versions.
PHP Modules
The following PHP modules are required:
php
php-cli
php-common
php-curl
php-fpm
php-gd
php-mysql or php-pgsql (depending on your database)
php-intl
php-mbstring
php-xml
php-zip
php-opcache (recommended)
imagick (recommended for image processing)
memcached or redis (for caching)
Note: Replace php with the specific PHP version (e.g., php7.4, php8.1). Use your system’s package manager (e.g., apt, yum) to install these modules.
Database Server: MySQL 5.7+ or MariaDB 10.3+ are recommended. PostgreSQL is also supported. Optimized MySQL settings can be found at
cibox/cibox. Note that these settings may need adjustments based on your specific server resources and workload.
Web Server: Apache 2 with mod_php (known for stability) or Nginx with php-fpm (better for speed and scalability)
Apache: libapache2-mod-php
Nginx: Requires configuration to proxy PHP requests to php-fpm.
Caching (Optional but Recommended):
Memcached server
Redis server
Server Tools (Optional):
Ansible (for provisioning and configuration management)
Docker (for containerization)
SOLR 4.x or higher (for advanced search functionality)
Varnish (for HTTP caching and acceleration)
Note: Ensure that your firewall is properly configured and only necessary ports are open for security reasons. Regularly update your server software to patch security vulnerabilities.
4.43 - Smoke Tests Index
Smoke Tests Overview
Smoke tests are a type of software testing that verifies the most important functions of a system are working. The purpose is to ensure that the application is stable enough for further testing. The following links provide access to smoke tests for various components of the YMCA Website Services platform.
Here you can find instructions on how you can start a project based on the YMCA Website Services distribution.
New project from scratch based on YMCA Website Services
To start a new project from scratch, you can use the
installation instructions. These instructions will guide you through building your project and even setting up a development environment.
Add YMCA Website Services to an existing Drupal 10 project
To add YMCA Website Services to an existing Drupal 10 project, you’ll need to modify your composer.json file. Here’s a step-by-step guide:
Please take a look at the full composer.json file below that you should eventually get.
Example composer.json (Drupal 10 + YMCA Website Services)
{"name":"drupal/drupal","description":"Drupal is an open source content management platform powering millions of websites and applications.","type":"project","license":"GPL-2.0+","require":{"composer/installers":"^1.9","wikimedia/composer-merge-plugin":"~2.0","YCloudYUSA/yusaopeny":"2.0.*","cweagans/composer-patches":"^1.7"},"minimum-stability":"dev","prefer-stable":true,"config":{"preferred-install":"dist","sort-packages":true,"platform-check":false},"extra":{"drupal-scaffold":{"locations":{"web-root":"docroot/"}},"installer-types":["drupal-module","drupal-theme","drupal-profile","drupal-drush","drupal-library","drupal-core"],"installer-paths":{"docroot/core":["type:drupal-core"],"docroot/libraries/{$name}":["type:drupal-library"],"docroot/modules/contrib/{$name}":["type:drupal-module"],"docroot/profiles/contrib/{$name}":["type:drupal-profile"],"docroot/themes/contrib/{$name}":["type:drupal-theme"],"docroot/drush/contrib/{$name}":["type:drupal-drush"],"docroot/modules/custom/{$name}":["type:drupal-custom-module"],"docroot/themes/custom/{$name}":["type:drupal-custom-theme"]},"enable-patching":true,"patchLevel":{"drupal/core":"-p2"}},"autoload":{"classmap":["scripts/composer/ScriptHandler.php"],"files":["docroot/core/includes/bootstrap.inc"]},"scripts":{"drupal-scaffold":"DrupalComposer\\DrupalScaffold::scaffold","pre-install-cmd":["DrupalComposer\\DrupalScaffold::preInstallCmd"],"pre-update-cmd":["DrupalComposer\\DrupalScaffold::preUpdateCmd"],"post-install-cmd":["DrupalComposer\\DrupalScaffold::postInstallCmd","DrupalComposer\\DrupalScaffold::createRequiredFiles","DrupalComposer\\DrupalScaffold::removePatchesDir","DrupalComposer\\DrupalScaffold::removeVendorGitFolders"],"post-update-cmd":["DrupalComposer\\DrupalScaffold::postUpdateCmd","DrupalComposer\\DrupalScaffold::createRequiredFiles","DrupalComposer\\DrupalScaffold::removePatchesDir","DrupalComposer\\DrupalScaffold::removeVendorGitFolders"],"post-create-project-cmd":["DrupalComposer\\DrupalScaffold::postCreateProjectCmd","DrupalComposer\\DrupalScaffold::removePatchesDir","DrupalComposer\\DrupalScaffold::removeVendorGitFolders"],"remove-vendor-git-folders":["bash scripts/remove_vendor_git_folders.sh || :"]},"repositories":[{"type":"composer","url":"https://packages.drupal.org/10"},{"type":"package","package":{"name":"library-kenwheeler/slick","version":"1.8.1","type":"drupal-library","source":{"url":"https://github.com/kenwheeler/slick","type":"git","reference":"1.8.1"}}},{"type":"package","package":{"name":"library-dinbror/blazy","version":"1.10.3","type":"drupal-library","source":{"url":"https://github.com/dinbror/blazy","type":"git","reference":"v1.10.3"}}},{"type":"package","package":{"name":"library-gdsmith/jquery.easing","version":"1.4.1","type":"drupal-library","source":{"url":"https://github.com/gdsmith/jquery.easing","type":"git","reference":"1.4.1"}}},{"type":"package","package":{"name":"library-enyo/dropzone","version":"5.7.6","type":"drupal-library","source":{"url":"https://github.com/enyo/dropzone","type":"git","reference":"v5.7.6"}}},{"type":"package","package":{"name":"library-jaypan/jquery_colorpicker","version":"1.0.1","type":"drupal-library","source":{"url":"https://github.com/jaypan/jquery_colorpicker","type":"git","reference":"da978ae124c57817021b3166a31881876882f5f9"}}},{"type":"package","package":{"name":"library-ckeditor/panelbutton","version":"4.7.0","type":"drupal-library","dist":{"url":"http://download.ckeditor.com/panelbutton/releases/panelbutton_4.7.0.zip","type":"zip"}}},{"type":"package","package":{"name":"library-ckeditor/colorbutton","version":"4.7.0","type":"drupal-library","dist":{"url":"http://download.ckeditor.com/colorbutton/releases/colorbutton_4.7.0.zip","type":"zip"}}},{"type":"package","package":{"name":"library-ckeditor/colordialog","version":"4.7.0","type":"drupal-library","dist":{"url":"http://download.ckeditor.com/colordialog/releases/colordialog_4.7.0.zip","type":"zip"}}},{"type":"package","package":{"name":"library-ckeditor/glyphicons","version":"2.2","type":"drupal-library","dist":{"url":"http://download.ckeditor.com/glyphicons/releases/glyphicons_2.2.zip","type":"zip"}}}]}
Add YMCA Website Services as a dependency:
Add "YCloudYUSA/yusaopeny": "2.0.*" to the require section of your composer.json. This line specifies that you want to include the YMCA Website Services package, version 2.x, in your project. See
example.
Add required repositories:
Add all the necessary repositories, as
listed here, to your composer.json. These repositories provide information about where to find the required libraries and packages.
Configure installer paths:
Add the installer paths configuration to your composer.json. This configuration tells Composer where to place different types of packages (modules, themes, etc.) within your Drupal installation. See
example.
If your composer.json is located inside the docroot directory, use the following:
Add "cweagans/composer-patches": "^1.7" to the require section of your composer.json. This allows you to apply patches to contributed modules and themes. See
example.
Enable patching in extra section:
Add "enable-patching": true to the extra section in your composer.json. See
example.
Disable Secure HTTP:
Add "secure-http": false to the config section in your composer.json. See
example.
Clean up:
Remove the composer.lock file and the vendor directory from your project if they exist. This ensures that you’re starting with a clean slate and that Composer will resolve all dependencies correctly.
Remove “replace” section:
Remove the "replace" section from your composer.json file. This section is not typically needed and can sometimes cause conflicts.
(Optional) Clean up vendor Git folders:
If you keep the vendor directory in your Git repository, it’s recommended to remove the .git folders inside modules and libraries. To do this:
Run composer install to install the YMCA Website Services and its dependencies. This command reads your composer.json file and downloads the specified packages into the vendor directory.
CIBox
In this section you can learn how to configure development environment and CI server using Open Source product
CIBox.
Open link(e.g. http://IP/core/install.php) from console output and finish YMCA Website Services installation
Video tutorial
End to end installation
4.45 - technology pipeline
To deliver the best technologies for the YMCA movement, the YMCA Website Services development community maintains the following documents and best practices. This pipeline outlines the standards, processes, and resources used to develop and maintain the YMCA Website Services platform.
A Slack Team
by invite with a #developers channel where we discuss technical issues with our partners and YUSA. Request an invitation to join the Slack team for real-time collaboration and discussions.
A list of
3rd party dependencies which are reviewed periodically for new features and deprecations. - Regularly reviewed for updates, security vulnerabilities, and compatibility.
4.46 - Terms and Conditions
These Terms & Conditions must be agreed to upon installing YMCA Website Services
These terms are maintained in
the distribution codebase at TermsOfUseForm.php and are subject to change at any time. Any change in the terms will require site owners to agree to the new terms and a record of the date of agreement is maintained in the site database. Terms can be viewed on your site at Admin > YMCA Website Services > Terms and Conditions (/admin/openy/terms-and-conditions).
YMCA of the USA supports the Website Services platform with respect to use by its Member Associations but is not responsible for and does not control the services provided by 3rd party agencies, which are using and modifying YMCA Website Service distribution.
YMCA of the USA recommends that each participating YMCA association develop and implement its own cybersecurity policies and obtain cyber liability and data privacy insurance.
I acknowledge that YMCA Website Service is open source content and that all content is provided “as is” without any warranty of any kind. YMCA of the USA makes no warranty that its services will meet your requirements, be safe, secure, uninterrupted, timely, accurate, or error-free, or that your information will be secure. YMCA of the USA will not maintain and support YMCA Website Service templates indefinitely. The entire risk as to the quality and performance of the content is with you.
YMCA of the USA recommends obtaining a reputable agency to assist with the implementation of the YMCA Website Service platform and further development for your specific needs.
All demonstration content, including but not limited to text, images, graphics, videos, audio, and any other materials displayed on this website, is the exclusive property of YMCA of the USA. The demonstration content is provided solely for illustrative purposes and to showcase the capabilities of YMCA’s Website Service. Nonetheless, YMCA member associations may use demonstration content for their websites, as applicable.
By accessing and/or using this website, you agree to respect the ownership and intellectual property rights of YMCA of the USA over the demonstration content. Users and visitors are strictly prohibited from reproducing, distributing, modifying, or otherwise using the demonstration content without explicit written permission from YMCA of the USA.
Any unauthorized use or misuse of the demonstration content is a violation of these Terms and Conditions and may be subject to applicable laws and regulations, result in your access being revoked, and/or legal action taken, if applicable.
YMCA of the USA reserves the right to change, modify, or remove the demonstration content from the website at any time without prior notice. We are not responsible for any inaccuracies or errors in the demonstration content and make no guarantees about its accuracy or completeness.
4.47 - Testing YMCA Website Services for PHP 7.4 version support
Requirements
php-cli 7.4 ( memory_limit value should be large (2000M) or unlimited (-1) in order to not fail)
Composer 2
Steps
Obtain the latest development code of YMCA Website Services.
cd profiles/contrib/openy
sh runtests.sh --tags run_selenium
Open the installed VNC Viewer and connect to the server with IP 192.168.56.132:5901.
Password: secret
Run the tests. You should see everything performed by the Behat tests in the VNC client.
bin/behat
Custom Behat Functionality
Create entities in table forms, with a key to use for reference and reference entities by key.
KEY is optional and must be all CAPS.
Taxonomy
Given I create "taxonomy_term" of type "color" with key for reference:
| KEY | name | field_color | | Blue | Blue | 0000FF | | Red | Red | FF0000 |
Paragraphs
Given I create "paragraph" of type "small_banner" with key for reference:
| KEY | field_prgf_headline | field_prgf_color | | banner1 | Headline 1 | Blue | | banner2 | Headline 2 | Red |
Media entities
Given I create "media" of type "image" with key for reference:
| KEY | name | file | | gallery_1 | Gallery image 1 | gallery.png | | gallery_2 | Gallery image 2 | gallery2.png | | gallery_3 | Gallery image 3 | gallery3.png |
Create nodes in table forms, with a key to use for reference and reference entities by key.
KEY is optional and must be all CAPS.
Basic create
Given I create "landing_page" content:
| KEY | title | field_lp_layout | field_content | | landing_1 | Test Landing 01 | one_column | banner1 | | landing_2 | Test Landing 02 | one_column | banner2 |
Vertical field table
Given I create large "landing_page" content:
| KEY | landing_3 | landing_4 | | title | Test Landing 03 | Test Landing 04 | | field_lp_layout | one_column | one_column | | field_content | banner1 | banner2 |
Create & view immediately
Given I view a "landing_page" content:
| KEY | landing_5 | | title | Test Landing 05 | | field_lp_layout | one_column | | field_content | banner1 |
Multiple referenced entities by key on a field.
Given I create "landing_page" content:
| KEY | title | field_lp_layout | field_content | | landing_6 | Test Landing 06 | one_column | banner1, banner2 |
Example Address and Latitude + Longitude
Fields with subfields/columns: The machine name and columns can be found in the form markup in the field name property.
The first portion, field_location_address, represents the Drupal field machine name, while the second array key, address_line1, represents the column.
Add Address
Given I view a "branch" content:
| title | Branch Example | | field_location_address:country_code | US | | :address_line1 | Main road 10 | | :locality | Seattle | | :administrative_area | WA | | :postal_code | 98101 |
Add Latitude and Longitude
Given I view a "branch" content:
| title | Branch Example 2 | | field_location_coordinates:lat | 47.293433 | | :lng | -122.238717 | | field_location_phone | +1234567890 |
4.49 - Theming and Design
Welcome to YMCA Website Services Theming and Design documentation.
How to Change Styles on a Content Type Level
Given:
As a YMCA Website Services site developer, I want to be able to easily change the CSS for a Camp page independently from a Location page, so I can better customize the site to meet the needs of my customers.
How to:
Enable Custom CSS: Navigate to the theme configuration page and check “Enable or disable custom CSS” within the “Custom CSS” section.
Input CSS Code: Enter your custom CSS code into the provided textarea.
To target CSS changes to specific pages, use the following selectors:
.page-node-type-{node-type} - Targets pages based on their content type. For example, .page-node-type-camp would apply styles only to Camp pages.
.node-id-{node-ID} - Targets a specific page based on its node ID. For example, .node-id-123 would apply styles only to the page with a node ID of 123.
.path-frontpage - Targets the site’s front page.
Here’s a list of existing node types in the YMCA Website Services distribution:
activity
alert
blog
branch
camp
class
facility
landing-page
membership
news
program
program-subcategory
session
Example:
To change the background color of all Camp pages to light blue, you would add the following CSS to the Custom CSS textarea:
.page-node-type-camp{background-color:lightblue;}
Important Considerations:
CSS Specificity: Be aware of CSS specificity when writing your custom styles. More specific selectors will override less specific selectors. You may need to use !important in some cases, but it’s generally best to avoid it if possible by writing more specific selectors.
Theme Updates: Custom CSS is stored in the database. Theme updates will not overwrite your CSS changes.
Performance: While Custom CSS provides flexibility, excessive use of custom CSS can impact site performance. Consider using a child theme for more extensive customizations.
Alternative approach: If you are developing a new module or a small customization, consider using SASS following the info in /docroot/modules/contrib/paragraphs/css/README.md or /docroot/modules/contrib/ws_small_y/README.md.
4.50 - Tour
Using YMCA Website Services Tour Tokens
Some modules offer tour tips. To enhance interactivity, you can add a token that triggers an action (like a click) on a specific selector.
Important: Tours provide users with guided tours of the administrative interface, highlighting elements and explaining key concepts. Users need “Access tour” permission and JavaScript enabled in their browsers to view tours.
Adding a Token
Locate the Tour YAML file: Open the tour’s YAML configuration file within your module.
Edit the Tip: Select the specific tour tip you want to modify. Within the tip’s body, insert the token using the following format: [openy_tour:click:button_name:selector]
Apply the Changes: Implement a hook update for your changes and run drush updb -y in the command line to apply the database updates.
Token Components
[openy_tour:click:button_name:selector]
openy_tour: (Required) This is the base token name.
click: (Required) This is the command to execute. Currently, click is the only supported command, which simulates a user click.
button_name: (Required) The text to display on the button within the tour tip.
selector: (Required) A
jQuery selector that identifies the element to be clicked. Ensure the selector accurately targets the desired element on the page.
This token will render a button with the text “Add content” in the tour tip. When clicked, it will trigger a click event on the element matching the selector .toolbar-icon-node-add.
Important Considerations:
jQuery Selectors: Use precise jQuery selectors to avoid unintended clicks on other elements. Test your selectors thoroughly.
Accessibility: Consider the accessibility implications of automated clicks. Ensure the tour remains navigable and understandable for all users, including those using assistive technologies.
Alternative Creation: Tours can be written as YAML documents or by using the contributed
Tour UI module.
4.51 - Upgrade OpenY 8.1.3 to 8.2.2.1
This document is archived but may contain useful information for troubleshooting future updates. For updated update steps, visit
How to upgrade YMCA Website Services.
These are instructions for upgrading a very old version of YMCA Website Services to the latest version.
Given the fact
Drupal 8.7+ has no support for automatic entity updates ( BaseFieldDefinitions ) we have to upgrade to 8.2.2.1 of OpenY, which is still on Drupal 8.6 Core, and then update to the latest YMCA Website Services version as usual.
Environment
vagrant@vagrant:/var/www/docroot$ uname -a
Linux vagrant 4.15.0-29-generic #31-Ubuntu SMP Tue Jul 17 15:39:52 UTC 2018 x86_64 x86_64 x86_64 GNU/Linuxvagrant@vagrant:/var/www/docroot$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 18.04.1 LTS
Release: 18.04
Codename: bionic
vagrant@vagrant:/var/www/docroot$ php -v
**PHP 7.1.31-1**+ubuntu18.04.1+deb.sury.org+1 (cli)(built: Aug 72019 10:23:12)( NTS )Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies
with Zend OPcache v7.1.31-1+ubuntu18.04.1+deb.sury.org+1, Copyright (c) 1999-2018, by Zend Technologies
with Xdebug v2.7.2, Copyright (c) 2002-2019, by Derick Rethans
vagrant@vagrant:/var/www/docroot$ drush --version
**Drush Version : 8.2.3**
vagrant@vagrant:/var/www/docroot$ composer --version
**Composer version 1.7.2** 2018-08-16 16:57:12
Step-by-step guide for update
Use PHP7.1 for upgrade and install php7.1-mysql php7.1-mcrypt php7.1-cli php7.1-common php7.1-curl php7.1-dev php7.1-fpm php7.1-gd php7.1-mysql php7.1-memcached php7.1-imagic php7.1-xml php7.1-xdebug php7.1-mbstring php7.1-soap php7.1-zip php7.1-xml
Go to the folder of OpenY code tree where docroot folder is contained
drush en openy_upgrade_tool openy_er openy_prgf_loc_finder openy_map openy_data_wrapper openy_loc_branch content_moderation focal_point
drush ev "Drupal::service('module_installer')->install(['openy']);" <- This steps fixes some hidden bug when openy profile removed from core.extension configuration for unknown reason.
Manual step (optional, if you have issues with drush updatedb): Edit all yml files in profiles folder to comment media.type.image , field.field.node.program.field_header_content, field.field.node.branch.field_location_amenities in dependencies sections.
run drush updatedb -y <- this will fail for the first time ( Media not installed yet ), disregard
run drush updatedb -y <- this should run properly.
run drush entup
4.52 - Upgrade path
All changes in configurations should be added to the appropriate hook_update_N function in order to update already existing environments. We suggest using the
Config installer module for working with hook_update_N.
openy.install in profile
In this file, include updates that are related to the distribution in general and don’t fit into any specific feature. Examples include:
Enabling/disabling modules
General configuration changes
openy_*.install in modules
If you are updating a configuration for a specific feature, be sure to place the updates into the appropriate module’s .install file.
Updating specific configuration properties
With the help of the openy_upgrade_tool.param_updater service, you can update only a specific part of a full configuration.
To update a specific property in a configuration:
Go to the module related to the configuration.
Create a new hook_update_N function in the openy_*.install file.
$config variable contains the full path to the configuration file.
views.view.images_library - is the configuration name.
display.default.display_options.pager - is the specific property within the configuration that you want to update. You can target values within nested arrays of variable depth.
Example using openy_block_basic module:
useDrupal\Core\Extension\Extension;/**
* Update description for field and block.
*/functionopeny_block_basic_update_8001(){$config_dir=\Drupal::service('extension.list.module')->getPath('openy_block_basic').'/config/install/';// Update multiple configurations.
$configs=['block_content.type.basic_block'=>['description',],'field.field.block_content.basic_block.field_block_content'=>['description',],];$config_updater=\Drupal::service('openy_upgrade_tool.param_updater');foreach($configsas$config_name=>$params){$config=$config_dir.$config_name.'.yml';foreach($paramsas$param){$config_updater->update($config,$config_name,$param);}}}
Updating entire configurations
To update an entire configuration or multiple configurations from a directory, use the openy_upgrade_tool.importer service.
This document is archived but may contain useful information for troubleshooting future updates. For updated update steps, visit
How to upgrade YMCA Website Services.
Upgrade to old, Open Y 1.x version (tested on upgrading 8.0.2 to 8.1.1.14)
Your own OpenY instance should have a Virtual machine injected into your site codebase. Just find Vagrantfile and proceed with vagrant upaccordingly to the documentation.
Obtain a local copy of your production site
You have to create a local copy of your site locally to be able to proceed with the upgrade.
For that:
Make a backup of your production database and copy it to your local machine.
Make a copy of your production site codebase and copy it to your local machine.
…
Detect the version of your OpenY
Starting from OpenY 1.10 release, you should see the version of OpenY in your site reports dashboard.
For previous versions, the best way to check your version is to analyze the creation date of index.php or README.txt file in the docroot folder of your site and compare it to the release date from
https://github.com/YCloudYUSA/yusaopeny/releases. Your OpenY version should be the one which is older than the creation date of the files.
Run the command with the next never version
In the same folder where your docroot folder is located, run:
mv composer.json composer.json.bak ||truewget https://raw.githubusercontent.com/YCloudYUSA/yusaopeny-project/8.1.x/composer.json
cd docroot/profiles/contrib/openy/
rm -f yparse*
wget https://raw.githubusercontent.com/YCloudYUSA/yusaopeny-project/8.1.x/scripts/yparse.sh
drush cr
sh yparse.sh | xargs drush en -y
cd ../../../../
composer require YCloudYUSA/yusaopeny:NEW_VERSION_HERE --no-update
composer update --prefer-dist --with-dependencies --prefer-stable --update-with-all-dependencies --no-suggest
Update the site
Go to the docroot folder of your codebase and run:
drush updatedb
drush entup
Sometimes, when updatedb fails, it is important to get a stable version of some modules we found causing problems:
Ensure the commands above finished with no error messages. The best way to check it - run them one more time. If the next run shows:
$ drush updatedb
No database updates required [success]$ drush entup
No entity schema updates required [success]
You almost 100% proved the updates were executed correctly.
Check for regressions
…
Backup current state of the updated site
…
Proceed with an update to the next version until succeeded (Start from item 1)
…
4.54 - Upgrade use case from 8.2.2.3 to 8.2.7.3
This document is archived but may contain useful information for troubleshooting future updates. For updated upgrade steps, visit
How to upgrade YMCA Website Services.
Follow these steps to upgrade from version 8.2.2.3 to 8.2.7.3.
Remove the image.style.browser_thumbnail configuration:
drush cdel image.style.browser_thumbnail
Enable the openy_focal_point and media_directories_ui modules.
Run drush updatedb and follow the remaining steps in the
upgrade tutorial.
4.55 - Upgrading from 9.2.11.5 to 10.3
Scenario
A YMCA website is currently running on Y USA Open Y (openy-9.x-2.11.5) using Drupal 9. They want to upgrade to the latest YMCA Website Services distribution (10.3) on Drupal 10.
Upgrade Steps
Note: Before starting, ensure you have a backup of your database and files. It is highly recommended to perform these steps on a staging environment first.
Prepare for Upgrade to WS
Ensure your site is on the latest Y USA Open Y 9.x release (9.2.13.0). This step is crucial for a smooth transition.
Backup: Always back up your site and database before performing any major upgrades.
Testing: Thoroughly test your site after each upgrade step on a staging environment before deploying to production.
Customizations: If you have made significant customizations to your site, consult with a Drupal developer to ensure a smooth upgrade process.
Drush Path: Adjust the ../vendor/drush/drush/drush path if your Drush installation is located elsewhere.
$SITE_URL: Replace $SITE_URL with the actual URL of your site.
Configuration Management: After upgrading, review your site’s configuration and ensure it aligns with the new features and settings in version 10.3.
Module Compatibility: Verify that all contributed modules are compatible with Drupal 10. Update or replace modules as needed.
Theme Compatibility: Ensure your theme is compatible with Drupal 10. You may need to update your theme or switch to a compatible theme.
Clear Caches: After each major step, clear Drupal’s caches to ensure the changes are reflected. Use drush cr or navigate to Configuration > Development > Performance > Clear all caches.
Disclaimer: This use case provides a general outline for upgrading the YMCA Website Services Drupal distribution. Specific steps and commands may vary depending on your site’s configuration and any additional modules or customizations you have installed. Always refer to the official YMCA Website Services documentation and Drupal.org for the most up-to-date information and best practices.
4.56 - Upgrading to a new version of the distribution
To proceed with the upgrade, create a local copy of your production site.
Database Backup: Make a backup of your production database and copy it to your local machine.
Codebase Copy: Make a copy of your production site codebase and copy it to your local machine.
Check for Manually Removed Modules: Ensure you have not manually removed Drupal modules in your database without uninstalling them first! If you have, return the module to the codebase and uninstall it via the Drupal Extend UI or Drush before proceeding.
Upgrade to the latest Open Y 9.2.x version: Ensure your site is on the latest 9.2.x release before proceeding to newer major versions. See the
Open Y documentation for specific instructions on upgrading to the latest 9.2.x release.
Run the Composer Update Command
In the same folder as your docroot, run the following commands:
This script replaces your composer.json file. Therefore, it is only suitable for websites with an unmodified composer.json.
If your composer.json file has been modified, manually merge the changes. The most important part is usually updating the repositories section.
Update the Database
Navigate to the docroot folder of your codebase and run:
drush updatedb
If updatedb Fails…
You can use Drupal’s hook_update_dependencies API to alter the order of updates. See
this example for guidance.
Ensure the commands finish without errors. Run them a second time. If the output is:
$ drush updatedb
No database updates required [success]
This confirms the updates were executed correctly.
If Loading the Site Fails…
You might encounter an error like this:
Error: Class … not found in …
This occurs when Drupal cannot find renamed modules. Manually clear Drupal’s caches:
drush ev "drupal_flush_all_caches();"drush cr
This should resolve the errors.
Visit the OpenY Upgrade Tool Dashboard
Review and revert or apply updated configuration versions after the upgrade.
Check for Regressions/Run Smoke Tests
Perform smoke tests to identify regressions after the upgrade. The YMCA Website Services team maintains a
smoke tests database document to assist with this process.
Backup the Updated Site
Use
drush sql-dump or another backup tool to create a backup of the site in its current state.
Proceed to the Next Version (Repeat from Step 1)
Repeat these steps to upgrade to the next desired version.
4.57 - Videos
Video Tutorials
The YMCA Digital Services team maintains a
YouTube channel with video tutorials for developers, content editors, evaluators, and more. Visit YouTube for the full list of content.
Once Virtual Y is installed, the system creates a set of required landing pages with predefined URLs. These pages are:
Virtual Y Landing page - /virtual-ymca
Virtual Y Login Landing page - /virtual-y-login
The URLs to the pages above are then set as configuration values at /admin/openy/virtual-ymca.
It is the administrator’s responsibility to keep these pages in the system or to properly update the configuration with new values to ensure Virtual Y functionality continues to work correctly. These pages are built using the “Landing Page (Layout Builder)” content type.
Protecting Virtual Y Pages
If content editors modify the alias or remove the Virtual Y pages above, the Virtual Y site may break. Site administrators may want to add additional protections to the site to prevent editors from making those changes. We recommend
Node Keep for this purpose:
Add node_keep to your repo with composer require 'drupal/node_keep'
Enable the module in Drupal
Edit each of the pages above and set the Node Keep options as you wish to protect the pages
Virtual Y Log Module
The Virtual Y Log module can be configured via configuration files. Available settings:
activity_granularity_interval: Default value 600 - sets the interval in seconds to track user activity on the site.
archiver_enabled: Default value true - enables/disables the activity logs archiver cron execution.
archiver_store_period: Default value 1 year - sets the period for which activity logs will be collected and placed in the same archive. This value should be set as a Relative Date/Time PHP string, e.g., 1 week, 2 months, 1 year, etc.
4.59 - Website Services Terms of Use
Version 2.1, December 2022
This is a free service provided by YUSA (“we,” “us,” and “our”) for users in the YMCA community (“users,” “you,” and “your”). By using the Website Services distribution repository, you agree to these Terms of Use.
We reserve the right to modify or discontinue, temporarily or permanently, any services or the Terms of Use at any time, with or without prior notice to users. YUSA is not liable for any damage to any user or other third party that may result from any such modification, suspension, or discontinuance of the service or of the Terms of Use.
Downloading
YUSA is not responsible for the content maintained in the repository. Any material downloaded or otherwise obtained through your use of our services is done at your own discretion and risk, and you will be solely responsible for any damage to your computer system or loss of data that results from the download of any such material. You agree that we have no responsibility or liability for the deletion of, or the failure to store or to transmit, any content or communication maintained by the service. We retain the right to create limits on use and storage at our sole discretion at any time with or without notice.
We are not responsible for the content, data, or actions of third parties, and you release YUSA, our directors, officers, employees, and agents from any claims and damages, known and unknown, arising out of or in any way connected with any claim you have against any such third parties. No advice or information, whether oral or written, obtained by you from us or through or from our services, creates any warranty not expressly stated in these Terms of Use.
All code downloaded from Website Services distribution is based on the Drupal® code base, which is subject to the terms of the Drupal license (
www.drupal.org). Website Services distribution code is a derivative work of Drupal, and any distribution must be under the terms of the
GNU General Public License version 2 or later versions.
Unless otherwise stated, all content (excluding code), including user-generated content, such as comments and discussions on the Website Services distribution web site, is licensed under
Creative Commons License, Attribution-ShareAlike 2.0.
Contributing
The term “contribution” means any source code, object code, patch, tool, sample, graphic, specification, manual, documentation, comments, or any other content posted or submitted by you to Website Services distribution. We welcome proposed contributions; however, all contributions are subject to review and approval, and potential modification, before inclusion in a release as part of Website Services distribution.
It is your responsibility to obtain appropriate licensing and attribution for content that you submit to Website Services distribution. Content without appropriate licensing or attribution will be removed.
You represent and warrant that:
Each contribution that you submit is an original work of authorship, and you can legally grant the rights set out in these Terms of Use;
To the best of your knowledge, each contribution will not violate any third party’s copyrights, trademarks, patents, or other intellectual property rights;
Each contribution shall be in compliance with U.S. export control laws and other applicable export and import laws.
You agree to notify us if you become aware of any circumstance which would make any of the foregoing representations inaccurate in any respect.
All code must comply with the reasonable standards issued by Website Services distribution, including architecture and security protocols. All code submitted to the repository that is a derivative work must be
GPLv2+ compatible and will automatically be redistributed as GPLv2+.
YUSA, in its sole discretion, will review, modify, and determine whether to include code in its next release. We can refuse or remove any contributions at our discretion and without prior notice.
Disclaimer
All content is provided “as is,” without any warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement; (ii) YUSA makes no other warranty that its services will meet your requirements, be safe, secure, uninterrupted, timely, accurate, or error-free, or that your information will be secure; and (iii) the entire risk as to the quality and performance of the content is with you.
Limit of Liability
In no event will YUSA, its affiliates, or their licensors, service providers, employees, agents, officers, or directors be liable for any indirect, special, incidental, consequential, or punitive damages, including but not limited to loss of revenue, loss of profits, loss of business or anticipated savings, loss of goodwill, and whether caused by tort (including negligence), breach of contract or otherwise, even if foreseeable. The foregoing does not affect any liability which cannot be excluded or limited under applicable law.
Copyright DMCA Notice
If a user or other third party believes that its content has been copied in a way that constitutes copyright infringement, that user or third party should provide YUSA with the following information: (a) an electronic or physical signature of the person authorized to act on behalf of the owner of the copyright interest; (b) a description of the copyrighted work that has been infringed; (c) a description of where the allegedly infringing material is located; (d) the affected user or third party’s address, telephone number, and email address; (e) a statement by the affected user or third party that he or she has a good faith belief that the disputed use is not authorized by the copyright owner, its agent, or the law; and (f) a statement by the affected user or third party, under penalty of perjury, that the above information is accurate and that such user or third party is the copyright owner or is otherwise authorized to act on the copyright owner’s behalf. Please report any alleged copyright infringements to
https://ymca.org.
Venue and Governing Law
This Agreement shall be governed by, and construed in accordance with, the laws of the State of Minnesota, without reference to conflicts of laws principles. The parties agree that the federal and state courts in the county of Hennepin, Minnesota will have exclusive jurisdiction and venue under this Agreement, and each party hereby agrees to submit to such jurisdiction exclusively.
GitHub Actions to manage the deployment of the site to GitHub Pages.
Hugo is an open-source static site generator that provides us with templates, content organization in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.
All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult
GitHub Help for more information on using pull requests.
Updating a Single Page
If you’ve spotted something you’d like to change while using the docs, Docsy has a shortcut for you:
Click Edit this page in the right (second) sidebar.
If you don’t already have an up-to-date fork of the project repo, you are prompted to get one. Click Fork this repository and propose changes or Update your Fork to get an up-to-date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
Make your changes and open a Pull Request. The maintainers will review, provide feedback, and merge.
Previewing Your Changes Locally
If you want to run your own local Hugo server to preview your changes as you work:
Follow the instructions in
Getting started to install Hugo and any other tools you need.
Fork the
yusaopeny_docs repo into your own project, then create a local copy using git clone.
Run hugo server in the site root directory. By default, your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.
Common Options
Hugo has
a number of flags you can use to change local server behavior. Here are a few we like:
--tlsAuto generate and use locally-trusted certificates to run the site over https
--buildDrafts include content marked as draft
--buildFuture include content with publishdate in the future
With all of these, you might end up with something like:
hugo serve --tlsAuto --buildDrafts --buildFuture
Creating an Issue
If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the
yusaopeny_docs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right-hand corner of the page.
Useful Resources
Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
In addition to the
full documentation, here are some commonly used functions in the YMCA Website Services Docs.
General Styles
The YMCA Website Services Docs are written in
Markdown, an easy-to read and write formatting language.
The old documentation made heavy use of horizontal rules --- and slashes in headings ## // Heading. We try to use standard Markdown headings for organization and remove those visual indicators for better accessibility.
Headings within a page should start with level 2 ## in order to properly build the in-page navigation.
Links
Internal links should be made with Markdown and page-relative locations, like:
The old community documentation used headings inside blockquotes (starting each line with >). That formatting doesn’t work in Hugo. We can use
Docsy alerts instead.
{{%alerttitle="Warning"%}}This is a warning.
{{%/alert%}}
Warning
This is a warning.
Although blockquotes sometimes work just as well:
> **Warning:** This is a warning.
Warning: This is a warning.
Color Swatches
The color shortcode can be used to display a small color swatch after a hex or RGB color value. Pass one quoted value for hex, or three numeric values for RGB.
When using this shortcode in code fences, use <> instead of %% as the shortcode delimiter so that the code is
not further rendered.
The include-remote-md shortcode fetches a remote markdown file and includes it in the page. This happens only when your Docsy project is built, so future changes to the remote markdown file are only included when you rebuild your project. See
docsy#1739
If the file has a H1 (# ....) instead of frontmatter, you can put the title line in as the second parameter and it will be removed instead. For example:
Linkcheck may encounter issues with localhost. To address this, consider setting up your local site to run through
Cloudflare Tunnel for reliable link checking.
This command targets all Markdown files within the specified directory and its subdirectories, applying linting rules and automatically fixing violations where possible.
6 - Glossary
ACTIVENet
“The world’s most powerful facility, registration and membership management software makes it easier to run your organization better than ever before.” Integrates with Activity Finder. Also “Active Network”.
ACTIVENet.
Activity Finder
A major component of the distribution which allows users to search YMCA programs with an interactive interface. Integrates with Daxko, ActiveNet, or Personify. Frontend built with Vue.js. Code at
YCloudYUSA/yusaopeny_activity_finder.
Avocado
“A powerful and flexible recreation and facility management platform running on the world’s leading CRM solution” (Salesforce). Used by some Canadian YMCAs to integrate with Activity Finder and Group Exercise.
Avocado.
Block
A Drupal data structure that contains a reusable set of content and can be placed on a page using the Block Layout or Layout Builder.
Blocks.
The newest and most widely used of the distribution themes. “Carnation offers image-rich page layouts and simple, mobile-optimized menus.” See
Sandboxes.
Content type
An item of content data with shared fields, like an image, text, and address. Content types have different purposes (Branch, Event, Landing Page) and are displayed in different ways on the site. See the
Drupal User Guide and
Content Types in the distribution.
Daxko
A service provider offering member management, facility management, and more. Integrates with most features of the distribution that have integrations.
Daxko.
Distribution
Full copies of Drupal that include Drupal Core, along with additional software such as themes, modules, libraries, and installation profiles. Used here to refer to the YMCA Website Services distribution.
Drupal Distributions.
Drupal
The Content Management System that powers the distribution.
Drupal.
EGYM
A service provider offering cloud-connected equipment and services to YMCAs. See
EGYM.
Five Jars
A partner agency that works on the distribution and provides services directly to YMCAs. Also “5J”.
Five Jars.
GroupEx Pro
A group-exercise management platform. Integrates with the Group Schedules feature. Acquired by Daxko in 2019.
GroupEx PRO.
ImageX
A partner agency that works on the distribution and provides services directly to YMCAs. Also “ImageX Media”.
ImageX.
ITCare
A partner agency that works on the distribution and provides services directly to YMCAs.
IT Care.
Layout Builder
A Drupal module that allows content editors to create visual layouts for displaying content using a drag-and-drop interface. See
Layout Builder.
Lily
One of the distribution themes. “Lily offers bold banner headings and eye-catching tiles to organize child page content.” See
Sandboxes.
Membership calculator
A feature of the distribution providing a wizard-style flow to assist members with choosing a membership and then funnel them into the member management system. See
Membership Calculator.
Officially the “Mid-Major YMCA Network”. Organization representing mid-sized YMCAs.
OneEach
A partner agency that provides development and hosting services directly to YMCAs.
OneEach Technologies
Open Y
The original name of the distribution currently known as YMCA Website Services. In 2016 a group of YMCA digital, marketing, and technology experts recognized the digital opportunities that exist if we work together as a community and established Open Y. The original core team was led by a small group of YMCAs including the YMCA North, Greater Seattle and YMCA of Greater Houston.
A service provider that offers member management systems and more. Integrates with a number of features of the distribution.
Personify.
Rose
One of the distribution themes. Rose offers sprawling site menu options and high accessibility for blind and low-vision users. See
Sandboxes.
Sandbox
A set of example sites for evaluating and testing the distribution. See
Sandboxes.
Small Y
YMCAs that have only a single or a few branches. Represented by the “Small and Mid-Size YMCA Network”.
SSO
Single Sign-On. A feature of some member management systems that can provide integrations into the distribution.
Theme
A set of templates, styles, and code that define the presentation layer of a site. See
Theming Drupal.
YMCA Canada, Y Canada
The Canadian YMCA Federation is made up of a national office and Member Associations across the country. See
ymca.ca.
YMCA North American Network, YNAN
The organization representing the largest YMCA associations in the country.
YMCA of the North, Y North
Formerly YMCA of the Twin Cities. One of the founding associations of Open Y. Lovers of llamas. See
ynorth.org.
YMCA of the USA, YUSA, Y-USA
The national resource office, supporting thousands of YMCAs, tens of thousands of staff, and hundreds of thousands of volunteers in 10,000 communities across the USA. Headquartered in Chicago.
YMCA of the USA.
YMCA’s Cloud Hosting Service
An enterprise-grade platform that enables Associations (Y’s) to create, host and personalize digital experiences. A product of YMCA’s Digital Services. Formerly YCloud Hosting. See
ds.ymca.org.
YMCA‘s Digital Content Hub
A submodule of YMCA’s Website Service enabling content sharing across YMCA websites. Formerly known as Y Content Hub A product of YMCA’s Digital Services.
YMCA’s Digital Services
The collection of mostly open-source cloud-based services maintained in collaboration between YUSA, the movement, and agency partners. Formerly known as the YCloud Ecosystem. See
ds.ymca.org.
YMCA’s Mobile Experience Platform
A mobile app to engage YMCA associations’ members across the USA. A product of YMCA’s Digital Services. Formerly known as the Universal App. See
ds.ymca.org.
YMCA’s Virtual Experience Platform
A gated and secure digital space created to provide content, programming, and other resources to YMCA Association members. A product of YMCA’s Digital Services. Formerly known as Virtual Y. See
ds.ymca.org.
YMCA’s Website Service
A collection of Drupal modules, themes, configuration, and content bundled together in a “distribution” to enable digital transformation for YMCAs across the country. A product of YMCA’s Digital Services. Formerly known as Open Y. See
ds.ymca.org.
