Skip to content
Snippets Groups Projects
Commit 2c7c60a6 authored by Joe 🤘 Shindelar's avatar Joe 🤘 Shindelar Committed by Adam G-H
Browse files

Issue #3473439 by eojthebrave, phenaproxima: Create a few POC pages for a future Drupal CMS Guide

parent 88fb69c4
No related branches found
No related tags found
1 merge request!82Initial pass at example pages for future Drupal CMS Guide.
Pipeline #280391 passed
Showing
with 400 additions and 0 deletions
......@@ -6,3 +6,4 @@ patches.lock.json
/web
/.editorconfig
/.gitattributes
.DS_Store
......@@ -36,6 +36,8 @@ build project:
paths:
- project
expire_in: 1 hour
rules:
- when: on_success
build trial artifact:
stage: build
......@@ -47,6 +49,8 @@ build trial artifact:
- trial.zip
expire_in: 1 day
public: true
rules:
- when: on_success
run tests:
stage: test
......@@ -66,6 +70,8 @@ run tests:
- project/$_WEB_ROOT/sites/simpletest
when: on_failure
expire_in: 1 week
rules:
- when: on_success
run trial tests:
stage: test
......@@ -76,6 +82,19 @@ run trial tests:
- cd trial
- npm clean-install
- npm run test
rules:
- when: on_success
# Check spelling in the documentation.
check spelling:
stage: test
rules:
# Only do this if Markdown files in the docs directory changed because of
# a push, or a change in a merge request.
- if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_PIPELINE_SOURCE == "push"
changes:
- docs/**/*.md
script: npx cspell --show-suggestions --show-context --no-progress docs
# Build trial. This job name is pre-defined by GitLab, it has to be "pages".
pages:
......
......@@ -46,3 +46,6 @@
[trial experience track] @mglaman
/trial/
[documentation] @amberhimesmatz @eojthebrave
/docs/
# Demo Documentation
The docs here are incomplete, and are not currently intended for public consumption. Rather, they are an example of what an eventual Drupal CMS Guide might look like and a place to start working out an outline and formatting conventions.
There are three example pages that document a sub-set of the Events recipe's features:
- [Concept: Events](./features/events/events--overview.md)
- [Create a Single Event](./features/events/events--create-single.md)
- [Create a Recurring Event](./features/events/events--create--recurring.md)
## Conventions
Any text that appears in the user interface is formatted in italics and should be written exactly as it appears in the interface.
Examples:
```md
Choose the _Extend_ option from the navigation.
Check the box for the _Block content_ module then scroll to the bottom of the page and press the _Save_ button.
Select the _Add another item_ button.
```
Stubbed links are enclosed by square brackets and point to a non-existent /bad-links.md file. This consistency makes them easier to find, and fix, later.
Example:
```md
[this is a link](/bad-link.md)
```
## Guide content types
Types of content in the guide:
### Concepts
- Illuminate a specific topic with background knowledge, term definitions, and examples.
- Provide an overview of the use cases for a feature, helping the learner envision how they might solve their own problems.
- Discuss what tacos are, rather than a step-by-step recipe for how to make a taco.
### Tasks / Tutorials
- Provide step-by-step instructions on how to complete a specific task.
- Learning-oriented, especially learning by doing.
- Focus on learning _how_ rather than learning _what_.
- Help a learner understand how to accomplish a task, and gain confidence in applying the skills to their own specific use case.
---
id: toc
---
# Table of Contents
_Example of what a broader Drupal CMS Guide table of contents might look like._
This is a parsed-down simplified version of the Table of Contents with emphasis on the Events and Locations sections, and the Starshot tracks.
- Get started
- Install Drupal CMS
- Log in for the first time
- Concept: Dashboard
- Set up your first user account
- Get to know Drupal CMS
- Create a site
- Features (aka. recipes)
- Modules
- Structure
- Appearance
- Layouts
- Configuration
- Manage content
- Concept: Content administration
- Tour the Drupal CMS Text Editor
- How to use the AI assistant in the editor
- Concept: Publishing workflows
- Concept: Accessible content
- Basic pages
- Blog posts
- Events
- [Concept: Events](./features/events/events--overview.md)
- [Create a single event](./features/events/events--create-single.md)
- [Create a recurring event](./features/events/events--create-recurring.md)
- Customize the event content type
- Configure the event listing and calendar pages
- Locations
- Concept: Locations
- Create a location
- Blocks
- Media
- Webforms
- Translate content
- Customize your site
- Change the appearance of your site
- Configure your site
- Manage data privacy and compliance (GDPR/CCP)
- Configure site search
- Set up a multilingual site
- Manage people on your site
- Access reports and logs
- Site analytics
- Promote your site
- Optimize your site for search engines (SEO)
- Keep your site up-to-date
- Concept: Automatic Updates
- Set up your site for automatic updates
starshot
webforms
{
"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
"version": "0.2",
"language": "en-US",
"dictionaryDefinitions": [
{
"name": "drupal",
"path": "cspell-dictionary.txt",
"addWords": true
}
],
"dictionaries": [
"drupal"
],
"ignorePaths": [
"cspell-dictionary.txt"
]
}
---
id: events--create-recurring
title: Create a Recurring Event
---
# Create a Recurring Event
## Summary
Have a weekly team call, or need to schedule a volunteer training that takes place at the same time from 9:00 am to 11:00 am over 3 consecutive days? Save time by creating a recurring event instead of multiple single events.
## Goal
Publish an event that repeats.
## Prerequisites
The Events feature must be enabled. If this was not done when the site was initially created, enable it before continuing. Learn more in [Enabling a New Feature](/bad-link.md). After the feature is enabled, it must be configured for recurring events. See the “Configure Drupal CMS for recurring events” section below.
## Configure Drupal CMS for recurring events
Before a content editor can create recurring events, an administrator will need to add a module and configure it.
1. Install the _Smart Date Recurring_ module. Learn how to [install modules](/bad-link.md).
1. Edit the _When_ field for the _Event_ content type. In the _Administration Toolbar_, navigate to _Structure_ > _Content types > Event_. Select the _Manage fields_ button for the _Event_ content type, then select the _Edit_ button for the _When_ field in the field list. (_/admin/structure/types/manage/event/fields/node.event.field\_when_).
1. Toggle _Allow recurring date values_ to **on**.
<!-- 📸Screenshot: Field settings form for smart date field with recurring date values option toggled on. -->
![Form widget showing "Allow recurring date values" toggle toggled on.](./images/events-field-recurring-dates-enabled.png)
1. Select _Save settings_ to update the field settings.
A content editor will now be able to use the recurring dates feature with Drupal CMS Events.
## How to create and publish a recurring event
1. In the _Administration Toolbar_ navigate to _Create_ > _Event_ (_/admin/event_).
1. Fill in the _Create Event_ form with the details for your event.
**Title:** Enter a name for the event.
**When:** Start by entering the date and time of the **first** occurrence of the event.
Then configure the repeating sequence:
1. Choose a repeating frequency (for example, daily or monthly).
1. Set the relevant time frame for the event to repeat (for example, every 2 weeks). For events that repeat on specific days, open the _Advanced_ configuration, and choose the day(s) the event should repeat on.
1. Configure when the recurring event will end by entering a specific number of occurrences or a specific date using the _Ends_ field.
<!-- 📸Screenshot: Smart date field on event node configured to recur every other Tuesday. -->
![Date field on event node configured to recur every other Tuesday.](./images/event-create-repeating-date-widget.png)
**Where:** Choose a location for the event from the list of available locations. To add new locations to the list see [Add a Location](/bad-link.md).
**Body:** Add a detailed description of the event. The description can include formatted text, images, and other media. Learn more about [using the Drupal CMS text editor](/bad-link.md) and how to [manage media](/bad-link.md).
By default, a trimmed version of the description is used on the _Events_ listing page. For more control over the content of the summary, select the _Edit summary_ link and fill in the _Summary_ field.
1. In the editor sidebar, the event’s _Current state_ value defaults to _Draft_. Leave it as _Draft_ to save the event as a draft. Or, set _Change to_ to _Published_, if you’re ready to publish the event. Draft events are only viewable by editors. Once published, the event will become available to the public.
<!-- 📸Screenshot: Cropped image of publish/draft area of form. Repeat from previous tutorial. -->
![Form widget for changing node status. Currently set to "Draft".](./images/event-publish-draft-widget.png)
4. Select the _Save_ button.
### Override a specific instance of a recurring event
What if you need to override a single occurrence of a recurring event? For example, an event that occurs once a week on Tuesday needs to be canceled on the date that it overlaps with a holiday.
1. In the _Administration Toolbar_, navigate to _Content_ (_/admin/content_).
1. Filter the list to display _Content type: Events_.
1. Find the event in the list and select the _Edit_ button.
1. Select the _Manage instances_ button for the _When_ field.
<!-- 📸Screenshot: Of editing the "When" field with the manage instances button highlighted. -->
![Date field widget with "Manage instances" button highlighted.](./images/event-manage-instances-button.png)
1. A modal window opens listing all future dates for the event. Find the one you wish to modify and select the _Override_ button.
### Add a one-off date to a recurring event
Add a specific date that falls outside the recurring schedule for special events, or other exceptions.
1. Edit the recurring event.
1. Under the _When_ section of the event form, select the _Add another item_ button to add an additional date that occurs outside of the recurring schedule.
1. Set the date and time of the one-off date.
1. Select the _Save_ button to save the updated event.
<!-- 📸Screenshot: "When" field on Event form with multiple date values added. One for "Every other Tuesday", and one for a "random Monday in September". -->
![Date field widget with multiple values added. Second value in list highlighted to show where to find it.](./images/event-create-repeating-date-widget-add-more.png)
## Feedback
Was this helpful? [yes] | [no]
### Additional resources
- [Configure Content Types](/bad-link.md)
- [Add a Module](/bad-link.md)
- [Concept: Events](./events--overview.md)
- [Add a Single Event](./events--create-single.md)
---
id: events--create-single
title: Create a Single Event
---
# Create a Single Event
## Summary
Learn to create one-off events like a meeting or a party. Start by creating and previewing an event draft. When everything looks good, publish the event, and share it with the world.
## Goal
Publish a new single occurrence event.
## Prerequisites
The Events feature must be enabled. If this was not done when the site was initially created, enable it before continuing. Learn more in [Enabling a New Feature](/bad-link.md).
## How to create and publish one-off events
!!! note "Tip"
If you create the same event more than once, save time by [creating a recurring event](./events--create-recurring.md).
### Create an event draft
1. In the _Administration Toolbar_ navigate to _Create_ > _Event_ (_/admin/event_).
<!-- 📸Screenshot: Cropped screenshot of admin toolbar showing where to find add an event in the menu. -->
![Admin toolbar expanded to show "Create" section with "Event" highlighted.](./images/create-event-menu.png)
1. Fill in the _Create Event_ form with the details for your event.
**Title:** Enter a name for the event.
**When:** Enter the dates and times for when the event begins and ends. Or choose *All day* for events that don’t have a specific time. For single occurrence events, enter *Repeats: never*.
Tip: For events that happen more than once, but don’t follow any specific recurring pattern like weekly, or every 2nd Monday, you can add additional single dates for the same event by selecting the _Add another item_ option.
**Where:** Choose a location for the event from the list of available locations. To add new locations to the list see [Add a Location](/bad-link.md).
**Body:** Add a detailed description of the event. The description can include formatted text, images, and other media. Learn more about how to [use the Drupal CMS text editor](/bad-link.md) and [manage media](/bad-link.md).
By default, a trimmed version of the description is used on the Events listing page. For more control over the content of the summary, select the *Edit summary* link and fill in the *Summary* field.
<!-- 📸Screenshot: Event note form with form filled in. Cropped to show just the form. -->
![Form for creating a new Event node.](./images/create-event-form.png)
1. In the editor sidebar, the Event’s _Current state_ will default to _Draft_. Leave it as _Draft_ to save the event as a draft. Or, set _Change to_ to _Published_ if you’re ready to publish the event. Draft events are only viewable by editors. Once published, the event will become available to the public.
<!-- 📸Screenshot: Cropped image of publish/save section of event create form. -->
![Form widget for changing node status. Currently set to "Draft".](./images/event-publish-draft-widget.png)
1. Select the _Save_ button.
### Publish an event
After creating a draft of the event and previewing the content to ensure it looks correct, publish your event to share it with the world.
To publish an event:
1. In the _Administration Toolbar_, navigate to _Content_ (_/admin/content_).
1. Filter the list to display _Content type: Events_ and _Published status: Draft_.
1. Find the event in the list and select the _Edit_ button.
1. In the sidebar, the _Current status_ should be _Draft_. Set _Change to_ to _Published_.
1. Select the _Save_ button.
<!-- 📸Screenshot: Cropped image of publish/save section of event form editing an existing event node. -->
![Form widget for changing a nod status. Displaying changing select field value from Draft to Published.](./images/event-publish-change-widget.png)
Your event is now available to the public and can be found on your site’s _Events_ listing and _Calendar_ pages.
## FAQs
- Q: Can I share the drafts I created with other editors?
A: Yes.
- Q: Can I change a published event back to a draft?
A: No. But you can create a new draft version of an event with edits that need to be reviewed. Or, you can remove an event from your public website by changing its status to _Archived_. Learn more about [publishing workflows](/bad-link.md).
### Feedback
Was this helpful? [yes] | [no]
### Additional resources
- [Create a Recurring Event](./events--create-recurring.md)
- [Configuring the Event Listing and Calendar Pages](/bad-link.md)
- [Concept: Events](./events--overview.md)
---
id: events--overview
title: "Concept: Events"
---
# Concept: Events
## Summary
Whether you are planning a meeting, hosting a party, or getting people together for a weekly coffee, Drupal CMS Events let you tell others about your event.
## What are Drupal CMS Events?
The events feature consists of an _Event_ content type with a date field, and pre-configured listing pages such as a calendar and an archive. Whether you’re building a calendar to track community meetings, a site for listing upcoming games for your soccer league, or the capability of tracking who is registered for an upcoming workshop, the Drupal CMS Events feature is a great starting point.
### Events feature
In order to use the events capabilities the Drupal CMS Events, and Events Locations features must be enabled. Learn more in [Enabling New Features](/bad-link.md).
### Single or recurring events
With Drupal CMS, you can either [create single events](./events--create-single.md) or [create recurring events](./events--create-recurring.md).
If you regularly host the same event, there's no need to start from scratch each time. By setting up a [recurring event](./events--create-recurring.md), you can streamline the process and save time, while still having the flexibility to adjust individual instances.
<!-- 📸Screenshot: A screenshot of an event node page showing example event with location field configured to display as a map. -->
![Event details page showing an event named "Trivia Night"](./images/event-details-view.png)
### Browse events
Your site’s users can browse a list of future and past events on the provided _Events_ listing or _Events Calendar_ pages. Both pages can be customized to meet your site’s needs.
<!-- 📸Screenshot: Calendar page provided by events recipe with some example events on it. -->
![Event calendar listing page showing the month of September with some events populated on the calendar.](./images/events-calendar-view.png)
### View detailed event information
Visitors can select any event in the Events listing or Calendar pages to view event-specific details. This includes a detailed description of the event (including media), a map (for events with a location), and date and time information. All of which can be customized for your specific use case.
The event details page includes handy _Add to calendar_ links to make it straightforward for visitors to add an event to their calendar.
### Manage your guests
With the Event Registration feature enabled, visitors can RSVP to an event, and event managers can see who is coming, email participants, print a list of attendees, check in attendees when they arrive, and more.
### Custom event details
Like all Drupal CMS content types, the base event content type can be extended by adding application-specific fields. Add categories for event types, collect and display links for online meeting spaces, or add a field for uploading event specific documents. Learn more in [Managing Drupal CMS Content Types](/bad-link.md).
## Feedback
Was this tutorial helpful? [yes] | [no]
## Additional resources
- [Create a Single Event](events--create-single.md)
- [Create a Recurring Event](events--create-recurring.md)
- [Manage Drupal CMS Content Types](/bad-link.md)
- [Concept: Features](/bad-link.md)
- [Enabling New Features](/bad-link.md)
docs/features/events/images/create-event-form.png

481 KiB

docs/features/events/images/create-event-menu.png

196 KiB

docs/features/events/images/event-create-repeating-date-widget-add-more.png

178 KiB

docs/features/events/images/event-create-repeating-date-widget.png

118 KiB

docs/features/events/images/event-details-view.png

1.58 MiB

docs/features/events/images/event-manage-instances-button.png

99.1 KiB

docs/features/events/images/event-publish-change-widget.png

137 KiB

docs/features/events/images/event-publish-draft-widget.png

71.9 KiB

docs/features/events/images/events-calendar-view.png

207 KiB

docs/features/events/images/events-field-recurring-dates-enabled.png

62.2 KiB

0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment