From 4e7bf203baa68bbf823d8fee34c4ed073692499e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20G=C3=BCnther?= Date: Tue, 1 Apr 2025 15:51:20 +0200 Subject: [PATCH] Docs --- .../enterprise_edition/banner_component.rb | 2 - .../upsale_buttons_component.rb | 4 +- config/static_links.yml | 2 +- .../patterns/18-enterprise-components.md.erb | 79 +++++++++++++++++++ .../banner_component_preview.rb | 4 +- .../upsale_page_component_preview.rb | 8 +- .../banner_component_spec.rb | 4 +- 7 files changed, 90 insertions(+), 13 deletions(-) create mode 100644 lookbook/docs/patterns/18-enterprise-components.md.erb diff --git a/app/components/enterprise_edition/banner_component.rb b/app/components/enterprise_edition/banner_component.rb index 2eefef0cc33..53830c76db5 100644 --- a/app/components/enterprise_edition/banner_component.rb +++ b/app/components/enterprise_edition/banner_component.rb @@ -62,8 +62,6 @@ module EnterpriseEdition private - attr_reader :skip_render - def render? !(EnterpriseToken.hide_banners? || feature_available? || dismissed?) end diff --git a/app/components/enterprise_edition/upsale_buttons_component.rb b/app/components/enterprise_edition/upsale_buttons_component.rb index a8a8942908f..abb909c1669 100644 --- a/app/components/enterprise_edition/upsale_buttons_component.rb +++ b/app/components/enterprise_edition/upsale_buttons_component.rb @@ -87,11 +87,11 @@ module EnterpriseEdition end def enterprise_link - href_value = OpenProject::Static::Links.links.dig(:enterprise_docs, feature_key, :href) + href_value = OpenProject::Static::Links.links.dig(:enterprise_features, feature_key, :href) unless href_value raise "A link for this feature needs to be provided " \ - "in OpenProject::Static::Links.enterprise_docs[#{feature_key}][:href]" + "in OpenProject::Static::Links.enterprise_features[#{feature_key}][:href]" end href_value diff --git a/config/static_links.yml b/config/static_links.yml index f3469acc3d4..3d7f13bc09e 100644 --- a/config/static_links.yml +++ b/config/static_links.yml @@ -130,7 +130,7 @@ pricing: href: https://www.openproject.org/pricing/ progress_tracking_docs: href: https://www.openproject.org/docs/user-guide/time-and-costs/progress-tracking/ -enterprise_docs: +enterprise_features: work_package_subject_generation: href: https://www.openproject.org/docs/system-admin-guide/manage-work-packages/work-package-types/#work-package-subject-configuration-enterprise-add-on form_configuration: diff --git a/lookbook/docs/patterns/18-enterprise-components.md.erb b/lookbook/docs/patterns/18-enterprise-components.md.erb new file mode 100644 index 00000000000..9d148033091 --- /dev/null +++ b/lookbook/docs/patterns/18-enterprise-components.md.erb @@ -0,0 +1,79 @@ +OpenProject provides multiple ways to render upsale components. This document describes the different components and how to use them. + +# Requirements + +## Token Gem + +In order to add a new enterprise feature, you need to add it the [token gem](https://github.com/opf/openproject-token) `plans.rb` file, +so it gets distributed and associated to the correct plan. + +## Translations + +To use the banners below, you need to add translations and links. + +**Translations** + +You need to add translations for the feature and the upsale banner. +The feature translation is used in the feature list, the upsale translation is used in the upsale banner. + +This is the default convention: + +```yaml +en: + # ... other keys + ee: + feature: + # ... + your_feature_name: "Fancy EE feature!" + upsale: + # ... + your_feature_name: + title: "Title of the banner" + description: "My description" + features: + foo: "Has foo!" + bar: "Has bar!" +``` + +You can optionally provide a `i18n_scope` parameter to the components below to customize the place to look +for the upsale translation keys. + +**docs/static_links.yml** + +Every feature has a "More information" link going to the website, an enterprise landing page, or a documentation page. +You need to add a link to the [`docs/static_links.yml`](https://github.com/opf/openproject/blob/dev/config/static_links.yml) +file under the `enterprise_features` section. + +## Full-page upsale pages + +Use when: You have a feature video / image and a full page to fill + +```ruby +render EnterpriseEdition::UpsalePageComponent.new( + :enterprise_feature, + video: "enterprise/some-video.mp4", + # or image: "enterprise/some-image.png" +) +``` + +<%= embed OpenProject::EnterpriseEdition::UpsalePageComponentPreview, :default, panels: %i[] %> + +## Inline upsale banners + +Use when: You want to show content below the banners, e.g. in administrative setting pages. + +```ruby +render EnterpriseEdition::BannerComponent.new(:enterprise_feature) +``` + +<%= embed OpenProject::EnterpriseEdition::BannerComponentPreview, :default, panels: %i[] %> + +## Dismissible upsale banners + +Use when: You want to show a feature to regular users, but allow them to hide it for good. + +```ruby +render EnterpriseEdition::BannerComponent.new(:enterprise_feature, dismissable: true) +``` + +<%= embed OpenProject::EnterpriseEdition::BannerComponentPreview, :dismissable, panels: %i[] %> diff --git a/lookbook/previews/open_project/enterprise_edition/banner_component_preview.rb b/lookbook/previews/open_project/enterprise_edition/banner_component_preview.rb index 116a0f719ed..8bcfdbd3a19 100644 --- a/lookbook/previews/open_project/enterprise_edition/banner_component_preview.rb +++ b/lookbook/previews/open_project/enterprise_edition/banner_component_preview.rb @@ -54,8 +54,9 @@ module OpenProject # You can also provide a custom i18n_scope to change the place where the component looks for # title, description, and features. # - # The href is inferred from `OpenProject::Static::Links.enterprise_docs[feature_key][:href]`. + # The href is inferred from `OpenProject::Static::Links.enterprise_features[feature_key][:href]`. # @param dismissable toggle + # @display min_height 250px def default(dismissable: false) render( ::EnterpriseEdition::BannerComponent @@ -63,6 +64,7 @@ module OpenProject ) end + # @display min_height 250px def dismissable render( ::EnterpriseEdition::BannerComponent diff --git a/lookbook/previews/open_project/enterprise_edition/upsale_page_component_preview.rb b/lookbook/previews/open_project/enterprise_edition/upsale_page_component_preview.rb index ac1a7898486..2bb707db984 100644 --- a/lookbook/previews/open_project/enterprise_edition/upsale_page_component_preview.rb +++ b/lookbook/previews/open_project/enterprise_edition/upsale_page_component_preview.rb @@ -60,12 +60,10 @@ module OpenProject # To provide a video or image, use the respective `video:` or `image:` tags. # If none or provided, a default image will be used. # - # The href is inferred from `OpenProject::Static::Links.enterprise_docs[feature_key][:href]`. + # The href is inferred from `OpenProject::Static::Links.enterprise_features[feature_key][:href]`. + # @display min_height 450px def default - render( - ::EnterpriseEdition::UpsalePageComponent - .new(:customize_life_cycle) - ) + render ::EnterpriseEdition::UpsalePageComponent.new(:customize_life_cycle) end def video diff --git a/spec/components/enterprise_edition/banner_component_spec.rb b/spec/components/enterprise_edition/banner_component_spec.rb index 171aaa8b71e..03e5621cc33 100644 --- a/spec/components/enterprise_edition/banner_component_spec.rb +++ b/spec/components/enterprise_edition/banner_component_spec.rb @@ -50,7 +50,7 @@ RSpec.describe EnterpriseEdition::BannerComponent, type: :component do end let(:static_links) do { - enterprise_docs: { + enterprise_features: { some_enterprise_feature: { href: } @@ -244,7 +244,7 @@ RSpec.describe EnterpriseEdition::BannerComponent, type: :component do context "without a link key in the static_link file" do let(:static_links) do { - enterprise_docs: { + enterprise_features: { some_enterprise_feature: {} } }