Merge pull request #90 from froboy/june-docs

PEF Schedules/Group Schedules

content/en/docs/howto/avoid-outdated-config/_index.md

@@ -0,0 +1,59 @@
+---
+title: How to avoid outdated configuration
+linkTitle: avoid outdated configuration
+description: Managing config across versions of a module can result in unexpected challenges.
+---
+
+Sometimes, in the process of making successive config changes, we need to maintain old config files so that outdated update hooks can still run successfully for sites who 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.
+
+In order to enable our modules to move quickly and minimize the need for developers to [stop their update process at important versions](../../development/important-versions-for-upgrade-path#important-versions), we have come up with a process of retaining "outdated" configuration when necessary.
+
+## Overview
+
+This process ends up with a configuration directory that looks like:
+
+```shell
+config/
+|- 1.0/
+|--- a.bunch.of.yml
+|- 1.3/
+|--- some.different.yml
+|- install/
+|--- the.regular.yml
+|- optional/
+|--- other.optional.yml
+| etc
+```
+
+See a few examples:
+
+- [ws_event - MR !72](https://git.drupalcode.org/project/ws_event/-/merge_requests/72)
+- [lb_accordion - MR !24](https://git.drupalcode.org/project/lb_accordion/-/merge_requests/24)
+- [lb_cards - MR !45](https://git.drupalcode.org/project/lb_cards/-/merge_requests/45)
+
+## Fixing an update hook
+
+1. Find the version of the module where the failing update hook was committed.
+2. Checkout or download the old version to a separate working directory.
+3. Copy all config files that are being imported in that hook into a new
+ directory, like `config/outdated/x.x.x`.
+4. Change the `$path` line in the failing update hook, changing
+ `/config/optional` to `/config/outdated/x.x.x`.
+5. Commit those changes and test thoroughly.
+
+## Warning signs
+
+The error above is the most significant indicator of an issue, but it would be optimal to avoid those errors altogether.
+
+Look out for changes in these types of files:
+
+`core.entity_form_display.block_content.*.default.yml`
+`core.entity_view_display.block_content.*.default`
+
+Adding or removing major features or fields could also result in the error.

content/en/docs/user-documentation/layout-builder/repeat-schedules/_index.md

@@ -0,0 +1,21 @@
+---
+title: Repeat Schedules
+description: Place the Repeat Schedules application in a Layout Builder page.
+tags:
+ - "Group Schedules"
+---
+
+Repeat Schedules combines data from [the Activity, Class, and Session](../../content-types/activity-class-session/) content types into an interactive tool. Learn more about [Group Schedules](../../schedules/group-schedules).
+
+Before you can use the Repeat Schedules block, you will need to:
+
+- Ensure the `openy_repeat` module is updated to [at least 2.2.0](https:/ynorth-projects/openy_repeat/releases).
+- Enable the **Repeat (Group) Schedules** (`lb_repeat_schedules`) module at **Admin** > **Extend** (`/admin/modules`).
+
+{{< readfile "../lb-add-block.partial" >}}
+
+Configure the options:
+
+- See [Group Schedules Block Configuration](../../schedules/group-schedules#block-configuration) for configuration details.
+
+{{< readfile "../lb-save-block.partial" >}}

content/en/docs/user-documentation/paragraphs/repeat-schedules/_index.md

@@ -1,9 +1,14 @@
 ---
 title: Repeat Schedules
 description: Display programs in a schedule view with an optional PDF export.
-tags: "Group Schedules"
+tags:
+ - "Group Schedules"
 ---
 
+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.
+
+See [Group Schedules](../../schedules/group-schedules) for more details.
+
 ## Examples
 
 [On the sandbox site](https://sandbox-carnation-cus.y.org/schedules-0).
@@ -16,27 +21,9 @@ To use the Repeat Schedules paragraph:
 
 - Expand the **Content Area** on a Landing Page.
 - Choose **Add Repeat Schedules**.
-- 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 aith autocomplete to only show certain categories.
- - **Filters** - choose the filters that show up in the sidebar.
- - **Limit by Location** - choose a location to only show events from that location.
- - **Display instructor**
- - **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.
+- See [Group Schedules Block Configuration](../../schedules/group-schedules#block-configuration) for configuration details.
 - Save the page.
 
 ## What fields are where
 
-Data from Session, Class, 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:
-
-![A diagram listing the relationships between the fields in Repeat Schedules table and their names.](repeat-schedules--table-fields.png)
-
-Fields used in the popup view:
-
-![A diagram listing the relationships between the fields in Repeat Schedules modal and their names.](repeat-schedules--modal-fields.png)
-
+See [Group Schedules Front-end](../../schedules/group-schedules#front-end).

content/en/docs/user-documentation/schedules/group-schedules/_index.md

@@ -2,15 +2,42 @@
 title: Group Schedules
 description: Displays daily group exercise classes with filters and a PDF download.
 tags:
- - "Decoupled Applications"
- - "Group Schedules"
+  - "Decoupled Applications"
+  - "Group Schedules"
 ---
 
-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. You can see [an example of this on our sandbox site](https://sandbox-carnation-cus.y.org/schedules-0).
+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](https://sandbox-carnation-cus.y.org/schedules-0).
 
 Developers can find more information in [`ynorth-project/openy_repeat`](https:/ynorth-projects/openy_repeat) and [Program Event Framework](../../../development/program-event-framework).
 
 ## Using Group Schedules
 
 - [Repeat Schedules Paragraph](../../paragraphs/repeat-schedules)
-- Using Repeat Schedules in Layout Builder is not yet supported.
+- [Repeat Schedules Layout Builder](../../layout-builder/repeat-schedules)
+ - Available with `openy_repeat` [2.2.0 and above](https:/ynorth-projects/openy_repeat/releases) 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.
+- **Limit by Location** - choose a location to only show events from that location.
+- **Display instructor**
+- **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:
+
+![A diagram listing the relationships between the fields in the Repeat Schedules table and their names.](repeat-schedules--table-fields.png)
+
+Fields used in the popup view:
+
+![A diagram listing the relationships between the fields in the Repeat Schedules modal and their names.](repeat-schedules--modal-fields.png)

content/en/docs/user-documentation/schedules/simple-schedules/_index.md

@@ -9,4 +9,86 @@ tags:
 
 See [PEF Schedules](../../../development/program-event-framework/pef-schedules) for installation instructions.
 
-User instructions are coming soon.
+Once you install the PEF Schedules module, you will be able to build schedules and add sessions via a calendar-based builder.
+
+## Before you start
+
+### Create schedule groupings
+
+The Schedule editor allows Content Editors to create Sessions on a "WYSIWYG" calendar interface. As described in the [PEF data model](../../../development/program-event-framework#data-model), [Sessions](../../content-types/activity-class-session#session) require [Classes](../../content-types/activity-class-session#class), which require [Activities](../../content-types/activity-class-session#activity), which require [Program Subcategories](../../content-types/program-subcategory), which require [Programs](../../content-types/program).
+
+```mermaid
+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.
+
+![An example of different colored Activity labels](simple-schedules--activity-colors.png)
+
+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](../../../development/colorways#base-variables). 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`).
+
+Options include:
+
+- Slot settings - These relate to creating events on the calendar.
+ - **Slot Duration** - The default length of each time slot.
+ - **Snap Duration** - The default granularity to which events "snap" when clicking and dragging on the calendar.
+ - **Slot Label Interval** - The interval between time labels on the calendar's time axis.
+- 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.
+ - **Max Time** - The latest time that is visible on the calendar view.
+
+## 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.
+
+![A description of the options available when managing the schedule.](simple-schedules--manage.png)
+
+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.
+
+![The options available when creating a session.](simple-schedules--create.png)
+
+- 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:
+
+1. All items added via the Simple Schedule will be shown in [Activity Finder](../activity-finder) or [Group Schedules](../group-schedules). Follow the directions on those pages to configure the respective components and add them to a page.
+2. Download the schedule PDF and upload it somewhere on your site.