hanami-mailer 0.0.0 → 0.2.0

data/lib/hanami/mailer/dsl.rb

@@ -0,0 +1,288 @@
+require 'hanami/mailer/rendering/template_name'
+require 'hanami/mailer/rendering/templates_finder'
+
+module Hanami
+  module Mailer
+    # Class level DSL
+    #
+    # @since 0.1.0
+    module Dsl
+      # Set the template name IF it differs from the convention.
+      #
+      # For a given mailer named <tt>Signup::Welcome</tt> it will look for
+      # <tt>signup/welcome.*.*</tt> templates under the root directory.
+      #
+      # If for some reason, we need to specify a different template name, we can
+      # use this method.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload template(value)
+      #   Sets the given value
+      #   @param value [String, #to_s] relative template path, under root
+      #   @return [NilClass]
+      #
+      # @overload template
+      #   Gets the template name
+      #   @return [String]
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Mailers::Configuration.root
+      #
+      # @example Custom template name
+      #   require 'hanami/mailer'
+      #
+      #   class MyMailer
+      #     include Hanami::Mailer
+      #     template 'mailer'
+      #   end
+      def template(value = nil)
+        if value.nil?
+          @template ||= ::Hanami::Mailer::Rendering::TemplateName.new(name, configuration.namespace).to_s
+        else
+          @template = value
+        end
+      end
+
+      # Returns a set of associated templates or only one for the given format
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload templates(format)
+      #   Returns the template associated with the given format
+      #   @param value [Symbol] the format
+      #   @return [Hash]
+      #
+      # @overload templates
+      #   Returns all the associated templates
+      #   Gets the template name
+      #   @return [Hash] a set of templates
+      #
+      # @since 0.1.0
+      # @api private
+      def templates(format = nil)
+        if format.nil?
+          @templates = ::Hanami::Mailer::Rendering::TemplatesFinder.new(self).find
+        else
+          @templates.fetch(format, nil)
+        end
+      end
+
+      # Sets the sender for mail messages
+      #
+      # It accepts a hardcoded value as a string, or a symbol that represents
+      # an instance method for more complex logic.
+      #
+      # This value MUST be set, otherwise an exception is raised at the delivery
+      # time.
+      #
+      # When a value is given, specify the sender of the email
+      # Otherwise, it returns the sender of the email
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload from(value)
+      #   Sets the sender
+      #   @param value [String, Symbol] the hardcoded value or method name
+      #   @return [NilClass]
+      #
+      # @overload from
+      #   Returns the sender
+      #   @return [String, Symbol] the sender
+      #
+      # @since 0.1.0
+      #
+      # @example Hardcoded value (String)
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #
+      #     from "noreply@example.com"
+      #   end
+      #
+      # @example Method (Symbol)
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #     from :sender
+      #
+      #     private
+      #
+      #     def sender
+      #       "noreply@example.com"
+      #     end
+      #   end
+      def from(value = nil)
+        if value.nil?
+          @from
+        else
+          @from = value
+        end
+      end
+
+      # Sets the recipient for mail messages
+      #
+      # It accepts a hardcoded value as a string or array of strings.
+      # For dynamic values, you can specify a symbol that represents an instance
+      # method.
+      #
+      # This value MUST be set, otherwise an exception is raised at the delivery
+      # time.
+      #
+      # When a value is given, specify the recipient of the email
+      # Otherwise, it returns the recipient of the email
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload to(value)
+      #   Sets the recipient
+      #   @param value [String, Array, Symbol] the hardcoded value or method name
+      #   @return [NilClass]
+      #
+      # @overload to
+      #   Returns the recipient
+      #   @return [String, Array, Symbol] the recipient
+      #
+      # @since 0.1.0
+      #
+      # @example Hardcoded value (String)
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #
+      #     to "user@example.com"
+      #   end
+      #
+      # @example Hardcoded value (Array)
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #
+      #     to ["user-1@example.com", "user-2@example.com"]
+      #   end
+      #
+      # @example Method (Symbol)
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #     to :email_address
+      #
+      #     private
+      #
+      #     def email_address
+      #       user.email
+      #     end
+      #   end
+      #
+      #   user = User.new(name: 'L')
+      #   WelcomeMailer.deliver(user: user)
+      #
+      # @example Method that returns a collection of recipients
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #     to :recipients
+      #
+      #     private
+      #
+      #     def recipients
+      #       users.map(&:email)
+      #     end
+      #   end
+      #
+      #   users = [User.new(name: 'L'), User.new(name: 'MG')]
+      #   WelcomeMailer.deliver(users: users)
+      def to(value = nil)
+        if value.nil?
+          @to
+        else
+          @to = value
+        end
+      end
+
+      # Sets the subject for mail messages
+      #
+      # It accepts a hardcoded value as a string, or a symbol that represents
+      # an instance method for more complex logic.
+      #
+      # This value MUST be set, otherwise an exception is raised at the delivery
+      # time.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload subject(value)
+      #   Sets the subject
+      #   @param value [String, Symbol] the hardcoded value or method name
+      #   @return [NilClass]
+      #
+      # @overload subject
+      #   Returns the subject
+      #   @return [String, Symbol] the subject
+      #
+      # @since 0.1.0
+      #
+      # @example Hardcoded value (String)
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #
+      #     subject "Welcome"
+      #   end
+      #
+      # @example Method (Symbol)
+      #   require 'hanami/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Hanami::Mailer
+      #     subject :greeting
+      #
+      #     private
+      #
+      #     def greeting
+      #       "Hello, #{ user.name }"
+      #     end
+      #   end
+      #
+      #   user = User.new(name: 'L')
+      #   WelcomeMailer.deliver(user: user)
+      def subject(value = nil)
+        if value.nil?
+          @subject
+        else
+          @subject = value
+        end
+      end
+
+      protected
+
+      # Loading mechanism hook.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Hanami::Mailer.load!
+      def load!
+        templates.freeze
+        configuration.freeze
+      end
+    end
+  end
+end

data/lib/hanami/mailer/rendering/template_name.rb

@@ -0,0 +1,52 @@
+require 'hanami/utils/string'
+
+module Hanami
+  module Mailer
+    module Rendering
+      # @since 0.1.0
+      # @api private
+      #
+      # TODO this is identical to Hanami::View, consider to move into Hanami::Utils
+      class TemplateName
+        # @since 0.1.0
+        # @api private
+        NAMESPACE_SEPARATOR = '::'.freeze
+
+        # @since 0.1.0
+        # @api private
+        def initialize(name, namespace)
+          @name = name
+          compile!(namespace)
+        end
+
+        # @since 0.1.0
+        # @api private
+        def to_s
+          @name
+        end
+
+        private
+        # @since 0.1.0
+        # @api private
+        def compile!(namespace)
+          tokens(namespace) { |token| replace!(token) }
+          @name = Utils::String.new(@name).underscore
+        end
+
+        # @since 0.1.0
+        # @api private
+        def tokens(namespace)
+          namespace.to_s.split(NAMESPACE_SEPARATOR).each do |token|
+            yield token
+          end
+        end
+
+        # @since 0.1.0
+        # @api private
+        def replace!(token)
+          @name.gsub!(%r{\A#{ token }#{ NAMESPACE_SEPARATOR }}, '')
+        end
+      end
+    end
+  end
+end

data/lib/hanami/mailer/rendering/templates_finder.rb

@@ -0,0 +1,133 @@
+require 'hanami/mailer/template'
+
+module Hanami
+  module Mailer
+    module Rendering
+      # Find templates for a mailer
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Mailer::Template
+      class TemplatesFinder
+        # Default format
+        #
+        # @api private
+        # @since 0.1.0
+        FORMAT    = '*'.freeze
+
+        # Default template engines
+        #
+        # @api private
+        # @since 0.1.0
+        ENGINES   = '*'.freeze
+
+        # Recursive pattern
+        #
+        # @api private
+        # @since 0.1.0
+        RECURSIVE = '**'.freeze
+
+        # Initialize a finder
+        #
+        # @param mailer [Class] the mailer class
+        #
+        # @api private
+        # @since 0.1.0
+        def initialize(mailer)
+          @mailer = mailer
+        end
+
+        # Find all the associated templates to the mailer.
+        # It recursively looks for templates under the root path of the mailer,
+        # that are matching the template name
+        #
+        # @return [Hash] the templates
+        #
+        # @api private
+        # @since 0.1.0
+        #
+        # @see Hanami::Mailer::Dsl#root
+        # @see Hanami::Mailer::Dsl#templates
+        #
+        # @example
+        #   require 'hanami/mailer'
+        #
+        #   module Mailers
+        #     class Welcome
+        #       include Hanami::Mailer
+        #     end
+        #   end
+        #
+        #   Mailers::Welcome.root     # => "/path/to/templates"
+        #   Mailers::Welcome.templates # => {[:html] => "welcome"}
+        #
+        #   # This mailer has a template:
+        #   #
+        #   #   "/path/to/templates/welcome.html.erb"
+        #
+        #   Hanami::Mailer::Rendering::TemplatesFinder.new(Mailers::Welcome).find
+        #     # => [#<Hanami::Mailer::Template:0x007f8a0a86a970 ... @file="/path/to/templates/welcome.html.erb">]
+        def find
+          templates = Hash.new
+          _find.map do |template|
+            name = File.basename(template)
+            format = (( name.split(".") )[-2]).to_sym
+            templates[ format ] = Mailer::Template.new(template)
+          end
+          templates
+        end
+
+        protected
+
+        # @api private
+        # @since 0.1.0
+        def _find(lookup = search_path)
+          Dir.glob( "#{ [root, lookup, template_name].join(separator) }.#{ format }.#{ engines }" )
+        end
+
+        # @api private
+        # @since 0.1.0
+        def template_name
+          Rendering::TemplateName.new(@mailer.template, @mailer.configuration.namespace).to_s
+        end
+
+        # @api private
+        # @since 0.1.0
+        def root
+          @mailer.configuration.root
+        end
+
+        # @api private
+        # @since 0.1.0
+        def search_path
+          recursive
+        end
+
+        # @api private
+        # @since 0.1.0
+        def recursive
+          RECURSIVE
+        end
+
+        # @api private
+        # @since 0.1.0
+        def separator
+          ::File::SEPARATOR
+        end
+
+        # @api private
+        # @since 0.1.0
+        def format
+          FORMAT
+        end
+
+        # @api private
+        # @since 0.1.0
+        def engines
+          ENGINES
+        end
+      end
+    end
+  end
+end