عرض مصدر Rails/action mailer

<noinclude>{{DISPLAYTITLE:المكتبة Action Mailer في ريلز}}</noinclude>
[[تصنيف:Rails]]
[[تصنيف:Rails Getting Started]]
إنَّ Action Mailer هو إطار عمل لتصميم طبقات خدمة البريد الإلكتروني. تُستخدَم هذه الطبقات لإنشاء شيفرة تعمل على إرسال البريد الإلكتروني المتعلق بكلمات المرور المنسية، ورسائل الترحيب بالعضو الجديد، والفواتير الواجب دفعها، وأية حالة أخرى تتطلب إرسال تنبيه مكتوب إمَّا إلى الشخص نفسه أو إلى نظام آخر.

يعدُّ Action Mailer مغلفًا حول Action Controller والجوهرة Mail، إذ يوفر وسيلةً لإنشاء رسائل البريد الإلكتروني عبر قوالبٍ مُستعمِلًا الطريقة نفسها التي يصير بها [[Rails/action controller|Action Controller]] واجهات العرض المستندة إلى قوالب جاهزة.

أضف إلى ذلك أن الصنف Action Mailer يمكن استخدامه لمعالجة رسائل البريد الإلكتروني الواردة مثل السماح لمدونة بقبول منشورات جديدة عبر البريد الإلكتروني (الذي يمكن أن يُرسَل من الهاتف).

يمكنك الاطلاع على المزيد حول Action Mailer في دليل [[Rails/action mailer basics|أساسيات Action Mailer]].

== إرسال الرسائل البريدية ==
يعمل الإطار عبر تهيئة متغيرات النسخة التي تريدها أن تكون متاحة في قالب رسالة البريد ثم استدعاء <code>mail</code> لتوصيل الرسالة. يمكن تنفيذ ذلك بكل بساطة عبر الشيفرة التالية:<syntaxhighlight lang="rails">
class Notifier < ActionMailer::Base
  default from: 'system@loudthinking.com'

  def welcome(recipient)
    @recipient = recipient
    mail(to: recipient,
         subject: "[Signed up] Welcome #{recipient}")
  end
end
</syntaxhighlight>يُنشَأ محتوى البريد عبر استعمال قالب [[Rails/action view|Action View]] (ملف ERB اعتيادي) يحوي متغيرات النسخة التي صُرِّح عنها.

أي يمكن أن يكون محتوى القالب المقابل للتابع المذكور في الشيفرة السابقة شيئًا شبيهًا بالقالب التالي:<syntaxhighlight lang="html">
Hello there,

Mr. <%= @recipient %>

Thank you for signing up!
</syntaxhighlight>إن كانت قيمة المستلم <code>recipient</code> هي david@loudthinking.com مثلًا، فسيبدو البريد الذي يُولَّد ويُرسَل بالشكل التالي:<syntaxhighlight lang="text">
Date: Mon, 25 Jan 2010 22:48:09 +1100
From: system@loudthinking.com
To: david@loudthinking.com
Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
Subject: [Signed up] Welcome david@loudthinking.com
Mime-Version: 1.0
Content-Type: text/plain;
	charset="US-ASCII";
Content-Transfer-Encoding: 7bit

Hello there,

Mr. david@loudthinking.com

Thank you for signing up!
</syntaxhighlight>لإرسال رسائل بريد إلكتروني، يمكنك ببساطة استدعاء التابع ثم استدعاء <code>deliver_now</code> مع القيمة المعادة.

يعيد استدعاء التابع كائنًا من النوع <code>Mail::Message</code>:<syntaxhighlight lang="rails">
message = Notifier.welcome("david@loudthinking.com")   # => Returns a Mail::Message object
message.deliver_now                                    # => delivers the email

</syntaxhighlight>أو يمكنك سلسلة التابعين مع بعضهما بعضًا مباشرةً:<syntaxhighlight lang="rails">
Notifier.welcome("david@loudthinking.com").deliver_now 
# إنشاء البريد وإرساله مباشرة

</syntaxhighlight>

== ضبط قيم افتراضية ==
يُحتمَل ضبط قيم افتراضية يراد استعمالها في كل تابع موجود في الصنف Action Mailer. ما عليك فعله لتنفيذ ذلك هو استدعاء  تابع الصنف العام <code>default</code> الذي يمكنك الحصول عليه من <code>ActionMailer::Base</code> دون مقابل. يقبل هذا التابع [[Ruby/Hash|جدول Hash]] كمعامل، إذ تكون المفاتيح المستعملة فيه أيًّا من الترويسات - التي تملكها رسائل البريد - مثل <code>from:</code>. يمكنك أيضًا تمرير سلسلة نصية تمثِّل المفتاح مثل <code>Content-Type</code> ولكن يقبل Action Mailer ذلك بشكل غير اعتيادي من أجلك، فلا تقلق حيال ذلك. أخيرًا - وليس آخرًا -، يمكن أيضًا تمرير كائن من النوع <code>[[Ruby/Proc|Proc]]</code> يُقيَّم عند الحاجة إليه.

انتبه إلى أن كل قيمة تضبطها مع هذا التابع ستُستبدَل إن استعملت المفتاح نفسه مع التابع المرسل الخاص بك.

إليك المثال التالي:<syntaxhighlight lang="rails">
class AuthenticationMailer < ActionMailer::Base
  default from: "awesome@application.com", subject: Proc.new { "E-mail was generated at #{Time.now}" }
  .....
end

</syntaxhighlight>

== الضبط ==
الصنف <code>Base</code> يملك قائمة شاملة بخيارات الضبط. إليك المثال التالي:<syntaxhighlight lang="rails">
ActionMailer::Base.smtp_settings = {
  address:        'smtp.yourserver.com', # default: localhost
  port:           '25',                  # default: 25
  user_name:      'user',
  password:       'pass',
  authentication: :plain                 # :plain, :login or :cram_md5
}

</syntaxhighlight>

== التنزيل والتثبيت ==
يمكنك تنزيل أحدث إصدار من Action Mailer مع RubyGems:<syntaxhighlight lang="shell">
$ gem install actionmailer

</syntaxhighlight>يمكن تنزيل الشيفرة المصدرية كجزء من [https://github.com/rails/rails/tree/master/actionmailer مشروع ريلز على GitHub].

== مصادر ==
* [https://github.com/rails/rails/tree/master/actionmailer صفحة Action Mailer من مشروع ريلز على GitHub.]