diff --git a/.editorconfig b/.editorconfig index 686c443ce..a30b52e3c 100644 --- a/.editorconfig +++ b/.editorconfig @@ -13,5 +13,8 @@ charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true +[*.md] +indent_size = 4 + [composer.{json,lock}] indent_size = 4 diff --git a/content/en/docs/development/GoogleCustomSearchConfiguration/_index.md b/content/en/docs/development/GoogleCustomSearchConfiguration/_index.md index 42da3033f..e8cc9b297 100644 --- a/content/en/docs/development/GoogleCustomSearchConfiguration/_index.md +++ b/content/en/docs/development/GoogleCustomSearchConfiguration/_index.md @@ -2,29 +2,27 @@ title: Google Custom Search Configuration --- -The YMCA Website Services release **8.2.4** introduces Google Custom Search for the website out of the box. +The YMCA Website Services release **8.2.4** introduces Google Custom Search (aka Google Programmable Search Engine) for the website out of the box. ## Enabling the module ### Fresh installations -The search feature is included in the `Extended` installation type. -For `Standard` see the Existing websites section. +The search feature is included in the `Extended` installation type. For `Standard` see the Existing websites section. -If you are installing a fresh YMCA Website Services website and going through the installation process via the Web interface, on the 3rd party integration step you can specify Google Search ID. If you specify the Google Search ID in this form your site's search feature is up. +If you are installing a fresh YMCA Website Services website and going through the installation process via the web interface, on the third-party integration step, you can specify a Google Search ID. If you specify the Google Search ID in this form, your site's search feature will be up and running. ### Existing websites -The search feature is not automatically enabled after upgrading an YMCA Website Services website. You have to manually enable it. +The search feature is not automatically enabled after upgrading a YMCA Website Services website. You have to manually enable it. -In order to do that: +To do that: 1. Log in as an admin (or a user with the `administrator` role). 1. Go to the YMCA Website Services package install page (Admin menu > YMCA Website Services > Extend > Install, or `/admin/openy/extend/list`) -1. Find the `SEARCH` package there, tick the checkbox and submit the form. +1. Find the `Search` package there, tick the checkbox, and submit the form. -Now the search modules are enabled and the header of the website should have a search field. -Upon installation, the modules create a Landing page for search results and point the header search form to the page. +Now, the search modules are enabled, and the website header should have a search field. Upon installation, the modules create a Landing page for search results and point the header search form to the page. ## Configuring the Google Search modules @@ -33,8 +31,8 @@ Upon installation, the modules create a Landing page for search results and poin ### Obtaining Search Engine ID -1. Go to https://cse.google.com/, register if you haven't yet, log in if you aren't logged in. -1. Create the Search Engine (this process is explained in Google documentation https://support.google.com/customsearch/answer/4513882?hl=en&ref_topic=4513742): +1. Go to https://cse.google.com/, register if you haven't yet, and log in if you aren't logged in. +1. Create the Search Engine (this process is explained in [Google's documentation](https://support.google.com/programmable-search/answer/11082370?hl=en&ref_topic=4513742&sjid=719872083080201556-NC): 1. Click "New Search Engine". 1. Specify the domain of your website (e.g. `www.example.com`). 1. Specify the name of the Search Engine (e.g. `example.com`). @@ -43,50 +41,81 @@ Upon installation, the modules create a Landing page for search results and poin ## Configuring the Search Engine look and feel -1. Go to `Look and feel` section of the Search Engine -1. In the `Layout` tab, select `Full width` option and click `Save` +1. Go to the `Look and feel` section of the Search Engine +1. In the `Layout` tab, select the `Full width` option and click `Save` -If this change hasn't made, the search results on the website are shown in a popup window. +If this change hasn't been made, the search results on the website are shown in a popup window. ### Dealing with ads -By default, newly created Search engines use Free Edition (with ads) of the service. As YMCAs are non-profit organizations they have the option to switch to Non-profit Edition of the CSE, where it is possible to disable ads. - -Take a look here https://support.google.com/customsearch/answer/4542102?hl=en&ctx=topic +By default, newly created Search engines use the Free Edition (with ads) of the service. As YMCAs are non-profit organizations they have the option to [switch to Non-profit Edition](https://support.google.com/programmable-search/answer/11082370?hl=en&ref_topic=4513742&sjid=719872083080201556-NC) of the CSE, where it is possible to disable ads. If you are already registered as a Non-profit in Google: + 1. From the [CSE Control Panel](https://cse.google.com), select the search engine you want to change. -1. Click **Setup** then **Make Money** +1. Click **Overview** then **Ads** 1. Toggle the **Show Ads** option to off. +### Layout Builder and Google Search + +The Google Custom Search Engine can also be used with [Layout Builder](../../user-documentation/layout-builder): + +1. 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. +2. 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**. +3. Add a [Small Banner](../../user-documentation/layout-builder/banner) to the header with a title for the page, like "Search". +4. Add the search results code to the page: + - In the **Body** section, **Add block** and choose **Code Block** + - In **Code**, add the embed code from the CSE configuration. You may need to add an outer div to fit your page layout, for example: + ```html +
+ +
+
+ ``` + - **Save layout** and check your page +5. Change the Google Search config to use your new page: + - Go to **Admin** > **YMCA Website Services** > **Settings** > **Google Search settings** (`/admin/openy/settings/google-search`) and set the **Search page id** to the node id of your new page. + - Or, change the config with drush: + ``` + drush cset openy_google_search.settings search_page_id + ``` +6. Test the search box in the Layout Builder page header to ensure the new configuration works as expected. + ## Advanced setup -Official Google documentation https://support.google.com/customsearch/topic/4542213?hl=en&ref_topic=4513868 +Google maintains documentation on [how to configure advanced search features](https://support.google.com/customsearch/topic/4542213?hl=en&ref_topic=4513868) ### Mutli-site search -You can add not only your website's domain but other domains as well if you have other websites dedicated to your Association but split from the main website. +You can add multiple domains to the custom search engine if your association maintains multiple websites, for example, if your camps run at different website domains -You can also add not only the whole websites but their parts by specifying patterns like `example.com/blog/*`. +You can also add not only the whole website but its parts by specifying patterns like `example.com/blog/*`. See [Update sites in your search engine](https://support.google.com/programmable-search/answer/12397162?hl=en&ref_topic=4513742&sjid=719872083080201556-NC) for details. ### Refinements and facets -https://support.google.com/customsearch/answer/4542637?hl=en&ctx=topic&topic=2642564&visit_id=637166170019174137-3540762397&rd=1 +[Use Refinements to narrow the scope of search](https://support.google.com/programmable-search/answer/12425418?hl=en&ref_topic=4542213&sjid=719872083080201556-NC) -Refinements let users filter results according to categories you provide. +Refinements let users filter results according to the categories you provide. -Refinements appear in the search results page as tabs. The content of each tab is configured in Search features > Refinement section of the Custom Search Control panel. +Refinements appear in the search results page as tabs. The content of each tab is configured in the Search features > Refinement section of the Custom Search Control panel. To set up a dedicated tab in search results for Blog posts do the following: -1. In Control panel, go to `Search features` > `Refinements` +1. In the Control panel, go to `Search features` > `Refinements` 1. Click `Add` 1. Set the name of the refinement to `Blog` 1. Select `Search only the sites with this label` for `How to search sites with this label?` 1. Click `Ok` 1. Go to `Setup` 1. Find `Sites to search`, click `Add` - 1. Add the `yourymcadomain.org/blog/*` in the text field + 1. Add the `example.org/blog/*` in the text field 1. Select `Blog` in the Label dropdown 1. Select `Include just this specific page or URL pattern I have entered` 1. Click `Save` @@ -95,7 +124,7 @@ The search results page now shows the `Blog` tab that only shows blog entries re ### Promotions -Official Google documentation https://support.google.com/customsearch/answer/4542640?hl=en&ref_topic=4542213 +[Use Promotions to highlight a page in searches](https://support.google.com/programmable-search/answer/13280560?hl=en&ref_topic=4542213&sjid=719872083080201556-NC) ## Information for developers @@ -104,6 +133,7 @@ Official Google documentation https://support.google.com/customsearch/answer/454 ### Enabling via Drush Use the following snippet to enable the package on existing websites: + ``` drush en openy_google_search ``` @@ -111,6 +141,7 @@ drush en openy_google_search ### Configuring the module via Drush Use the following snippet when you install YMCA Website Services via Drush to set the Search Engine ID: + ``` drush site-install openy \ --account-pass=password \ diff --git a/content/en/docs/development/Install-Solr-site-search-for-Open-Y/_index.md b/content/en/docs/development/Install-Solr-site-search-for-Open-Y/_index.md index 969591a5f..e0e6d63f0 100644 --- a/content/en/docs/development/Install-Solr-site-search-for-Open-Y/_index.md +++ b/content/en/docs/development/Install-Solr-site-search-for-Open-Y/_index.md @@ -14,27 +14,27 @@ YMCA Website Services leverages [Apache Solr](https://solr.apache.org/) for a fe - Log in as admin. - Go to `admin/modules` and enable the YMCA Website Services Search API module. -![image](https://user-images.githubusercontent.com/563412/142628630-b412aa4b-8f2b-42f6-ba06-c5bb6a78469c.png) + ![image](https://user-images.githubusercontent.com/563412/142628630-b412aa4b-8f2b-42f6-ba06-c5bb6a78469c.png) - Approve the next step for enabling Database Search. -![image](https://user-images.githubusercontent.com/563412/142628735-6aa409bd-5ff5-4305-a0f0-7f6bc96d0740.png) + ![image](https://user-images.githubusercontent.com/563412/142628735-6aa409bd-5ff5-4305-a0f0-7f6bc96d0740.png) - 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. -![image](https://user-images.githubusercontent.com/563412/142629065-e13c8bb4-cad8-436f-93c6-30fa6ac6fdf7.png) + ![image](https://user-images.githubusercontent.com/563412/142629065-e13c8bb4-cad8-436f-93c6-30fa6ac6fdf7.png) -tip: Admins can enable and the Solr search and switch the index between servers. +> TIP: Admins can enable and the Solr search and switch the index between servers. - Index content by clicking "Index now". -![image](https://user-images.githubusercontent.com/563412/142629227-8607eeca-4022-47c4-b5fd-6e38ccfb7bab.png) + ![image](https://user-images.githubusercontent.com/563412/142629227-8607eeca-4022-47c4-b5fd-6e38ccfb7bab.png) - Go to the homepage and search for any keyword. -![image](https://user-images.githubusercontent.com/563412/142629467-e275b536-2505-4ddf-8d78-7c6f4ae0e716.png) + ![image](https://user-images.githubusercontent.com/563412/142629467-e275b536-2505-4ddf-8d78-7c6f4ae0e716.png) - Verify search results are displayed correctly. @@ -64,10 +64,36 @@ Watch a [video tutorial](https://youtu.be/-Sq3uZb5K_U) on how to switch an exist - 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](../../user-documentation/layout-builder), and requires a few extra steps: + +1. 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. +2. 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**. +3. Add a [Small Banner](../../user-documentation/layout-builder/banner) to the header with a title for the page, like "Search". +4. 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. +5. 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. + - Or, change the config with drush: + ``` + drush cset openy_search_api.settings search_page_id + ``` +6. 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](https://www.drupal.org/project/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](https://git.drupalcode.org/project/search_api_solr/-/blob/4.x/modules/search_api_solr_legacy/README.md]. As of January 2022, Search API Solr Legacy supports Solr 3.6 through 6.4. +The contrib [Search API Solr](https://www.drupal.org/project/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](https://git.drupalcode.org/project/search_api_solr/-/blob/4.x/modules/search_api_solr_legacy/README.md). As of January 2022, Search API Solr Legacy supports Solr 3.6 through 6.4. -The error message may look something like this: +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() diff --git a/content/en/docs/howto/set-up-lb/_index.md b/content/en/docs/howto/set-up-lb/_index.md new file mode 100644 index 000000000..96161b0ee --- /dev/null +++ b/content/en/docs/howto/set-up-lb/_index.md @@ -0,0 +1,77 @@ +--- +title: "How to set up a Layout Builder site" +linkTitle: "set up a Layout Builder site" +description: Before you build content with Layout Builder, you (or your development partner) must install and configure your site. +--- + +## Install and prepare + +1. Install YMCA Website Services 10.3.0 or higher. + - If you are starting a new site, follow the [distribution install instructions](https://github.com/YCloudYUSA/yusaopeny#installation). + - If you are starting with an internal toolchain, `composer require ycloudyusa/yusaopeny` at the root of the project. +2. Go to **Admin** > **Configuration** > **Basic site settings** and configure the website name and slogan. + +## Enable Layout Builder modules + +The core functionality of the Layout Builder features is packaged inside the [Y Layout Builder module (`y_lb`)](https://github.com/YCloudYUSA/y_lb). This module is required by the profile and comes with it out of the box. + +Layout Builder modules could be disabled by default. The complete [list of available components](https://github.com/YCloudYUSA/y_lb/blob/main/composer.json#L16) is available in `y_lb/composer.json`. There are two different methods to enable them: + +1. To install only selected modules: Go to **Admin** > **Extend** (`/admin/modules`) and enable only the components that you choose to use. +2. To install all the modules: Go to **Admin** > **YMCA Website Services** > **Extend** > **Install** (`/admin/openy/extend/list`). Check the box for **Layout Builder**, then **Install**. + +## Configure layouts & listings + +Layout Builder relies on a system of [Layout Defaults](https://www.drupal.org/docs/8/core/modules/layout-builder/creating-layout-defaults) and [Layout Overrides](https://www.drupal.org/docs/8/core/modules/layout-builder/creating-layout-overrides). An important concept to understand from these pages is: + +> Once a Layout is overridden on an entity, that entity will not be impacted by changes to Layout Defaults. + +In building Landing Pages, we will override the Default Layout for every page (by placing content blocks). For this reason, it is important that we **configure the desired defaults before building pages**. + +### Landing Pages + +You will use the [Landing Page (with Layout Builder)](../../user-documentation/content-types/lb-landing-page) content type to build landing pages. + +- Configure its [content type styles](../../user-documentation/layout-builder/advanced-options/#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](../../user-documentation/content-types/branch), [Camp](../../user-documentation/content-types/camp), and [Facility](../../user-documentation/content-types/facility) content types to build pages that contain the contact and amenity details for each location. + +- For new sites, you may set the **Use Layout Builder** checkbox to be true by default at `/admin/structure/types/manage/branch/fields/node.branch.field_use_layout_builder`. +- Configure the default layout and settings for each type on their corresponding layout settings pages: + - Branch: `/admin/structure/types/manage/branch/display` + - Camp: `/admin/structure/types/manage/camp/display` + - Facility: `/admin/structure/types/manage/facility/display` +- Create a locations page with the URL alias `/locations` using [Location Finder](../../user-documentation/layout-builder/location-finder). + +### Events + +Enable [Events with Layout Builder (`ws_event`)](https://www.drupal.org/project/ws_event) to use Events with Layout Builder. + +- Configure its default layout and settings at `admin/structure/types/manage/lb_event/display`. +- Create an events listing page with the URL alias `/events` using [Events Views & Filters](../../user-documentation/layout-builder/event-views) + +### Articles + +Enable [Articles with Layout Builder (`y_lb_article`)](https://www.drupal.org/project/y_lb_article) to use Articles with Layout Builder. + +- Configure its default layout and settings at `/admin/structure/types/manage/article_lb/display`. +- Add an article listing page with the URL alias `/news` using [Article Views & Filters](../../user-documentation/layout-builder/article-views). + +## Activity Finder + +Enable `openy_node_session`, `openy_node_program`, `openy_node_category`, `openy_node_activity`, and `openy_node_class` to set up the Program Event Framework (PEF) if you plan to use Schedules or Activity Finder on the project. + +Then require and enable [`yusaopeny_activity_finder`](https://github.com/YCloudYUSA/yusaopeny_activity_finder) to use [Activity Finder](../../user-documentation/schedules/activity-finder). + +## Canadian YMCAs + +For Canadian YMCA sites, enable [`ws_colorway_canada`](https://www.drupal.org/project/ws_colorway_canada). This module contains [colorways and logos](../../user-documentation/layout-builder/designs/#canadian-colourways) approved by their local Y authorities.