This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Development

Welcome to the development corner of the Open Y distribution.

Here you can find all needed documentation and how-to work with Open Y codebase from developer’s point of view.)

1 - Acceptance Testing

Open Y is a big distribution with a large amount of modules, components, subsystems, and business processes, therefore we have to take appropriate steps to ensure the stability of major functionality during development.

For the automated tests we have created General Checks template on GitHub every developer should follow to get review approval from Open Y core team. However, General Checks are for testing functionality for the current proposed change only, not for Regression Testing.

For regression testing, Behat tests in this flow are provided automatically on each build by Open Y community.

Every pull request should include a testing plan prior to release into Open Y. This plan should cover the testing of all workflows and functionality to ensure that they continue to work with any new code or change implemented. This is because it is possible for conflicts to occur between elements of Open Y, Drupal Modules, and Drupal Core. These pull request testing plans will increase productivity and decrease effort for manual Acceptance Testing of upcoming Releases. This testing plan should cover specific features and functionality that is likely to cause regression issues post-release or post-upgrade to the latest version of Open Y once this new code is implemented.

Example of testing plan: If the Drupal core is updated it is important to gather all Drupal core Release Notes since last release core upgrade for Open Y and analyze important issues fixed. Example - in case if you are doing upgrade from latest 8.4.0 to 8.4.4:

This means the list of systems should be tested are

  • multilingual
  • postgreSQL support
  • migration
  • taxonomy
  • ckeditor
  • composer

This list could be extended by analyzing some highly important parts of Open Y distributions that depends from the above subsystems. It is not required to spend time on every module that has a dependency taxonomy, but it is important to test at least one impacted module to ensure it is still working post-implementation. In case if there is a Behat test already created for the subsystem in a list then a manual test could be skipped as long as the build is not failing due to the module or element covered in the associated Behat test.

How to choose which modules to test: These can be a random selection from the list of systems impacted, or one of the oldest modules in a system impacted. This is because there is a higher chance that a minor change could cause a regression issue for the modules that have not received recent or regular updates.

The oldest modules(contrib modules) that have dependencies from the above list should also be updated, but to improve productivity, these updates should only be initiated if there is a security issue or a module stopped working because of the subsystems getting updated within an upcoming release. In case if a respective module update creates more issues that the older version of said module - then it is better to keep the old module and fix an associated regression bug. Tip: usually a new version of the module already contains a bug fix, so adding a patch from the drupal.org to composer.json of the Open Y distribution is preferred to get distribution released. Keep in mind, you will need to create a follow-up task for the module to be updated after release.

After creating list of modules that could introduce regression issues it is highly recommended to follow Quick-start section of the module’s readme files, that usually is shipped with modules. Example for the location_finder. In case if a module has no Quick-start or Acceptance testing section in readme - it is important to test at least one place where functionality of the module should be working. It is highly recommended to add this manual test steps as a follow-up task, new issue or even better - create Pull Request with changes to readme into Open Y repository. For the sake of performance, adding step by step how-to to the respective module’s README.md file is highly recommended. It takes only a few minutes to write a couple of lines of documentation which will greatly help others with future contributions and changes.

Optional, but greatly appreciated: Add a Drupal tour for the how-to, created in README will benefit future Open Y users and developers. Having a tour for the business functionality is highly recommended to ship with the component - it creates an in-site visual guided documentation and helps to decrease time for the Acceptance testing.

And last, but not the lease - adding Behat tests to the system will ensure functionality is tested on every pull request, on every CI build in the future.

Rule

Every release of Open Y since 8.1.9 should include list of subsystems, changed in release for the community to be aware of the possible regressions on their end.

2 - AddThis

How to configure AddThis

Open Y AddThis module allow you easy add Social icons to any node.

  1. Go to http://www.addthis.com and create your account and get public id.

  2. Go to admin/openy/settings/openy-addthis add public id Enter Public id

  3. Select the content type for which to show the social icons and save.

How to use AddThis paragraph

You can add AddThis to specific node use ‘Social share icons’ paragraph

  1. Click on ‘Edit’ any node

  2. After content add ‘Social share icons’ paragraph Enter Public id

3 - Composer

Please always make sure composer.lock file is updated after any changes in composer.json file. You can use composer update command to update any package, in this case composer will take care about updating of composer.lock file.

composer update drupal/metatag

Also you can use composer update --lock command to force updating of composer.lock file according to dependencies in composer.json.

Please check official composer documentation for details: https://getcomposer.org/doc/01-basic-usage.md

4 - Configuration for social posts import

Add import social posts to site (Facebook, Instagram, Twitter)

How configure import of posts from the social networks

Given: As an Open Y site developer, I want to be able import posts from company’s accounts form social networks (Twitter, Facebook, Instagram) and save them as content on the site.

How to:

  • Open configuration page /admin/config/social_feed_fetcher_settings - Configuration -> Social Feed Settings
  • Select checkbox for needed social network and add additional settings. Every social network has their own API, please read documentation for this settings on the official pages of each social networks.
  • When all settings will be filled - click on the button - Run Cron. Import is started.

5 - Contributing

Issues

If you have a support request, you’ve found a bug or you have a feature request:

Pull Requests

If you have some time to make a contribution to the project, here are the steps that will help you:

  • Create fork of main project. How to create fork.
  • Commit & push changes into your fork
  • Create new Pull Request. How to create Pull Request.
  • 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.
  • Create Drupal tour module, based on steps for review and ship it with the module which provides a functionality.
  • 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.

Drupal.org credits

If you would like to get drupal.org credits for your contribution:

  • Create issue on drupal.org
  • Link drupal.org issue to GitHub Pull Request
  • Specify in GitHub Pull Request link to drupal.org issue
  • Once PR has been merged, reviewer will close drupal.org issue with appropriate credits.

6 - Create & Use New View Modes

As with any other entity in Drupal, when it comes to render the rendering it in different contexts, you might want to have specific view modes.

Here you can find instructions how you can add new view modes into embedded entity form on Open Y distribution.

Create a new View Mode

  1. Go to ‘View modes’ page: Structure -> Display modes -> View modes (or visit the URL: /admin/structure/display-modes/view Configuration project add/update form

Configuration project add/update form

  1. Create new view mode: click ‘Add view mode’ button and select entity type (or visit the URL: /admin/structure/display-modes/view/add

Configuration project add/update form

or after each entity type you can see ‘Add new {Name} view mode’ and click on it Configuration project add/update form

  1. Select “Media” and then give a name to your new view mode (or visit the URL: /admin/structure/display-modes/view/add/media Configuration project add/update form

Use the View Mode

  1. Go to Configuration -> Text editor embed buttons (or visit the URL: /admin/config/content/embed Configuration project add/update form

Configuration project add/update form

  1. Then make sure you enable the new view mode in “Allowed Entity Embed Display plugins”, and at the bottom of the page click “Save”. Configuration project add/update form

7 - Data Layer

See also the Data Layer module README.

The Data Layers module output data on the page in a json format. By default it will output properties (langcode, vid, name, uid, created, status, roles) and related taxonomy for any node, user, or any route based entity.

A limited set of properties are available via the Data Layers configuration form at /admin/config/search/datalayer (langcode, vid, name, uid, created, status, roles).

Adding additional properties can be done through use of hook_datalayer_meta().

function my_module_datalayer_meta() {
  return array(
    'property',
  );
}

It will be added to the page as:

{
  "entityProperty": "whatever the value is"
}

Altering which properties will be output can be done via hook_datalayer_meta_alter().

function my_module_datalayer_meta_alter(&$properties) {
  // Override module norm in all cases.
  unset($properties['entityUid']);

  // Specific situation alteration...
  $type = false;
  if ($obj = _datalayer_menu_get_any_object($type)) {
    if ($type === 'node' && in_array(array('my_bundle', 'my_nodetype'), $obj->type)) {
      // Remove author names on some content type.
      if ($key = array_search('name', $properties)) {
        unset($properties[$key]);
      }
    }
    elseif ($type === 'my_entity_type') {
      // Remove some property on some entity type.
      if ($key = array_search('my_property', $properties)) {
        unset($properties[$key]);
      }
    }
  }
}

Adding additional data can be done using datalayer_add().

function _my_module_myevent_func($argument = FALSE) {
  if ($argument) {
    datalayer_add(array(
      'drupalMyProperty' => $argument,
      'userAnotherProperty' => _my_module_other_funct($argument),
    ));
  }
}

To alter the data to be output use hook_datalayer_alter().

function my_module_datalayer_alter(&$data_layer) {
  // Make the title lowercase on some node type.
  if (isset($data_layer['entityBundle']) && $data_layer['entityBundle'] == 'mytype') {
    $data_layer['entityLabel'] = strtolower($data_layer['entityLabel']);
  }
}

8 - Daxko

Relates to: Program Registration (Daxko)

Configuration setting at /admin/config/development/daxko

Account configuration must be setup before the Program Registration paragraph will work.

9 - Fonts

From YMCA Link:

Typography is an important element of our brand identity. Cachet and Verdana, the only two fonts used on YMCA collateral, help provide our words with a distinctive look and welcoming feel. And Cachet, as our primary font, should be used for all internal and external materials whenever possible.

To help Ys incorporate the Cachet font into their online applications, Y-USA is now licensing the web font version of Cachet for all YMCAs. Previously, Ys could only access the desktop version of the font from the Brand Resource Center (BRC).

Visit the BRC to:

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

  • Visit Admin > Extend and ensure the “@fontyourface” and “@fontyourface - Local Fonts” modules are enabled.
  • Visit Admin > Appearance > @font-your-face > Custom Fonts
  • Click + Add Custom Font and add each of the Cachet font files you downloaded above with the following settings:
LabelFont FamilyFont StyleFont WeightFont ClassificationFont File
Cachet Extra LightCachetNormal300Sans SerifCachetW05-ExtraLight.woff
Cachet BookCachetNormal400Sans SerifCachetW05-Book.woff
Cachet MediumCachetNormal500Sans SerifCachetW05-Medium.woff
Cachet BoldCachetNormal700Sans SerifCachetW05-Bold.woff

Add_custom_font|591x500

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

Custom_Font|690x156, 100%

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

This content was originally published on the Open Y Message Board.

10 - Google Analytics

Introduction

Open Y uses the Drupal contrib Google Analytics module to enable Google Analytics tracking on your Open Y site.

To get started, you should first create a GA property. Use the Analytics Help for assistance.

Configuration

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

Google Analytics Version Compatibility

In the 9.2.11 release in November 2021, Open Y added support for Google Analytics 4. If your site has been updated to Open Y 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.

See this community post for more information.

11 - Google Custom Search Configuration

The Open Y release 8.2.4 introduces Google Custom Search 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.

If you are installing a fresh Open Y 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.

Existing websites

The search feature is not automatically enabled after upgrading an Open Y website. You have to manually enable it.

In order to do that:

  1. Log in as an admin (or a user with the administrator role).
  2. Go to the Open Y package install page (Admin menu > Open Y > Extend > Install, or /admin/openy/extend/list)
  3. 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.

Configuring the Google Search modules

  1. Go to the Google Search settings form (Admin menu > Open Y > Settings > Google Search settings, or /admin/openy/settings/google-search).
  2. Set the value of the Google Search ID field (see the following section for details) and submit the form.

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.
  2. Create the Search Engine (this process is explained in Google documentation https://support.google.com/customsearch/answer/4513882?hl=en&ref_topic=4513742):
    1. Click “New Search Engine”.
    2. Specify the domain of your website (e.g. www.openymca.org).
    3. Specify the name of the Search Engine (e.g. openymca.org).
    4. Click “Create”.
  3. On the newly created Search Engine page there is the Search engine ID field. Use this value in the Open Y Google Search configuration form.

Configuring the Search Engine look and feel

  1. Go to Look and feel section of the Search Engine
  2. In the Layout tab, select Full width option and click Save

If this change hasn’t 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

If you are already registered as a Non-profit in Google:

  1. From the CSE Control Panel, select the search engine you want to change.
  2. Click Setup then Make Money
  3. Toggle the Show Ads option to off.

Advanced setup

Official Google documentation https://support.google.com/customsearch/topic/4542213?hl=en&ref_topic=4513868

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 also add not only the whole websites but their parts by specifying patterns like example.com/blog/*.

Refinements and facets

https://support.google.com/customsearch/answer/4542637?hl=en&ctx=topic&topic=2642564&visit_id=637166170019174137-3540762397&rd=1

Refinements let users filter results according to 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.

To set up a dedicated tab in search results for Blog posts do the following:

  1. In Control panel, go to Search features > Refinements
  2. Click Add
    1. Set the name of the refinement to Blog
    2. Select Search only the sites with this label for How to search sites with this label?
    3. Click Ok
  3. Go to Setup
  4. Find Sites to search, click Add
    1. Add the yourymcadomain.org/blog/* in the text field
    2. Select Blog in the Label dropdown
    3. Select Include just this specific page or URL pattern I have entered
    4. Click Save

The search results page now shows the Blog tab that only shows blog entries relevant to the search term.

Promotions

Official Google documentation https://support.google.com/customsearch/answer/4542640?hl=en&ref_topic=4542213

Information for developers

Google Custom Search Developers documentation

Enabling via Drush

Use the following snippet to enable the package on existing websites:

drush en openy_google_search

Configuring the module via Drush

Use the following snippet when you install Open Y via Drush to set the Search Engine ID:

drush site-install openy \
   --account-pass=password \
   --db-url="mysql://user:pass@host:3306/db" \
   --root=/var/www/docroot \
   openy_configure_profile.preset=extended \
   openy_theme_select.theme=openy_rose \
   openy_third_party_services.google_search_engine_id="01234567890123456789:abcedefgh"

The openy_third_party_services.google_search_engine_id parameter sets the Search Engine ID (01234567890123456789:abcedefgh in the example).

Use the following snippet to set the Search Engine ID on already installed websites:

drush config-set openy_google_search.settings google_engine_id "01234567890123456789:abcedefgh"

12 - Installation With Drush

Use drush site-install command.

Basically you use something like this:

drush site-install openy --account-pass=password --db-url="mysql://user:pass@host:3306/db" --root=/var/www/docroot

Complete Open Y profile preset and Open Y Rose theme is used in this case.

You can set which preset must be installed by specifying it with openy_configure_profile.preset variable, and theme with openy_theme_select.themevariable e.g.:

drush site-install openy --account-pass=password --db-url="mysql://user:pass@host:3306/db" --root=/var/www/docroot openy_configure_profile.preset=extended openy_theme_select.theme=openy_rose

13 - Module Development

Module content removal

When deleting an entity, where plugins or services of removing module are used, then content removal should be done in the hook_uninstall() of that module. See openy_prgf_camp_menu.install as example.

14 - Patch Open Y

Here you can find instructions how you can patch Open Y distribution used on your project.

When you need to patch Open Y

  • In case you found a bug and prepared a patch for Open Y on github.
  • In case you developed a new feature that will be good to have in Open Y and created Pull Request to Open Y repository
  • In case you want to add a feature that added to Open Y but not included yet to Open Y release.

How to patch Open Y via composer?

If you followed instructions docs/Development/Start new Open Y project and you have configured composer.json you need just to do a few simple steps:

  1. Build a link to a patch using pull request ID

    https://patch-diff.githubusercontent.com/raw/ymcatwincities/openy/pull/XXX.patch
    

Where XXX is a number of pull request you want to use.

  1. Add a new section patches to the section extra and add a patch to Open Y repository, as on this example:

    "extra": {
        "installer-paths": {
          ...
        },
        "enable-patching": true,
        "patches": {
            "ymcatwincities/openy": {
                "Patch description": "https://patch-diff.githubusercontent.com/raw/ymcatwincities/openy/pull/XXX.patch"
            }
        }
    }
    
  2. After adding a patch execute command composer update

  3. Verify you can see added changes in Open Y

  4. Enjoy!

15 - Search Tracking with Google Analytics

Prerequisites

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

Steps

  1. Log in to Google Analytics account that configured to track your Open Y site.

  2. Click Admin button in bottom right corner of main screen Google Analytics Main Screen

  3. Click View Settings Google Analytics View Settings

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

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

  6. Reports about the search tracking you can find at main screen in Behavior → Site Search Section

Attention: Data processing latency for search tracking reports is 24-48 hours (see Google’s support doc).

16 - Server Requirements

If you need to prepare server for the Open Y instance, here below you should find all needed software to meet its requirements.

List of requirements

  1. Ubuntu LTS (14 or 16) is preferred. CentOS is ok as well. Or even any other Linux distribution, but was not tested by Open Y team so far.

  2. (Drupal 8 server requirements should be met)[https://www.drupal.org/docs/system-requirements/php-requirements].

  3. PHP 5.6+ (PHP 7 is better in terms of performance)

List of PHP modules server should have:

  • php{{ php_version }}
  • php{{ php_version }}-mcrypt
  • php{{ php_version }}-cli
  • php{{ php_version }}-common
  • php{{ php_version }}-curl
  • php{{ php_version }}-dev
  • php{{ php_version }}-fpm
  • php{{ php_version }}-gd
  • php{{ php_version }}-mysql
  • php{{ php_version }}-memcached
  • php{{ php_version }}-imagick
  • php{{ php_version }}-xml
  • php{{ php_version }}-xdebug
  • php{{ php_version }}-mbstring
  • php{{ php_version }}-soap
  • php{{ php_version }}-zip
  1. MySQL 5.5+ . Here are the best settings https://github.com/cibox/cibox/blob/master/core/facade-mysql/defaults/main.yml to get it fast and furious
  2. Apache 2 with mod-php (preffered for stability) or nginx with php-fpm (better for speed and scalability)
  • libapache2-mod-php{{ php_version }}
  1. Memcache server (optional)

  2. Server tools

  • Ansible (optional)
  • Docker (optional)
  • SOLR 4.x (if there will be requirement for SOLR search support)
  • Varnish (optional)

17 - Start new Open Y project

Here you can find instructions how you can start project based on Open Y distribution.

New project from scratch based on Open Y

In order to start new project from scratch, you can use installation instructions that will build your project and even add development environment.

Add Open Y to existing Drupal 8 project

Please take a look at the full composer.json file below that you should eventually get.

 Example composer.json (Drupal 8.3.2 + Open Y 1.2)
{
    "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.0.24",
        "wikimedia/composer-merge-plugin": "~1.4",
        "ymcatwincities/openy": "8.*.*",
        "cweagans/composer-patches": "~1.0"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "config": {
        "preferred-install": "dist",
        "autoloader-suffix": "Drupal8",
        "secure-http": false
    },
    "extra": {
        "_readme": [
            "By default Drupal loads the autoloader from ./vendor/autoload.php.",
            "To change the autoloader you can edit ./autoload.php.",
            "This file specifies the packages.drupal.org repository.",
            "You can read more about this composer repository at:",
            "https://www.drupal.org/node/2718229"
        ],
        "merge-plugin": {
            "include": [
                "core/composer.json"
            ],
            "recurse": false,
            "replace": false,
            "merge-extra": false
        },
        "installer-paths": {
          "core": ["type:drupal-core"],
          "libraries/{$name}": ["type:drupal-library"],
          "modules/contrib/{$name}": ["type:drupal-module"],
          "profiles/contrib/{$name}": ["type:drupal-profile"],
          "themes/contrib/{$name}": ["type:drupal-theme"],
          "drush/contrib/{$name}": ["type:drupal-drush"],
          "modules/custom/{$name}": ["type:drupal-custom-module"],
          "themes/custom/{$name}": ["type:drupal-custom-theme"]
        },
        "enable-patching": true
    },
    "autoload": {
        "psr-4": {
            "Drupal\Core\Composer\": "core/lib/Drupal/Core/Composer"
        }
    },
    "scripts": {
        "pre-autoload-dump": "Drupal\Core\Composer\Composer::preAutoloadDump",
        "post-autoload-dump": [
          "Drupal\Core\Composer\Composer::ensureHtaccess"
        ],
        "post-package-install": "Drupal\Core\Composer\Composer::vendorTestCodeCleanup",
        "post-package-update": "Drupal\Core\Composer\Composer::vendorTestCodeCleanup",
        "post-install-cmd": [
            "bash scripts/remove_vendor_git_folders.sh || :"
        ],
        "post-update-cmd": [
            "bash scripts/remove_vendor_git_folders.sh || :"
        ]
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        {
            "type": "package",
            "package": {
                "name": "library-kenwheeler/slick",
                "version": "1.6.0",
                "type": "drupal-library",
                "source": {
                    "url": "https://github.com/kenwheeler/slick",
                    "type": "git",
                    "reference": "1.6.0"
                }
            }
        },
        {
            "type": "package",
            "package": {
                "name": "library-dinbror/blazy",
                "version": "1.8.2",
                "type": "drupal-library",
                "source": {
                    "url": "https://github.com/dinbror/blazy",
                    "type": "git",
                    "reference": "1.8.2"
                }
            }
        },
        {
            "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": "4.3.0",
                "type": "drupal-library",
                "source": {
                    "url": "https://github.com/enyo/dropzone",
                    "type": "git",
                    "reference": "v4.3.0"
                }
            }
        },
        {
            "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"
                }
            }
        }
    ]
}
  1. Add "ymcatwincities/openy": "8.*.*" to the require section in your composer.json, like here

  2. Add all required repositories that are listed here to your composer.json

  3. Add installer path as here to your composer json. See example.

  • composer.json inside of docroot Installer path will look like this:

    "installer-paths": {
        "core": ["type:drupal-core"],
        "libraries/{$name}": ["type:drupal-library"],
        "modules/contrib/{$name}": ["type:drupal-module"],
        "profiles/contrib/{$name}": ["type:drupal-profile"],
        "themes/contrib/{$name}": ["type:drupal-theme"],
        "drush/contrib/{$name}": ["type:drupal-drush"],
        "modules/custom/{$name}": ["type:drupal-custom-module"],
        "themes/custom/{$name}": ["type:drupal-custom-theme"]
    }
    
  • composer.json outside of docroot Installer path will look like this:

    "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"],
        "drush/contrib/{$name}": ["type:drupal-drush"],
        "docroot/modules/custom/{$name}": ["type:drupal-custom-module"],
        "docroot/themes/custom/{$name}": ["type:drupal-custom-theme"]
    }
    
  1. Add "cweagans/composer-patches": "~1.0" to the require section in you composer.json. See example.

  2. Add "enable-patching": true to the extra section in your composer.json See example.

  3. Add "secure-http": false to the config section in your composer.json See example.

  4. Remove composer.lock and vendor folder from the project if they are exist in your folder.

  5. Remove "replace" section from your composer.json

  6. (Optional) If you keep vendor folder in your git repository, we recommend to clean up project from .git folder inside modules and libraries. To do so

  • Add cleaner script to your project from Open Y composer package. You can just copy it and paste onto your project.

  • Adjust folders that you would like to cleanup

  • Execute it in post-install-cmd and post-update-cmd:

    "post-install-cmd": [
        "bash scripts/remove_vendor_git_folders.sh || :"
    ],
    "post-update-cmd": [
        "bash scripts/remove_vendor_git_folders.sh || :"
    ]
    
  1. Run composer install

CIBox

In this section you can learn how to configure development environment and CI server using Open Source product CIBox.

Create project

  1. Generate project based on this quickstart

  2. Add Open Y to the project using (Add Open Y to already existing Drupal 8 project)

  3. Init git and add initial commit

cd OPENY_PROJECT
git init
git commit -m "Init Open Y project"
git remote add origin git@github.com:NAMESPACE/PROJECT.git
git push -u origin master
  1. Spin up your local vagrant machine
vagrant up --provision
  1. Setup CI server for new project based on CIBox documentation.
  • Follow quick start starting from Jenkins Provisioning Step http://docs.cibox.tools/en/latest/Quickstart/#jenkins-provisioning (Here we will get PR builds and DEMO site (DEV environment) with credentials to it )
  • Setup hosting STAGE environment (it should be a 1:1 copy of existing or expected hosting account for ability to provide performance testing there)
  • Setup deployment plans for CI by reusing DEMO builder job

Install Open Y on DigitalOcean

  1. Create new Droplet using “One-click apps” image Drupal 8.*.* on 14.04
  2. Login to server via SSH or web console
  3. Run command
bash <(curl -s https://raw.githubusercontent.com/ymcatwincities/openy/8.x-1.x/build/openy-digital-ocean.sh)
  1. Open link(e.g. http://IP/core/install.php) from console output and finish Open Y installation

Video tutorial

Open Y v1.0b - Install Tutorial

End to end installation

Open Y install - in 16 minutes end to end, no tutorial

18 - Tests

These instructions explain how you can run tests.

Behat

Requirements

Run full test suite

  1. Execute command

    $ cd profiles/contrib/openy
    $ sh runtests.sh
    
  2. Open http://site.com/profiles/contrib/openy/build/reports/behat in browser.

Run selenium container + Behat tests in usual way

In order to run only selenium container + behat in usual way:

$ cd profiles/contrib/openy
$ sh runtests.sh --tags run_selenium
$ bin/behat

Stop selenium container

In order to stop selenium container:

$ cd profiles/contrib/openy
$ sh runtests.sh --tags stop_selenium

If necessary, edit behat.local.yml to match your environment.

Visual debugging - Video

When you develop JS tests, it’s important to see what’s going on the Selenium screen. You can easily see this during development.

  1. Install https://www.realvnc.com/download/viewer
  2. Run selenium using command
$ cd profiles/contrib/openy
$ sh runtests.sh --tags run_selenium
  1. Open installed VNC Viewer and connect to the server with IP 192.168.56.132:5901
  • Password = secret
  1. Run tests and you should see everything that is performed by behat tests in VNC client
$ bin/behat

Debugging JavaScript Behat tests

Custom Behat functionality

  • Create entities in table forms, with key to use in 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 key to use in 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 sub field/columns: The machine name and columns can be found in the form markup in the field name property. Inspect form field name depicted 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      |
    

19 - Theming and Design

Welcome to Open Y Theming and Design documentation.

How to change styles on content type level

Given: As an Open Y 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:

  • If you need to change CSS on some pages independently, you should enable Custom CSS functionality on the theme configuration page - Custom CSS - check “Enable or disable custom CSS”.
  • Input CSS code into the textarea.

In order to change CSS on each particular page you should use the following selectors:

  • .page-node-type-{node type};
  • .node-id-{node ID};
  • .path-frontpage.

The existing node types are: activity, alert, blog, branch, camp, class, facility, landing-page, membership, news, program, program-subcategory, session.

20 - Tour

How to use Open Y Tour Token with Tour

In someone modules have tour tips and for more interactivity, you can add a token with a click to any selector.

  1. In the module open tour yml file. Configuration project add/update form

  2. Select the tip for edit and in body add token like this [openy_tour:click:button_name:selector] Configuration project add/update form

  3. Create hook update for you changes and in command line run drush updb -y

Token components:

[openy_tour:click:button_name:selector]*

openy_tour - token name;

click - command in the token;

button_name - name of button when show in a tip;

selector - selector to be clicked.

Please see and use jQuery selectors.

21 - Upgrade path

All changes in configurations should be added to appropriate hook_update_N in order to update already existing environments. We suggest to use https://www.drupal.org/project/confi for working with hook_update_N.

openy.install in profile

In this file we should put updates that are related to the distribution in general and don’t fit into any feature.

  • Enable/Disable module
  • General configs

openy_*.install in modules

In case if you update some configuration for specific feature, make sure that you put updates into appropriate module.

Revert only specific property from config

With config_import module help we can update only part from full config.

For updating specific property in config (use service ‘openy_upgrade_tool.param_updater’):

  1. go to related to this config module

  2. create new hook_update_N in openy_*.install file

  3. in update add next code (this is example):

$config = drupal_get_path('module', 'openy_media_image') . '/config/install/views.view.images_library.yml';
$config_importer = \Drupal::service('openy_upgrade_tool.param_updater');
$config_importer->update($config, 'views.view.images_library', 'display.default.display_options.pager');

Where:

  • $config variable contains path to config with config name
  • “views.view.images_library” - config name
  • “display.default.display_options.pager” - config specific property (you can set value from a nested array with variable depth)

Revert full configs

For updating full config or several configs from directory use service ‘openy_upgrade_tool.importer’.

$config_dir = drupal_get_path('module', 'openy_media_image') . '/config/install';
$config_importer = \Drupal::service('openy_upgrade_tool.importer');
$config_importer->setDirectory($config_dir);
$config_importer->importConfigs(['views.view.images_library']);

Where:

  • $config_dir - path to directory with config
  • “views.view.images_library” - config name

Also you can update several configs from directory:

$config_importer->importConfigs([
  'views.view.images_library',
  'views.view.example_view',
]);