Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

Add technical docs

Mir Bhatia8791d7dd98da
diff --git a/app/components/op_primer/email_updates_mode_selector_component.rb b/app/components/op_primer/email_updates_mode_selector_component.rb
index d734537e663..26b7aecb1c4 100644
--- a/app/components/op_primer/email_updates_mode_selector_component.rb
+++ b/app/components/op_primer/email_updates_mode_selector_component.rb
@@ -29,7 +29,7 @@
#++
module OpPrimer
- class EmailUpdatesModeSelectorComponent < Primer::Component # rubocop:disable OpenProject/AddPreviewForViewComponent
+ class EmailUpdatesModeSelectorComponent < Primer::Component
include OpTurbo::Streamable
include OpPrimer::ComponentHelpers
diff --git a/lookbook/docs/components/email_updates_mode.md.erb b/lookbook/docs/components/email-updates-mode-selector.md.erb
similarity index 56%
rename from lookbook/docs/components/email_updates_mode.md.erb
rename to lookbook/docs/components/email-updates-mode-selector.md.erb
index 9694f16bce8..fb4f63ea092 100644
--- a/lookbook/docs/components/email_updates_mode.md.erb
+++ b/lookbook/docs/components/email-updates-mode-selector.md.erb
@@ -1,16 +1,16 @@
-The Email Updates Mode selector is used to let users enable or disable automatic email updates when significant events take place. It serves as both a mode indicator and, if the user has the necessary permissions, control to change the mode.
+The Email Updates Mode Selector is used to let users enable or disable automatic email updates when significant events take place. It serves as both a mode indicator and, if the user has the necessary permissions, control to change the mode.
## Overview
-[Code example here]
+<%= embed OpPrimer::EmailUpdatesModeSelectorComponentPreview, :playground %>
## Anatomy
The component is simple: it consists of a static header, a text that indicates mode (and what that status means) and, in some cases, a button to change the mode.
-The current mode is always indicated in bold.
+The current mode is always indicated in bold.
-The action to change the mode (often 'Enable' or 'Disable') is a button with scheme `link`, with a leading icon. If a suitable leading icon is not available, it can also be used without an icon.
+The action to change the mode (often 'Enable' or 'Disable') is a button with scheme `link`, with a leading icon. If a suitable leading icon is not available, it can also be used without an icon.
This action is not present in some views; for example, if it is not possible to change the mode in the current view. (For example, in an occurrence of a meeting series, this component simply indicates mode; the actual change has to happen in the meeting template and the text is updated to convey this).
@@ -22,7 +22,6 @@ This action is not present in some views; for example, if it is not possible to
- Use simple, non-jargon language when describing what the current mode is doing.
- If the information concerning current mode is not relevant in a particular view (eg. if a meeting is closed or the user does not have any rights to modify the state), then hide the component altogether.
-
**Don't**
- Do not use this component when a checkbox or a toggle is more relevant. However, because toggle switches are activated immediately and the request sent asynchronously before a form submit (regardless of whether the request is successful or not), they might not always be the right component to use. This is the case for email updates.
@@ -32,13 +31,25 @@ This action is not present in some views; for example, if it is not possible to
The component is used in:
* Meetings to indicate (and, when the user has the necessary permissions, control) the automatic sending of updated calendar invites by email to all participants when there are significant changes to meeting details, such as date, time or location.
-* File storage health check email updates to admins
+* File storage health check email updates to admins.
+## Examples
-## Technical notes
+For detailed examples have a look at the other [preview examples](/lookbook/inspect/OpenProject/Primer/email_updates_mode_selector/playground) of the component.
+
+This is an example playground of the `OpPrimer::EmailUpdatesModeSelectorComponent`.
-[Add info if necessary, else remove section]
+<%= embed OpPrimer::EmailUpdatesModeSelectorComponentPreview, :playground, panels: %i[params source] %>
+
+## Technical notes
-### Code structure
+The parameters that can be passed are:
-[Add info if necessary, else remove section]
\ No newline at end of file
+* `toggle`: (required) the boolean attribute that is being toggled (e.g. `@meeting.notify?`, `@storage.health_notifications_should_be_sent?`)
+* `path`: (required) the path for the toggle button
+* `title`: (required) the title of the sidebar section
+* `enabled_description`: (required) the description when email updates are enabled
+* `disabled_description`: (required) the description when email updates are disabled
+* `alt_text`: (optional, but required when setting `show_button`) the alternative text displayed when the toggle button is hidden - defaults to `nil`
+* `show_button`: (optional) a boolean/conditional value that sets when the button is hidden and `alt_text` is shown instead - defaults to `true`
+* `method`: (optional) the method for the toggle button - defaults to `:get`
diff --git a/lookbook/previews/op_primer/email_updates_mode_selector_component_preview.rb b/lookbook/previews/op_primer/email_updates_mode_selector_component_preview.rb
new file mode 100644
index 00000000000..979c9cc1c32
--- /dev/null
+++ b/lookbook/previews/op_primer/email_updates_mode_selector_component_preview.rb
@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+module OpPrimer
+ # @logical_path OpenProject/Primer
+ class EmailUpdatesModeSelectorComponentPreview < Lookbook::Preview
+ # See the [component documentation](/lookbook/pages/components/email_updates_mode_selector) for more details.
+ # @param toggle [Boolean]
+ # @param path [String]
+ # @param title [String]
+ # @param enabled_description [String]
+ # @param disabled_description [String]
+ # @param alt_text [String]
+ # @param show_button [Boolean]
+ # @param method [Symbol] select [get, post, patch]
+ def playground(
+ toggle: true,
+ path: "/projects/demo-project/meetings/113/toggle_notifications",
+ title: "Sidebar component title",
+ enabled_description: "Email updates are enabled for all users.",
+ disabled_description: "Email updates are disabled for all users.",
+ alt_text: "To change this, edit the series template.",
+ show_button: true,
+ method: :patch
+ )
+ render OpPrimer::EmailUpdatesModeSelectorComponent.new(
+ toggle:,
+ path:,
+ title:,
+ enabled_description:,
+ disabled_description:,
+ alt_text:,
+ show_button:,
+ method:
+ )
+ end
+
+ def enabled(toggle: true, path: "", title: "Sidebar component title",
+ enabled_description: "Email updates are enabled for all users.",
+ disabled_description: "Email updates are disabled for all users.")
+ render OpPrimer::EmailUpdatesModeSelectorComponent.new(
+ toggle:,
+ path:,
+ title:,
+ enabled_description:,
+ disabled_description:
+ )
+ end
+
+ def disabled(toggle: false, path: "", title: "Sidebar component title",
+ enabled_description: "Email updates are enabled for all users.",
+ disabled_description: "Email updates are disabled for all users.")
+ render OpPrimer::EmailUpdatesModeSelectorComponent.new(
+ toggle:,
+ path:,
+ title:,
+ enabled_description:,
+ disabled_description:
+ )
+ end
+
+ def with_conditional_alt_text(toggle: true, path: "", title: "Sidebar component title",
+ enabled_description: "Email updates are enabled for all users.",
+ disabled_description: "Email updates are disabled for all users.",
+ alt_text: "To change this, edit the series template.", show_button: false)
+ render OpPrimer::EmailUpdatesModeSelectorComponent.new(
+ toggle:,
+ path:,
+ title:,
+ enabled_description:,
+ disabled_description:,
+ alt_text:,
+ show_button:
+ )
+ end
+
+ def with_different_button_method(toggle: true, path: "", title: "Sidebar component title",
+ enabled_description: "Email updates are enabled for all users.",
+ disabled_description: "Email updates are disabled for all users.", method: :patch)
+ render OpPrimer::EmailUpdatesModeSelectorComponent.new(
+ toggle:,
+ path:,
+ title:,
+ enabled_description:,
+ disabled_description:,
+ method:
+ )
+ end
+ end
+end