From 0109fb5f586f095fe222a4cca03938706024bbb8 Mon Sep 17 00:00:00 2001 From: nJim Date: Fri, 6 Oct 2023 10:36:32 -0400 Subject: [PATCH] docs (YALB-1204): updating all custom module readme files --- .../modules/custom/ys_alert/README.md | 12 ++++++-- .../modules/custom/ys_captcha/README.md | 23 +-------------- .../modules/custom/ys_core/README.md | 15 ++++++---- .../modules/custom/ys_layouts/README.md | 4 +++ .../modules/custom/ys_mail/README.md | 24 +--------------- .../modules/custom/ys_node_access/README.md | 4 +++ .../modules/custom/ys_secrets/README.md | 28 +------------------ .../modules/custom/ys_toolbar/README.md | 8 ++++++ .../modules/custom/ys_views_basic/README.md | 10 +++++++ 9 files changed, 48 insertions(+), 80 deletions(-) create mode 100644 web/profiles/custom/yalesites_profile/modules/custom/ys_layouts/README.md create mode 100644 web/profiles/custom/yalesites_profile/modules/custom/ys_node_access/README.md create mode 100644 web/profiles/custom/yalesites_profile/modules/custom/ys_toolbar/README.md create mode 100644 web/profiles/custom/yalesites_profile/modules/custom/ys_views_basic/README.md diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_alert/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_alert/README.md index 436aa138a6..f7a7ca7100 100644 --- a/web/profiles/custom/yalesites_profile/modules/custom/ys_alert/README.md +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_alert/README.md @@ -1,5 +1,11 @@ # YaleSites Alert -This module creates an alert banner to display a message across all pages of a -YaleSite. A backend interface allows site owners to enable or disable alerts. -Message can be an announcement, marketing, or emergency alert. +## Description +The YaleSite Alert Banner module enhances your website by providing a versatile alert banner that can display messages on all pages. Whether you want to make announcements, run marketing campaigns, or communicate emergency information, this module has got you covered. + +## Features +- **Alert Management Interface**: We offer a user-friendly admin interface at admin/yalesites/alert for efficient management of alerts. +- **Global Alert Display**: Enabled alerts are prominently displayed across all pages of your website, ensuring your message reaches your audience effectively. +- **Toggle Switch**: A convenient toggle switch allows site owners to enable or disable alerts at their convenience. +- **Alert Types**: Customize your message by specifying the alert type: announcement, marketing, or emergency. Each type has a different visual treatment and mechanism for minimizing or dismissing. +- **Confirmation Message**: For emergency alerts, we've added an extra layer of caution. Authors will receive a confirmation message before setting emergency alerts, helping prevent accidental broadcasts. diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_captcha/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_captcha/README.md index 8feba4298a..fd18350ca0 100644 --- a/web/profiles/custom/yalesites_profile/modules/custom/ys_captcha/README.md +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_captcha/README.md @@ -1,24 +1,3 @@ # YaleSites Recaptcha -This module customizes recaptcha settings for the YaleSites platform. - -This includes: - -- Setting the recaptcha v2 and v3 API keys from a value stored in a Terminus secrets file. -- Disabling the recaptcha API key field to improve the admin interface. - -## Requirements - -Recaptcha API keys must be set in a `secrets.json` file to use the service. -After enabling this module, verify that the API keys are set. - -```bash -lando drush config-get recaptcha.settings --include-overridden -lando drush config-get recaptcha_v3.settings --include-overridden -``` - -If this file is missing, then pull the latest files into the local environment. - -```bash -lando pull --database=none --files=dev --code=none -``` +This module ensures all sites on the YaleSites platform have Google ReCaptcha setup in a consistant way. Currently this module is only used to obfuscate the API keys within the Drupal admin interface. diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_core/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_core/README.md index 8edcfa9f98..08c940efb8 100644 --- a/web/profiles/custom/yalesites_profile/modules/custom/ys_core/README.md +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_core/README.md @@ -1,6 +1,11 @@ -# YaleSites Starterkit +# YaleSites Core -This module is used to organize custom functionality that is core to the -YaleSites platform. Code is included in the ys_core module if it does not fit -within an existing custom module. Custom code should be placed in a different -module if it can offer utility to non-YaleSites properties. +## Description +The YaleSites Core Functionality module serves as the central repository for organizing custom functionality that is fundamental to the YaleSites platform. Within this module, you'll find templates, assets, configuration overrides, and custom code that are vital for the seamless operation of all sites hosted on the platform. + +However, before adding new features or functionality to this module, platform developers are encouraged to contemplate the creation of separate custom modules. These custom modules can encapsulate specific sets of features, enhancing modularity and ensuring that the codebase remains clean and organized. This approach promotes a more efficient and maintainable development process for the YaleSites platform. + +## Features +- **Sitewide Elements**: This category covers a wide array of elements including plugins, forms, templates, and various assets used for managing sitewide components such as the site header, footer, and breadcrumbs. These elements may also extend into the styling realm within the Atomic theme and the component library. +- **Install Configuration**: The module houses default values for YaleSites-specific configuration files used during the creation of new sites on the platform. While technically not mandatory, maintaining these install files is considered a best practice, as they ensure consistency and serve as a reference point for values that should ideally reside in the profile's config/sync directory. +- **Hooks and Custom Functionality**: It provides a growing list of hooks for adding and altering form elements, tokens, caching rules, and website behavior. These hooks empower developers to customize and fine-tune the platform's behavior to meet specific requirements. diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_layouts/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_layouts/README.md new file mode 100644 index 0000000000..b53a6890de --- /dev/null +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_layouts/README.md @@ -0,0 +1,4 @@ +# YaleSites Layouts + +## Description +The layouts module organizes work related to YaleSite's implementation of Layout Builder. This includes the definition of custom layouts including the banner, page meta, and two column sections. diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_mail/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_mail/README.md index 5480d71253..81cb49613b 100644 --- a/web/profiles/custom/yalesites_profile/modules/custom/ys_mail/README.md +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_mail/README.md @@ -1,25 +1,3 @@ # YaleSites Mail -This module customizes emails sent from sites on the YaleSites platform. - -This includes: - -- Setting the MailChimp API from a value stored in a Terminus secrets file. -- Disabling the MailChimp API key field to improve the admin interface. -- Altering email metadata to ensure useful data is sent to MailChimp. - -## Requirements - -A MailChimp API key must be set in a `secrets.json` file to use the -transactional email service. After enabling this module, verify that -the api key is set. - -```bash -lando drush config-get mailchimp_transactional.settings mailchimp_transactional_api_key --include-overridden -``` - -If this file is missing, then pull the latest files into the local environment. - -```bash -lando pull --database=none --files=dev --code=none -``` +The YaleSites Mail module ensures all sites on the platform have the MailChimp transactional email handling setup in a consistant way. Currently this module is only used to obfuscate the API keys within the Drupal admin interface and make minor changes to email handling. \ No newline at end of file diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_node_access/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_node_access/README.md new file mode 100644 index 0000000000..912f8b47cc --- /dev/null +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_node_access/README.md @@ -0,0 +1,4 @@ +# YaleSites Node Access + +## Description +The YaleSites Node Access module offers a flexible mechanism that allows site authors to control access to the canonical view of a node exclusively for CAS authenticated users. This feature serves as a valuable tool for selectively restricting access to specific page content. However, it is important to note that this module is not intended to function as a secure repository for sensitive content. Other mechanisms within the platform may still expose assets and metadata associated with these nodes to users who are not authenticated, which means that sensitive content should be handled through alternative, more secure means. diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_secrets/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_secrets/README.md index ce93feb29a..478ff77bc9 100644 --- a/web/profiles/custom/yalesites_profile/modules/custom/ys_secrets/README.md +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_secrets/README.md @@ -1,29 +1,3 @@ # YaleSites Secrets Mannager -The YaleSites upstream project and all of its configurations are stored in a -public repository. As a result sensative information such as API keys are stored -in the Pantheon secrets.json file instead of the standard Drupal config YAML -files. Utilities in this module help to load API keys from the secrets file at -runtime. - -## How to add a secret API key to the platform - -Step 1. Within the Drupal interface add a fake API key with the value 'HIDDEN'. -Config-export the changes to store the value as stagged configuration. For -example, see: web/profiles/custom/yalesites_profile/config/sync/mailchimp_transactional.settings.yml - -Step 2. Disable the API key field within the Drupal interface using a -ys_mail_form_FORM_ID_alter() so that future site builders are not confused by -the 'HIDDEN' value. The `disableField` method is useful for disabling the field. -It is not obvious when Drupal's config-override system is being used to replace -a value so we want to leave clues for future developers. For example, see -ys_mail_form_mailchimp_transactional_admin_settings_alter() - -Step 3. Set the API key in the appropriate Pantheon environment. This will -require the [Terminus Secrets Plugin](https://github.com/pantheon-systems/terminus-secrets-plugin). -Following the format: `terminus secrets:set site.env key value` - -Step 4. Create a class to override Drupal configuration with values stored in -the secrets.json file. This class will map the name of the configuration in -Drupal with the key in the secrets.json file. See example: -Drupal/ys_mail/Config/MailConfigOverrides +This module is no longer used and can be removed once all sites adopt the new environmented variables. diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_toolbar/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_toolbar/README.md new file mode 100644 index 0000000000..6cb3306987 --- /dev/null +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_toolbar/README.md @@ -0,0 +1,8 @@ +# YaleSites Toolbar + +## Description +The YaleSites Toolbar module enhances the Drupal Admin toolbar, tailored to empower site owners in managing their websites effectively. This module integrates with and builds upon the Toolbar and Gin Toolbar modules, customizing the authoring experience for the YaleSites community. + +## Features +- **Enhanced Local Task Links**: The module introduces a collection of new local task links, offering quick access to essential functions such as editing, publishing, unpublishing, and changing the layout of a node. These links provide a consistent and efficient toolset for site authors, simplifying common tasks and streamlining content management. +- **Labels and Icons**: To enhance usability and user understanding, several toolbar items receive refreshed names and icons. This thoughtful approach establishes a standardized naming convention that aligns with Yale's training practices, ensuring that all authors have a clear grasp of content management intricacies. diff --git a/web/profiles/custom/yalesites_profile/modules/custom/ys_views_basic/README.md b/web/profiles/custom/yalesites_profile/modules/custom/ys_views_basic/README.md new file mode 100644 index 0000000000..128e633bb3 --- /dev/null +++ b/web/profiles/custom/yalesites_profile/modules/custom/ys_views_basic/README.md @@ -0,0 +1,10 @@ +# YaleSites Views Basic + +## Description +The View Basic module is a custom utility, built on Drupal Views, that gives advanced users with the ability to generate dynamic content lists based on content metadata. This feature lets users curate the collections of news, events, people, and pages across various sections of their website more effectively. This module serves as a valuable resource for authors seeking to create multiple content streams, leveraging taxonomy and other filters to tailor their content displays. It gives them the ability to create custom queries with little training and in a no-code interface. + +## Features +- **Field Plugin**: Data describing a view is stored within a custom schema as a serialized object. This modular design allows for seamless addition and removal of features without compromising metadata storage integrity. +- **Field Widget**: Users interact with a specialized form for constructing queries and render logic using a user-friendly, no-code interface. Natural language and intuitive icons simplify query building, requiring minimal training for authors. +- **Field Formatter**: Metadata is rendered consistently through custom templates, blocks, display modes, and a Drupal View. This consistency ensures that content creators construct Views that align with the YaleSites Design System. +- **View Plugins**: The module incorporates numerous view plugins that interpret view definitions into sorts, filters, pagers, and styles compatible with the core Drupal Views module, enhancing functionality and flexibility.