Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Mailer documentation cleanup #1413

Merged
merged 5 commits into from Sep 15, 2013
Merged

Mailer documentation cleanup #1413

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d412b35
Cleanup of base file
Sep 15, 2013
1a0193f
Cleanup of ext file
Sep 15, 2013
52c834d
Cleanup of helpers file
Sep 15, 2013
4cac1ec
Cleanup of mime file
Sep 15, 2013
564b762
Cleanup of padrino-mailer file
Sep 15, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
10 changes: 4 additions & 6 deletions padrino-mailer/lib/padrino-mailer.rb
View file
Open in desktop
Expand Up @@ -7,7 +7,8 @@

module Padrino
##
# This component uses the +mail+ library to create a powerful but simple mailer within Padrino (and Sinatra).
# This component uses the +mail+ library to create a powerful but simple
# mailer within Padrino (and Sinatra).
# There is full support for using plain or html content-types as well as for file attachments.
#
# Using the mailer in Padrino has two forms. The 'quick' method requires only use
Expand All @@ -23,8 +24,6 @@ module Padrino
# end
# end
#
# For a more detailed guide, please read the {Padrino Mailer}[http://www.padrinorb.com/guides/padrino-mailer] guide.
#
module Mailer
class << self
##
Expand All @@ -38,7 +37,6 @@ class << self
# register Padrino::Mailer::Helpers
# end
#
# @api public
def registered(app)
require 'padrino-mailer/base'
require 'padrino-mailer/helpers'
Expand All @@ -53,5 +51,5 @@ def registered(app)
end
alias :included :registered
end
end # Mailer
end # Padrino
end
end
18 changes: 8 additions & 10 deletions padrino-mailer/lib/padrino-mailer/base.rb
View file
Open in desktop
Expand Up @@ -41,11 +41,10 @@ module Mailer
#
# deliver(:sample, :registration, "Bob", "21")
#
# For a more detailed guide, please read the {Padrino Mailer}[http://www.padrinorb.com/guides/padrino-mailer] guide.
#
class Base
attr_accessor :delivery_settings, :app, :mailer_name, :messages

##
# Constructs a +Mailer+ base object with specified options.
#
# @param [Sinatra::Application] app
Expand All @@ -56,7 +55,6 @@ class Base
# The +email+ definitions block.
#
# @see Padrino::Mailer::Helpers::ClassMethods#mailer
# @api private
def initialize(app, name, &block)
@mailer_name = name
@messages = {}
Expand All @@ -65,7 +63,8 @@ def initialize(app, name, &block)
instance_eval(&block)
end

# Defines a mailer object allowing the definition of various email messages that can be delivered.
# Defines a mailer object allowing the definition of various email
# messages that can be delivered.
#
# @param [Symbol] name
# The name of this email message.
Expand All @@ -81,7 +80,6 @@ def initialize(app, name, &block)
# render 'birthday'
# end
#
# @api public
def email(name, &block)
raise "The email '#{name}' is already defined" if self.messages[name].present?
self.messages[name] = Proc.new { |*attrs|
Expand All @@ -94,7 +92,8 @@ def email(name, &block)
end
alias :message :email

# Defines the default attributes for a message in this mailer (including app-wide defaults).
# Defines the default attributes for a message in this mailer
# (including app-wide defaults).
#
# @param [Hash] attributes
# The hash of message options to use as default.
Expand All @@ -105,14 +104,13 @@ def email(name, &block)
# email(:foo) do; end
# end
#
# @api public
def defaults(attributes=nil)
if attributes.nil? # Retrieve the default values
@app.respond_to?(:mailer_defaults) ? @app.mailer_defaults.merge(@defaults) : @defaults
else # updates the default values
@defaults = attributes
end
end
end # Base
end # Mailer
end # Padrino
end
end
end
35 changes: 27 additions & 8 deletions padrino-mailer/lib/padrino-mailer/ext.rb
View file
Open in desktop
Expand Up @@ -12,23 +12,22 @@ def initialize_with_app(*args, &block)
settings.views = File.join(app.views, 'mailers')
settings.reload_templates = app.reload_templates?
else
# Set a default view for this class
settings.views = File.expand_path("./mailers")
settings.reload_templates = true
end

initialize_template_settings!

# Run the original initialize
initialize_without_app(*args, &block)
end
alias_method_chain :initialize, :app

##
# Setup like in Sinatra/Padrino apps content_type and template lookup.
#
# @example
# # This add an email plain part if a template called bar.plain.* is found
# # and a html part if a template called bar.html.* is found
# # and a HTML part if a template called bar.html.* is found
# email do
# from 'from@email.com'
# to 'to@email.com'
Expand All @@ -45,6 +44,7 @@ def provides(*formats)
end
end

##
# Helper to add a text part to a multipart/alternative email. If this and
# html_part are both defined in a message, then it will be a multipart/alternative
# message and set itself that way.
Expand All @@ -60,7 +60,8 @@ def text_part(value = nil, &block)
&block)
end

# Helper to add a html part to a multipart/alternative email. If this and
##
# Helper to add a HTML part to a multipart/alternative email. If this and
# text_part are both defined in a message, then it will be a multipart/alternative
# message and set itself that way.
#
Expand All @@ -87,6 +88,7 @@ def add_resolved_part(attributes = {}, &block)
end
end

##
# Allows you to add a part in block form to an existing mail message object.
#
# @example
Expand Down Expand Up @@ -114,12 +116,14 @@ def do_delivery_with_logging
end
alias_method_chain :do_delivery, :logging if Padrino.respond_to?(:logger)

##
# Sinatra and Padrino compatibility.
#
def settings
self.class
end

##
# Sets the message defined template path to the given view path.
#
def views(value)
Expand All @@ -133,55 +137,64 @@ def locals(value)
@_locals = value
end

##
# Returns the templates for this message.
#
def self.templates
@_templates ||= {}
end

##
# Sets the message defined template path to the given view path.
#
def self.views=(value)
@_views = value
end

##
# Returns the template view path defined for this message.
#
def self.views
@_views
end

##
# Modify whether templates should be reloaded (for development).
#
def self.reload_templates=(value)
@_reload_templates = value
end

##
# Returns true if the templates will be reloaded; false otherwise.
#
def self.reload_templates?
@_reload_templates
end

##
# Return the path of this file, only for compatibility with Sinatra rendering methods.
#
def self.caller_locations
[[File.dirname(__FILE__), 1]]
end

##
# Return the default encoding.
#
def self.default_encoding
"utf-8"
end

##
# Modify the default attributes for this message (if not explicitly specified).
#
def defaults=(attributes)
@_defaults = attributes
@_defaults.each_pair { |k, v| default(k.to_sym, v) } if @_defaults.is_a?(Hash)
end

##
# Check if we can log.
#
def self.logging?
Expand All @@ -192,7 +205,9 @@ def self.logging=(value)
@_logging = value
end

# Shortcut for delivery_method with smarter SMTP overwrites
##
# Shortcut for delivery_method with smarter SMTP overwrites.
#
def via(method = nil, settings = {})
if method.nil?
delivery_method
Expand All @@ -203,6 +218,7 @@ def via(method = nil, settings = {})
end
end

##
# If the value is empty return a symbol that represent the content type so:
#
# "text/plain" => :plain
Expand All @@ -218,10 +234,11 @@ def content_type_with_symbol(value=nil)

private

##
# Defines the render for the mailer utilizing the padrino 'rendering' module
#
def render(engine, data=nil, options={}, locals={}, &block)
locals = @_locals if options[:locals].blank? && locals.blank?
# Reload templates
@template_cache.clear if settings.reload_templates?

provides.each do |format|
Expand All @@ -235,11 +252,13 @@ def render(engine, data=nil, options={}, locals={}, &block)
self.body = super(engine, data, options, locals, &block) if provides.empty?
end

##
# Register all special template configurations Padrino has to our fake settings object.
#
def initialize_template_settings!
Padrino::Rendering.engine_configurations.each do |name, value|
settings.class.instance_eval { define_method(name) { value } }
end
end
end # Message
end # Mail
end
end
29 changes: 16 additions & 13 deletions padrino-mailer/lib/padrino-mailer/helpers.rb
View file
Open in desktop
Expand Up @@ -8,6 +8,7 @@ def self.included(base) # @private
base.extend(ClassMethods)
end

##
# Delivers an email with the given mail attributes.
#
# @param [Hash] mail_attributes
Expand All @@ -25,11 +26,11 @@ def self.included(base) # @private
# end
#
# @see ClassMethods#email
# @api public
def email(mail_attributes={}, &block)
settings.email(mail_attributes, &block)
end

##
# Delivers a mailer message email with the given attributes.
#
# @param [Symbol] mailer_name
Expand All @@ -44,27 +45,29 @@ def email(mail_attributes={}, &block)
# deliver(:example, :message, "John")
#
# @see ClassMethods#deliver
# @api public
def deliver(mailer_name, message_name, *attributes)
settings.deliver(mailer_name, message_name, *attributes)
end

# Class methods responsible for registering mailers, configuring settings and delivering messages.
# Class methods responsible for registering mailers, configuring
# settings and delivering messages.
#
module ClassMethods
def inherited(subclass) # @private
def inherited(subclass)
@_registered_mailers ||= {}
super(subclass)
end

##
# Returns all registered mailers for this application.
#
# @private
def registered_mailers
@_registered_mailers ||= {}
end

# Defines a mailer object allowing the definition of various email messages that can be delivered.
##
# Defines a mailer object allowing the definition of various
# email messages that can be delivered.
#
# @param [Symbol] name
# The name of the mailer to initialize.
Expand All @@ -80,7 +83,6 @@ def registered_mailers
# end
# end
#
# @api public
def mailer(name, &block)
mailer = Padrino::Mailer::Base.new(self, name, &block)
mailer.delivery_settings = delivery_settings
Expand All @@ -89,6 +91,7 @@ def mailer(name, &block)
end
alias :mailers :mailer

##
# Delivers a mailer message email with the given attributes.
#
# @param [Symbol] mailer_name
Expand All @@ -102,17 +105,17 @@ def mailer(name, &block)
# deliver(:sample, :birthday, "Joey", 21)
# deliver(:example, :message, "John")
#
# @api public
def deliver(mailer_name, message_name, *attributes)
message = registered_mailers[mailer_name].messages[message_name].call(*attributes)
message.delivery_method(*delivery_settings)
message.deliver
end

##
# Delivers an email with the given mail attributes with specified and default settings.
#
# @param [Hash] mail_attributes
# The attributes for this message (to, from, subject, cc, bcc, body, etc).
# The attributes for this message (to, from, subject, cc, bcc, body, etc.).
# @param [Proc] block
# The block mail attributes for this message.
#
Expand All @@ -128,7 +131,6 @@ def deliver(mailer_name, message_name, *attributes)
# body 'path/to/my/template', :locals => { :a => a, :b => b }
# end
#
# @api public
def email(mail_attributes={}, &block)
message = _padrino_mailer::Message.new(self)
message.delivery_method(*delivery_settings)
Expand All @@ -139,6 +141,7 @@ def email(mail_attributes={}, &block)
end

private
##
# Returns the parsed delivery method options.
#
def delivery_settings
Expand All @@ -151,6 +154,6 @@ def delivery_settings
end
end
end
end # Helpers
end # Mailer
end # Padrino
end
end
end