عرفت حتى الآن الغرض من إطار عمل جانغو Django، وسنوضّح الآن كيفية إعداد واختبار بيئة تطوير جانغوعلى أنظمة التشغيل ويندوز ولينكس (أوبنتو) وماك أو إس macOS، إذ يجب أن يعطيك هذا المقال ما تحتاجه لتكون قادرًا على البدء في تطوير تطبيقات جانغو بغض النظر عن نظام التشغيل الذي تستخدمه.

• المتطلبات الأساسية: معرفة أساسية باستخدام سطر الأوامر أو الطرفية Terminal وكيفية تثبيت الحزم البرمجية على نظام تشغيل حاسوب التطوير خاصتك.
• الهدف: تشغيل بيئة تطوير جانغو على حاسوبك.

تتألف هذه السلسلة الفرعية من السلسلة الأشمل تعلم تطوير الويب من المقالات التالية:

• مدخل إلى إطار عمل الويب جانغو Django
• إعداد بيئة تطوير تطبيقات جانغو
• تطبيق عملي لتعلم جانغو - الجزء الأول: إنشاء موقع ويب هيكلي لمكتبة محلية
• تطبيق عملي لتعلم جانغو - الجزء الثاني: استخدام النماذج Models
• تطبيق عملي لتعلم جانغو - الجزء الثالث: موقع مدير جانغو Django Admin
• تطبيق عملي لتعلم جانغو - الجزء الرابع: إنشاء صفحة المكتبة الرئيسية
• تطبيق عملي لتعلم جانغو - الجزء الخامس: العروض Views العامة والتفصيلية
• تطبيق عملي لتعلم جانغو - الجزء السادس: إدارة الجلسات Sessions
• تطبيق عملي لتعلم جانغو - الجزء السابع: استيثاق المستخدمين وأذوناتهم
• تطبيق عملي لتعلم جانغو - الجزء الثامن: العمل مع الاستمارات Forms
• تطبيق عملي لتعلم جانغو - الجزء التاسع: اختبار تطبيق جانغو
• تطبيق عملي لتعلم جانغو - الجزء 10: نشر تطبيق جانغو في بيئة الإنتاج
• تعرف على أمان تطبيقات جانغو

نظرة عامة إلى بيئة تطوير جانغو

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

ما هي بيئة تطوير جانغو؟

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

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

خيارات إعداد جانغو

يُعَد جانغو مرنًا جدًا من حيث كيفية ومكان تثبيته وإعداده، إذ يمكن أن يكون جانغو:

• مثبتًا على أنظمة تشغيل مختلفة.
• مثبتًا من المصدر من نظام إدارة الحزم Python Package Index -أو PyPi اختصارًا- ومن تطبيق مدير الحزم للحاسوب المضيف في كثير من الحالات.
• مُعَدًا لاستخدام واحدة من عدة قواعد بيانات، والتي يمكن أن تحتاج إلى التثبيت والإعداد بصورة منفصلة.
• يُشغَّل في بيئة نظام بايثون الرئيسي، أو ضمن بيئات بايثون الافتراضية المنفصلة.

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

ملاحظة: خيارات التثبيت الممكنة الأخرى موضَّحة في توثيق جانغو الرسمي، وسنقدّم روابطًا إلى التوثيق المناسب لاحقًا.

أنظمة التشغيل المدعومة

يمكن تشغيل تطبيقات جانغو على أيّ جهاز تقريبًا يمكنه تشغيل لغة بايثون 3 مثل أنظمة ويندوز وماك أو إس ولينكس/ يونيكس وسولاريس Solaris. يجب أن يتمتع أي حاسوب تقريبًا بالأداء اللازم لتشغيل جانغو أثناء عملية التطوير. سنقدم في هذا المقال إرشادات لأنظمة ويندوز وماك أو إس ولينكس/ يونيكس.

نسخة بايثون التي يجب استخدامها

يمكنك استخدام أيّ نسخة من بايثون يدعمها إصدار جانغو المستهدف. النسخ المسموح بها بالنسبة لإصدار جانغو 4.0.2 هي إصدار بايثون 3.8 إلى 3.10 (اطلع على نسخة بايثون التي يمكن استخدامها مع جانغو).

يوصي مشروع جانغو (ويدعم رسميًا) باستخدام أحدث إصدار مدعوم من بايثون.

مكان تنزيل جانغو

هناك ثلاثة أماكن لتنزيل جانغو، هي:

• مستودع حزم بايثون Python Package Repository -أو اختصارًا PyPi- باستخدام أداة Pip، وهي أفضل طريقة للحصول على أحدث نسخة مستقرة من جانغو.
• استخدم نسخةً من مدير حزم حاسوبك، إذ تقدم توزيعات جانغو المُجمَّعة مع أنظمة التشغيل آلية تثبيت مألوفة. يمكن أن تكون النسخة المُضمَّنة قديمة جدًا، ولا يمكن تثبيتها إلا في بيئة بايثون الخاصة بالنظام (وهذا ما لا تريده).
• التثبيت من المصدر، إذ يمكنك الحصول على أحدث نسخة من جانغو وتثبيتها من المصدر، وهذا غير موصَى به للمبتدئين ولكنه ضروري عندما تكون مستعدًا لبدء المساهمة في جانغو.

يوضح هذا المقال كيفية تثبيت جانغو من مستودع حزم PyPi للحصول على أحدث نسخة مستقرة.

قاعدة البيانات المستخدمة

يدعم جانغو رسميًا قواعد بيانات PostgreSQL و MariaDB و MySQL و Oracle و SQLite، وهناك مكتبات مجتمعية توفر مستويات مختلفة من الدعم لقواعد بيانات SQL و NoSQL الشائعة الأخرى. نوصيك باختيار قاعدة البيانات نفسها لكل من الإنتاج والتطوير، إذ لا تزال هناك مشاكل محتملة يُفضَّل تجنبها بالرغم من أن جانغو يجرّد العديد من الاختلافات في قاعدة البيانات باستخدام رابط الكائنات العلائقي Object-Relational Mapper -أو ORM اختصارًا.

سنستخدم في هذا المقال قاعدة بيانات SQLite التي تخزن بياناتها في ملف؛ إذ صُمِّمت قاعدة بيانات SQLite للاستخدام بوصفها قاعدة بيانات خفيفة الوزن ولا يمكنها دعم مستوى عالٍ من التزامن، ولكنها تُعَد اختيارًا ممتازًا للتطبيقات التي تكون للقراءة فقط.

ملاحظة: أُعِّد جانغو لاستخدام قاعدة بيانات SQLite افتراضيًا عند بدء مشروع موقع الويب باستخدام الأدوات المعيارية (django-admin)، وتُعَد خيارًا رائعًا عند البدء لأنها لا تتطلب أي إعداد أو ضبط إضافي.

التثبيت على مستوى النظام أم في بيئة بايثون الافتراضية

تحصل بتثبيت بايثون 3 على بيئة عامة واحدة تشترك فيها جميع شيفرات بايثون البرمجية، ويمكنك تثبيت أيّ حزمة من حزم بايثون التي تريدها في هذه البيئة، ولكن يمكنك تثبيت نسخة معينة واحدة فقط من كل حزمة في الوقت نفسه.

ملاحظة: يُحتمَل أن تتعارض تطبيقات بايثون المثبتة في البيئة العامة مع بعضها بعضًا، أي إذا كانت معتمدة على نسخ مختلفة من الحزمة نفسها.

إذا ثبَّتَ جانغو في البيئة الافتراضية أو العامة، فستتمكّن فقط من استهداف نسخة واحدة من جانغو على الحاسوب، ويمكن أن يشكّل ذلك مشكلة إذا أردتَ إنشاء مواقع ويب جديدة (باستخدام أحدث نسخة من جانغو) مع الاستمرار في الحفاظ على مواقع الويب التي تعتمد على النسخ القديمة، لذا يشغّل مطورو بايثون/جانغو ذوو الخبرة تطبيقات بايثون في بيئات بايثون الافتراضية المستقلة، مما يتيح العديد من بيئات جانغو المختلفة على حاسوب واحد. يوصي فريق مطوري جانغو باستخدام بيئات بايثون الافتراضية.

تفترض هذه السلسلة من المقالات أنك ثبَّتَ جانغو في بيئة افتراضية، وسنوضح فيما يلي كيفية ذلك.

تثبيت لغة بايثون 3

يجب تثبيت بايثون على نظام التشغيل لاستخدام جانغو، وإذا كنت تستخدم بايثون 3، فستحتاج أداة الخاصة بمستودع حزم بايثون Python Package Index وهي pip3 التي تُستخدَم لإدارة (تثبيت وتحديث وحذف) حزم أو مكتبات بايثون التي تستخدمها تطبيقات جانغو وتطبيقات بايثون الأخرى.

يشرح هذا القسم بإيجاز كيفية التحقق من نسخ بايثون الموجودة مسبقًا ويوضح طريقة تثبيت نسخ جديدة حسب الحاجة لنظام التشغيل أوبنتو لينكس 20.04 ونظام ماك أو إس ونظام ويندوز 10.

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

تثبيت لغة بايثون على نظام التشغيل لينكس أوبنتو

يتضمن نظام أوبنتو لينكس LTS‏ 20.04 بايثون 3.8.10 افتراضيًا، ويمكنك التأكّد من ذلك من خلال تشغيل الأمر التالي في طرفية باش Bash:

python3 -V
 Python 3.8.10

ليست الأداة pip3 الخاصة بمستودع حزم بايثون التي ستحتاجها لتثبيت حزم بايثون 3 (بما في ذلك جانغو) متوفرة افتراضيًا، إذ يمكنك تثبيت pip3 في طرفية باش باستخدام الأمر التالي:

sudo apt install python3-pip

ملاحظة: تُعَد بايثون 3.8 أقدم نسخة يدعمها جانغو 4.0. يوصي إطار عمل جانغو بالتحديث إلى أحدث نسخة، ولكنك لا تحتاج إلى استخدام أحدث نسخة في هذه السلسلة من المقالات. إذا أردت تحديث بايثون، فيمكنك البحث عن التعليمات على الإنترنت.

تثبيت لغة بايثون على نظام ماك أو إس

لا تتضمن النسخة إل كابيتان El Capitan من نظام ماك أو إس والنسخ الأحدث الأخرى لغةَ بايثون 3، ويمكنك التأكّد من ذلك من خلال تشغيل الأوامر التالية في طرفية zsh أو طرفية باش:

$ python3 -V
  python3: command not found

يمكنك بسهولة تثبيت بايثون 3 (إضافةً إلى أداة pip3) من موقع بايثون كما يلي:

1. نزّل برنامج التثبيت المطلوب:
   • انتقل إلى موقع بايثون الرسمي.
   • نزّل أحدث نسخة مدعومة تعمل مع جانغو 4.0.2 (وهي نسخة بايثون 3.10.2 في وقت كتابة هذا المقال).
2. حدّد موقع الملف باستخدام مدير الملفات فايندر Finder، وانقر نقرًا مزدوجًا على ملف الحزمة، ثم اتبع خطوات التثبيت.

يمكنك الآن تأكيد التثبيت الناجح من خلال التحقق من نسخة بايثون 3 كما يلي:

python3 -V
 Python 3.10.2

يمكنك التحقق من تثبيت أداة pip3 من خلال سرد الحزم المتاحة:

pip3 list

تثبيت لغة بايثون على نظام ويندوز 10 أو 11

لا يتضمن نظام ويندوز لغة بايثون افتراضيًا، ولكن يمكنك تثبيتها بسهولة (إضافةً إلى أداة pip3) من موقع بايثون كما يلي:

1. نزّل برنامج التثبيت المطلوب بالطريقة التالية:
   • انتقل إلى موقع بايثون.
   • نزّل أحدث نسخة مدعومة تعمل مع جانغو 4.0.2 (وهي نسخة بايثون 3.10.2 في وقت كتابة هذا المقال).
2. ثبّت بايثون بالنقر المزدوج على الملف الذي نزّلته واتبّع خطوات التثبيت.
3. تأكد من تحديد المربع المسمَّى "إضافة بايثون إلى المسار Add Python to PATH".

يمكنك بعد ذلك التحقق من تثبيت بايثون 3 من خلال إدخال النص التالي في موجّه الأوامر:

py -3 -V
 Python 3.10.2

يضمّن مثبِّت نظام ويندوز الأداة pip3 (مدير حزمة بايثون) افتراضيًا، ويمكنك سرد الحزم المُثبَّتة كما يلي:

pip3 list

ملاحظة: يجب على المثبِّت إعداد كل ما تحتاجه حتى يعمل الأمر السابق. إذا تلقيتَ رسالةً مفادها أنه لا يمكن العثور على بايثون، فيمكن أن تكون قد نسيت إضافتها إلى مسار نظامك، ويمكنك تطبيق ذلك من خلال تشغيل المثبت مرةً أخرى وتحديد الخيار "تعديل Modify" وتحديد المربع المسمى "إضافة بايثون إلى متغيرات البيئة Add Python to Environment Variables" في الصفحة الثانية.

استخدام جانغو ضمن بيئة بايثون الافتراضية

المكتبات التي سنستخدمها لإنشاء بيئاتنا الافتراضية هي virtualenvwrapper (لينكس وماك أو إس) وvirtualenvwrapper-win (ويندوز)، إذ تستخدم هاتان المكتبتان أداة virtualenv. تنشئ الأدوات المغلِّفة واجهة متناسقة لإدارة الواجهات على جميع المنصات.

تثبيت برمجيات البيئة الافتراضية

سنتعرّف الآن على كيفية إعداد البيئة الافتراضية في كل من أنظمة تشغيل أوبنتو وماك وويندوز.

إعداد بيئة أوبنتو الافتراضية

يمكنك بعد تثبيت بايثون وأداة pip تثبيت المكتبة virtualenvwrapper التي تتضمن المكتبة virtualenv. يمكنك الاطلاع على دليل التثبيت الرسمي أو اتباع الإرشادات التالية.

ثبّت الأداة أو المكتبة باستخدام الأداة pip3 كما يلي:

sudo pip3 install virtualenvwrapper

أضف بعد ذلك الأسطر التالية إلى نهاية ملف بدء تشغيل الصدفة Shell، وهو اسم ملف مخفي "‎.bashrc" في مجلدك الرئيسي. تحدد الأسطر التالية الموقع الذي توجد فيه البيئات الافتراضية وموقع مجلدات مشروع التطوير وموقع السكربت المُثبَّت مع هذه الحزمة:

export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export VIRTUALENVWRAPPER_VIRTUALENV_ARGS=' -p /usr/bin/python3 '
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh

ملاحظة: تشير المتغيرات VIRTUALENVWRAPPER_PYTHON و VIRTUALENVWRAPPER_VIRTUALENV_ARGS إلى موقع التثبيت العادي لبايثون 3، ويشير المصدر ‎/usr/local/bin/virtualenvwrapper.sh إلى الموقع الاعتيادي للسكربت virtualenvwrapper.sh. إذا لم تعمل مكتبة virtualenv عند اختبارها، فالشيء الوحيد الذي يجب التحقق منه هو أن بايثون والسكربت موجودان في الموقع المتوقع، ثم غيّر ملف بدء التشغيل بطريقة مناسبة. يمكنك العثور على المواقع الصحيحة لنظامك باستخدام الأوامر which virtualenvwrapper.sh و which python3.

أعِد بعد ذلك تحميل ملف بدء التشغيل من خلال تشغيل الأمر التالي في الطرفية:

source ~/.bashrc

يجب الآن أن ترى مجموعة من السكربتات التي تُشغَّل كما يلي:

virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/premkproject
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/postmkproject
# …
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/preactivate
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/postactivate
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/get_env_details

يمكنك الآن إنشاء بيئة افتراضية جديدة باستخدام الأمر mkvirtualenv.

إعداد البيئة الافتراضية لنظام ماك أو إس

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

ثبّت المكتبة Virtualenvwrapper (وتجميع المكتبة virtualenv) باستخدام الأداة pip كما يلي:

sudo pip3 install virtualenvwrapper

أضف بعد ذلك الأسطر الآتية إلى نهاية ملف بدء تشغيل الصدفة، وهي السطور في نظام أوبنتو نفسها. إذا كنت تستخدم صدفة zsh، فسيكون ملف بدء التشغيل ملفًا مخفيًا باسم "‎.zshrc" في مجلدك الرئيسي، وإذا كنت تستخدم صدفة باش Bash، فسيكون ملفًا مخفيًا باسم "‎.bash_profile"، وقد تحتاج إلى إنشاء الملف إن لم يكن موجودًا بعد.

export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh

ملاحظة: يشير المتغير VIRTUALENVWRAPPER_PYTHON إلى موقع التثبيت العادي لبايثون 3، ويشير المصدر ‎/usr/local/bin/virtualenvwrapper.sh إلى الموقع الاعتيادي للسكربت virtualenvwrapper.sh. إذا لم تعمل المكتبة virtualenv عند اختبارها، فالشيء الوحيد الذي يجب التحقق منه هو أن بايثون والسكربت موجودان في الموقع المتوقع، ثم غيّر ملف بدء التشغيل بطريقة مناسبة.

انتهى اختبار أحد التثبيتات على نظام ماك أو إس مثلًا بالأسطر التالية التي تُعَد ضرورية في ملف بدء التشغيل:

export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/Library/Frameworks/Python.framework/Versions/3.7/bin/python3
export PROJECT_HOME=$HOME/Devel
source /Library/Frameworks/Python.framework/Versions/3.7/bin/virtualenvwrapper.sh

يمكنك العثور على المواقع الصحيحة لنظامك باستخدام الأوامر which virtualenvwrapper.sh و which python3.

أعِد بعد ذلك تحميل ملف بدء التشغيل من خلال إجراء الاستدعاء التالي في الطرفية:

source ~/.bash_profile

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

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

تبدو الأوامر كما يلي بافتراض أنك تستخدم باش Bash:

cd ~  # الانتقال إلى المجلد الرئيسي
ls -la #قائمة محتويات المجلد. ‫يجب أن ترى ‎.bash_profile
nano .bash_profile # ‫افتح الملف في محرر نصوص نانو nano ضمن الطرفية
# انتقل إلى نهاية الملف، وانسخ الأسطر السابقة
# استخدم‫ Ctrl + X للخروج من نانو، واختر Y لحفظ الملف.

إعداد بيئة ويندوز الافتراضية

يُعَد تثبيت مكتبة virtualenvwrapper-win أبسط من إعداد مكتبة virtualenvwrapper، لأنك لا تحتاج إلى إعداد مكان تخزين الأداة لمعلومات البيئة الافتراضية، فهناك قيمة افتراضية، وكل ما عليك فعله هو تشغيل الأمر التالي في موجّه الأوامر:

pip3 install virtualenvwrapper-win

يمكنك الآن إنشاء بيئة افتراضية جديدة باستخدام الأمر mkvirtualenv.

إنشاء بيئة افتراضية

يكون العمل مع البيئات الافتراضية متشابهًا جدًا على جميع المنصات بعد تثبيت المكتبة virtualenvwrapper أو virtualenvwrapper-win.

يمكنك الآن إنشاء بيئة افتراضية جديدة باستخدام الأمر mkvirtualenv، إذ سترى أثناء تشغيل هذا الأمر البيئة التي يجري إعدادها (يكون ما تراه خاصًا بالمنصة). ستكون البيئة الافتراضية الجديدة نشطةً عندما يكتمل الأمر، ويمكنك رؤية ذلك لأن بداية موجّه الأوامر ستكون اسم البيئة بين قوسين، إذ سنعرض ذلك لنظام أوبنتو، ولكن السطر الأخير مشابه لنظام ويندوز وماك أو إس.

$ mkvirtualenv my_django_environment

Running virtualenv with interpreter /usr/bin/python3
# …
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/t_env7/bin/get_env_details
(my_django_environment) ubuntu@ubuntu:~$

أصبحت الآن ضمن البيئة الافتراضية، ويمكنك تثبيت جانغو والبدء في التطوير.

ملاحظة: يُرجَى من الآن فصاعدًا في هذا المقال (وهذه السلسلة من المقالات) افتراض أن أيّ أوامر مُشغَّلة ضمن بيئة بايثون الافتراضية تشبه الأمر الذي ضبطناه سابقًا.

استخدام البيئة الافتراضية

لا يوجد سوى عدد قليل من الأوامر المفيدة الأخرى التي يجب أن تعرفها، إذ يوجد المزيد في توثيق الأدوات، ولكن الأوامر التالية هي التي سنستخدمها بانتظام:

• deactivate: الخروج من بيئة بايثون الافتراضية الحالية.
• workon: سرد البيئات الافتراضية المتاحة.
• workon name_of_environment: تنشيط بيئة بايثون الافتراضية المحددة.
• rmvirtualenv name_of_environment: إزالة البيئة المحددة.

تثبيت جانغو

يمكنك استخدام الأداة pip3 لتثبيت جانغو بعد إنشاء بيئة افتراضية واستدعاء الأمر workon للدخول إليها كما يلي:

pip3 install django~=4.0

يمكنك اختبار تثبيت جانغو من خلال تشغيل الأمر التالي، وهو مجرد اختبار لإمكانية أن تعثر بايثون على وحدة جانغو:

# Linux/macOS
python3 -m django --version
 4.0.2

# Windows
py -3 -m django --version
 4.0.2

ملاحظة: إن لم يُظهِر أمر ويندوز السابق وجود وحدة جانغو، فجرّب الأمر التالي:

py -m django --version

تُشغَّل سكربتات بايثون 3 في ويندوز من خلال أن نضع py -3 في بداية الأمر، بالرغم من أن ذلك يمكن أن يختلف اعتمادًا على التثبيت المحدد، وحاول حذف المعدِّل ‎-3 إذا واجهت أي مشاكل مع الأوامر. بينما يكون الأمر هو python3 في لينكس وماك.

ملاحظة: تستخدم هذه السلسلة من المقالات أمر لينكس python3 لاستدعاء بايثون 3، فإذا كنت تعمل على نظام ويندوز، فاستبدل هذه البادئة بالبادئة py -3.

أدوات بايثون الأخرى

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

لاحظ أنه يجب عليك استخدام منقّح صياغة جانغو مثل pylint-django. يمكن أن تبلّغ منقحات صياغة بايثون شائعة الاستخدام مثل pylint بصورة غير صحيحة عن أخطاء في الملفات المعيارية التي جرى إنشاؤها لجانغو.

اختبار تثبيتك لجانغو Django

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

mkdir django_test
cd django_test

يمكنك بعد ذلك إنشاء موقع هيكلي جديد بالاسم "mytestsite" باستخدام الأداة django-admin كما هو موضح. يمكنك -بعد إنشاء الموقع- الانتقال إلى المجلد حيث ستجد السكربت الرئيسي لإدارة المشاريع والذي يُسمَّى manage.py.

django-admin startproject mytestsite
cd mytestsite

يمكننا تشغيل خادم الويب الخاص بالتطوير من داخل هذا المجلد باستخدام manage.py والأمر runserver كما يلي:

$ python3 manage.py runserver
Watching for file changes with StatReloader
Performing system checks…

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
March 01, 2022 - 01:19:16
Django version 4.0.2, using settings 'mytestsite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

ملاحظة: يعرض الأمرُ السابق الأمرَ الخاص بنظام لينكس أو ماك. يمكنك تجاهل التحذيرات بشأن عمليات التهجير غير المُطبَّقة "‎18 unapplied migration(s)‎" حاليًا.

يمكنك بمجرد تشغيل الخادم عرض الموقع بالانتقال إلى عنوان URL التالي على متصفح الويب المحلي الخاص بك: http://127.0.0.1:8000/‎، ويجب أن تشاهد موقعًا يشبه ما يلي:

الخلاصة

لديك الآن بيئة تطوير جانغو التي تعمل على حاسوبك. رأيتَ في قسم الاختبار بإيجاز كيف يمكننا إنشاء موقع جانغو جديد باستخدام الأمر django-admin startproject وتشغيله في متصفحك باستخدام خادم تطوير الويب (python3 manage.py runserver). سنتوسّع في هذه العملية ونبني تطبيق ويب بسيط وكامل في المقال التالي.

اطّلع أيضًا على المقالات التالية:

• تثبيت إطار العمل جانغو على أوبنتو.
• دليل التثبيت السريع (توثيق جانغو).
• كيفية تثبيت جانغو - الدليل الكامل (توثيق جانغو): يغطي كيفية إزالة جانغو أيضًا.
• كيفية تثبيت جانغو على نظام ويندوز (توثيق جانغو).

ترجمة -وبتصرُّف- للمقال Setting up a Django development environment.

اقرأ أيضًا

• المقال التالي: تطبيق عملي لتعلم جانغو - الجزء الأول: إنشاء موقع ويب هيكلي لمكتبة محلية
• المقال السابق: مدخل إلى إطار عمل الويب جانغو من طرف الخادم
• إعداد تطبيق جانغو جاهز للنشر مع قاعدة بيانات Postgres وخادم Nginx و Gunicorn
•  البدء مع إطار العمل جانغو لإنشاء تطبيق ويب
• حزم بايثون الثمانية التي تسهل تعاملك مع Django

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

تتألف هذه السلسلة الفرعية من السلسلة الأشمل تعلم تطوير الويب من المقالات التالية:

• مدخل إلى إطار عمل الويب جانغو Django
• إعداد بيئة تطوير تطبيقات جانغو
• تطبيق عملي لتعلم جانغو - الجزء الأول: إنشاء موقع ويب هيكلي لمكتبة محلية
• تطبيق عملي لتعلم جانغو - الجزء الثاني: استخدام النماذج Models
• تطبيق عملي لتعلم جانغو - الجزء الثالث: موقع مدير جانغو Django Admin
• تطبيق عملي لتعلم جانغو - الجزء الرابع: إنشاء صفحة المكتبة الرئيسية
• تطبيق عملي لتعلم جانغو - الجزء الخامس: العروض Views العامة والتفصيلية
• تطبيق عملي لتعلم جانغو - الجزء السادس: إدارة الجلسات Sessions
• تطبيق عملي لتعلم جانغو - الجزء السابع: استيثاق المستخدمين وأذوناتهم
• تطبيق عملي لتعلم جانغو - الجزء الثامن: العمل مع الاستمارات Forms
• تطبيق عملي لتعلم جانغو - الجزء التاسع: اختبار تطبيق جانغو
• تطبيق عملي لتعلم جانغو - الجزء 10: نشر تطبيق جانغو في بيئة الإنتاج
• تعرف على أمان تطبيقات جانغو

المتطلبات الأساسية

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

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

تتألف هذه السلسلة الفرعية من السلسلة الأشمل تعلم تطوير الويب من المقالات التالية:

• مدخل إلى إطار عمل الويب جانغو من طرف الخادم: سنجيب في مقالنا الأول على سؤال "ما هو إطار عمل جانغو؟" وسنقدّم نظرةً عامة على ما يجعله إطار عمل مميز، وسنحدّد الميزات الرئيسية بما في ذلك بعض الوظائف المتقدمة التي لن يكون لدينا الوقت لتغطيتها بالتفصيل. سنوضّح أيضًا بعض أساسيات تطبيق جانغو لإعطائك فكرة عمّا يمكنه تطبيقه قبل إعداده والبدء به.
• إعداد بيئة تطوير جانغو: سنوضّح بعد معرفة الغرض من إطار عمل جانغو كيفية إعداد واختبار بيئة تطويره على أنظمة تشغيل ويندوز ولينكس (أوبونتو Ubuntu) وماك أو إس MacOS. يجب أن يعطيك هذا المقال ما تحتاج إليه لتكون قادرًا على البدء في تطوير تطبيقات جانغو بغض النظر عن نظام التشغيل الشائع الذي تستخدمه.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء الأول: إنشاء موقع ويب هيكلي لمكتبة محلية: يشرح هذا المقال ما ستتعلمه، ويوفر نظرةً عامة على موقع "المكتبة المحلية Local Library"، وهو مثال لموقع الويب الذي سنعمل من خلاله ونطوّره في مقالات لاحقة. يوضح هذا المقال كيفية إنشاء مشروع موقع الويب الهيكلي، والذي يمكنك بعد ذلك ملؤه بالإعدادات الخاصة بالموقع وعناوين URL والنماذج والعروض والقوالب.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء الثاني: استخدام النماذج Models: يوضح هذا المقال كيفية تحديد النماذج Models لموقع ويب المكتبة المحلية؛ إذ تمثل النماذج بنى البيانات التي نريد تخزين بيانات التطبيق فيها، وتسمح لجانغو بتخزين البيانات في قاعدة بياناتنا وتعديلها لاحقًا. يشرح هذا المقال أيضًا مفهوم النموذج وكيفية التصريح عنه وبعض أنواع الحقول الرئيسية، ويعرض بإيجاز بعض الطرق الرئيسية التي يمكنك من خلالها الوصول إلى بيانات النموذج.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء الثالث: موقع مدير جانغو: أنشأنا نماذج موقع ويب المكتبة المحلية، وسنستخدم الآن موقع مدير جانغو Django Admin لإضافة بعض بيانات الكتب الحقيقية، إذ سنوضح أولًا كيفية تسجيل النماذج في موقع المدير، ثم سنوضح كيفية تسجيل الدخول وإنشاء بعض البيانات، وسنعرض بعض الطرق التي يمكنك من خلالها تحسين عرض موقع المدير.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء الرابع: إنشاء الصفحة الرئيسية: نحن الآن جاهزون لإضافة الشيفرة البرمجية لعرض صفحتنا الأولى الكاملة، وهي الصفحة الرئيسية للمكتبة المحلية التي تعرض عددًا من السجلات لكل نوعٍ من النماذج وتوفر روابط تنقّل جانبية إلى صفحاتنا الأخرى، وسنكتسب خبرةً عملية في كتابة روابط عناوين URL والعروض الأساسية والحصول على السجلات من قاعدة البيانات واستخدام القوالب.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء الخامس: عروض القائمة المعممة والعروض التفصيلية: سنوسّع في هذا المقال موقع المكتبة المحلية من خلال إضافة قائمة وصفحات تفصيلية للكتب والمؤلفين، إذ سنتعرف على العروض المعمَّمة Generic Views المستندة إلى الأصناف، وسنوضّح كيف يمكنها تقليل مقدار الشيفرة البرمجية التي يجب عليك كتابتها لحالات الاستخدام الشائعة، وسننتقل إلى معالجة عناوين URL بمزيد من التفصيل مع توضيح كيفية إجراء مطابقة الأنماط الأساسية.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء السادس: إطار عمل الجلسة: سنوسّع في هذا المقال موقع المكتبة المحلية من خلال إضافة عدّاد زيارات مستند إلى جلسات الصفحة الرئيسية، إذ يُعَد ذلك مثالًا بسيطًا نسبيًا، ولكنه يوضّح كيفية استخدام إطار عمل الجلسة لتوفير سلوك مستمر للمستخدمين المجهولين على مواقعك الخاصة.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء السابع: استيثاق المستخدمين وأذوناتهم: سنشرح في هذا المقال كيفية السماح للمستخدمين بتسجيل الدخول إلى موقعك بحساباتهم الخاصة وكيفية التحكم بما يمكنهم فعله ومشاهدته بناءً على ما إذا قد سجّلوا الدخول أم لا وبناءً على أذوناتهم، إذ سنوسّع موقع ويب المكتبة المحلية من خلال إضافة صفحات تسجيل الدخول والخروج وصفحات خاصة بالمستخدمين والموظفين لعرض الكتب المستعارة.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء الثامن: التعامل مع الاستمارات: سنشرح في هذا المقال كيفية التعامل مع استمارات HTML في إطار عمل جانغو وخاصة استخدام أسهل طريقة لكتابة الاستمارات Forms لإنشاء نسخ من النماذج Model وتحديثها وحذفها، إذ سنوسّع موقع الويب للمكتبة المحلية بحيث يمكن لأمناء المكتبة تجديد الكتب وإنشاء المؤلفين وتحديثهم وحذفهم باستخدام الاستمارات بدلًا من استخدام تطبيق المدير.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء التاسع: اختبار تطبيق جانغو: يصبح الاختبار اليدوي لمواقع الويب أصعب مع زيادة حجمها، بسبب وجود المزيد لاختباره، إضافةً إلى زيادة تعقيد التفاعلات بين المكونات، إذ يمكن أن يتطلب تغيير بسيط في منطقة واحدة العديدَ من الاختبارات الإضافية للتحقق من تأثيره على مناطق أخرى. تتمثل إحدى طرق التخفيف من هذه المشاكل في كتابة الاختبارات الآلية التي يمكن تشغيلها بسهولة وموثوقية في كل مرة تُجري فيها تغييرًا. يوضّح هذا المقال كيفية جعل اختبار الوحدة Unit Testing لموقع الويب آليًا باستخدام إطار اختبار جانغو.
• تطبيق عملي لتعلم إطار عمل جانغو - الجزء العاشر: نشر تطبيق جانغو في بيئة الإنتاج: أنشأتَ واختبرتَ موقعًا رائعًا للمكتبة المحلية، ويجب الآن تثبيته على خادم ويب عام حتى يصل إليه موظفو المكتبة وأعضاؤها عبر الإنترنت. يقدّم هذا المقال نظرةً عامةً حول كيفية البحث عن مضيف لنشر موقع الويب وما يجب فعله لتجهيز موقعك للإنتاج.
• أمان تطبيق جانغو: تُعَد حماية بيانات المستخدم جزءًا أساسيًا من تصميم أيّ موقع ويب، إذ شرحنا سابقًا بعض الهجمات الأمنية الأكثر شيوعًا في مقال أمان مواقع الويب، وسيقدّم هذا المقال شرحًا عمليًا لكيفية تعامل أدوات الحماية المُضمَّنة في إطار عمل جانغو مع هذه الهجمات.

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

لنبدأ بمقالنا الأول من هذه السلسلة من خلال التعرف على إطار عمل جانغو.

مقدمة إلى إطار العمل جانغو

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

• المتطلبات الأساسية: المهارات الحاسوبية الأساسية، وفهم عام لبرمجة مواقع الويب من طرف الخادم وخاصةً تفاعلات الخادم مع العميل في مواقع الويب.

• الهدف: التعرف على إطار عمل جانغو والوظائف التي يوفرها وأساسيات بناء تطبيق جانغو.

ما هو جانغو؟

يُعَد جانغو إطار عمل ويب عالي المستوى يستخدم لغة بايثون ويتيح التطوير السريع لمواقع الويب الآمنة والقابلة للصيانة. صمّم مطورون ذوو خبرة إطار عمل جانغو الذي يخلصك من الكثير من متاعب تطوير الويب، بحيث يمكنك التركيز على كتابة تطبيقك دون الحاجة إلى إعادة اختراع العجلة، وهو إطار عمل مجاني ومفتوح المصدر وله مجتمع مزدهر ونشط وتوثيق رائع والعديد من خيارات الدعم المجاني والمدفوع.

يساعدك جانغو في كتابة برمجيات تتمتع بالمواصفات التالية:

• مكتملة: يتبع جانغو فلسفة أنه يتضمن كل شيء "Batteries Included" ويوفر تقريبًا كل ما يرغب المطوّرون في تطبيقه. بما أن كل ما تحتاجه هو جزء من منتج واحد، فإن كل شيء يعمل مع بعضه بعضًا بسلاسة ويتبع مبادئ تصميم متناسقة ويحتوي على توثيق شامل ومُحدَّث.

• متعددة الاستعمالات: يمكن استخدام جانغو -وقد اُستخدِم فعليًا- لبناء أيّ نوع من مواقع الويب تقريبًا بدءًا من أنظمة إدارة المحتوى ومواقع الويكي مرورًا بشبكات التواصل الاجتماعي والمواقع الإخبارية. يمكن لجانغو العمل مع أيّ إطار عمل من طرف العميل، ويمكنه تقديم المحتوى بأي تنسيق تقريبًا، مثل HTML، و RSS Feeds، و JSON، و XML. يوفّر جانغو داخليًا خيارات لأي وظيفة تقريبًا ترغب فيها مثل دعم العديد من أنواع قواعد البيانات الشائعة ومحركات القوالب وغيرها، ولكن يمكن توسيعه لاستخدام مكونات أخرى إذا لزم الأمر.

• آمنة: يساعد جانغو المطورين على تجنب العديد من الأخطاء الأمنية الشائعة من خلال توفير إطار عمل مُصمَّم لتطبيق الأشياء الصحيحة بهدف حماية الموقع آليًا، فمثلًا يوفر جانغو طريقةً آمنةً لإدارة حسابات المستخدمين وكلمات المرور وتجنب الأخطاء الشائعة مثل وضع معلومات الجلسة في ملفات تعريف الارتباط Cookies، حيث تكون معرضةً للخطر، وذلك من خلال جعل ملفات تعريف الارتباط cookies تحتوي على مفتاح فقط وتخزين البيانات الفعلية في قاعدة البيانات، أو تخزين كلمات المرور مباشرةً بدلًا من تعمية Hash كلمة المرور التي هي قيمة ذات طول ثابت تُنشَأ من خلال إرسال كلمة المرور عبر دالة تعمية مُشفَّرة Cryptographic Hash Function. يمكن لجانغو التحقق مما إذا كانت كلمة المرور المدخَلة صحيحة من خلال تشغيلها عبر دالة التعمية وموازنة الخرج مع قيمة التعمية المخزنة، ولكن حتى إذا اُخترِقت قيمة التعمية المخزنة، فمن الصعب على المهاجم معرفة كلمة المرور الأصلية نظرًا لطبيعة الدالة أحادية الاتجاه. يتيح جانغو الحماية ضد العديد من الثغرات افتراضيًا بما في ذلك حقن استعلامات SQL وهجمات السكربتات العابرة للمواقع وتزوير الطلبات عبر المواقع والاختطاف بالنقر clickjacking (اطلع على مقال أمان مواقع الويب لمزيد من التفاصيل حول هذه الهجمات).

• قابلة للتوسّع: يستخدم جانغو معمارية "لا شيء مشترك shared-nothing" القائمة على المكونات، إذ يكون كل جزء من المعمارية مستقلًا عن الأجزاء الأخرى، وبالتالي يمكن استبداله أو تغييره حسب الحاجة. يعني وجود فصل واضح بين الأجزاء المختلفة أنه يمكن توسيع حركة الزوار المتزايدة من خلال إضافة عتاد على أي مستوى من خوادم التخزين المؤقت، أو خوادم قواعد البيانات، أو خوادم التطبيقات. وقد نجحت بعض المواقع الأكثر ازدحامًا في توسيع جانغو لتلبية مطالبهم مثل إنستغرام وديسكاس Disqus.

• قابلة للصيانة: كُتِبت شيفرة جانغو البرمجية باستخدام مبادئ وأنماط التصميم التي تشجع على إنشاء شيفرة برمجية قابلة للصيانة وإعادة الاستخدام؛ إذ يستخدم جانغو مبدأ لا تكرر نفسك Don't Repeat Yourself -أو DRY اختصارًا، لذلك لا يوجد تكرار غير ضروري، مما يقلل من كمية الشيفرة البرمجية. كما يدعم جانغو تجميع الوظائف المرتبطة ببعضها ضمن تطبيقات قابلة لإعادة الاستخدام، وتجميع الشيفرة البرمجية المرتبطة ببعضها ضمن وحدات على مستوى أدنى مثل نمط نموذج-عرض-مُتحكِّم Model View Controller -أو MVC اختصارًا.

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

تاريخ إطار عمل جانغو

طوّر فريقُ ويب كان مسؤولًا عن إنشاء مواقع الصحف وصيانتها إطارَ عمل جانغو في البداية بين عامي 2003 و2005، ثم بدأ الفريق -بعد إنشاء عدد من المواقع- في تحليل وإعادة استخدام الكثير من أنماط التصميم والشيفرة البرمجية المشتركة. تطورت هذه الشيفرة البرمجية المشتركة إلى إطار عمل عام لتطوير الويب، والذي أصبح مشروع جانغو مفتوح المصدر في الشهر 7 من عام 2005.

استمر إطار عمل جانغو في النمو والتحسن من الإصدار الأول 1.0 في الشهر التاسع من عام 2008 وحتى الإصدار 4.0 الصادر مؤخرًا في عام 2022. أضاف كل إصدار وظائفًا جديدة وإصلاحات للأخطاء بدءًا من دعم الأنواع الجديدة من قواعد البيانات ومحركات القوالب والتخزين المؤقت وإضافة دوال وأصناف العرض المعمَّمة التي تقلل من مقدار الشيفرة البرمجية التي يجب أن يكتبها المطورون لعددٍ من المهام البرمجية.

ملاحظة: تحقَّق من ملاحظات الإصدارات على موقع جانغو لترى ما الذي تغير في الإصدارات الأخيرة ومقدار العمل المبذول في تحسين جانغو.

يُعَد جانغو الآن مشروعًا تعاونيًا مزدهرًا ومفتوح المصدر، ولديه عدة آلاف من المستخدمين والمساهمين، وقد تطوّر إلى إطار عمل متعدد الاستخدامات قادر على تطوير أيّ نوع من مواقع الويب، بالرغم من أنه لا يزال يحتوي على بعض الميزات التي تعكس أصله.

ما مدى شعبية جانغو؟

لا يوجد أي مقياس نهائي ومتوفر حاليًا لشعبية أطر العمل من طرف الخادم، بالرغم من أنه يمكنك تقدير الشعبية باستخدام آليات، مثل حساب عدد مشاريع غيت هَب GitHub وأسئلة موقع StackOverflow لكل منصة، لذا يُفضَّل أن تسأل ما إذا كان جانغو يتمتع بشعبية كافية لتجنب مشاكل المنصات التي لا تحظى بشعبية، وما إذا كان مستمرًا في التطور ويمكنك الحصول على المساعدة إذا احتجت إليها، وإذا كان هناك فرصة لك للحصول على عمل مدفوع الأجر إذا تعلمت جانغو. يمكن القول أن جانغو إطار عمل شائع الاستخدام استنادًا إلى عدد المواقع البارزة التي تستخدمه وعدد الأشخاص المساهمين في قاعدة الشيفرة البرمجية وعدد الأشخاص الذين يقدمون الدعم المجاني والمدفوع.

تشمل المواقع البارزة التي تستخدم جانغو: ديسكاس Disqus وإنستغرام و Knight Foundation و MacArthur Foundation وموزيلا Mozilla وناشيونال جيوغرافيك National Geographic و Open Knowledge Foundation وينترست Pinterest و Open Stack (المصدر: موقع جانغو الرسمي).

هل جانغو إطار عمل متشبث برأيه؟

تشير أطر عمل الويب إلى نفسها في أغلب الأحيان على أنها "قائمة على رأيها أو متشبثة برأيها Opinionated" أو أنها "غير قائمة على رأيها Unopinionated"، فأطر العمل القائمة على رأيها هي أطر العمل التي لديها آراء حول الطريقة الصحيحة للتعامل مع أيّ مهمة معينة، وتدعم التطور السريع أو حل المشاكل في مجال معين، إذ تكون الطريقة الصحيحة لفعل أي شيء عادةً مفهومة ومُوثَّقة جيدًا، لكن يمكن أن تكون أقل مرونة في حل المشاكل خارج مجالها الرئيسي، وتميل إلى تقديم خيارات أقل للمكونات والأساليب التي يمكن استخدامها.

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

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

كيف تبدو شيفرة جانغو البرمجية؟

ينتظر تطبيق الويب طلبات HTTP من متصفح الويب (أو عميل آخر) في موقع ويب تقليدي مُوجَّه بالبيانات، إذ يعمل التطبيق عند تلقي طلب على تحديد ما هو مطلوب بناءً على عنوان URL وربما على المعلومات الموجودة في بيانات طلب POST أو بيانات طلب GET، ثم يمكنه بعد ذلك اعتمادًا على ما هو مطلوب قراءة المعلومات، أو كتابتها من قاعدة بيانات، أو أداء مهام أخرى مطلوبة لتلبية الطلب، ثم سيعيد التطبيق استجابةً إلى متصفح الويب، وينشئ غالبًا صفحة HTML ديناميكيًا ليعرضها المتصفح من خلال إدخال البيانات المُسترجَعة ضمن عناصر بديلة في قالب HTML.

تجمّع تطبيقاتُ ويب جانغو الشيفرةَ البرمجية التي تعالج كل خطوة من الخطوات السابقة ضمن ملفات منفصلة كما يلي:

• عناوين URL: يمكن معالجة الطلبات من كل عنوان URL باستخدام دالة واحدة، ولكن تُعَد كتابة دالة عرض منفصلة للتعامل مع كل مورد أمرًا قابلًا للصيانة بصورة أفضل، إذ يُستخدَم رابط Mapper عنوان URL لإعادة توجيه طلبات HTTP إلى العرض المناسب بناءً على عنوان URL الخاص بالطلب، ويمكن لرابط عنوان URL مطابقة أنماط معينة من السلاسل النصية أو الأرقام التي تظهر في عنوان URL وتمريرها إلى دالة عرض بوصفها بيانات.

• العرض View: العرض هو دالة معالج الطلب والتي تتلقى طلبات HTTP وتعيد استجابات HTTP. تصل العروض إلى البيانات اللازمة لتلبية الطلبات باستخدام النماذج وتكلّف القوالب Templates بتنسيق الاستجابة.

• النموذج Model: النماذج هي كائنات بايثون تعرّف بنية بيانات التطبيق وتوفّر آليات لإدارة (إضافة وتعديل وحذف) السجلات والاستعلام عنها في قاعدة البيانات.

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

ملاحظة: يشير جانغو إلى هذا التنظيم بأنه معمارية نموذج-عرض-قالب Model View Template -أو MVT اختصارًا، إذ تمتلك هذه المعمارية العديد من أوجه التشابه مع معمارية نموذج-عرض-مُتحكِّم MVC الأكثر شيوعًا.

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

إرسال الطلب إلى العرض الصحيح: الملف urls.py

يُخزَّن رابط عنوان URL في ملف يسمى urls.py، إذ يعرّف الرابط urlpatterns في المثال الآتي قائمةً من الروابط بين الوجهات Routes (وهي أنماط Patterns عنوان URL مُحدَّدة) ودوال العرض المقابلة لها. إذا اُستلِم طلب HTTP يحتوي على عنوان URL يطابق نمطًا محددًا، فستُستدعَى دالة العرض المرتبطة به ويُمرَّر الطلب.

urlpatterns = [
    path('admin/', admin.site.urls),
    path('book/<int:id>/', views.book_detail, name='book_detail'),
    path('catalog/', include('catalog.urls')),
    re_path(r'^([0-9]+)/$', views.best),
]

كائن urlpatterns هو قائمة من دوال path()‎ و/ أو re_path()‎. تُعرَّف قوائم بايثون باستخدام أقواس مربعة، إذ تُفصَل العناصر بفواصل ويمكن أن تحتوي على فاصلة لاحقة اختيارية مثل [item1, item2, item3,‎].

الوسيط الأول لكلا التابعين هو الوجهة أو النمط الذي ستجري مطابقته. يستخدم التابع path()‎ أقواس زاوية لتحديد أجزاء من عنوان URL التي ستُلتقَط وتُمرَّر إلى دالة العرض بوصفها وسائطًا مُسمَّاة، بينما تستخدم الدالة re_path()‎ أسلوبًا مرنًا لمطابقة الأنماط يُعرَف بالتعبير النمطي Regular Expression الذي سنتحدث عنه لاحقًا.

الوسيط الثاني هو دالة أخرى تُستدعَى عند مطابقة النمط، إذ تشير الصيغة views.book_detail إلى أن الدالة تسمى book_detail()‎ ويمكن العثور عليها في الوحدة views، أي ضمن الملف views.py.

معالجة الطلب: الملف views.py

تُعَد العروض قلب تطبيق الويب، فهي تتلقى طلبات HTTP من عملاء الويب وتعيد استجابات HTTP، وتنظّم الموارد الأخرى لإطار العمل للوصول إلى قواعد البيانات وعرض القوالب وغير ذلك. وتُخزَّن العروض عادةً في ملف يسمى views.py.

يوضّح المثال الآتي أصغر دالة عرض index()‎ التي كان من الممكن أن يستدعيها رابط عنوان URL في القسم السابق؛ إذ تتلقى هذه الدالة مثل جميع دوال العرض كائن HttpRequest بوصفه معاملًا request وتعيد كائن HttpResponse، إذ لا نفعل أيّ شيء مع الطلب في هذه الحالة، وتعيد استجابتنا سلسلةً نصيةً ثابتة Hard-coded، وسنعرض لاحقًا طلبًا يفعل شيئًا آخر أكثر إثارة للاهتمام.

# اسم الملف‫: views.py (دوال عرض جانغو)

from django.http import HttpResponse

def index(request):
    # الحصول على‫ HttpRequest - معامل الطلب
    # إجراء العمليات باستخدام المعلومات الواردة في الطلب‫.
    # إعادة‫ HttpResponse
    return HttpResponse('Hello from Django!')

ملاحظة: إليك بعض المعلومات عن لغة بايثون:

• وحدات بايثون هي مكتبات من الدوال مُخزَّنة في ملفات منفصلة، والتي يمكن أن نرغب في استخدامها في شيفرتنا البرمجية. نستورد في مثالنا كائن HttpResponse من الوحدة django.http حتى نتمكّن من استخدامه في عرضنا from django.http import HttpResponse، وهناك طرق أخرى لاستيراد بعض الكائنات أو جميعها من وحدةٍ ما.

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

تعريف نماذج البيانات: الملف models.py

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

يُظهِر مقتطف الشيفرة البرمجية الآتي نموذج جانغو بسيط جدًا للكائن Team، فالصنف Team مُشتَق من صنف جانغو models.Model، ويعرّف اسم الفريق ومستوى الفريق بوصفها حقولًا محرفية ويحدد الحد الأقصى لعدد المحارف التي ستُخزَّن لكل سجل. يمكن أن يكون مستوى الفريق team_level قيمةً من عدة قيم، لذلك نحدّده بوصفه حقلًا اختياريًا ونوفّر ربطًا بين الخيارات المراد عرضها والبيانات المراد تخزينها إلى جانب القيمة الافتراضية.

# اسم الملف: models.py

from django.db import models

class Team(models.Model):
    team_name = models.CharField(max_length=40)

    TEAM_LEVELS = (
        ('U09', 'Under 09s'),
        ('U10', 'Under 10s'),
        ('U11', 'Under 11s'),
        # …
        # قائمة مستويات الفريق الأخرى
    )
    team_level = models.CharField(max_length=3, choices=TEAM_LEVELS, default='U11')

ملاحظة:

إليك بعض المعلومات عن لغة بايثون: تدعم لغة بايثون البرمجة كائنية التوجه التي تُعَد نمطًا من البرمجة، إذ ننظم شيفرتنا البرمجية ضمن كائنات، والتي تتضمن بيانات ودوال متعلقة بها للعمل على تلك البيانات. يمكن للكائنات أن ترث، أو توسّع، أو تُشتَق من كائنات أخرى، مما يسمح بمشاركة السلوك المشترك بين الكائنات المتعلقة ببعضها. نستخدم في لغة بايثون الكلمة المفتاحية class لتعريف المخطط الأولي للكائن. يمكننا إنشاء نسخ متعددة محددة لنوع الكائن بناءً على النموذج في الصنف؛ فلدينا في مثالنا الصنف Team مُشتَق من الصنف Model، وهذا يعني أنه نموذج وسيحتوي على جميع توابعه، ولكن يمكننا منحه ميزات خاصة به أيضًا. نحدد في نموذجنا الحقول التي ستحتاجها قاعدة البيانات لتخزين بياناتنا من خلال منحها أسماءً محددة. يستخدم جانغو هذه التعريفات -بما في ذلك أسماء الحقول- لإنشاء قاعدة البيانات الأساسية.

الاستعلام عن البيانات: الملف views.py

يوفر نموذج جانغو واجهة برمجة تطبيقات استعلام بسيطة للبحث في قاعدة البيانات المرتبطة به، ويمكن أن تتطابق هذه الواجهة مع عدد من الحقول في وقت واحد باستخدام معايير مختلفة، مثل التطابق التام exact وغير الحساس لحالة الأحرف case-insensitive وأكبر من وغير ذلك، ويمكن أن يدعم العبارات المعقدة، فمثلًا يمكنك تحديد بحث عن فرق U11 التي يبدأ اسم فريقها بالحرفين "Fr" أو ينتهي بالحرفين "al".

يُظهِر مقتطف الشيفرة البرمجية التالية دالة العرض (معالج المورد) لعرض جميع فرق U09، إذ يوضح السطر التالي:

list_teams = Team.objects.filter(team_level__exact="U09")‎

كيف يمكننا استخدام واجهة API للاستعلام عن النموذج لترشيح جميع السجلات، إذ يحتوي الحقل team_level على النص "U09" حرفيًا (لاحظ كيف تُمرَّر هذه المعايير إلى الدالة filter()‎ بوصفها وسيطًا مع فصل اسم الحقل ونوع المطابقة بشرطة سفلية مزدوجة: team_level__exact).

## اسم الملف: views.py

from django.shortcuts import render
from .models import Team

def index(request):
    list_teams = Team.objects.filter(team_level__exact="U09")
    context = {'youngest_teams': list_teams}
    return render(request, '/best/index.html', context)

تستخدم الدالةُ السابقة الدالةَ render()‎ لإنشاء الكائن HttpResponse الذي يُرسَل إلى المتصفح، إذ تُعَد هذه الدالة اختصارًا Shortcut ينشئ ملف HTML من خلال الجمع بين قالب HTML محدَّد وبعض البيانات لإدخالها في القالب (تتوفر هذه البيانات في المتغير المُسمَّى "context"). سنوضّح في القسم التالي كيفية إدخال البيانات في القالب لإنشاء ملف HTML.

عرض البيانات: قوالب HTML

تسمح لك أنظمة القوالب بتحديد بنية مستند الخرج باستخدام عناصر بديلة للبيانات التي ستُملَأ عند إنشاء الصفحة، إذ تُستخدَم القوالب غالبًا لإنشاء مستندات HTML، ولكن يمكنها إنشاء أنواع أخرى من المستندات أيضًا. يدعم جانغو كلًا من نظام القوالب الأصيل Native ومكتبة بايثون الشهيرة الأخرى التي تسمى Jinja2، ويمكن جعله يدعم أنظمة أخرى إن لزم الأمر.

يوضح مقتطف الشيفرة البرمجية التالية الشكل الذي يمكن أن يبدو عليه قالب HTML الذي تستدعيه الدالة render()‎ في القسم السابق. كُتِب هذا القالب على أساس الافتراض بأنه يمكنه الوصول إلى متغير قائمة يُسمَّى youngest_teams عند عرضه (يوجد هذا المتغير ضمن المتغير context في الدالة render()‎). يوجد ضمن بنية HTML تعبيرٌ يتحقق أولًا من وجود المتغير youngest_teams، ثم يكرره في حلقة for، إذ يعرض القالب في كل تكرار قيمة team_name لكل فريق في عنصر <li>.

## اسم الملف: best/templates/best/index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Home page</title>
</head>
<body>
  {% if youngest_teams %}
    <ul>
      {% for team in youngest_teams %}
        <li>{{ team.team_name }}</li>
      {% endfor %}
    </ul>
  {% else %}
    <p>No teams are available.</p>
  {% endif %}
</body>
</html>

ميزات جانغو الأخرى

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

• الاستمارات Forms: تُستخدَم استمارات HTML لتجميع بيانات المستخدم لمعالجتها على الخادم. يبسّط جانغو إنشاء الاستمارات والتحقق من صحتها ومعالجتها.

• استيثاق Authentication المستخدم وأذوناته: يتضمن جانغو نظامًا قويًا لاستيثاق المستخدم وأذوناته، إذ أُنشئ هذا النظام مع وضع الأمان في الحسبان.

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

• موقع المدير Administration site: يُضمَّن موقع مدير جانغو افتراضيًا عند إنشاء تطبيق باستخدام الهيكل الأساسي، مما يسهّل توفير صفحة مدير لمديري الموقع لإنشاء أي نماذج بيانات في موقعك وتعديلها وعرضها.

• سَلسَلة البيانات Serializing data: يسهّل جانغو من سَلسَلة بياناتك وتقديمها بتنسيق XML أو JSON، ويمكن أن يكون ذلك مفيدًا عند إنشاء خدمة ويب (موقع ويب يقدّم البيانات فقط لتستهلكها تطبيقات أو مواقع أخرى ولا يعرض أيّ شيء بنفسه)، أو عند إنشاء موقع ويب تعالج فيه الشيفرة البرمجية من طرف العميل كل عملية عرض أو تصيير البيانات.

الخلاصة

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

ترجمة -وبتصرُّف- للمقالين Django Web Framework (Python) و Django introduction.

اقرأ أيضًا

• المقال التالي: إعداد بيئة تطوير تطبيقات جانغو
• المقال السابق: تعرف على أمان مواقع الويب
• أطر عمل الويب من طرف الخادم
• المرجع الشامل إلى تعلم لغة بايثون
• برمجة عملاء ويب باستخدام بايثون

يستخدم الناس أنواعًا مختلفة من الأجهزة للاتصال بالإنترنت وتصفح الويب، ولهذا تحتاج إلى تمكين المستخدمين من الوصول إلى التطبيقات مهما كان موقعهم؛ ففي حالة المواقع التقليدية، يكفي غالبًا امتلاك واجهة مستخدم متجاوبة؛ بينما تحتاج في حالة التطبيقات الأعقد إلى استخدام تقنيات ومعماريات أخرى، منها امتلاك تطبيقات ريست REST مستقلة للواجهة الأمامية والواجهة الخلفية والتي يمكن تنفيذها مثل تطبيقات ويب من جهة العميل أو تطبيقات ويب تقدّميّة Progressive Web Apps -اختصارًا PWA- أو تطبيقات جوال أصلية.

نذكر فيما يلي بعض الأدوات الممكن استخدامها لبناء تطبيقات أعقد:

• ريآكت، وهو إطار عمل مبني بلغة جافا سكريبت يتيح للمطورين بناء تطبيقات ويب بواجهات أمامية وأصلية للواجهات الخلفية لواجهة برمجة التطبيقات API ريست.
• جانغو، وهو إطار عمل ويب مبني بلغة بايثون مفتوح المصدر ومجاني يتبع نموذج معمارية البرمجيات نموذج عرض متحكم Model View Controller -أو اختصارًا MVC-.
• إطار عمل جانغو ريست، الذي يمثّل أدوات قوية ومرنة لبناء واجهة برمجة تطبيقات ريست APIs بجانغو.

ستبني في هذه المقالة تطبيق ويب حديث مع واجهة REST API خلفية منفصلة وواجهة أمامية مستخدمًا لهذا الغرض ريآكت وجانغو وإطار عمل جانغو ريست، إذ يمكنك باستخدام ريآكت وجانغو معًا الاستفادة من أحدث الترقيات في جافا سكريبت وتطوير الواجهات الأمامية، وبدلًا من بناء تطبيق جانغو يستخدم محرك قوالب داخلي، ستستخدم ريآكت مثل مكتبة واجهة مستخدم UI library مستفيدًا من نموذج كائن الوثيقة Document Object Model الافتراضي -أو اختصارًا DOM-، والطريقة التصريحية declarative والمكونات التي تصيّر render سريعًا التغيرات على البيانات.

يخزن تطبيق الويب الذي ستبنيه سجلات العملاء في قاعدة بيانات، ويمكنك استخدامها بمثابة نقطة بداية لتطبيق إدارة علاقات العملاء CRM، وعند انتهائك ستكون قادرًا على إنشاء وقراءة وتحديث وحذف السجلات باستخدام واجهة ريآكت المُنسقة مستخدمًا بوتستراب 4.

المتطلبات الأساسية

ستحتاج لإتمام هذه المقالة وتطبيق ما فيها إلى ما يلي:

• جهاز تطوير مع نظام تشغيل أوبنتو Ubuntu 18.04.
• تثبيت بايثون 3 و pip و venv على جهازك باتباع الخطوتين الأولى والثانية من مقالة كيف تثبت بايثون 3 وتعد بيئة برمجية محلية على نظام أبونتو 18.04.
• تثبيت الإصدار 6 أو ما بعده من نود جي إس Node.js و npm 5.2 أو أعلى منه على جهازك، ويمكنك تثبيت كليهما باتباع التعليمات الواردة في مقالة كيف تثبت نود جي إس على نظام أوبنتو 18.04 حول التثبيت من مستودعات البرمجيات التي يطلق عليها اسم أرشيف الحزم الشخصية personal package archive -أو اختصارًا PPA.

الخطوة الأولى - إنشاء بيئة بايثون افتراضية وتثبيت الاعتماديات

ستنشئ في هذه الخطوة بيئةً افتراضيةً وتثبت الاعتمادات اللازمة لتطبيقك بما فيها جانغو وإطار عمل جانغو ريست وحزمة django-cors-headers.

سيستخدم تطبيقنا خادمي تطوير مختلفين لجانغو وريآكت، وسيعملان على منفذين مختلفين وبمثابة نطاقين منفصلين، ولهذا نحتاج تفعيل سياسة تعدد الموارد cross-origin resource sharing -أو اختصارًا CORS- لإرسال طلبات من نوع HTTP من ريآكت إلى جانغو دون التعرض للحظر على يدي المتصفح.

انتقل إلى المجلد الأساسي وأنشئ بيئة افتراضية باستخدام وحدة venv في بايثون 3:

$ cd ~
$ python3 -m venv ./env

فعّل البيئة الافتراضية التي أنشأتها مستخدمًا الأمر source:

$ source env/bin/activate

ثم ثبّت اعتماديات المشروع مستخدمًا pip، وهذه الاعتمادات هي:

• جانغو: وهو إطار عمل ويب المشروع.
• إطار عمل جانغو ريست: تطبيق جانبي (منشأ من طرف ثالث) يبني واجهات برمجة التطبيقات لريست بواسطة جانغو.
• حزمة django-cors-headers: وهي حزمة تفعّل سياسة تعدد الموارد CORS.

ثبّت إطار عمل جانغو بالأمر التالي:

(env) ali@ubuntu:$ pip install django djangorestframework django-cors-headers

والآن أصبح بإمكانك بعد أن ثبتّت اعتمادات المشروع أن تنشئ مشروع جانغو وواجهة ريآكت الأمامية.

الخطوة الثانية - إنشاء مشروع جانغو

سنولّد في هذه الخطوة مشروع جانغو باستخدام التعليمات والأدوات التالية:

• أداة django-admin startproject project-name، إذ تُعد django-admin أداةً تعمل في بيئة سطر الأوامر وتُستخدم لإتمام المهام بواسطة جانغو. ينشئ الأمرstartproject مشروع جانغو جديد.
• أداة سكريبت python manage.py startapp myapp، إذ يُعد manage.py سكريبت برمجي يضاف تلقائيًا لكل مشروع جانغو وهو يؤدي عددًا من المهام الإدارية، مثل إنشاء تطبيقات جديدة وتهجير ملفات قاعدة البيانات وخدمة مشروع جانغو محلي. ينشئ الأمر startapp التابع لهذا السكريبت تطبيق جانغو داخل مشروع جانغو. يُقصد بالمصطلح "تطبيق application" في جانغو حزمة بايثون توفّر بعض المزايا في المشروع.

ولكي تبدأ، أنشئ مشروع جانغو باستخدام الأمر django-admin startproject، وسنطلق على التطبيق اسم "djangoreactproject":

(env) ali@ubuntu:$ django-admin startproject djangoreactproject

سننظر إلى بنية المجلد لمشروع جانغو الذي نعمل عليه باستخدام الأمر tree قبل المتابعة.

نصيحة: الأمر tree هو أمرٌ مفيد لعرض بُنى الملفات والمجلدات من مستوى سطر الأوامر، يمكنك تثبيته مستخدمًا الأمر التالي:

$ sudo apt-get install tree

ولكي تستخدمه انتقل إلى المجلد الذي تريد رؤية بنيته واكتب tree أو اكتب المسار كاملًا وصولًا إلى نقطة البداية "tree /home/ali/ali-project".

انتقل إلى المجلد djangoreactproject ضمن جذر مشروعك ونفذ الأمر tree:

(env) ali@ubuntu:$ cd ~/djangoreactproject
(env) ali@ubuntu:$ tree

سيظهر لك الخرج التالي:

├── djangoreactproject
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── manage.py

يمثّل المجلد "djangoreactproject/~" جذر المشروع، وتوجد داخله عدة ملفات مهمة لمشروعك، هي:

• "manage.py": وهو سكريبت خدمي يؤدي عددًا من المهام الإدارية.
• "settings.py": هو ملف التهيئة الرئيسي لمشروع جانغو، حيث يمكنك تعديل إعدادات المشروع، إذ تتضمن هذه الإعدادات متحولاتٍ، مثل INSTALLED_APPS الذي يحدد قائمة التطبيقات النشطة في مشروعك. ويوجد في توثيق جانغو معلومات أعمق عن الإعدادات المتاحة.
• "urls.py": يحتوي هذا الملف على قائمة بنماذج محددات الموارد الموحدة URL والعروض المرتبطة بها، إذ يُنظِّم كل نموذج اتصالًا بين عنوان محدد موارد موحد URL والدالة التي يجب أن تُستدعى لذلك العنوان URL.

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

(env) ali@ubuntu:$ nano ~/djangoreactproject/djangoreactproject/settings.py

انتقل إلى الإعداد INSTALLED_APPS وأضف التطبيقين "rest_framework" و "corsheaders" أسفل القائمة:

...
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'corsheaders'
]

ثم أضف البرمجية الوسيطة corsheaders.middleware.CorsMiddleware من حزمة سياسة تعدد الموارد CORS التي ثبتناها سابقًا إلى الإعداد MIDDLEWARE، الذي يمثّل قائمةً بالبرمجيات الوسيطة middlewares؛ وهو صنف بايثون يحتوي على شيفرة تُعالج في كل مرة يتعامل تطبيق الويب مع طلب أو استجابة:

...

MIDDLEWARE = [
...
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware',
'corsheaders.middleware.CorsMiddleware'
]

يمكنك بعد ذلك تفعيل CORS، إذ يحدّد الإعداد CORS_ORIGIN_ALLOW_ALL ما إذا كنت ستسمح بسياسة تعدد الموارد لكل النطاقات أم لا، والإعداد CORS_ORIGIN_WHITELIST هو صف بايثون يحتوي على عناوين URL المسموحة.

سيعمل خادم تطوير ريآكت على العنوان "http://localhost:3000"، لذلك سنضيف الإعدادين التاليين إلى ملف الإعدادات "settings.py":

CORS_ORIGIN_ALLOW_ALL = False
(,'CORS_ORIGIN_WHITELIST('localhost:3000

حيث يمكنك إضافة هذين الإعدادين في أي مكان تشاء من هذا الملف:

...
CORS_ORIGIN_ALLOW_ALL = False

CORS_ORIGIN_WHITELIST = (
       'localhost:3000',
)
…

ويمكنك العثور على المزيد من خيارات التهيئة في وثائق django-cors-headers.

احفظ الملف واخرج من محرر النصوص عندما تنتهي.

نحتاج إلى إنشاء تطبيق جانغو جديد داخل المجلد "djangoreactproject/~" اسمه "customers":

(env) ali@ubuntu:$ python manage.py startapp customers

سيحتوي هذا التطبيق على النماذج models والعروض views لإدارة العملاء؛ إذ تعرّف النماذجُ الحقولَ والسلوكات لبيانات التطبيق؛ بينما تمكّن العروض تطبيقنا من التعامل مع الطلبات على النحو المناسب وإعادة الاستجابات المطلوبة على النحو المناسب أيضًا.

بعد ذلك، أضف التطبيق إلى قائمة التطبيقات المثبتة في ملف المشروع "settings.py" لكي يتعرف جانغو عليه على أنه جزءٌ من المشروع. افتح الملف "settings.py" مرةً أخرى:

(env) ali@ubuntu:$ nano ~/djangoreactproject/djangoreactproject/settings.py

أضف التطبيق "customers":

...
INSTALLED_APPS = [
    ...
    'rest_framework',
    'corsheaders',
    'customers'
]
…

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

هجّر قاعدة البيانات كما يلي:

(env) ali@ubuntu:$ python manage.py migrate

وشغّل خادم التطوير المحلي:

(env) ali@ubuntu:$ python manage.py runserver

سترى خرجًا يشابه التالي:

Performing system checks...

System check identified no issues (0 silenced).
October 22, 2018 - 15:14:50
Django version 2.1.2, using settings 'djangoreactproject.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

سيعمل تطبيق الويب من خلال العنوان "http://127.0.0.1:8000"، وإذا انتقلت إلى هذا العنوان في متصفحك فيفترض أن ترى الصفحة التالية:

دع التطبيق يعمل وافتح نافذة طرفية جديدة لمتابعة تطوير المشروع.

الخطوة الثالثة - إنشاء الواجهة الأمامية لريآكت

سننشئ في هذا القسم تطبيق الواجهة الأمامية لمشروعنا مستخدمين ريآكت؛ إذ يوجد لدى ريآكت برنامج خدمي رسمي يسمح لك بتوليد مشاريع ريآكت بسرعة دون الحاجة إلى ضبط مجمع الوحدات Webpack، التي تمثّل مجمع وحدات module bundler يُستخدم لتجميع أصول الويب، مثل شيفرة جافا سكريبت و CSS والصور. قبل أن تتمكن من استخدام Webpack، ستحتاج عادةً إلى تحديد خيارات ضبط متعددة، لكن بفضل الأداة create-react-app لن تحتاج للتعامل مع Webpack مباشرةً حتى تقرر أو عندما تكون بحاجةٍ لمزيدٍ من التحكم. يمكنك استخدام أداة npx (وهي أداة تنفّذ الملفات الثنائية لحزم npm) لتشغيل create-react-app.

تأكد في نافذة الطرفية الثانية أنك موجود داخل مجلد المشروع:

$ cd ~/djangoreactproject

أنشئ مشروع ريآكت اسمه "frontend" باستخدام create-react-app و npx:

$ npx create-react-app frontend

ثم انتقل إلى داخل تطبيق ريآكت وشغّل خادم التطوير:

$ cd ~/djangoreactproject/frontend
$ npm start

سيعمل تطبيقك باستخدام العنوان "/http://localhost:3000":

دع خادم تطوير ريآكت يعمل وافتح نافذة طرفية جديدة للمتابعة.

ولرؤية بنية مجلدات كامل المشروع عند هذه النقطة، انتقل إلى المجلد الجذر ونفّذ الأمر tree مرةً أخرى:

$ cd ~/djangoreactproject
$ tree

سترى بنيةً تشبه التالية:

├── customers
│   ├── admin.py
│   ├── apps.py
│   ├── __init__.py
│   ├── migrations
│   │   └── __init__.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
├── djangoreactproject
│   ├── __init__.py
│   ├── __pycache__
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── frontend
│   ├── package.json
│   ├── public
│   │   ├── favicon.ico
│   │   ├── index.html
│   │   └── manifest.json
│   ├── README.md
│   ├── src
│   │   ├── App.css
│   │   ├── App.js
│   │   ├── App.test.js
│   │   ├── index.css
│   │   ├── index.js
│   │   ├── logo.svg
│   │   └── registerServiceWorker.js
│   └── yarn.lock
└── manage.py

سيستخدم تطبيقنا بوتستراب 4 لتحيدد تنسيق style واجهة ريآكت، لذلك سنضمّنه في الملف "frontend/src/App.css" الذي يدير إعدادات CSS. افتح الملف:

$ nano ~/djangoreactproject/frontend/src/App.css

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

@import  'https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css';

تعليمة import@ هي تعليمة CSS تُستخدم لاستيراد قواعد التنسيق style rules من صفحات تنسيق أخرى.

الآن بعد أن انتهينا من إنشاء تطبيق الواجهة الأمامية والواجهة الخلفية، دعنا ننشئ نموذج العميل Customer وبعض البيانات التجريبية.

الخطوة الرابعة - إنشاء نموذج العميل وبيانات التهيئة

بعد أن انتهينا من إنشاء تطبيق جانغو والواجهة الأمامية لريآكت، ستكون خطوتنا التالية هي إنشاء نموذج العميل Customer، الذي يمثّل جدول قاعدة البيانات الذي سيخزن معلومات العملاء. لن تحتاج إلى أي أوامر SQL، إذ سيتولى الرابط العلائقي للكائنات في جانغو Object Relational Mapper -أو اختصارًا ORM- أمر العمليات التي تجري على قاعدة البيانات من خلال إسقاط أصناف بايثون ومتحولاته على جداول SQL وأعمدته، وبهذه الطريقة يكون الرابط العلائقي للكائنات في جانغو قد جرّد تفاعلات SQL مع قاعدة البيانات من خلال واجهة بايثون.

فعّل البيئة الافتراضية من جديد:

$ cd ~
$ source env/bin/activate

انتقل إلى المجلد "customers" وافتح الملف "models.py"، وهو ملف بايثون يخزن كافة نماذج تطبيقك:

(env) ali@ubuntu:$ cd ~/djangoreactproject/customers/
(env) ali@ubuntu:$ nano models.py

سيحتوي الملف على المحتوى التالي:

from django.db import models
# Create your models here.

نشير إلى أنه قد استوردت واجهة برمجة التطبيقات لنموذج العملاء سلفًا ضمن الملف بفضل تعليمة الاستيرادfrom django.db import models. ستضيف الآن الصنف Customer المشتق من الصنف models.Model. كل نموذج في جانغو هو صنف بايثون مشتق من django.db.models.Model.

سيكون في نموذج العميل "Customer" حقول قاعدة البيانات التالية:

• first_name: الاسم الأول للعميل.
• last_name: اسم العائلة للعميل.
• email: البريد الإلكتروني للعميل.
• phone: رقم هاتف العميل.
• address: عنوان العميل.
• description: وصف العميل.
• createdAt: تاريخ إضافة العميل.

سنضيف أيضًا الدالة ()__str__ التي تعرّف طريقة عرض النموذج، والذي سيكون في حالتنا مع الاسم الأول للعميل. ولمزيدٍ من التفاصيل عن إنشاء الأصناف وتعريف الكائنات يرجى الاطلاع على المقالة كيف تبني الأصناف وتعرف الكائنات في بايثون 3.

أضف الشيفرة التالية إلى الملف "models.py":

from django.db import models

class Customer(models.Model):
    first_name = models.CharField("First name", max_length=255)
    last_name = models.CharField("Last name", max_length=255)
    email = models.EmailField()
    phone = models.CharField(max_length=20)
    address =  models.TextField(blank=True, null=True)
    description = models.TextField(blank=True, null=True)
    createdAt = models.DateTimeField("Created At", auto_now_add=True)

    def __str__(self):
        return self.first_name

ثم هجّر قاعدة البيانات لإنشاء جداول قاعدة البيانات. ينشئ الأمر makemigrations ملفات التهجير التي تضاف فيها التغييرات على النموذج، في حين يطبّق migrate التغييرات في ملفات التهجير إلى قاعدة البيانات.

عُد الآن إلى المجلد الجذر للمشروع:

(env) ali@ubuntu:$ cd ~/djangoreactproject

ونفذ ما يلي من أجل إنشاء ملفات التهجير:

(env) ali@ubuntu:$ python manage.py makemigrations

ستحصل على خرج يشبه التالي:

customers/migrations/0001_initial.py
    - Create model Customer

طبّق هذه التغييرات على قاعدة البيانات:

(env) ali@ubuntu:$ python manage.py migrate

وسترى خرجًا يشير إلى نجاح عملية التهجير:

Operations to perform:
  Apply all migrations: admin, auth, contenttypes, customers, sessions
Running migrations:
  Applying customers.0001_initial... OK

ستستخدم الآن ملف تهجير البيانات لإنشاء بيانات العميل المبدئية،إن أن ملف تهجير البيانات هو تهجير يضيف البيانات أو يعدّلها في قاعدة البيانات. أنشئ ملف تهجير بيانات فارغ للتطبيق customers:

(env) ali@ubuntu:$ python manage.py makemigrations --empty --name customers customers

سترى التأكيد التالي مع اسم ملف التهجير:

Migrations for 'customers':
  customers/migrations/0002_customers.py

لاحظ أن اسم ملف التهجير هو "customers.py‏_0002".

انتقل بعد ذلك إلى داخل مجلد التهجيرات للتطبيق customers.

(env) ali@ubuntu:$ cd ~/djangoreactproject/customers/migrations

افتح ملف التهجير المنشأ للتو:

(env) ali@ubuntu:$ nano 0002_customers.py

وهذا هو محتوى التهيئة للملف:

from django.db import migrations

class Migration(migrations.Migration):
    dependencies = [
        ('customers', '0001_initial'),
    ]
    operations = [
    ]

تستورد تعليمة الاستيراد واجهة برمجة التطبيقات للملف "migrations" وواجهة برمجة التطبيقات لجانغو من أجل إنشاء التهجيرات من الملف "django.db" والتي هي حزمة مبنية مسبقًا built-in تحتوي على الأصناف اللازمة للعمل مع قواعد البيانات.

الصنف Migration هو صنف بايثون يصف العمليات التي تُنفذ عند تهجير قواعد البيانات، وهو امتداد للصنف migrations.Migration، ويملك قائمتين:

• dependencies: تحتوي على التهجيرات المعتمدة.
• operations: تحتوي على العمليات التي ستُنفذ عندما نطبّق التهجير.

الآن، أضف تابعًا لإنشاء بيانات تجريبية للعملاء قبل تعريف الصنف Migration:

...
def create_data(apps, schema_editor):
    Customer = apps.get_model('customers', 'Customer')
    Customer(first_name="Customer 001", last_name="Customer 001", email="customer001@email.com", phone="00000000", address="Customer 000 Address", description= "Customer 001 description").save()

...

أمسكنا grab في هذا التابع الصنف Customer التابع للتطبيق customers وأنشأنا عميلًا تجريبيًّا لإدخاله إلى قاعدة البيانات.

للحصول على الصنف Customer، الذي سيمكّن من إنشاء عملاء جدد، نستخدم التابع ()get_model للكائن apps، الذي يمثّل مسجلًا registry للتطبيقات المثبتة ونماذج قواعد البيانات الخاصة بها.

سيمرّر الكائن apps من التابع ()RunPython عندما نستخدمه لتشغيل ()create_data. أضف التابع ()migrations.RunPython إلى القائمة الفارغة operations:

...
    operations = [
        migrations.RunPython(create_data),
    ]

يُعد التابع ()RunPython جزءًا من واجهة برمجة التطبيقات للتهجيرات التي تسمح لك بتشغيل شيفرة بايثون معينة في تهجير ما. تحدد القائمة operations أن هذا التابع سيُنفّذ عندما نطبق التهجير.

وفيما يلي الملف كاملًا:

from django.db import migrations

def create_data(apps, schema_editor):
    Customer = apps.get_model('customers', 'Customer')
    Customer(first_name="Customer 001", last_name="Customer 001", email="customer001@email.com", phone="00000000", address="Customer 000 Address", description= "Customer 001 description").save()

class Migration(migrations.Migration):
    dependencies = [
        ('customers', '0001_initial'),
    ]
    operations = [
        migrations.RunPython(create_data),
    ]

ولمزيدٍ من المعلومات عن تهجيرات البيانات، راجع التوثيق تهجير البيانات في جانغو.

الآن لتهجير قاعدة بياناتك، عُد أولًا إلى مجلد الجذر لمشروعك:

(env) ali@ubuntu:$ cd ~/djangoreactproject

هجّر قاعدة بياناتك لتنشئ البيانات التجريبية:

(env) ali@ubuntu:$ python manage.py migrate

سنرى خرجًا يؤكد على نجاح عملية التهجير:

Operations to perform:
  Apply all migrations: admin, auth, contenttypes, customers, sessions
Running migrations:
  Applying customers.0002_customers... OK

ولمزيدٍ من المعلومات عن العملية، راجع مقالة كيف تنشئ نماذج جانغو.

وهكذا بعد إنشاء نموذج العميل والبيانات التوضيحية، يمكننا المتابعة إلى بناء واجهة برمجة التطبيقات لريست REST API.

الخطوة الخامسة - إنشاء واجهة برمجة التطبيقات لريست REST API

سننشئ في هذه الخطوة واجهة برمجة التطبيقات لريست باستخدام إطار عمل جانغو ريست، إذ سننشئ عدة عروض مختلفة لواجهة برمجة التطبيقات؛ إذ يُقصد بعرض واجهة برمجة التطبيقات API view دالة تعالج طلب واجهة برمجة تطبيقات أو استدعاء واجهة برمجة التطبيقات؛ في حين أن نقطة نهاية واجهة برمجة التطبيقات هي عنوان URL متفرد يمثّل نقطة تماس مع نظام ريست. على سبيل المثال، عندما يرسل المستخدم طلب من نوع GET إلى نقطة نهاية واجهة برمجة التطبيقات، يستدعي جانغو الدالة المقابلة، أو عرض واجهة برمجة التطبيقات لمعالجة الطلب وإعادة أي نتائج محتملة.

سنستفيد أيضًا من المسلسِلات Serializers؛ إذ يسمح المسلسِل في إطار عمل جانغو بأن تُحوّل نسخ النماذج المعقدة ومجموعات الاستعلام QuerySets إلى صيغة محتوى JSON من أجل استهلاك واجهة برمجة التطبيقات، ويمكن أن يعمل صنف المسلسِل في الاتجاه الآخر أيضًا، إذ يزوِّد بآليات لتحليل وإلغاء سَلسَلة البيانات إلى نماذج جانغو ومجموعات استعلامه.

ستتضمن نقاط نهاية واجهة برمجة التطبيقات ما يلي:

• "api/customers": تُستخدم نقطة النهاية هذه لإنشاء عملاء وإعادة مجموعات العملاء المرقمة.
• "<api/customers/<pk": تُستخدم نقطة النهاية هذه للحصول على عملاء منفردين وتحديثهم وحذفهم بالاستعانة بمفتاح أساسي أو معرّف id.

سننشئ أيضًا عناوين URL في الملف "urls.py" التابع للمشروع من أجل نقاط النهاية المقابلة، أي "api/customers" و "<api/customers/<pk".

دعنا نبدأ بإنشاء الصنف serializer من أجل نموذجنا Customer.

إضافة صنف المسسلسل Serializer

يُعد إنشاء صنف مسلسِل لنموذج "Customer" ضروري لتحويل نسخ العملاء ومجموعات الاستعلام QuerySets من وإلى JSON، ولإنشاء الصنف المسلسِل، أنشئ أولًا الملف "serializers.py" داخل التطبيق "customers":

(env) ali@ubuntu:$ cd ~/djangoreactproject/customers/
(env) ali@ubuntu:$ nano serializers.py

أضف الشيفرة التالية لاستيراد واجهة برمجة التطيبقات للمسلسِلات ونموذج العميل Customer:

from rest_framework import serializers
from .models import Customer

ثم أنشئ صنف مسلسِل مُمتد عن الصنف serializers.ModelSerializer ويحدد الحقول التي ستُسلسَل:

...
class CustomerSerializer(serializers.ModelSerializer):

    class Meta:
        model = Customer 
        fields = ('pk','first_name', 'last_name', 'email', 'phone','address','description')

يحدد الصنف Meta النموذج والحقول التي ستُسلسَل، وهي:

• pk
• first_name
• last_name
• email
• phone
• address
• description

وهذا هو المحتوى الكامل لملف serializers.py:

from rest_framework import serializers
from .models import Customer

class CustomerSerializer(serializers.ModelSerializer):

    class Meta:
        model = Customer 
        fields = ('pk','first_name', 'last_name', 'email', 'phone','address','description')

الآن وبعد أن انتهينا من إنشاء صنف المسلسِل، يمكننا إضافة عروض واجهة برمجة التطبيقات.

إضافة عروض واجهة برمجة التطبيقات

سننشئ في هذا القسم عروض API لتطبيقنا الذي سيستدعيه جانغو عندما يزور المستخدمُ نقطةَ النهاية المقابلة لدالة العرض.

افتح الملف التالي:

(env) ali@ubuntu:$ nano ~/djangoreactproject/customers/views.py

احذف محتوى الملف وأضف أوامر الاستيراد التالية:

from rest_framework.response import Response
from rest_framework.decorators import api_view
from rest_framework import status

from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger
from .models import Customer 
from .serializers import *

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

بعد ذلك، أضف العرض الذي سيتولى معالجة طلبات من نوع POST و GET HTTP:

...

@api_view(['GET', 'POST'])
def customers_list(request):
    """
 List  customers, or create a new customer.
 """
    if request.method == 'GET':
        data = []
        nextPage = 1
        previousPage = 1
        customers = Customer.objects.all()
        page = request.GET.get('page', 1)
        paginator = Paginator(customers, 10)
        try:
            data = paginator.page(page)
        except PageNotAnInteger:
            data = paginator.page(1)
        except EmptyPage:
            data = paginator.page(paginator.num_pages)

        serializer = CustomerSerializer(data,context={'request': request} ,many=True)
        if data.has_next():
            nextPage = data.next_page_number()
        if data.has_previous():
            previousPage = data.previous_page_number()

        return Response({'data': serializer.data , 'count': paginator.count, 'numpages' : paginator.num_pages, 'nextlink': '/api/customers/?page=' + str(nextPage), 'prevlink': '/api/customers/?page=' + str(previousPage)})

    elif request.method == 'POST':
        serializer = CustomerSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

نستخدم أولًا المزخرِف (['api_view(['GET', 'POST@ لإنشاء عرض واجهة برمجة تطبيقات يمكنه قبول طلبات GET و POST، إذ يُعد المزخرِف decorator دالة تأخذ دالةً أخرى وتمدّدها extend تلقائيًا.

نستخدم المتغيّر request.method داخل متن التابع لفحص تابع HTTP الحالي وتنفيذ المنطق المقابل اعتمادًا على نوع الطلب:

• إذا كان الطلب من النوع GET، يرقّم التابع البيانات باستخدام مرقّم جانغو Django Paginator ويعيد الصفحة الأولى من البيانات بعد السَّلسَلَة، وعدد العملاء المتوفرين وعدد الصفحات المتوفرة والروابط إلى الصفحات السابقة واللاحقة. المرقّم paginator هو صنف جانغو داخلي يقسّم قوائم البيانات في عدة صفحات ويزوّد بتوابع للوصول إلى عناصر كل صفحة.
• إذا كان الطلب من النوع POST، يسلسِل التابع بيانات العميل المستلمة ثم يستدعي التابع ()save لكائن المسلسِل، ثم يعيد كائن استجابة Response وهو نسخة عن استجابة http أو HttpResponse مع رمز الحالة 201. كل عرض تنشؤه مسؤول عن إعادة كائن HttpResponse. يحفظ التابع ()save البيانات المسلسَلة في قاعدة البيانات.

أضف الآن عرض واجهة برمجة التطبيقات الذي سيكون مسؤولًا عن معالجة طلبات GET و PUT و DELETE من أجل جلب وتحديث وحذف العملاء اعتمادًا على المفتاح الأساسي pk:

...
@api_view(['GET', 'PUT', 'DELETE'])
def customers_detail(request, pk):
 """
 Retrieve, update or delete a customer by id/pk.
 """
    try:
        customer = Customer.objects.get(pk=pk)
    except Customer.DoesNotExist:
        return Response(status=status.HTTP_404_NOT_FOUND)

    if request.method == 'GET':
        serializer = CustomerSerializer(customer,context={'request': request})
        return Response(serializer.data)

    elif request.method == 'PUT':
        serializer = CustomerSerializer(customer, data=request.data,context={'request': request})
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

    elif request.method == 'DELETE':
        customer.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

زُخرِف التابعُ باستخدام (['api_view(['GET', 'PUT', 'DELETE@ للإشارة إلى أنه عرض واجهة برمجة تطبيقات API view يمكنه قبول طلبات من النوع GET و PUT و DELETE.

التحقق الموجود في الحقل request.method يتحقق من تابع الطلب واعتمادًا على قيمته يستدعي المنطق المناسب:

• إذا كان الطلب من النوع GET، تُسَلسَلُ بياناتُ العميل وترسلُ باستخدام كائن استجابة Response.
• إذا كان الطلب من النوع PUT، ينشئ التابع مسلسِلًا لبيانات العميل الجديد، ثم يستدعي التابع ()save لكائن المسلسَل المُنشأ، وأخيرًا يرسل كائن الاستجابة Response مع العميل المحدّث.
• إذا كان الطلب من النوع DELETE، يستدعي التابعُ التابعَ ()delete لكائن العميل لحذفه، ثم يعيد كائن استجابة دون بيانات.

يبدو ملف "views.py" المكتمل كما يلي:

from rest_framework.response import Response
from rest_framework.decorators import api_view
from rest_framework import status

from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger
from .models import Customer 
from .serializers import *


@api_view(['GET', 'POST'])
def customers_list(request):
    """
 List  customers, or create a new customer.
 """
    if request.method == 'GET':
        data = []
        nextPage = 1
        previousPage = 1
        customers = Customer.objects.all()
        page = request.GET.get('page', 1)
        paginator = Paginator(customers, 5)
        try:
            data = paginator.page(page)
        except PageNotAnInteger:
            data = paginator.page(1)
        except EmptyPage:
            data = paginator.page(paginator.num_pages)

        serializer = CustomerSerializer(data,context={'request': request} ,many=True)
        if data.has_next():
            nextPage = data.next_page_number()
        if data.has_previous():
            previousPage = data.previous_page_number()

        return Response({'data': serializer.data , 'count': paginator.count, 'numpages' : paginator.num_pages, 'nextlink': '/api/customers/?page=' + str(nextPage), 'prevlink': '/api/customers/?page=' + str(previousPage)})

    elif request.method == 'POST':
        serializer = CustomerSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

@api_view(['GET', 'PUT', 'DELETE'])
def customers_detail(request, pk):
    """
 Retrieve, update or delete a customer by id/pk.
 """
    try:
        customer = Customer.objects.get(pk=pk)
    except Customer.DoesNotExist:
        return Response(status=status.HTTP_404_NOT_FOUND)

    if request.method == 'GET':
        serializer = CustomerSerializer(customer,context={'request': request})
        return Response(serializer.data)

    elif request.method == 'PUT':
        serializer = CustomerSerializer(customer, data=request.data,context={'request': request})
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

    elif request.method == 'DELETE':
        customer.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

يمكننا الآن المتابعة إلى إنشاء نقاط النهاية.

إضافة نقاط النهاية لواجهة برمجة التطبيقات

سننشئ الآن نقطتي النهاية لواجهة برمجة التطبيقات، الأولى /‎api/customers من أجل الاستعلام عن العملاء وإنشائهم، والثانية <api/customers/<pk من أجل جلب وتحديث وحذف العملاء المنفردين اعتمادًا على المفاتيح الأساسية لكل منهم.

افتح الملف التالي:

(env) ali@ubuntu:$ nano ~/djangoreactproject/djangoreactproject/urls.py

دع المحتويات كما هي ولكن أضف الاستيراد إلى عروض customers في أعلى الملف:

from django.contrib import admin
from django.urls import path
from customers import views
from django.conf.urls import url

ثم أضف عنواني URL لكلٍ من /api/customers و <api/customers/<pk إلى قائمة نماذج عناوين URL urlpatterns التي تحتوي على عناوين URLs للتطبيق:

...

urlpatterns = [
    path('admin/', admin.site.urls),
    url(r'^api/customers/$', views.customers_list),
    url(r'^api/customers/(?P<pk>[0-9]+)$', views.customers_detail),
]

الآن بعد أن انتهينا من إنشاء نقاط النهاية لريست، لنرى كيف نستهلكها.

الخطوة السادسة - استهلاك واجهة برمجة التطبيقات لريست باستخدام اكسيوس Axios

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

نبدأ بإيقاف تنشيط البيئة الافتراضية:

(env) ali@ubuntu:$ deactivate

ثم ننتقل إلى مجلد الواجهة الأمامية "frontend":

(env) ali@ubuntu:$ cd ~/djangoreactproject/frontend

ثبت اكسيوس axios من npm باستخدام الأمر التالي:

(env) ali@ubuntu:$ npm install axios --save

يضيف الخيار save– اعتمادية axios إلى ملف التطبيق "package.json".

ثم أنشئ ملف جافا سكريبت اسمه "CustomersService.js" الذي سيحتوي على الشيفرة التي ستستدعي واجهات برمجة التطبيقات لريست. سنفعّل هذا داخل مجلد "src"، حيث توجد شيفرة التطبيق لمشروعنا:

$ cd src
$ nano CustomersService.js

أضف الشيفرة التالية التي تحتوي على توابع ستتصل بواجهات برمجة التطبيقات لجانغو ريست:

import axios from 'axios';
const API_URL = 'http://localhost:8000';

export default class CustomersService{

    constructor(){}


    getCustomers() {
        const url = `${API_URL}/api/customers/`;
        return axios.get(url).then(response => response.data);
    }  
    getCustomersByURL(link){
        const url = `${API_URL}${link}`;
        return axios.get(url).then(response => response.data);
    }
    getCustomer(pk) {
        const url = `${API_URL}/api/customers/${pk}`;
        return axios.get(url).then(response => response.data);
    }
    deleteCustomer(customer){
        const url = `${API_URL}/api/customers/${customer.pk}`;
        return axios.delete(url);
    }
    createCustomer(customer){
        const url = `${API_URL}/api/customers/`;
        return axios.post(url,customer);
    }
    updateCustomer(customer){
        const url = `${API_URL}/api/customers/${customer.pk}`;
        return axios.put(url,customer);
    }
}

سيستدعي الصنف CustomersService توابع اكسيوس Axios التالية:

• ()getCustomers: يحصل على الصفحة الأولى من العملاء.
• ()getCustomersByURL: يحصل على العملاء بواسطة عنوان URL، ويتيح هذا بدوره الحصول على الصفحات التالية من العملاء بتمرير روابط، مثل "api/customers/?page=2/".
• ()getCustomer: يحصل على عميل بواسطة مفتاحه الأساسي.
• ()createCustomer: ينشئ عميلًا.
• ()updateCustomer: يحدّث عميلًا.
• ()deleteCustomer: يحذف عميلًا.

نستطيع الآن عرض البيانات من واجهة برمجة التطبيقات الخاصة بنا في واجهة المستخدم لريآكت بإنشاء مكوّن CustomersList.

الخطوة السابعة - عرض البيانات من واجهة برمجة التطبيقات في تطبيق ريآكت

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

أنشئ أولًا الملف "CustomersList.js" في المجلد "frontend/src":

$ nano ~/djangoreactproject/frontend/src/CustomersList.js

ثم ابدأ في استيراد React و Component لإنشاء مكون ريآكت:

import  React, { Component } from  'react';

ثم استورد واستنسخ الوحدة CustomersService التي أنشأتها في الخطوة السابقة، والتي توفر توابع تُربط مع الواجهة الخلفية لواجهة برمجة تطبيقات ريست REST API:

...
import  CustomersService  from  './CustomersService';

const  customersService  =  new  CustomersService();

ثم أنشئ المكون CustomersList المُمتد عن الصنف Component، الذي سيستدعي واجهة برمجة التطبيقات لريست، إذ يجب أن يمتد مكون ريآكت عن الصنف Component أو أن يكون صنفًا فرعيًا عنه.

أضف الشيفرة التالية إلى الملف "CustomersList.js" لإنشاء مكون ريآكت الذي يمتدّ عن المكوّن react.Component:

...
class  CustomersList  extends  Component {

    constructor(props) {
        super(props);
        this.state  = {
            customers: [],
            nextPageURL:  ''
        };
        this.nextPage  =  this.nextPage.bind(this);
        this.handleDelete  =  this.handleDelete.bind(this);
    }
}
export  default  CustomersList;

هيأنا في الشيفرة كائن الحالة state داخل الباني constructor؛ إذ يحتفظ هذا الكائن بحالة متغيرات مكوّننا باستخدام مصفوفة عملاء فارغة. ستحتفظ هذه المصفوفة بالعملاء والمتغير nextPageURL الذي يحتفظ بعنوان URL للصفحة التالية التي ستستعيدها من واجهة برمجة تطبيقات الواجهة الخلفية.

ربطنا أيضًا التابعين ()nextPage و ()handleDelete بالمؤشر this بحيث يستطاع الوصول إليهما من شيفرة HTML، ثم أضفنا التابع ()componentDidMount واستدعاءً للتابع ()getCustomers ضمن الصنف CustomersList قبل قوس الإغلاق.

يُعد التابع ()componentDidMount تابع دورة حياة المكوّن ويُستدعى عند إنشاء المكوّن وإدخاله إلى نموذج كائن الوثيقة DOM. يستدعي التابع ()getCustomers كائن خدمة العملاء Customers Service للحصول على صفحة البيانات الأولى ورابط الصفحة التالية من الواجهة الخلفية لجانغو:

...
componentDidMount() {
    var  self  =  this;
    customersService.getCustomers().then(function (result) {
        self.setState({ customers:  result.data, nextPageURL:  result.nextlink})
    });
}

أضف تحت التابع ()componentDidMount بالضبط التابع ()handleDelete، الذي يتولى مهمة حذف عميل:

...
handleDelete(e,pk){
    var  self  =  this;
    customersService.deleteCustomer({pk :  pk}).then(()=>{
        var  newArr  =  self.state.customers.filter(function(obj) {
            return  obj.pk  !==  pk;
        });
        self.setState({customers:  newArr})
    });
}

يستدعي التابعُ ()handleDelete التابعَ ()deleteCustomer لحذف عميل باستخدام مفتاحه الأساسي، وإذا كانت العملية ناجحة، ستُرشّح filtered المصفوفة لتعكس آخر حالة بعد حذف ذلك العميل.

بعد ذلك، أضف التابع ()nextPage لتحصل على بيانات الصفحة التالية وحدّث رابط الصفحة التالية:

...
nextPage(){
    var  self  =  this;
    customersService.getCustomersByURL(this.state.nextPageURL).then((result) => {
        self.setState({ customers:  result.data, nextPageURL:  result.nextlink})
    });
}

يستدعي التابعُ ()nextPage التابعَ ()getCustomersByURL، الذي يأخذ عنوان URL للصفحة التالية من كائن الحالة this.state.nextPageURL ويحدّث مصفوفة العملاء customers بالبيانات المعادة.

وأخيرًا، أضف التابع ()render، الذي يصيّر جدولًا للعملاء من حالة المكوّن:

...
render() {

    return (
    <div  className="customers--list">
        <table  className="table">
            <thead  key="thead">
            <tr>
                <th>#</th>
                <th>First Name</th>
                <th>Last Name</th>
                <th>Phone</th>
                <th>Email</th>
                <th>Address</th>
                <th>Description</th>
                <th>Actions</th>
            </tr>
            </thead>
            <tbody>
                {this.state.customers.map( c  =>
                <tr  key={c.pk}>
                    <td>{c.pk}  </td>
                    <td>{c.first_name}</td>
                    <td>{c.last_name}</td>
                    <td>{c.phone}</td>
                    <td>{c.email}</td>
                    <td>{c.address}</td>
                    <td>{c.description}</td>
                    <td>
                    <button  onClick={(e)=>  this.handleDelete(e,c.pk) }> Delete</button>
                    <a  href={"/customer/" + c.pk}> Update</a>
                    </td>
                </tr>)}
            </tbody>
        </table>
        <button  className="btn btn-primary"  onClick=  {  this.nextPage  }>Next</button>
    </div>
    );
}

وفيما يلي يظهر المحتوى الكامل للملف "CustomersList.js":

import  React, { Component } from  'react';
import  CustomersService  from  './CustomersService';

const  customersService  =  new  CustomersService();

class  CustomersList  extends  Component {

constructor(props) {
    super(props);
    this.state  = {
        customers: [],
        nextPageURL:  ''
    };
    this.nextPage  =  this.nextPage.bind(this);
    this.handleDelete  =  this.handleDelete.bind(this);
}

componentDidMount() {
    var  self  =  this;
    customersService.getCustomers().then(function (result) {
        console.log(result);
        self.setState({ customers:  result.data, nextPageURL:  result.nextlink})
    });
}
handleDelete(e,pk){
    var  self  =  this;
    customersService.deleteCustomer({pk :  pk}).then(()=>{
        var  newArr  =  self.state.customers.filter(function(obj) {
            return  obj.pk  !==  pk;
        });

        self.setState({customers:  newArr})
    });
}

nextPage(){
    var  self  =  this;
    console.log(this.state.nextPageURL);        
    customersService.getCustomersByURL(this.state.nextPageURL).then((result) => {
        self.setState({ customers:  result.data, nextPageURL:  result.nextlink})
    });
}
render() {

    return (
        <div  className="customers--list">
            <table  className="table">
            <thead  key="thead">
            <tr>
                <th>#</th>
                <th>First Name</th>
                <th>Last Name</th>
                <th>Phone</th>
                <th>Email</th>
                <th>Address</th>
                <th>Description</th>
                <th>Actions</th>
            </tr>
            </thead>
            <tbody>
            {this.state.customers.map( c  =>
                <tr  key={c.pk}>
                <td>{c.pk}  </td>
                <td>{c.first_name}</td>
                <td>{c.last_name}</td>
                <td>{c.phone}</td>
                <td>{c.email}</td>
                <td>{c.address}</td>
                <td>{c.description}</td>
                <td>
                <button  onClick={(e)=>  this.handleDelete(e,c.pk) }> Delete</button>
                <a  href={"/customer/" + c.pk}> Update</a>
                </td>
            </tr>)}
            </tbody>
            </table>
            <button  className="btn btn-primary"  onClick=  {  this.nextPage  }>Next</button>
        </div>
        );
  }
}
export  default  CustomersList;

الآن وبعد أنشأنا المكون CustomersList المسؤول عن عرض قائمة العملاء يمكننا الآن إضافة المكون الذي يتولى مهمة إنشاء العملاء وتحديثهم.

الخطوة الثامنة - إضافة مكون ريآكت لإنشاء العملاء وتحديثهم

سننشئ في هذه الخطوة المكون CustomerCreateUpdate الذي سيتولى مهمة إنشاء وتحديث العملاء، وذلك بإتاحة نموذج تعبئة form للمستخدمين لملئها ببيانات عميل جديد أو تحديث بيانات عميل موجود.

أنشئ الملف "CustomerCreateUpdate.js" داخل المجلد "frontend/src":

$ nano ~/djangoreactproject/frontend/src/CustomerCreateUpdate.js

أضف الشيفرة التالية لإنشاء مكون ريآكت الذي يستورد React و Component:

import  React, { Component } from  'react';

يمكنك أيضًا استيراد واستنساخ الصنف CustomersService الذي أنشأناه في الخطوة السابقة والذي يزود بتوابع توصل مع الواجهة الخلفية لواجهة برمجة تطبيقات ريست:

...
import  CustomersService  from  './CustomersService';

const  customersService  =  new  CustomersService();

ثم أنشئ المكون CustomerCreateUpdate المُمتدّ عن Component لإنشاء العملاء وتحديثهم:

...
class  CustomerCreateUpdate  extends  Component {

    constructor(props) {
        super(props);
    }

}
export default CustomerCreateUpdate;

أضف ضمن تعريف الصنف تابعَ المكوّن ()render الذي يصيّر نموذج HTML الذي يجمع معلومات عن العميل.

...
render() {
        return (
          <form onSubmit={this.handleSubmit}>
          <div className="form-group">
            <label>
              First Name:</label>
              <input className="form-control" type="text" ref='firstName' />

            <label>
              Last Name:</label>
              <input className="form-control" type="text" ref='lastName'/>

            <label>
              Phone:</label>
              <input className="form-control" type="text" ref='phone' />

            <label>
              Email:</label>
              <input className="form-control" type="text" ref='email' />

            <label>
              Address:</label>
              <input className="form-control" type="text" ref='address' />

            <label>
              Description:</label>
              <textarea className="form-control" ref='description' ></textarea>


            <input className="btn btn-primary" type="submit" value="Submit" />
            </div>
          </form>
        );
  }

يضيف هذا التابع الخاصية ref للوصول إلى عنصر النموذج التعبئة ووضع قيمة له وذلك من أجل كل عنصر إدخال ضمن نموذج التعبئة.

الآن، عرّف التابعَ (handleSubmit(event فوق التابع ()render لكي تمتلك الوظائف المناسبة عندما ينقر عميل على زر الإرسال submit:

...
handleSubmit(event) {
    const { match: { params } } =  this.props;
    if(params  &&  params.pk){
        this.handleUpdate(params.pk);
    }
    else
    {
        this.handleCreate();
    }
    event.preventDefault();
}

…

يعالج التابع (handleSubmit(event إرسال النموذج ويستدعي -اعتمادًا على المسار- إما التابع (handleUpdate(pk لتحديث العميل بالمفتاح الأساسي الممرر، أو التابع ()handleCreate لإنشاء عميل جديد. سنعرّف هذين التابعين باختصار.

عد إلى باني المكون، واربط التابع ()handleSubmit بالمؤشر this لكي تتمكن من الوصول إليه في نموذجك:

...
class CustomerCreateUpdate extends Component {

constructor(props) {
    super(props);
    this.handleSubmit = this.handleSubmit.bind(this);
}
...

ثم عرّف التابع ()handleCreate لإنشاء عميل من بيانات نموذج التعبئة، وأضف الشيفرة التالية فوق التابع (handleSubmit(event:

...
handleCreate(){
    customersService.createCustomer(
        {
        "first_name":  this.refs.firstName.value,
        "last_name":  this.refs.lastName.value,
        "email":  this.refs.email.value,
        "phone":  this.refs.phone.value,
        "address":  this.refs.address.value,
        "description":  this.refs.description.value
        }).then((result)=>{
                alert("Customer created!");
        }).catch(()=>{
                alert('There was an error! Please re-check your form.');
        });
}

…

سوف يُستخدَم التابع ()handleCreate من أجل إنشاء عميل من البيانات المُدخلة، إذ يستدعي التابع المقابل ()CustomersService.createCustomer الذي يجري استدعاءً لواجهة برمجة التطبيقات الفعلية للواجهة الخلفية لينشئ عميلًا جديدًا.

بعد ذلك عرّف التابع (handleUpdate(pk الذي يجري التحديثات أسفل التابع ()handleCreate:

...
handleUpdate(pk){
customersService.updateCustomer(
    {
    "pk":  pk,
    "first_name":  this.refs.firstName.value,
    "last_name":  this.refs.lastName.value,
    "email":  this.refs.email.value,
    "phone":  this.refs.phone.value,
    "address":  this.refs.address.value,
    "description":  this.refs.description.value
    }
    ).then((result)=>{

        alert("Customer updated!");
    }).catch(()=>{
        alert('There was an error! Please re-check your form.');
    });
}

سيحدّث التابع ()updateCustomer العميل ذا المفتاح الأساسي pk بالمعلومات الجديدة التي جلبها من نموذج معلومات العميل، ويستدعي التابع ()customersService.updateCustomer.

الآن، أضف التابع ()componentDidMount، وبالتالي إذا زار المستخدم الوجهة "customer/:pk"، فإننا نريد تعبئة النموذج بمعلومات مرتبطة بالعميل باستخدام المفتاح الأساسي من عنوان URL، ولفعل ذلك يمكننا إضافة التابع (getCustomer(pk بعد أن يُثبّت المكون في حدث دورة الحياة للتابع ()componentDidMount. أضف الشيفرة التالية أسفل باني المكون لإضافة هذا التابع:

...
componentDidMount(){
    const { match: { params } } =  this.props;
    if(params  &&  params.pk)
    {
        customersService.getCustomer(params.pk).then((c)=>{
            this.refs.firstName.value  =  c.first_name;
            this.refs.lastName.value  =  c.last_name;
            this.refs.email.value  =  c.email;
            this.refs.phone.value  =  c.phone;
            this.refs.address.value  =  c.address;
            this.refs.description.value  =  c.description;
        })
    }
}

وفيما يلي المحتوى الكامل للملف "CustomerCreateUpdate.js":

import React, { Component } from 'react';
import CustomersService from './CustomersService';

const customersService = new CustomersService();

class CustomerCreateUpdate extends Component {
    constructor(props) {
        super(props);

        this.handleSubmit = this.handleSubmit.bind(this);
      }

      componentDidMount(){
        const { match: { params } } = this.props;
        if(params && params.pk)
        {
          customersService.getCustomer(params.pk).then((c)=>{
            this.refs.firstName.value = c.first_name;
            this.refs.lastName.value = c.last_name;
            this.refs.email.value = c.email;
            this.refs.phone.value = c.phone;
            this.refs.address.value = c.address;
            this.refs.description.value = c.description;
          })
        }
      }

      handleCreate(){
        customersService.createCustomer(
          {
            "first_name": this.refs.firstName.value,
            "last_name": this.refs.lastName.value,
            "email": this.refs.email.value,
            "phone": this.refs.phone.value,
            "address": this.refs.address.value,
            "description": this.refs.description.value
        }          
        ).then((result)=>{
          alert("Customer created!");
        }).catch(()=>{
          alert('There was an error! Please re-check your form.');
        });
      }
      handleUpdate(pk){
        customersService.updateCustomer(
          {
            "pk": pk,
            "first_name": this.refs.firstName.value,
            "last_name": this.refs.lastName.value,
            "email": this.refs.email.value,
            "phone": this.refs.phone.value,
            "address": this.refs.address.value,
            "description": this.refs.description.value
        }          
        ).then((result)=>{
          console.log(result);
          alert("Customer updated!");
        }).catch(()=>{
          alert('There was an error! Please re-check your form.');
        });
      }
      handleSubmit(event) {
        const { match: { params } } = this.props;

        if(params && params.pk){
          this.handleUpdate(params.pk);
        }
        else
        {
          this.handleCreate();
        }

        event.preventDefault();
      }

      render() {
        return (
          <form onSubmit={this.handleSubmit}>
          <div className="form-group">
            <label>
              First Name:</label>
              <input className="form-control" type="text" ref='firstName' />

            <label>
              Last Name:</label>
              <input className="form-control" type="text" ref='lastName'/>

            <label>
              Phone:</label>
              <input className="form-control" type="text" ref='phone' />

            <label>
              Email:</label>
              <input className="form-control" type="text" ref='email' />

            <label>
              Address:</label>
              <input className="form-control" type="text" ref='address' />

            <label>
              Description:</label>
              <textarea className="form-control" ref='description' ></textarea>


            <input className="btn btn-primary" type="submit" value="Submit" />
            </div>
          </form>
        );
      }  
}

export default CustomerCreateUpdate;

وهكذا بعد إنشاء المكوّن CustomerCreateUpdate، أصبح بإمكاننا تحديث المكوّن App الرئيسي لإضافة روابط للمكونات المختلفة التي أنشأناها.

الخطوة التاسعة - تحديث مكون التطبيق الرئيسي

سنحدّث في هذا القسم المكوّن App من تطبيقنا لإنشاء روابط إلى المكونات التي أنشأناها في الخطوات السابقة.

نفذ الأمر التالي من المجلد "frontend"، لتثبيت موجه ريآكت الذي يمكّنك من إضافة المسارات والتنقلات بين مكونات ريآكت المتعددة.

$ cd ~/djangoreactproject/frontend
$ npm install --save react-router-dom

والآن افتح الملف "djangoreactproject/frontend/src/App.js/~":

$ nano ~/djangoreactproject/frontend/src/App.js

احذف كل شيء هناك وأضف الشيفرة التالية لاستيراد الأصناف اللازمة لإضافة التوجيه، إذ تتضمن هذه الأصناف الصنفَ BrowserRouter الذي ينشئ مكوّن الموجّه والصنفَ Route الذي ينشئ مكوّن الوُجهة route:

import  React, { Component } from  'react';
import { BrowserRouter } from  'react-router-dom'
import { Route, Link } from  'react-router-dom'
import  CustomersList  from  './CustomersList'
import  CustomerCreateUpdate  from  './CustomerCreateUpdate'
import  './App.css';

ملاحظة: يحافظ BrowserRouter على التزامن بين واجهة المستخدم وعنوان URL باستخدام واجهة برمجة تطبيقات تاريخ HTML5.

أنشئ نمطًا أساسيًّا ليزودنا بالمكون الأساسي الذي سيُغلِّفُه المكون BrowserRouter.

...

const  BaseLayout  = () => (
<div  className="container-fluid">
    <nav  className="navbar navbar-expand-lg navbar-light bg-light">
        <a  className="navbar-brand"  href="#">Django React Demo</a>
        <button  className="navbar-toggler"  type="button"  data-toggle="collapse"  data-target="#navbarNavAltMarkup"  aria-controls="navbarNavAltMarkup"  aria-expanded="false"  aria-label="Toggle navigation">
        <span  className="navbar-toggler-icon"></span>
    </button>
    <div  className="collapse navbar-collapse"  id="navbarNavAltMarkup">
        <div  className="navbar-nav">
            <a  className="nav-item nav-link"  href="/">CUSTOMERS</a>
            <a  className="nav-item nav-link"  href="/customer">CREATE CUSTOMER</a>
        </div>
    </div>
    </nav>
    <div  className="content">
        <Route  path="/"  exact  component={CustomersList}  />
        <Route  path="/customer/:pk"  component={CustomerCreateUpdate}  />
        <Route  path="/customer/"  exact  component={CustomerCreateUpdate}  />
    </div>
</div>
)

استخدمنا بالشيفرة أعلاه المكون Route لتعريف وجهات تطبيقنا، وهو المكون الذي يتعيّن على الموجّه تحميله عندما يجد تطابقًا. تحتاج كل وجهة إلى مسار path لتحديد المسار الذي سيجري مطابَقته، وإلى مكوّن component لتحديد المكون الذي سيحمّله. تخبر الخاصّيّة exact الموجّه أن يطابق المسار الصحيح.

وأخيرًا أنشئ المكون App المكوّن الجذر أو مكوّن مستوى القمة في تطبيق ريآكت:

...

class  App  extends  Component {

render() {
    return (
    <BrowserRouter>
        <BaseLayout/>
    </BrowserRouter>
    );
}
}
export  default  App;

وبما أننا نريد أن يعمل التطبيق في المتصفح، فقد غلّفنا المكوّن BaseLayout بالمكوّن BrowserRouter.

الآن يبدو ملف "App.js" المكتمل شبيهًا بما يلي:

import React, { Component } from 'react';
import { BrowserRouter } from 'react-router-dom'
import { Route, Link } from 'react-router-dom'

import  CustomersList from './CustomersList'
import  CustomerCreateUpdate  from './CustomerCreateUpdate'
import './App.css';

const BaseLayout = () => (
  <div className="container-fluid">
<nav className="navbar navbar-expand-lg navbar-light bg-light">
  <a className="navbar-brand" href="#">Django React Demo</a>
  <button className="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNavAltMarkup" aria-controls="navbarNavAltMarkup" aria-expanded="false" aria-label="Toggle navigation">
    <span className="navbar-toggler-icon"></span>
  </button>
  <div className="collapse navbar-collapse" id="navbarNavAltMarkup">
    <div className="navbar-nav">
      <a className="nav-item nav-link" href="/">CUSTOMERS</a>
      <a className="nav-item nav-link" href="/customer">CREATE CUSTOMER</a>

    </div>
  </div>
</nav>  

    <div className="content">
      <Route path="/" exact component={CustomersList} />
      <Route path="/customer/:pk"  component={CustomerCreateUpdate} />
      <Route path="/customer/" exact component={CustomerCreateUpdate} />

    </div>

  </div>
)

class App extends Component {
  render() {
    return (
      <BrowserRouter>
        <BaseLayout/>
      </BrowserRouter>
    );
  }
}

export default App;

بعد إضافة التوجيه إلى تطبيقنا، أصبحنا الآن جاهزين لاختبار التطبيق. انتقل إلى العنوان "http://localhost:3000"، ويفترض أن ترى الصفحة الأولى من التطبيق:

وبهذا يكتمل التطبيق، وأصبح لديك الآن الأساس لتطبيق إدارة علاقات العملاء CRM.

الخاتمة

أنشأت في هذا المقال تطبيقًا تجريبيًّا باستخدام جانغو وريآكت، واستخدمت إطار عمل جانغو ريست لبناء واجهة برمجة التطبيقات لريست REST واكسيوس Axios لاستهلاك واجهة برمجة التطبيقات وبوتستراب 4 لتنسيق CSS.

يمكنك العثور على الشيفرة المصدرية لهذا المشروع في مستودع غيت هب GitHub.

ترجمة - وبتصرف - للمقالة How To Build a Modern Web Application to Manage Customer Information with Django and React on Ubuntu 18.04 لصاحبها Ahmed Bouchefra.

اقرأ أيضًا

• بناء تطبيق مهام باستخدام جانغو Django وريآكت React
• البدء مع إطار العمل جانغو لإنشاء تطبيق ويب
• بناء تطبيق ويب من طرف الخادم باستخدام Nuxt.js وجانغو Django
• بناء تطبيق يعرض أحوال الطقس باستخدام جانغو Django

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

ستتولى واجهة برمجة التطبيقات لخرائط الطقس المفتوحة Open Weather Map API مسؤولية توفير بيانات الطقس الحالية. سنستخدم في عملنا قاعدة بيانات وننشئ نموذجًا، بحيث يمكن تطبيق ما سنتعلمه هنا لاحقًا في المشاريع الأعقد.

المتطلبات الأساسية

يلزم لهذا المشروع تثبيت بايثون Python على جهازك، وأن تتمكن من الرجوع إلى هذه السلسلة من المقالات التعليمية إذا احتجت إلى معلومات أكثر.

كُتبت الشيفرة المكتوبة في مقالنا هذا ببايثون 3 وجانغو 3.0، ولذلك لا بُد أن تكون ملمًا بهما جيدًا.

الخطوة الأولى - تجهيز المشروع

من السهل تثبيت جانغو كما هو حال أي مكتبة من مكتبات بايثون، بأحد الطريقتين التاليتين:

• فتح بيئة افتراضية وتنفيذ الأمر pip لتثبيت جانغو.
• إنشاء مجلد مشروع وتشغيل أداة pipenv، ثم تفعيل صدفة pipenv.

وتؤدي كلتا الطريقتين الغرض، لكننا سنستخدم في مقالتنا هذه أداة pipenv.

ملاحظة: يجب أن تكون قادرًا على الرجوع إلى هذه السلسلة من المقالات التعليمية إذا أردت استخدام طرق تثبيت جانغو الأخرى.

يحتوي التوثيق الرسمي لجانغو على تعليمات تثبيت pipenv، إما باستخدام Homebrew، أو Linuxbrew. يمكنك أيضًا تثبيت pipenv باستخدام pip.

أنشئ باستخدام نافذة الطرفية مجلدًا للبيئة:

$ mkdir the_weather_env

ثم انتقل إلى داخله:

$ cd the_weather_env

ثم استخدم pipenv لتثبيت جانغو:

$ pipenv install django

سيؤدي هذا إلى تثبيت آخر إصدار من جانغو على جهازك، وفي حالتنا كان آخر إصدار هو 3.0.5.

استخدم أيضًا pipenv لتثبيت مكتبة الطلبات Request التي ستستخدمها فيما بعد:

$ pipenv install requests

فعّل البيئة الافتراضية virtualenv للمشروع بتنفيذ الأمر التالي في الطرفية:

$ pipenv shell

سيولد هذا عمليةً فرعيةً جديدةً للصدفة.

الخطوة الثانية - افتتاح مشروع جانغو

بعد أن تنتهي من تثبيت جانغو أنشئ مجلدًا لهذا المشروع وانتقل إليه (إذا لم تكن قد فعلت ذلك).

يمكنك تنفيذ الأمر startproject الذي يوفره جانغو لتولّد المشروع.

(the_weather_env) django-admin startproject the_weather

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

لنجرب الآن تشغيل خادم التطوير، انتقل إلى المجلد الجديد في الطرفية:

(the_weather_env) cd the_weather 

والآن استخدم manage.py لتنفيذ الأمر unserver في الطرفية:

(the_weather_env) python manage.py runserver

سترى إذا دققت في الطرفية عنوان محدد الموارد الموحد URL لتطبيقك الذي يجب أن تكون قيمته الافتراضية هي "127.0.0.1:8000"، كما هو موضح في الصورة التالية:

افتح الآن متصفح الويب الذي تستخدمه واذهب إلى ذلك العنوان:

إذا كانت الصفحة صفحة تهنئة فاعلم أنك نجحت في إعداد جانغو بسلام.

الخطوة الثالثة - تسجيل الدخول إلى لوحة تحكم الإدارة

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

نحتاج أولًا لإيقاف تشغيل الخادم بالضغط إما على المفتاحين "CONTROL+C"، أو "CTRL+C" بحسب البيئة المُستخدمة، ثم ننفذ الأمر migrate في الطرفية:

(the_weather_env) python manage.py migrate

سينشئ جانغو عندئذٍ قاعدة بيانات SQLite وهي الافتراضية في الإعدادات، وسيضيف عدة جداول إليها. إذا رأيت في مجلد المشروع ملفًا جديدًا اسمه "db.sqlite3" فاعلم أن قاعدة البيانات قد أنشئت.

من الجداول التي يوفرها جانغو: جدول المستخدمين user table، الذي يخزن بيانات مستخدمي التطبيق، ولن نحتاج في تطبيقنا الذي نعمل عليه لأي مستخدمين باستثناء المستخدم المدير admin الذي يمكّننا من الوصول إلى لوحة تحكم الإدارة.

وعلى هذا، لننشئ مستخدم المدير بتنفيذ الأمر createsuperuser في الطرفية:

(the_weather_env) python manage.py createsuperuser

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

(the_weather_env) python manage.py runserver

اذهب من شاشة المتصفح إلى العنوان "127.0.0.1:8000‎/admin" الذي هو عنوان لوحة تحكم المدير، وننوه هنا إلى أن إعداد المستخدم admin ضمن الملف "urls.py" هو الذي مكّنك من الذهاب إلى تلك الصفحة.

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

يظهر في الصورة السابقة نموذجان يتيح لك جانغو الوصول إليهما، وهما: Groups و Users؛ إذ أن النماذج في حقيقتها ما هي إلا تمثيلات لجداول قاعدة البيانات. لذلك، هذان النموذجان انعكاسًا لجدولي قاعدة البيانات المقابلين، ومع أن جانغو قد أنشأ جداول أخرى غيرهما، إلا أنه لا حاجة بنا للوصول إليها مباشرةً لذا لم تُنشأ نماذج تقابلها.

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

دعنا نغادر لوحة الإدارة الآن ونركز على كتابة الشيفرة. ستحتاج إلى إنشاء تطبيق داخل مشروعك ليجلب لنا معلومات حالة الطقس.

الخطوة الرابعة - إنشاء التطبيق

يمكّننا جانغو من فصل الوظائف البرمجية عن بعضها بعضًا في المشروع الواحد باستخدام التطبيقات، فكل تطبيق يؤدي وظيفة معينة مُكلفٌ بها ضمن المشروع الواحد؛ فإذا نظرنا إلى الملف "settings.py" على سبيل المثال، فسنرى قائمة التطبيقات المثبتة "INSTALLED_APPS". وأول التطبيقات المثبتة هو "django.contrib.admin" الذي استخدمته للتو، إذ يتولى هذا التطبيق مسؤولية وظائف الإدارة فقط ولا شيء غير ذلك. مثال آخر على تطبيق موجود في المشروع افتراضيًّا، هو التطبيق "django.contrib.auth" الذي سمح لنا بتسجيل الدخول إلى لوحة الإدارة.

نحتاج في حالتنا إلى إنشاء تطبيق جديد يتولى مهمة إظهار حالة الطقس.

أوقف تشغيل الخادم أولًا، ثم نفذ الأمر startapp في الطرفية:

(the_weather_env) python manage.py startapp weather

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

دعنا ننشئ مع الملفات التي وُلِّدت للتو ملفًا جديدًا اسمه "urls.py" في مجلد التطبيق weather:

from django.urls import path

urlpatterns = [
]

هذا الملف مماثل للملف "urls.py" في مجلد "the_weather"، ويتمثّل الفرق بينهما هو أن هذا الملف "urls.py" يحتوي على جميع عناوين URL المرتبطة بالتطبيق نفسه.

لم تحدِّد أي عناوين URL بعد، لكن يمكنك إعداد المشروع لكي يتعرف على تطبيقك ويوجه أي عناوين URL معينة لتطبيقك إلى ملف التطبيق "urls.py".

اذهب إلى قائمة التطبيقات المثبتة INSTALLED_APPS في الملف settings.py وأضف اسم التطبيق weather إلى القائمة:

...

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'weather',
]

...

وبهذا تخبر جانغو أنك تريد استخدام التطبيق "weather" في مشروعك، وعندئذ سيعلم جانغو أين سيبحث عن ملفات التهجير وعناوين URL.

ستحتاج الآن إلى تعديل الملف الأصلي urls.py بحيث يشير إلى ملف urls.py الذي في التطبيق، ولذلك أضف سطرًا تحت المسار الموجود للوحة الإدارة، كما ستحتاج أيضًا إلى استيراد المكتبة include لتتمكن من الإشارة إلى ملف urls.py للتطبيق:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('weather.urls')),
]

تعني السلسلة الفارغة أنك لن تحتاج لاستخدام نقطة نهاية من أجل نقطة الدخول إلى تطبيقنا، بل سنترك للتطبيق مهمة معالجة أي نقاط نهاية محددة، وبالرفم من أنه كان بإمكاننا وضع شيء على نحو (...,'/path('weather، والذي كان سيُلزِمنا بكتابة /127.0.0.1:8000‎/weather للحصول على أي شيء مرافق لتطبيق الطقس، لكن لأن مشروعنا بسيط أصلًا فلن نفعل هذا هنا.

الخطوة الخامسة - إضافة القالب والعرض

سنحتاج الآن لإضافة القالب إلى المشروع الذي نعمل عليه؛ والقالب في جانغو ما هو إلا ملف HTML يتيح لنا تعليمات أوسع في شيفرته، الأمر الذي يجعل القالب ديناميكيًا، إذ سنتمكن فيه من معالجة وظائف، مثل إضافة المتغيرات والتعليمات الشرطية if والحلقات.

نذهب في الطرفية إلى مجلد التطبيق "weather":

(the_weather_env) cd weather

ثم ننشئ المجلد "templates":

(the_weather_env) mkdir templates

ثم ننتقل إلى داخله:

(the_weather_env) cd templates

أنشئ مجلدًا آخر يحمل نفس اسم التطبيق، لأن جانغو يدمج جميع مجلدات القوالب من التطبيقات الموجودة سابقًا لدينا معًا، وللحيلولة دون تكرار أسماء الملفات، يمكنك استخدام اسم التطبيق:

(the_weather_env) mkdir weather

من داخل مجلد weather هذا، أنشئ ملفًا جديدًا اسمه index.html الذي سيكون القالب الأساسي.

وفيما يلي شيفرة HTML التي ستستخدمها للقالب:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>What's the weather like?</title>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.6.2/css/bulma.css" />
</head>
<body>
    <section class="hero is-primary">
        <div class="hero-body">
            <div class="container">
                <h1 class="title">
                    What's the weather like?
                </h1>
            </div>
        </div>
    </section>
    <section class="section">
        <div class="container">
            <div class="columns">
                <div class="column is-offset-4 is-4">
                    <form method="POST">
                        <div class="field has-addons">
                            <div class="control is-expanded">
                                <input class="input" type="text" placeholder="City Name">
                            </div>
                            <div class="control">
                                <button class="button is-info">
                                    Add City
                                </button>
                            </div>
                        </div>
                    </form>
                </div>
            </div>
        </div>
    </section>
    <section class="section">
        <div class="container">
            <div class="columns">
                <div class="column is-offset-4 is-4">
                    <div class="box">
                        <article class="media">
                            <div class="media-left">
                                <figure class="image is-50x50">
                                    <img src="http://openweathermap.org/img/w/10d.png" alt="Image">
                                </figure>
                            </div>
                            <div class="media-content">
                                <div class="content">
                                    <p>
                                        <span class="title">Las Vegas</span>
                                        <br>
                                        <span class="subtitle">29° F</span>
                                        <br> thunderstorm with heavy rain
                                    </p>
                                </div>
                            </div>
                        </article>
                    </div>
                </div>
            </div>
        </div>
    </section>
    <footer class="footer">
    </footer>
</body>
</html>

ملاحظة: استخدمنا مكتبة بولما Bulma خلف الكواليس لمعالجة التنسيقات styling والتخطيطات layout.

بعد أن فرغت من إنشاء القالب ستنشئ مزيجًا يضم عرضًا view وعنوان URL معًا، لتتمكن من رؤية هذا فعليًا في التطبيق؛ والعروض في جانغو هي إما دوال أو أصناف، وفي حالتنا هذه ونظرًا لأنك تنشئ عرضًا بسيطًا فستنشئ دالةً، ثم تضيف هذه الدالة إلى ملف views.py:

from django.shortcuts import render

def index(request):
    return render(request, 'weather/index.html') #returns the index.html template

سُمّي العرض باسم "index" لأنه سيكون في فهرس التطبيق الذي هو عنوان URL الجذر. لا بُد من إعادة request لتصيير القالب، لأنه ضروري لدالة render واسم ملف القالب الذي تريد تصييره، والذي هو في حالتنا weather/index.html.

دعنا الآن نضيف عنوان URL الذي سيرسل الطلب إلى هذا العرض. لذلك، حدِّث القائمة urlpatterns في ملف urls.py للتطبيق كما يلي:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.index),  #the path for our index view
]

يتيح لك هذا فهرسة العرض الذي أنشأته للتو.

سيطابق جانغو أي عنوان URL ليس لديه نقطة نهاية ويوجهه إلى تابع العرض الذي أنشأته.

الآن، اذهب إلى نافذة الطرفية وعد فيها إلى جذر المشروع (the_weather)، ثم شغّل الخادم:

(the_weather_env) python manage.py runserver

ثم افتح متصفح الويب واذهب للعنوان 127.0.0.1:8000 مرةً أخرى.

سترى صفحة HTML المُصيرة للملف index.html، ويوجد فيها حقل يمكّنك من إضافة مدينة، ويظهر أيضًا قيمةٌ ضمنيةٌ مسبقةٌ لطقس لاس فيجاس، لكن ما يزال النموذج غير جاهز والطقس في الوقت الحالي هو مجرد موضع مؤقت placeholder، لذا سنعمل على هذه الأمور في الخطوات التالية.

الخطوة السادسة - استخدام واجهة برمجة تطبيقات الطقس Weather API

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

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

ملاحظة: من المهم الحفاظ على سرية مفاتيح واجهة برمجة التطبيقات الطقس لمنع الأطراف الخارجية من استخدامها. تخيل ماذا سيحدث لو رُبِط مفتاح واجهة برمجة التطبيقات بمستودع بعيد مثل مستودعات Github. لا أعتقد أن أحدًا منا يرغب في أن يحدث هذا معه.

نقطة النهاية الوحيدة التي ستستخدمها موضحةٌ فيما يلي، إذ يمكنك رؤية البيانات المعادة بتعديل عنوان URL التالي بحيث يحتوي مفتاح واجهة برمجة التطبيقات، ثم الذهاب إلى عنوان URL في المتصفح:

http://api.openweathermap.org/data/2.5/weather?q=las%20vegas&units=imperial&appid=YOUR_APP_KEY

يستغرق تفعيل مفتاح واجهة برمجة التطبيقات بعض الوقت، لذا إذا لم يعمل في بادئ الأمر فانتظر بضع دقائق، ثم كرّر المحاولة.

من المتوقع الحصول على استجابة بصيغة JSON تحتوي على الإحداثيات ودرجات الحرارة وأحوال الطقس.

دعنا الآن نضيف طلبًا للحصول على البيانات وإخراجها إلى التطبيق، ونعدّل العرض index لإرسال طلب إلى عنوان URL الذي لديك.

from django.shortcuts import render
import requests

def index(request):
    url = 'http://api.openweathermap.org/data/2.5/weather?q={}&units=imperial&appid=YOUR_APP_KEY'

    city = 'Las Vegas'

    city_weather = requests.get(url.format(city)).json() #request the API data and convert the JSON to Python data types

    return render(request, 'weather/index.html') #returns the index.html template

أضف الآن import requests و url و city و city_weather.

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

سنعطي في الوقت الحالي القيمة الثابتة "Las Vegas" للمدينة city، لكن في المستقبل ستحدّد بقيم المدن الموجودة في قاعدة البيانات. أخيرًا، سترسل الطلب إلى عنوان URL باستخدام المدينة وتحصل على تمثيل JSON لتلك المدينة.

إذا جربت طباعة print النتيجة إلى الطرفية، ستتمكن من رؤية نفس البيانات التي حصلت عليها عندما وضعت عنوان URL في شريط العنوان:

...
def index(request):
    ...
    print(city_weather) #temporarily view output

    return render(request, 'weather/index.html') #returns the index.html template

إذا أعدت تحميل الصفحة في المتصفح فسترى أن البيانات طُبعت إلى الطرفية. كان الغرض من إضافة تعليمة print هو التحقق من صحة ما ذكرناه. الآن وقد حصل ذلك، سنحذف تعليمة print من الشيفرة.

الخطوة السابعة - عرض البيانات في القالب

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

لننشئ قاموسًا يخزن كافة البيانات التي تحتاجها. ستحتاج من بين البيانات المعادة temp و description و icon.

...
def index(request):
    ...
    weather = {
        'city' : city,
        'temperature' : city_weather['main']['temp'],
        'description' : city_weather['weather'][0]['description'],
        'icon' : city_weather['weather'][0]['icon']
    }

    return render(request, 'weather/index.html') #returns the index.html template

الآن وقد بات لديك كل المعلومات التي تريدها، يمكنك أن تمررها إلى القالب، ولذلك ستنشئ متغيرًا اسمه context سيكون قاموسًا يسمح لك باستخدام قيَمِهِ داخل القالب، ثم ستضيف في الدالة render وسيطًا ثالثًا هو context كما يلي:

...
def index(request):
    ...
    context = {'weather' : weather}

    return render(request, 'weather/index.html', context) #returns the index.html template

وهكذا بعد أن أصبحت بيانات الطقس داخل الـمتغير context، دعنا نذهب إلى القالب لنضيف هذه البيانات؛ فكل ما تحتاج فعله داخل القالب index.html هو تعديل شيفرة HTML لتستخدم المتغيرات بدلًا من استخدام القيم المسبقة الضمنية، إذ ستستخدِم هذه المتغيّرات الوسوم {{ }}، وستسنِد reference كل شيء داخل قاموس context.

نلاحظ أن جانغو يحوّل قيم القاموس، بحيث لا يمكن الوصول إليها إلا باستخدام صيغة الاستدعاء النقطية dot notation، إذ سنحصل مثلًا عند استخدام weather.city على اسم المدينة. لا تستخدم ['weather['city كما هو مُستخدم في بايثون.

ابحث عن الصندوق <div> وعدّله ليستخدم المتغيرات:

...
<div class="box">
    <article class="media">
        <div class="media-left">
            <figure class="image is-50x50">
                <img src="http://openweathermap.org/img/w/{{ weather.icon }}.png" alt="Image">
            </figure>
        </div>
        <div class="media-content">
            <div class="content">
                <p>
                    <span class="title">{{ weather.city }}</span>
                    <br>
                    <span class="subtitle">{{ weather.temperature }}° F</span>
                    <br> {{ weather.description }}
                </p>
            </div>
        </div>
    </article>
</div>
...

وهكذا بعد استبدال جميع المتغيرات، ستحصل على قيم الطقس الحالية للمدينة التي حددتها.

لكن ما تزال المدينة تظهر قيمتها ضمنية المسبقة، لذا فما ستفعله الآن هو سحب القيم من قاعدة البيانات وعرض بيانات المدن الموجودة فيها.

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

اذهب إلى الملف "models.py" في التطبيق "weather" وأضف الشيفرة التالية:

from django.db import models

class City(models.Model):
    name = models.CharField(max_length=25)

    def __str__(self): #show the actual city name on the dashboard
        return self.name

    class Meta: #show the plural of city as cities instead of citys
        verbose_name_plural = 'cities'

سينشئ هذه الشيفرة جدولًا في قاعدة البيانات بعمود اسمه name يدل على اسم المدينة، وسيكون نوع المدينة هو charfield أي سلسلة عاديّة. ولقبول هذه التغيرات وتطبيقها على قاعدة البيانات، ستحتاج لتنفيذ الأمر makemigrations الذي سيولد الشيفرة التي ستحدِّث قاعدة البيانات وتجري عمليات التهجير إليها.

دعنا نوقف تشغيل الخادم وننفذ تلك التهجيرات في نافذة الطرفية:

(the_weather_env) python manage.py makemigrations

ثم نهجّر:

(the_weather_env) python manage.py migrate

نحتاج لتمكين رؤية النموذج في لوحة الإدارة، ولهذا لا بُد من تسجيله في الملف "admin.py" كما يلي:

from django.contrib import admin
from .models import City

admin.site.register(City)

الآن نعيد تشغيل الخادم وننظر في لوحة الإدارة في المتصفح:

كما نرى فقد أصبحت City الآن أحد الخيارات.

يمكن بعد ذلك الذهاب إلى لوحة الإدارة وإضافة بعض المدن. على سبيل المثال: لندن وطوكيو ولاس فيجاس.

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

from django.shortcuts import render
import requests
from .models import City

ثم نحدّث الطلب request بالمدن cities:

...
def index(request):
    url = 'http://api.openweathermap.org/data/2.5/weather?q={}&units=imperial&appid=YOUR_APP_KEY'

    cities = City.objects.all() #return all the cities in the database
    ...

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

ستنشئ أولًا قائمة بيانات الطقس weather_data التي ستحتفظ بقيمة الطقس weather لكل مدينة city، ثم نستبدل متغيّر المدينة city الأصلي بحلقة تمر بكل المدن cities. بعد ذلك، يجب إلحاق كل استجابة weather لكل مدينةcity ببيانات الطقس weather_data. سنحتاج أيضًا إلى تحديث السياق context لتمرير هذه القائمة بدلًا من تمرير قاموس وحيد.

في هذه اللحظة يُفترض أن يكون الملف views.py شبيهًا بالتالي:

...
def index(request):
    ...
    cities = City.objects.all() #return all the cities in the database

    weather_data = []

    for city in cities:

        city_weather = requests.get(url.format(city)).json() #request the API data and convert the JSON to Python data types

        weather = {
            'city' : city,
            'temperature' : city_weather['main']['temp'],
            'description' : city_weather['weather'][0]['description'],
            'icon' : city_weather['weather'][0]['icon']
        }

        weather_data.append(weather) #add the data for the current city into our list

    context = {'weather_data' : weather_data}

    return render(request, 'weather/index.html', context) #returns the index.html template

ثم ستحتاج داخل قالب index.html للمرور في هذه القائمة مستخدمًا حلقة، وتوليد شيفرة HTML لكل مدينة city من القائمة. يمكنك لتحقيق ذلك وضع حلقة for حول شيفرة HTML التي تولد صندوقًا وحيدًا <div> للمدينة city.

...
<div class="column is-offset-4 is-4">
    {% for weather in weather_data %}
    <div class="box">
        <article class="media">
            <div class="media-left">
                <figure class="image is-50x50">
                    <img src="http://openweathermap.org/img/w/{{ weather.icon }}.png" alt="Image">
                </figure>
            </div>
            <div class="media-content">
                <div class="content">
                    <p>
                        <span class="title">{{ weather.city }}</span>
                        <br>
                        <span class="subtitle">{{ weather.temperature }}° F</span>
                        <br> {{ weather.description }}
                    </p>
                </div>
            </div>
        </article>
    </div>
    {% endfor %}
</div>
…