django email signals

إشارات البريد الإلكتروني Django

تطبيق Django يوفر وظائف لإنشاء إشارات عبر لوحة المسؤول التي سترسل رسائل بريد إلكتروني بناءً على بعض التغييرات على بعض النماذج.

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

أقسام

• إشارات البريد الإلكتروني Django
  • أقسام
  • استخدام الحالات
  • مثال الاستخدام
    • إنشاء إشارة قاعدة
    • تحديد قيود الإشارة
  • تثبيت
  • يثبت
  • إضافة إشارات
  • ملعب
  • المساهمة
    • رمز الكتابة
    • التنسيق والبطانة
  • الاختبار

استخدام الحالات

يمكن للمسؤولين إعداد إشارات/رسائل البريد الإلكتروني بأنفسهم

إذا طلب أحد مستخدمي المسؤول إرسال بريد إلكتروني عندما يحدث شيء ما في قاعدة البيانات ، فماذا نفعل؟ نحن المطورين ينشئون إشارة جديدة ، ونضع أي قيود ، وإنشاء قوالب البريد الإلكتروني ، وتجميع كل شيء معًا ، وإنشاء اختبارات الوحدة ثم النشر. بسيطة نسبيًا ، ولكن لا تزال تستغرق وقتًا طويلاً خاصةً عندما تكون هناك إشارات متعددة لإعدادها لتغييرات مختلفة. هذا بسرعة يصبح عملية طويلة جدا.

يهدف هذا التطبيق إلى حل هذا من خلال توفير طريقة للمسؤولين لإنشاء هذه الإشارات بأنفسهم بدلاً من الاضطرار إلى طلب الميزة وانتظار النشر. هذه طريقة رائعة لتخفيف الضغط من المطورين مع إعطاء المسؤولين القدرة على الحصول على النتائج بسرعة.

كيف يمكن للمسؤول معرفة الحقول التي يجب إدخالها في المعاملات؟ يقوم التطبيق بالتحقق من صحة النموذج قبل حفظه ولكنه يوفر أيضًا الإكمال التلقائي للحقول.

النماذج الأولية بسرعة واختبار قالب البريد الإلكتروني

يمكن أن يكون إنشاء قوالب واختبار بعض الفرق الأكبر عملية تستغرق وقتًا طويلاً. هذا صحيح بشكل خاص عندما يكون الطلب من شخص لا يمكن لأي سبب لا يمكنه عرض شاشتك ويعتمد عليك النشر في بيئة اختبار لتتمكن من اختبار القالب.

ثم يمكن أن تصبح العملية مملة بعض الشيء. من أي وقت مضى في سيناريو حيث تقوم بنشر بعض التعليمات البرمجية للاختبار ، ومراجعته ، وعليها تعديل بعض التعليمات البرمجية ، وإعادة نشرها ، وتكرار العملية عدة مرات؟

يهدف هذا التطبيق إلى حل هذا من خلال توفير طريقة للمسؤولين لإنشاء محتوى HTML بأنفسهم باستخدام محرر نصية غني. هذا يسمح للمشرفين بالنموذج الأولي بسرعة واختبار محتوى البريد الإلكتروني بأنفسهم. بمجرد الاستعداد ، كل ما يحتاجون إليه هو النقر على "إظهار رمز المصدر" ، وإرسال رمز المصدر الحلو إليك.

مثال الاستخدام

دعونا نتخيل أننا نريد إخطار فريق معين كلما تم تقديم طلب جديد على موقعنا على الويب.

إنشاء إشارة قاعدة

سنبدأ عن طريق تعيين الإشارة التالية:

في لقطة الشاشة هذه ، نلاحظ بعض الأشياء.

تم تعيين النموذج على "sample_app | order". بالنسبة لهذا المثال ، أنشأنا نموذجًا للطلب (يمكن العثور عليه في example/sample_app/models.py ) وقمنا بتعيين نوع الإشارة على النشر .

هذا يعني أننا نقوم بإنشاء إشارة حفظ منشور على نموذج الطلب.

في هذا المثال ، أدخلنا قيمًا للنص العادي وحقول محتوى HTML. ستلاحظ أنه مثلما نفعل مع القوالب ، يمكننا إضافة أصحاب نائبة للسياق باستخدام الأقواس المجعد.

لقد استخدمنا هذه بالطريقة التالية:

Order ID: {{ instance.id }}
Customer Name {{ instance.customer.id }}
Customer Email {{ instance.customer.email }}

نظرًا لأن هذه الإشارة تتعلق بنموذج Order ، instance يمثل مثيل Order واحد.

عند إرسال البريد الإلكتروني ، سيتم استبدال العناصر النائبة بقيم السياق الفعلية.

من المهم أن نلاحظ أن السياق الوحيد المتاح هو instance ، وبالتالي يجب الوصول إلى أي سياق آخر عبر كائن instance .

هذه طريقة واحدة لتوفير سياق القالب. إذا كنت تفضل ذلك ، يمكنك بدلاً من ذلك توفير قيمة لحقل القالب الذي يعد طريقًا إلى ملف قالب.

يمكننا أيضًا أن نرى أننا قمنا بتعيين قائمة بريدية على new_order_mailing_list . في نموذج الطلب الخاص بنا ، لدينا طريقة new_order_mailing_list المقابلة التي تُرجع قائمة رسائل البريد الإلكتروني. هذا يعني أنه سيتم إرسال هذا البريد الإلكتروني المعين إلى رسائل البريد الإلكتروني التي تم إرجاعها بواسطة Order.new_order_mailing_list . من خلال إنشاء طرق مختلفة تحتوي على قوائم مختلفة من رسائل البريد الإلكتروني ، لدينا بشكل فعال طريقة لإنشاء قوائم بريدية مختلفة. بدلاً من ذلك ، يمكننا فقط استخدام قائمة رسائل البريد الإلكتروني المفوضة في القائمة البريدية.

قبل أن نبدأ في إضافة أي قيود ، نحن نحفظ الإشارة. سيؤدي ذلك إلى جعل قيود إشارة الإعداد سهلة لأنها ستسمح لميزة الإكمال التلقائي بمساعدتنا. إذا كنت قلقًا بشأن الوقت بين حفظ الإشارة ووضع قيود الإشارة ، فيمكنك دائمًا تعيين العلامة النشطة على False مسبقًا. هذا سيمنع أي بريد إلكتروني من إرساله.

تحديد قيود الإشارة

يمكننا الآن ضبط القيود على الإشارة. سنخلق قيودتين:

1. يجب أن يكون مثيلًا جديدًا ( created == True ).
2. يجب أن يكون معرف العميل أكبر من 10 ( customer.id > 10).

أحد الشيكات الشائعة عند إنشاء إشارة post_save هو التحقق من أن المثيل هو مثيل جديد. يمكن القيام بذلك عن طريق تعيين المعلمة على created والمقارنة مع "صحيح".

يحتوي نموذج الطلب لدينا على حقل customer يمثل مفتاحًا خارجيًا لنموذج customer . يمكننا اجتياز كائن customer للحصول على id العميل. يمكننا بعد ذلك التحقق مما إذا كان customer.id > 10 .

يحتوي التطبيق على ميزة إكمال تلقائي مفيد والتي ستساعدك على اجتياز حقول النماذج وأي خصائص مخزنة مؤقتًا. لا تقلق بشأن ارتكاب أي أخطاء حيث يوجد التحقق من الصحة لرفض أي معلمات لا يمكن الوصول إليها.

سيؤكد حفظ هذه الإشارة الآن إرسال الإشارة فقط عندما يكون الطلب مثيلًا جديدًا ومعرف العميل أكبر من 10.

تثبيت

لتثبيت التطبيق ، قم بتشغيل الأمر التالي:

 pip install django-email-signals

سيكون أمر تثبيت PIP هو كل ما هو مطلوب لمعظم الأشخاص ، ولكن إذا كنت تريد أن تنظر تحت الغطاء ومعرفة ما يحدث ، يمكنك استنساخ دليل المصدر:

 git clone https://github.com/Salaah01/django-email-signals.git

يثبت

1. أضف إلى INSTALLED_APPS i. أضف tinymce إلى INSTALLED_APPS في ملف settings.py الخاص بك.

 INSTALLED_APPS = [
  ' app_1 `,
  ' app_2 `,
  '...' ,
  'tinymce' ,
]

الثاني. أضف email_signals إلى INSTALLED_APPS في ملف settings.py . يجب إضافة هذا بعد أي تطبيقات تحتوي على نماذج ترغب في إنشاء إشارات باستخدام هذا التطبيق.

 INSTALLED_APPS = [
  ' app_1 `,
  ' app_2 `,
  '...' ,
  'tinymce' ,
  ' email_signals `
]

2. تشغيل الهجرات وجمع ثابت

 python manage.py migrate
python manage.py collectstatic

3. تحديث عناوين URL (اختيارية) تحديث ملف urls.py الجذر لتضمين ما يلي:

 from django . urls import include

url_patterns = [
  path ( 'email-signals/' , include ( 'email_signals.urls' )),
  path ( 'tinymce/' , include ( 'tinymce.urls' )),
]

نوصي بتغيير عنوان URL إلى شيء أصعب قليلاً في التخمين ، فقط لجعل الحياة أكثر صعوبة لأولئك المتلقين المزعمين. تتطلب جميع مسارات التطبيق من المستخدم أن يكون موظفًا قادرًا على الوصول إلى الروابط.

على الرغم من أن هذه الخطوة اختيارية ، فإننا نوصي بذلك لأنها ستجعل قيودًا في منطقة المشرف أسهل بكثير. هناك حاجة إلى عناوين URL لتوفير منسدلة مع خيارات عند بناء قيودك.

4. إضافة بريد إلكتروني افتراضي (اختياري) إضافة EMAIL_SIGNAL_DEFAULT_SENDER إلى الإعدادات الخاصة بك. على سبيل المثال: EMAIL_SIGNAL_DEFAULT_SENDER = '[email protected] إذا كنت لا ترغب في تحديد بريد إلكتروني مرسل بشكل صريح لكل إشارة تحددها ، يمكنك تعيين EMAIL_SIGNAL_DEFAULT_SENDER في settings.py المشروع.

5. أضف Model Mixin على النماذج التي تريد رفعها إشارات ، ستحتاج إلى إضافة Mixin التالي كاعتماد على النماذج: email_signals.models.EmailSignalMixin .

مثال: لنفترض أن لديك النموذج التالي.

 from django . db import models

class Customer ( models . Model ):
    name = models . CharField ( max_length = 200 , null = True )
    email = models . CharField ( max_length = 200 )

ستحتاج إلى تغيير هذا النموذج إلى ما يلي:

 from email_signals . models import EmailSignalMixin

class Customer ( models . Model , EmailSignalMixin ):
    name = models . CharField ( max_length = 200 , null = True )
    email = models . CharField ( max_length = 200 )

6. أضف المستلمين اعتمادًا على التغيير إلى البيانات ، قد ترغب في إرسال بريد إلكتروني إلى أشخاص مختلفين. نحن نسهل ذلك عن طريق إعداد قوائم البريد الممكنة المختلفة في النموذج نفسه. هذا واحد أسهل للعرض أولاً ثم شرح:

 from email_signals . models import EmailSignalMixin

class Customer ( models . Model , EmailSignalMixin ):
    name = models . CharField ( max_length = 200 , null = True )
    email = models . CharField ( max_length = 200 )

    def customer_emails ( self ):
        """Recipient is the customer."""
        return [ self . email ]
    
    def management_mailing_list ( self ):
        """Recipient list includes management."""
        return [ '[email protected]' , '[email protected]' ]

لقد أنشأنا وظيفتين تسمى customer_emails و management_mailing_list التي تُرجع كل مجموعة من عناوين البريد الإلكتروني. في وقت لاحق ، عندما نقوم بإعداد الإشارات ، سيُطلب منا تعيين القائمة البريدية لاستخدامها في كل إشارة. هذا هو المكان الذي ندخل فيه أسماء الوظائف لدينا `customer_emails or management_mailing_list`.

لذلك ، يسمح لنا بإعداد قوائم بريدية مختلفة داخل نماذجنا.

إضافة إشارات

الآن وبعد اكتمال الإعداد ، يمكن إضافة إشارات عبر المسؤول (أو عن طريق تحديث قاعدة البيانات مباشرة).

سوف نتخيل أنني أدير موقعًا على مضيف محلي ، وبالتالي يمكن العثور على لوحة المسؤول من خلال التنقل إلى http: // localhost: 8000/admin/. يمكن بعد ذلك الوصول إلى الإشارات عن طريق التنقل إلى http: // localhost: 8000/admin/email_signals/signal/. سنبدأ بإضافة بعض الإشارات. انقر فوق "إضافة إشارة" للبدء.

لقد علمني الرجل الحكيم أنه من الأفضل أن أبدو سخيفًا للحظة من عدم معرفة شيء ما ويشعر بالغباء إلى الأبد . لذلك ، في هذا السياق ، على الرغم من أنه قد يبدو واضحًا ، إلا أننا سنختار الخيارات في النموذج ونناقش ما هو كل خيار مسؤول عنه.

تسمية الحقل	اسم الحقل	وصف
اسم	اسم	اسم للإشارة الخاصة بك ، فقط لتسهيل التمييز عن السجلات الأخرى.
وصف	وصف	(اختياري) الوصف للإشارة الخاصة بك.
النموذج (الجدول)	content_type	اختر من منسدلة النموذج تتعلق هذه الإشارة.
محتوى نص عادي	plain_message	(اختياري) رسالة بريد إلكتروني نصية عادي لإرسالها.
HTML المحتوى	html_message	(اختياري) البريد الإلكتروني html لإرساله.
موضوع	موضوع	موضوع البريد الإلكتروني
من البريد الإلكتروني	من _email	(اختياري) مرسل البريد الإلكتروني. الإعدادات الافتراضية إلى settings.EMAIL_SIGNAL_DEFAULT_SENDER . email_signal_default_sender.
قائمة البريد	Mailing_List	قائمة المستلم حيث النص الذي تدخله ، يتوافق مع طريقة تسمى في فئة النموذج مع نفس الاسم. على سبيل المثال: إذا قمت بإدخال customer_mails ، فسيحتاج إلى أن تكون هناك طريقة تسمى customer_mails التي تُرجع مجموعة من رسائل البريد الإلكتروني في فئة النموذج. بدلاً من ذلك ، يمكن أن تكون هذه قائمة من رسائل البريد الإلكتروني مفصولة بفاصلة. على سبيل المثال: [email protected],[email protected] البريد الإلكتروني إلى كل من رسائل البريد الإلكتروني هذين.
نموذج	نموذج	(اختياري) المسار إلى قالب ، إذا كنت ترغب في تقديم بريد إلكتروني من قالب. يستخدم هذا محمل قالب Django ، بحيث يجب أن تكون القيمة التي تقدمها هنا نسبة إلى settings.TEMPLATES[i]['DIRS']
نوع الإشارة	Signal_type	نوع الإشارة لرفع لهذا السجل.
نشيط	نشيط	مفتاح لتشغيل هذه الإشارة وإيقافها.

قيود الإشارة هذا النموذج المضمن هو المكان الذي يمكنك فيه تعيين بعض القيود التي ستحدد ما إذا كان ينبغي رفع الإشارة على أساس كل حالة.

تسمية الحقل	اسم الحقل	وصف
المعلمة 1	param_1	المعلمة الأولى لاستخدامها عند اختبار القيد. يجب أن توجد هذه المعلمة في إشارة Kwargs أو مثيل النموذج.
مقارنة	مقارنة	تحديد كيفية مقارنة المعلمات. على سبيل المثال: المعلمة 1 أكبر من المعلمة 2.
المعلمة 1	param_1	(اختياري) المعلمة الثانية لاستخدامها عند اختبار القيد. يمكن ترك هذه المعلمة فارغة عندما يكون القيد أمرًا معقولًا. على سبيل المثال ، إذا كان القيد "صحيحًا" ، فليس هناك حاجة للمعلمة 2. ولكن إذا كان القيد ، "أكبر من" ، فإن المعلمة 2 مطلوبة. يمكن أن تكون المعلمة 2 أيضًا نوعًا بدائيًا مثل "A" ، "1" ، "1.1". سيحاول التطبيق تحويل السلاسل إلى أرقام إذا كان بإمكانه ذلك.

المعلمات عميقة على حد سواء المعلمتين 1 و 2 يسمح لك بالبحث بعمق داخل كائن. لنفترض أن لدينا الهيكل التالي والإشارة قد تلقوا مثيل CustomerOrder .

 classdiagram
    المستخدم <| -- عميل
    العميل <| - CustomerOrder

    مستخدم الفئة {
      بطاقة تعريف
      الاسم الأول
      اسم العائلة
      بريد إلكتروني
    }
    
    عميل الفئة {
      بطاقة تعريف
      مستخدم
      fav_language
    }

    Class Customerorder {
      بطاقة تعريف
      عميل
      order_id
      المجموع
    }

بالنظر إلى مثيل CustomerOrder (سوف نسمي هذا order المتغير) ، يمكننا تعيين ما يلي في قيودنا:

#	المعلمة 1	مقارنة	المعلمة 2
1	'customer.user.id'	أكبر من	'5'
2	'customer.user.first_name'	يساوي	'customer.user.last_name'

القيد 1 سوف تحقق ما يلي:

 order . customer . user . id > 5

وبالمثل ، سيقوم القيد 2 بالتحقق من ما يلي:

 order . customer . user . first_name == order . customer . user . last_name

فقط عندما يتم استيفاء جميع القيود ، سيتم إرسال البريد الإلكتروني.

ملعب

يأتي المستودع مع مشروع مثال لتبدأ. إذا كنت تفضل اختبار هذا التطبيق بنفسك ، فإنني أوصي باستنساخ المستودع.

التنقل إلى example وتشغيل مشروع Django في الداخل.

المساهمة

إذا كان لديك أي اقتراحات أو تحسينات ، فلا تتردد في فتح مشكلة أو طلب سحب.

رمز الكتابة

إذا كنت ترغب في المساهمة في الكود ، فيرجى اتباع الخطوات التالية:

1. شوكة المستودع
2. قم بإنشاء مشكلة لمناقشة الميزة التي ترغب في إضافتها أو الأخطاء التي ترغب في إصلاحها
3. استنساخ المستودع
4. قم بإنشاء فرع جديد للميزة أو إصلاح الأخطاء
5. إنشاء بيئة افتراضية وتثبيت المتطلبات
6. قم بتشغيل npm install لتثبيت التبعيات لمشروع المثال
7. إذا كنت تنوي إجراء تغييرات على ملفات TypeScript أو Sass ، npm start في بدء تشغيل خادم WebPack Dev. سيشاهد هذا التغييرات وإعادة ترجمة الملفات. خلاف ذلك ، قم بتشغيل npm run build لتجميع الملفات مرة واحدة.
8. اكتب بعض التعليمات البرمجية الرائعة
9. إجراء اختبارات (التعليمات موجودة هنا)
10. عندما تكون مستعدًا لإرسال الكود الخاص بك ، قم بتشغيل formatter و linter
11. ارتكب التغييرات الخاصة بك ، وادفع إلى شوكة الخاص بك وفتح طلب سحب

التنسيق والبطانة

عند المساهمة ، يرجى التأكد من أنك أضفت اختبارات لتغييراتك وأن جميع الاختبارات الخاصة بك تمر (انظر الاختبار). يرجى أيضًا التأكد من تنسيق الكود الخاص بك بشكل صحيح وأن الكود الخاص بك يمر.

نحن نستخدم black و flake8 لتنسيق وبرد الكود الخاص بنا. إذا كنت قد make تثبيتها ، فيمكنك تشغيل ما يلي لتنسيق الكود الخاص بك وترده:

make format
make lint

بدلاً من ذلك ، يمكنك تشغيل الأوامر التالية:

black email_signals
flake8 --exclude=migrations email_signals

الاختبار

يستخدم هذا المستودع tox لتشغيل الاختبارات مقابل إصدارات متعددة من Python و Django. إذا كنت قد make تثبيتها ، فيمكنك ببساطة تشغيل الاختبارات عن طريق تشغيل make tox . خلاف ذلك ، يمكنك تشغيل الاختبارات عن طريق تشغيل tox -s في جذر المستودع.

إذا كنت ترغب في إجراء اختبارات إصدار Python الحالي الخاص بك فقط ، فيمكنك إما تشغيل tox -e py أو python3 runtests.py .