README.md

Open Y Activity Finder

Requirements

This module requires the following modules:

• openy_map (For pulling the list of location-related content types.)

This module also requires one of the following to store data:

• A Solr server (preferably a server or index per-environment).
• A subscription with access to the Daxko API.

Recommended modules

Activity Finder is most often used with a syncer to pull data from an external source.

Installation

Activity Finder version 4 is the current major version. Prior to 9.2.10.0, the distribution required ^3.1 || ^4.0, allowing you to choose which version you want to use depending on the project requirements.

Deprecations

Outdated implementations are not removed immediately, allowing you to update your projects and migrate to new components without breaking your site. They are marked with [deprecated] notices in the next version and are planned to be removed in the future releases.

New Projects

Install as you would normally install a contributed Drupal module. For further information, see Installing Drupal Modules.

New projects should enable:

• Activity Finder (openy_activity_finder)

then choose one or both of the front ends:

• LB (Layout Builder) Activity Finder (lb_activity_finder)
• Open Y Paragraph Activity Finder (openy_prgf_activity_finder_4)

and finally enable one of these data stores:

• Search API Solr (search_api_solr)
• Daxko API v2 integration (openy_daxko2)

Existing Projects

You have a choice of either staying on the same version you use or to update to the next version. It depends on your project requirements and customizations. We recommend updating to the latest release if you have resources for it.

Update from version 3.x to version 4.x

Activity Finder is a complex functionality, it connects together many different pieces and might require additional steps to make it working. The list of actions below outlines the major steps to get Activity Finder updated to version 4.

• Update the codebase using the composer command: composer require ycloudyusa/yusaopeny_activity_finder:"^4.0"
• Run database updates drush -y updb.
  • Verify there were no errors and updates went fine.
• Install the new "Open Y Paragraph Activity Finder" (openy_prgf_activity_finder_4): drush en openy_prgf_activity_finder_4
• Create or update a existing Landing Page with Activity Finder.
• Add Activity Finder paragraph (replace the deprecated paragraph), configure it and save the page.
  • Verify the page and Activity Finder functionality is working fine
• The previous version of Activity Finder used 2 landing pages with 2 paragraph types - one for wizard and another one for results. Find and remove these pages.
• Uninstall "OpenY Paragraph Activity Finder" (openy_prgf_activity_finder).
• Uninstall "OpenY Paragraph Activity Finder Search" (openy_paragraph_activity_finder_search).

Configuration

Set up Solr

In order to install Solr - check the documentation on Drupal.org.

After enabling the above modules you should visit /admin/config/search/search-api and obtain config.zip from preconfigured by Open Y Solr Server setup

This configuration should be installed on your Solr server as an independent core. it should be extracted to the conf directory of a solr core

Once it is done - ensure the name of your core from core.properties file added to Solr Server config in Open Y

Solr server configuration could be found in Dropdown at /admin/config/search/search-api

If you prefer drush configuration you may use commands below, just replace SOLR_CORE_IS_HERE with real core name

drush cset -y search_api.server.solr backend_config.connector_config.host 127.0.0.1 -y
drush cset -y search_api.server.solr backend_config.connector_config.core ${SOLR_CORE_IS_HERE} -y
drush search-api:reset-tracker
drush search-api:index

Once this is done you should see Solr Server as Index as Enabled on a /admin/config/search/search-api

If you installed Open Y with Demo content now it is time to create a Landing Page with the Activity Finder v4 component on it.

In Open Y we have a specially created module which can this for you

Enable openy_prgf_af4_demo by drush command

drush en openy_prgf_af4_demo

and you’d get /activity-finder-v4 Landing Page created automatically which should look like

when you visited it. By visiting /activity-finder-v4?step=results or clicking on suggested buttons you should see results, activities with filters and all other functionality, shipped with Activity Finder v4 For the Demo content from OpenY, it should look like

Set Trusted Redirect Host patterns

Activity Finder has a feature to track redirects to 3rd party systems. In order to control the URLs to redirect to you should use the trusted host patterns. This feature works similar to Drupal core trusted_host_patterns setting.

Example - add this section to the settings.php:

// Trusted hosts to redirect to for Activity Finder.
$settings['activity_finder_trusted_redirect_host_patterns'] = [
  '^apm\.activecommunities\.com$',
];

It is also recommended to disallow these paths in robots.txt:

# Activity Finder redirects
Disallow: /af/register-redirect/
Disallow: /index.php/af/register-redirect/

Add the Activity Finder block

See the full documentation on Activity Finder for information on how to add the block to your page and block options.

Troubleshooting & FAQ

To demo Activity Finder, see these sandboxes:

• Activity Finder v4
  • Carnation https://sandbox-carnation-cus-d9.y.org/activity-finder-v4
  • Lily https://sandbox-lily-cus-d9.y.org/activity-finder-v4
  • Rose https://sandbox-rose-cus-d9.y.org/activity-finder-v4
• Activity Finder v3
  • Carnation https://sandbox-carnation-cus-d9.y.org/activity-finder
  • Lily https://sandbox-lily-cus-d9.y.org/activity-finder
  • Rose https://sandbox-rose-cus-d9.y.org/activity-finder

Limitations with using Daxko backend

When using the Daxko backend. Developers should be aware of these limitations:

• We can't use home branch functionality on start screen.
• We have to use Legacy mode.
• We can't display count of result for each age on the age's wizard step.
• We can't display count of available spots for each activity, before user click by activity details.
• Limited pager on results page. We can display only previous and next page link and can't display count of pages.

How to override processResults in Activity Finder

See openy_activity_finder.api.php

/**
 * Implements hook_activity_finder_program_process_results_alter().
 */
function custom_module_activity_finder_program_process_results_alter(&$data, NodeInterface $entity) {
  // Get formatted session data from some custom service.
  $formatted_session = \Drupal::service('ymca_class_page.data_provider')
    ->formatSessions([$entity], FALSE);
  $formatted_session = reset($formatted_session);

  // Fix pricing according to YMCA price customization.
  $data['price'] = '';
  if (!empty($formatted_session['prices'])) {
    foreach ($formatted_session['prices'] as $price) {
      $data['price'] .= implode(' ', $price) . '<br>';
    }
  }

  // Fix availability and registration according to YMCA customization.
  $messages = [
    'begun' => t('This class has begun.'),
    'will_open' => t('Registration for this class opens shortly. Please check back.'),
    'inperson' => t('Online registration is closed. Visit a YMCA branch to register.'),
    'included_in_membership' => t('Included in Membership'),
  ];

  if (isset($messages[$formatted_session['reg_state']])) {
    $data['availability_note'] = $messages[$formatted_session['reg_state']];
  }
}

How to add external functionality to analytics event

See openy_af4_vue_app/main.js

// Listen to a custom event to pass events in Google Analytics.
document.addEventListener('openy_activity_finder_event', (e) => {
  const { action, label, value, category } = e.detail

  if (window.gtag) {
    window.gtag('event', action, {
      event_category: category,
      event_label: label,
      value: value
    })
  } else if (window.ga) {
    window.ga('send', 'event', category, action, label, value)
  }
})

Example of custom event

document.addEventListener('openy_activity_finder_event', (e) => {
  const { action, label, value, category } = e.detail // Properties you can use for analitics.
  ...
  { your_functionality }
  ...
})

Add custom component in between of results

it allows flexibility in terms of results rendering for the developer:

          <ResultsList
            :results="data.table"
            :ages="ages"
            :selected-ages="selectedAges"
            :legacy-mode="legacyMode"
            :disable-spots-available="disableSpotsAvailable"
            @showActivityDetailsModal="showActivityDetailsModal($event)"
          />

can be changed to this:

          <ResultsList
            :results="data.table.slice(0, 2)"
            :ages="ages"
            :selected-ages="selectedAges"
            :legacy-mode="legacyMode"
            :disable-spots-available="disableSpotsAvailable"
            @showActivityDetailsModal="showActivityDetailsModal($event)"
          />
          <YGBWAds />
          <ResultsList
            :results="data.table.slice(2)"
            :ages="ages"
            :selected-ages="selectedAges"
            :legacy-mode="legacyMode"
            :disable-spots-available="disableSpotsAvailable"
            @showActivityDetailsModal="showActivityDetailsModal($event)"
          />

where YGBWAds is custom component to render custom content in between the results. See ymcatwincities#148