heya 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91788b17940c18fd1196e0cc20f2892fb91233c714a5dc7c876833459ae867d3
-  data.tar.gz: 6f8694d2562802ff9102fd62e04349beaf464dee5043fd928e0403fd4deb6bab
+  metadata.gz: 96972db7d19d5bc0a38361957c0f69e612783c00546441bb82c45c144ac9ff55
+  data.tar.gz: 4a52a5d0a83dfe781d68cf7dac1fa06eb74f2074e2d61b2dd651b263b13812df
 SHA512:
-  metadata.gz: 7315798099a708fa8bc0477e229672377634a29a97097139c2055ef09edd748edaf4a40a8685cfa015b87e766463ade73c3e10ea71ee41893184bea0ab7867ec
-  data.tar.gz: 3a437c995a6aaed616b75cce220c80bf28baf7d64364ac1956d11ce1e38c8bbf40d9a71bed97258e84d19d410970ae7ed48d07a6aaed92b92ebc3610ef9b654f
+  metadata.gz: cb98d146663bba6e56ce8208a591e1119e1cc033bcba8c902b42504a6947d43118e86dcdffbbf3a7972787df1ed04867db2266dad130802a8eaecd5047e93755
+  data.tar.gz: 6af0b7233154b3c17864e568b1b7c6db38336e09e9738d9301d033db46da6db8fe9b6d62e0975dcd06d967e937ce28943c826aa7f851946bb7ab7b647df236ac

data/CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2020-06-02
+### Added
+- Support I18n translations for email subjects (#81)
+
 ## [0.2.1] - 2020-04-23
 ### Fixed
 - Update the install and campaign generators.

data/README.md

@@ -3,6 +3,8 @@
 [![Gem Version](https://badge.fury.io/rb/heya.svg)](https://badge.fury.io/rb/heya)
 [![Maintainability](https://api.codeclimate.com/v1/badges/a6416e63ffc426715857/maintainability)](https://codeclimate.com/github/honeybadger-io/heya/maintainability)
 
+[![Twitter Follow](https://img.shields.io/twitter/follow/heyjoshwood?label=Follow%20Josh%20for%20dev%20updates&style=social)](https://mobile.twitter.com/heyjoshwood)
+
 Heya is a campaign mailer for Rails. Think of it like ActionMailer, but for timed email sequences. It can also perform other actions like sending a text message.
 
 ## Getting started
@@ -235,19 +237,19 @@ In the above example, Heya will send a message named `:welcome` one day after a
 
 The `wait` option tells Heya how long to wait before sending each message (the default is two days). There are a few scheduling options that you can customize for each step:
 
-| Option Name | Default | Description  |
-|:--|:--|:--|
-| `wait`  | `2.days` | The duration of time to wait before sending each message |
-| `segment`  | `nil` | The segment who should receive the message |
-| `action` | `Heya::Campaigns::Actions::Email` | The action to perform (usually sending an email) |
-| `queue` | `"heya"` | The ActiveJob queue |
+| Option Name | Default                           | Description                                              |
+| :---------- | :-------------------------------- | :------------------------------------------------------- |
+| `wait`      | `2.days`                          | The duration of time to wait before sending each message |
+| `segment`   | `nil`                             | The segment who should receive the message               |
+| `action`    | `Heya::Campaigns::Actions::Email` | The action to perform (usually sending an email)         |
+| `queue`     | `"heya"`                          | The ActiveJob queue                                      |
 
 Heya uses the following additional options to build the message itself:
 
-| Option Name | Default | Description  |
-|:--|:--|:--|
-| `subject`  | **required** | The email's subject |
-| `from`  | Heya default | The sender's email address |
+| Option Name | Default      | Description                |
+| :---------- | :----------- | :------------------------- |
+| `subject`   | **required** | The email's subject        |
+| `from`      | Heya default | The sender's email address |
 
 You can change the default options using the `default` method at the top of the campaign. Heya applies default options to each step which doesn't supply its own:
 
@@ -264,6 +266,58 @@ class OnboardingCampaign < ApplicationCampaign
 end
 ```
 
+#### Customizing email subjects for each user
+
+The subject can be customized for each user by using a `lambda` instead of a `String`:
+
+```ruby
+# app/campaigns/onboarding_campaign.rb
+class OnboardingCampaign < ApplicationCampaign
+  step :welcome,
+    subject: ->(user) { "Heya #{user.first_name}!" }
+end
+```
+
+#### Translations for email subjects (I18n)
+
+If you don't pass a `subject` to the `step` method, Heya will try to find it in your translations. The performed lookup will use the pattern `<campaign_scope>.<step_name>.subject` to construct the key.
+
+```ruby
+# app/campaigns/onboarding_campaign.rb
+class OnboardingCampaign < ApplicationCampaign
+  step :welcome
+end
+```
+
+```yaml
+# config/locales/en.yml
+en:
+  onboarding_campaign:
+    welcome:
+      subject: "Heya!"
+```
+
+To define parameters for interpolation, define a `#heya_attributes` method on your user model:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  def heya_attributes
+    {
+      first_name: name.split(" ").first
+    }
+  end
+end
+```
+
+```yaml
+# config/locales/en.yml
+en:
+  onboarding_campaign:
+    welcome:
+      subject: "Heya %{first_name}!"
+```
+
 ### Custom Actions
 
 You can override the default step behavior to perform custom actions by passing

data/app/mailers/heya/campaign_mailer.rb

@@ -5,10 +5,17 @@ module Heya
     def build
       user = params.fetch(:user)
       step = params.fetch(:step)
-      campaign = step.campaign
+
+      campaign_name = step.campaign_name.underscore
+      step_name = step.name.underscore
+
       from = step.params.fetch("from")
       reply_to = step.params.fetch("reply_to", nil)
-      subject = step.params.fetch("subject")
+
+      subject = step.params.fetch("subject") {
+        I18n.t("#{campaign_name}.#{step_name}.subject", **attributes_for(user))
+      }
+      subject = subject.call(user) if subject.respond_to?(:call)
 
       instance_variable_set(:"@#{user.model_name.element}", user)
 
@@ -17,13 +24,21 @@ module Heya
         reply_to: reply_to,
         to: user.email,
         subject: subject,
-        template_path: "heya/campaign_mailer/#{campaign.name.underscore}",
-        template_name: step.name.underscore
+        template_path: "heya/campaign_mailer/#{campaign_name}",
+        template_name: step_name
       )
     end
 
     protected
 
+    def attributes_for(user)
+      if user.respond_to?(:heya_attributes)
+        user.heya_attributes.symbolize_keys
+      else
+        {}
+      end
+    end
+
     def _prefixes
       @_prefixes_with_campaign_path ||= begin
         if params.is_a?(Hash) && (campaign_name = params[:step]&.campaign&.name&.underscore)

data/lib/heya/campaigns/actions/email.rb

@@ -4,6 +4,15 @@ module Heya
   module Campaigns
     module Actions
       class Email < Action
+        VALID_PARAMS = %w[subject from reply_to]
+
+        def self.validate_step(step)
+          step.params.assert_valid_keys(VALID_PARAMS)
+          unless step.params["subject"].present? || I18n.exists?("#{step.campaign_name.underscore}.#{step.name.underscore}.subject")
+            raise ArgumentError.new(%("subject" is required))
+          end
+        end
+
         def build
           CampaignMailer
             .with(user: user, step: step)

data/lib/heya/campaigns/base.rb

@@ -140,13 +140,13 @@ module Heya
               .merge(opts)
 
           attrs = opts.select { |k, _| STEP_ATTRS.key?(k) }
-          attrs[:params] = opts.reject { |k, _| STEP_ATTRS.key?(k) }.stringify_keys
           attrs[:id] = "#{self.name}/#{name}"
           attrs[:name] = name.to_s
-          attrs[:position] = steps.size
           attrs[:campaign] = instance
+          attrs[:position] = steps.size
+          attrs[:params] = opts.reject { |k, _| STEP_ATTRS.key?(k) }.stringify_keys
 
-          step = Step.new(attrs)
+          step = Step.new(**attrs)
           method_name = :"#{step.name.underscore}"
           raise "Invalid step name: #{step.name}\n  Step names must not conflict with method names on Heya::Campaigns::Base" if respond_to?(method_name)
 

data/lib/heya/campaigns/step.rb

@@ -12,6 +12,13 @@ module Heya
         campaign_name.constantize.steps.find { |s| s.id == id }
       end
 
+      def initialize(id:, name:, campaign:, position:, action:, wait:, segment:, queue:, params: {})
+        super
+        if action.respond_to?(:validate_step)
+          action.validate_step(self)
+        end
+      end
+
       def gid
         to_gid(app: "heya").to_s
       end
@@ -19,6 +26,10 @@ module Heya
       def in_segment?(user)
         Heya.in_segments?(user, *campaign.__segments, segment)
       end
+
+      def campaign_name
+        @campaign_name ||= campaign.name
+      end
     end
   end
 end

data/lib/heya/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Heya
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: heya
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Joshua Wood
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-23 00:00:00.000000000 Z
+date: 2020-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -58,9 +58,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Heya is a customer communication and automation framework for Ruby on
-  Rails. It's as robust as the hosted alternatives, without the integration and compliance
-  nightmare.
+description: Heya is a campaign mailer for Rails. Think of it like ActionMailer, but
+  for timed email sequences. It can also perform other actions like sending a text
+  message.
 email:
 - josh@honeybadger.io
 executables: []