From ce56e1377e8b8a5261f18d3a89610d1f9a6757d1 Mon Sep 17 00:00:00 2001 From: Mark Perkins Date: Thu, 10 Oct 2024 00:17:12 +0100 Subject: [PATCH] Disable mailers parsing by default, add config option to enable --- docs/alpha/01_usage.md | 4 +- docs/alpha/02_new_features.md | 123 ++++++++++++----------- lib/lookbook/config.rb | 2 + lib/lookbook/engine.rb | 6 ++ lib/lookbook/previews/previews.rb | 6 +- lib/lookbook/previews/previews_parser.rb | 4 + test/demo/config/application.rb | 2 + 7 files changed, 87 insertions(+), 60 deletions(-) diff --git a/docs/alpha/01_usage.md b/docs/alpha/01_usage.md index 6155b0899..beee9aa98 100644 --- a/docs/alpha/01_usage.md +++ b/docs/alpha/01_usage.md @@ -24,7 +24,7 @@ Add Lookbook to the `development` group in your Gemfile: ```rb group :development do - gem "lookbook", "~> 3.0.0.alpha.1" + gem "lookbook", "~> 3.0.0.alpha.2" gem "listen" # Required for 'live' UI updates when file changes are detected end ``` @@ -57,7 +57,7 @@ gem "actioncable" # Remove this! Lastly **update the Lookbook version** in your `Gemfile`: ```rb -gem "lookbook", "~> 3.0.0.alpha.1" +gem "lookbook", "~> 3.0.0.alpha.2" ``` Run `bundle update lookbook` to update to the latest Lookbook alpha release and then start your server in the usual way. diff --git a/docs/alpha/02_new_features.md b/docs/alpha/02_new_features.md index 93c7e790c..d154821ca 100644 --- a/docs/alpha/02_new_features.md +++ b/docs/alpha/02_new_features.md @@ -4,63 +4,6 @@ Below are details of some of the main new features that have been implemented so far in Lookbook v3. Give them a try and let us know what you think! -## 🆕 ActionMailer previews - -> ⚠️ ActionMailer preview support is still very much at an experimental stage. Any feedback and/or suggestions on this feature would be very welcome! - -[➡️ Demo example](https://v3-demo-app.lookbook.build/lookbook/previews/user_mailer/welcome) - -ActionMailer previews are supported out-of-the-box in v3, with no changes required to the regular [ActionMailer preview format](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails): - -```rb -class UserMailerPreview < ActionMailer::Preview - def welcome_email - UserMailer.with(name: "Bob").welcome_email - end -end -``` - -Any existing mailer previews in your should automatically appear in the Lookbook UI. - -Mailer previews can be located in the standard Rails mailer preview directory (`test/mailers/previews`) or if you prefer to keep things altogether they can be added into the main Lookbook previews directory. - -All the usual Lookbook [tags/annotations](https://lookbook.build/guide/tags) (apart from `@!group` tags) can be used in ActionMailer previews in exactly the same way as in component previews: - -```rb -class UserMailerPreview < ActionMailer::Preview - # @label New user welcome - def welcome_email - UserMailer.with(name: "Bob").welcome_email - end - - # This email is still WIP and not ready for use. - # @hidden - def experimental_email - UserMailer.with(name: "Bob").experimental_email - end -end -``` - -[Dynamic params](https://lookbook.build/guide/previews/params) work in the same way as component previews, as long as the param values are passed to the email template as instance variables: - -```rb -class UserMailer < ApplicationMailer - def welcome - @name = params[:name] - mail(to: "user@example.com", subject: "Welcome") - end -end -``` - -```rb -class UserMailerPreview < ActionMailer::Preview - # @param name - def welcome_email(name: "Bob") - UserMailer.with(name: name).welcome_email - end -end -``` - ## 🆕 Preview overview pages Preview overview pages are generated for each preview class and shown when clicking on the preview name in the navigation. @@ -202,10 +145,76 @@ label: Feedback In the example above the parent folder name would be displayed as `Feedback` instead of `Alerts` in the navigation. +## 🆕 ActionMailer previews +> ⚠️ ActionMailer preview support is still very much at an experimental stage. Any feedback and/or suggestions on this feature would be very welcome! +[➡️ Demo example](https://v3-demo-app.lookbook.build/lookbook/previews/user_mailer/welcome) + +### Enabling ActionMailer preview support + +Lookbook mailer previews are an experimental feature and must be enabled using the `experimental_features` config option: + +```rb +config.lookbook.experimental_features << :mailer_previews +``` + +### Usage + +The intention is to support standard ActionMailer previews are out-of-the-box in Lookbook v3, with no changes required to the regular [ActionMailer preview format](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails): + +```rb +class UserMailerPreview < ActionMailer::Preview + def welcome_email + UserMailer.with(name: "Bob").welcome_email + end +end +``` + +Any existing mailer previews in your should automatically appear in the Lookbook UI. + +Mailer previews can be located in the standard Rails mailer preview directory (`test/mailers/previews`) or if you prefer to keep things altogether they can be added into the main Lookbook previews directory. + +All the usual Lookbook [tags/annotations](https://lookbook.build/guide/tags) (apart from `@!group` tags) can be used in ActionMailer previews in exactly the same way as in component previews: + +```rb +class UserMailerPreview < ActionMailer::Preview + # @label New user welcome + def welcome_email + UserMailer.with(name: "Bob").welcome_email + end + + # This email is still WIP and not ready for use. + # @hidden + def experimental_email + UserMailer.with(name: "Bob").experimental_email + end +end +``` + +[Dynamic params](https://lookbook.build/guide/previews/params) work in the same way as component previews, as long as the param values are passed to the email template as instance variables: + +```rb +class UserMailer < ApplicationMailer + def welcome + @name = params[:name] + mail(to: "user@example.com", subject: "Welcome") + end +end +``` + +```rb +class UserMailerPreview < ActionMailer::Preview + # @param name + def welcome_email(name: "Bob") + UserMailer.with(name: name).welcome_email + end +end +``` +## Lots more! +More docs/info to come. diff --git a/lib/lookbook/config.rb b/lib/lookbook/config.rb index 57390c338..e5016204a 100644 --- a/lib/lookbook/config.rb +++ b/lib/lookbook/config.rb @@ -58,6 +58,8 @@ def defaults reload_on_change: Rails.env.development?, mount_path: "/lookbook", + experimental_features: [], + enabled: Rails.env.development? || Rails.env.test? }) end diff --git a/lib/lookbook/engine.rb b/lib/lookbook/engine.rb index 0e4ceb821..1b12fbbee 100644 --- a/lib/lookbook/engine.rb +++ b/lib/lookbook/engine.rb @@ -22,6 +22,12 @@ class Engine < Rails::Engine end config.after_initialize do + if Lookbook.config.experimental_features.any? + warn(%( + The following experimental features are enabled: #{Lookbook.config.experimental_features.join(", ")} + Please note these may change or be removed at any time.).strip_heredoc) + end + if Engine.enabled? start else diff --git a/lib/lookbook/previews/previews.rb b/lib/lookbook/previews/previews.rb index 349e22460..bb8bab835 100644 --- a/lib/lookbook/previews/previews.rb +++ b/lib/lookbook/previews/previews.rb @@ -65,7 +65,7 @@ def preview_class?(klass) def preview_paths @preview_paths ||= begin - action_mailer_paths = if Rails.application.config.respond_to?(:action_mailer) + action_mailer_paths = if mailer_previews_enabled? && Rails.application.config.respond_to?(:action_mailer) Rails.application.config.action_mailer.preview_paths end paths = [Lookbook.config.preview_paths, action_mailer_paths].compact.flatten @@ -122,6 +122,10 @@ def statuses end end + def mailer_previews_enabled? + Lookbook.config.experimental_features.include?(:mailer_previews) + end + private def clear_cache diff --git a/lib/lookbook/previews/previews_parser.rb b/lib/lookbook/previews/previews_parser.rb index 43d5f3b7e..4e6d89765 100644 --- a/lib/lookbook/previews/previews_parser.rb +++ b/lib/lookbook/previews/previews_parser.rb @@ -33,6 +33,10 @@ def parse(paths = @preview_paths, &callback) nil end + unless Previews.mailer_previews_enabled? + preview_entities = preview_entities.filter { !_1.mailer_preview? } + end + callback.call(preview_entities.compact) end end diff --git a/test/demo/config/application.rb b/test/demo/config/application.rb index 17ebd12a3..4d8e4962c 100644 --- a/test/demo/config/application.rb +++ b/test/demo/config/application.rb @@ -37,6 +37,8 @@ } } + config.lookbook.experimental_features << :mailer_previews + # Pages config config.lookbook.page_paths << "#{root}/lookbook/docs"