Module: Hanami::Mailer::Dsl

Defined in:
lib/hanami/mailer/dsl.rb

Overview

Class level DSL

Since:

  • 0.1.0

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(base) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.3.0



14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/hanami/mailer/dsl.rb', line 14

def self.extended(base)
  base.class_eval do
    @from        = nil
    @to          = nil
    @cc          = nil
    @bcc         = nil
    @reply_to    = nil
    @return_path = nil
    @subject     = nil
  end
end

Instance Method Details

#bcc(value) ⇒ NilClass #bcc ⇒ String, ...

Sets the bcc (blind carbon copy) 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 is optional.

When a value is given, it specifies the bcc for the email. When a value is not given, it returns the bcc 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.

Examples:

Hardcoded value (String)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to "[email protected]"
  bcc "[email protected]"
end

Hardcoded value (Array)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to ["[email protected]", "[email protected]"]
  bcc ["[email protected]", "[email protected]"]
end

Method (Symbol)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  to "[email protected]"
  bcc :email_address

  private

  def email_address
    user.email
  end
end

other_user = User.new(name: 'L')
WelcomeMailer.deliver(user: other_user)

Method that returns a collection of recipients

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  to "[email protected]"
  bcc :recipients

  private

  def recipients
    users.map(&:email)
  end
end

other_users = [User.new(name: 'L'), User.new(name: 'MG')]
WelcomeMailer.deliver(users: other_users)

Overloads:

  • #bcc(value) ⇒ NilClass

    Sets the bcc

    Parameters:

    • value (String, Array, Symbol) —

      the hardcoded value or method name

    Returns:

    • (NilClass)
  • #bcc ⇒ String, ...

    Returns the bcc

    Returns:

    • (String, Array, Symbol) —

      the recipient

Since:

  • 0.3.0



375
376
377
378
379
380
381
 
# File 'lib/hanami/mailer/dsl.rb', line 375

def bcc(value = nil)
  if value.nil?
    @bcc
  else
    @bcc = value
  end
end

#cc(value) ⇒ NilClass #cc ⇒ String, ...

Sets the cc (carbon copy) 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 is optional.

When a value is given, it specifies the cc for the email. When a value is not given, it returns the cc 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.

Examples:

Hardcoded value (String)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to "[email protected]"
  cc "[email protected]"
end

Hardcoded value (Array)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to ["[email protected]", "[email protected]"]
  cc ["[email protected]", "[email protected]"]
end

Method (Symbol)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  to "[email protected]"
  cc :email_address

  private

  def email_address
    user.email
  end
end

other_user = User.new(name: 'L')
WelcomeMailer.deliver(user: other_user)

Method that returns a collection of recipients

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  to "[email protected]"
  cc :recipients

  private

  def recipients
    users.map(&:email)
  end
end

other_users = [User.new(name: 'L'), User.new(name: 'MG')]
WelcomeMailer.deliver(users: other_users)

Overloads:

  • #cc(value) ⇒ NilClass

    Sets the cc

    Parameters:

    • value (String, Array, Symbol) —

      the hardcoded value or method name

    Returns:

    • (NilClass)
  • #cc ⇒ String, ...

    Returns the cc

    Returns:

    • (String, Array, Symbol) —

      the recipient

Since:

  • 0.3.0



286
287
288
289
290
291
292
 
# File 'lib/hanami/mailer/dsl.rb', line 286

def cc(value = nil)
  if value.nil?
    @cc
  else
    @cc = value
  end
end

#from(value) ⇒ NilClass #from ⇒ String, Symbol

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.

Examples:

Hardcoded value (String)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  from "[email protected]"
end

Method (Symbol)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  from :sender

  private

  def sender
    "[email protected]"
  end
end

Overloads:

  • #from(value) ⇒ NilClass

    Sets the sender

    Parameters:

    • value (String, Symbol) —

      the hardcoded value or method name

    Returns:

    • (NilClass)
  • #from ⇒ String, Symbol

    Returns the sender

    Returns:

    • (String, Symbol) —

      the sender

Since:

  • 0.1.0



197
198
199
200
201
202
203
 
# File 'lib/hanami/mailer/dsl.rb', line 197

def from(value = nil)
  if value.nil?
    @from
  else
    @from = value
  end
end

#reply_to(value) ⇒ NilClass #reply_to ⇒ String, ...

Sets the reply_to 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 is optional.

When a value is given, it specifies the reply_to for the email. When a value is not given, it returns the reply_to 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.

Examples:

Hardcoded value (String)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to "[email protected]"
  reply_to "[email protected]"
end

Hardcoded value (Array)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to ["[email protected]", "[email protected]"]
  reply_to ["[email protected]", "[email protected]"]
end

Method (Symbol)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  to "[email protected]"
  reply_to :email_address

  private

  def email_address
    user.email
  end
end

other_user = User.new(name: 'L')
WelcomeMailer.deliver(user: other_user)

Method that returns a collection of recipients

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  to "[email protected]"
  reply_to :recipients

  private

  def recipients
    users.map(&:email)
  end
end

other_users = [User.new(name: 'L'), User.new(name: 'MG')]
WelcomeMailer.deliver(users: other_users)

Overloads:

  • #reply_to(value) ⇒ NilClass

    Sets the reply_to

    Parameters:

    • value (String, Array, Symbol) —

      the hardcoded value or method name

    Returns:

    • (NilClass)
  • #reply_to ⇒ String, ...

    Returns the reply_to

    Returns:

    • (String, Array, Symbol) —

      the recipient

Since:

  • 1.3.0



464
465
466
467
468
469
470
 
# File 'lib/hanami/mailer/dsl.rb', line 464

def reply_to(value = nil)
  if value.nil?
    @reply_to
  else
    @reply_to = value
  end
end

#return_path(value) ⇒ NilClass #return_path ⇒ String, Symbol

Sets the MAIL FROM address for mail messages. This lets you specify a “bounce address” different from the sender address specified with ‘from`.

It accepts a hardcoded value as a string, or a symbol that represents an instance method for more complex logic.

This value is optional.

When a value is given, specify the MAIL FROM address of the email Otherwise, it returns the MAIL FROM address 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.

Examples:

Hardcoded value (String)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  return_path "[email protected]"
end

Method (Symbol)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer
  return_path :bounce_address

  private

  def bounce_address
    "[email protected]"
  end
end

Overloads:

  • #return_path(value) ⇒ NilClass

    Sets the MAIL FROM address

    Parameters:

    • value (String, Symbol) —

      the hardcoded value or method name

    Returns:

    • (NilClass)
  • #return_path ⇒ String, Symbol

    Returns the MAIL FROM address

    Returns:

    • (String, Symbol) —

      the MAIL FROM address

Since:

  • 1.3.2



141
142
143
144
145
146
147
 
# File 'lib/hanami/mailer/dsl.rb', line 141

def return_path(value = nil)
  if value.nil?
    @return_path
  else
    @return_path = value
  end
end

#subject(value) ⇒ NilClass #subject ⇒ String, Symbol

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.

Examples:

Hardcoded value (String)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  subject "Welcome"
end

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)

Overloads:

  • #subject(value) ⇒ NilClass

    Sets the subject

    Parameters:

    • value (String, Symbol) —

      the hardcoded value or method name

    Returns:

    • (NilClass)
  • #subject ⇒ String, Symbol

    Returns the subject

    Returns:

    • (String, Symbol) —

      the subject

Since:

  • 0.1.0



606
607
608
609
610
611
612
 
# File 'lib/hanami/mailer/dsl.rb', line 606

def subject(value = nil)
  if value.nil?
    @subject
  else
    @subject = value
  end
end

#template(value) ⇒ NilClass #template ⇒ String

Set the template name IF it differs from the convention.

For a given mailer named Signup::Welcome it will look for signup/welcome.. 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.

Examples:

Custom template name

require 'hanami/mailer'

class MyMailer
  include Hanami::Mailer
  template 'mailer'
end

Overloads:

  • #template(value) ⇒ NilClass

    Sets the given value

    Parameters:

    • value (String, #to_s) —

      relative template path, under root

    Returns:

    • (NilClass)
  • #template ⇒ String

    Gets the template name

    Returns:

    • (String)

See Also:

  • Hanami::Mailers::Configuration.root

Since:

  • 0.1.0



58
59
60
61
62
63
64
 
# File 'lib/hanami/mailer/dsl.rb', line 58

def template(value = nil)
  if value.nil?
    @template ||= ::Hanami::Mailer::Rendering::TemplateName.new(name, configuration.namespace).to_s
  else
    @template = value
  end
end

#templates(format) ⇒ Hash #templates ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Overloads:

  • #templates(format) ⇒ Hash

    Returns the template associated with the given format

    Parameters:

    • value (Symbol) —

      the format

    Returns:

    • (Hash)
  • #templates ⇒ Hash

    Returns all the associated templates Gets the template name

    Returns:

    • (Hash) —

      a set of templates

Since:

  • 0.1.0



84
85
86
87
88
89
90
 
# File 'lib/hanami/mailer/dsl.rb', line 84

def templates(format = nil)
  if format.nil?
    @templates = ::Hanami::Mailer::Rendering::TemplatesFinder.new(self).find
  else
    @templates.fetch(format, nil)
  end
end

#to(value) ⇒ NilClass #to ⇒ String, ...

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.

Examples:

Hardcoded value (String)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to "[email protected]"
end

Hardcoded value (Array)

require 'hanami/mailer'

class WelcomeMailer
  include Hanami::Mailer

  to ["[email protected]", "[email protected]"]
end

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)

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)

Overloads:

  • #to(value) ⇒ NilClass

    Sets the recipient

    Parameters:

    • value (String, Array, Symbol) —

      the hardcoded value or method name

    Returns:

    • (NilClass)
  • #to ⇒ String, ...

    Returns the recipient

    Returns:

    • (String, Array, Symbol) —

      the recipient

Since:

  • 0.1.0



550
551
552
553
554
555
556
 
# File 'lib/hanami/mailer/dsl.rb', line 550

def to(value = nil)
  if value.nil?
    @to
  else
    @to = value
  end
end