كيفية استخدام إستمارات (Forms) جانغو

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

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

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

إعداد إستمارات جانغو في العرض

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

فيما يلي مثال لفئة Form بسيطة تتضمن حقل نص واحد:

from django import forms

class ContactForm(forms.Form):
    name = forms.CharField(label='Your Name')

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

from django.shortcuts import render
from .forms import ContactForm

def contact(request):
    form = ContactForm()
    return render(request, 'contact.html', {'form': form})

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

عرض إستمارة جانغو في القالب

لعرض إستمارة جانغو في قالب، يمكنك استخدام علامة القالب {% for %} للتنقل عبر حقول الإستمارة وعرضها واحدًا تلو الآخر. تسمح لك العلامة {% for %} بالوصول إلى تسمية الحقل الحالي واسمه وأي أخطاء قد تحدث أثناء التحقق من صحة الإستمارة.

فيما يلي مثال لكيفية استخدام العلامة {% for %} لعرض إستمارة في قالب:

<form method="post">
  {% csrf_token %}
  {% for field in form %}
    <div class="form-group">
      {{ field.label_tag }} {{ field }}
      {% if field.errors %}
        <div class="invalid-feedback">
          {% for error in field.errors %}
            {{ error }}
          {% endfor %}
        </div>
      {% endif %}
    </div>
  {% endfor %}
  <button type="submit" class="btn btn-primary">Submit</button>
</form>

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

ملاحظة: لا تنس تضمين علامة القالب {% csrf_token %} للحماية من هجمات تزوير الطلبات عبر المواقع.

يمكنك أيضًا تخصيص الطريقة التي يتم بها عرض كل حقل باستخدام علامة القالب field.as_widget وتمرير أي سمات HTML إضافية تريد تضمينها. على سبيل المثال:

{{ field.as_widget(attrs={'class': 'form-control'}) }}

سيؤدي هذا إلى إضافة فئة  form-control إلى عنصر HTML الخاص بالحقل، والذي يمكن استخدامه لتطبيق التصميم باستخدام CSS.

تخصيص تسميات حقول الإستمارة والعناصر النائبة

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

تسمح لك وسيطة  label بتحديد النص الذي سيتم عرضه كتسمية للحقل. على سبيل المثال:

name = forms.CharField(label='Your Name')

يمكنك أيضًا تجاوز التسمية الافتراضية وقيم العناصر النائبة لحقل الإستمارة في القالب باستخدام علامة القالب {% with %}. على سبيل المثال:

{% with form.email as field %}
  {{ field.label_tag }} {{ field }}
  {% if field.errors %}
    <div class="invalid-feedback">
      {% for error in field.errors %}
        {{ error }}
      {% endfor %}
    </div>
  {% endif %}
{% endwith %}

سيعرض رمز القالب هذا حقل البريد الإلكتروني بالتسمية الافتراضية والعنصر النائب، ولكن يمكنك تجاوز هذه القيم بسهولة عن طريق تعيين متغيرات التسمية والعنصر النائب في الكتلة { {% with %.

{% with form.email as field %}
  {% with label='Email Address' placeholder='Enter your email address' %}
    {{ field.label_tag }} {{ field }}
    {% if field.errors %}
      <div class="invalid-feedback">
        {% for error in field.errors %}
          {{ error }}
        {% endfor %}
      </div>
    {% endif %}
  {% endwith %}
{% endwith %}

سيؤدي هذا إلى عرض حقل البريد الإلكتروني مع التصنيف المخصص والعنصر النائب.

التحقق من صحة بيانات الإستمارة مع فئات Form

للتحقق من صحة بيانات الإستمارة باستخدام فئات form في جانغو، يمكنك استخدام التابع  clean لفئة  form. حيث يتم استدعاء تابع  clean عند إرسال الإستمارة ويسمح لك بإجراء أي عملية تحقق مخصصة تحتاجها.

فيما يلي مثال لفئة  form تتضمن تابع  clean للتحقق من صحة بيانات الإستمارة:

from django import forms

class ContactForm(forms.Form):
    name = forms.CharField(label='Your Name')
    email = forms.EmailField(label='Your Email')
    message = forms.CharField(widget=forms.Textarea)

    def clean(self):
        cleaned_data = super().clean()
        name = cleaned_data.get('name')
        email = cleaned_data.get('email')
        message = cleaned_data.get('message')

        if not name and not email and not message:
            raise forms.ValidationError('You have to write something!')

في هذا المثال، يتحقق التابع ا clean مما إذا كانت كافة حقول الإستمارة فارغة، و في حالة كانت كذلك فإنها تظهر خطأ في التحقق من الصحة.

يمكنك أيضًا استخدام التابع  clean_<field_name> لإجراء التحقق من الصحة في حقل إستمارة محددة. على سبيل المثال:

def clean_email(self):
    email = self.cleaned_data.get('email')
    if not email.endswith('@example.com'):
        raise forms.ValidationError('Email must be from example.com')
    return email

يتحقق التابع clean_email مما إذا كان حقل البريد الإلكتروني ينتهي بـ @example.com وينشئ خطأ في التحقق إذا لم يكن كذلك.

لعرض أخطاء الإستمارة في القالب، يمكنك استخدام علامة القالب{% if %} للتحقق مما إذا كان النموذج يحتوي على أي أخطاء، ثم استخدام متغير القالب {{form.non_field_errors }} لعرض الأخطاء. فيما يلي مثال لكيفية القيام بذلك:

{% if form.errors %}
  <div class="alert alert-danger">
    {{ form.non_field_errors }}
  </div>
{% endif %}

سيعرض هذا الكود أي أخطاء في الإستمارة غير مرتبطة بحقل معين. و لعرض الأخطاء في حقل معين، يمكنك استخدام متغير القالب {{ field.errors }}.

{% if field.errors %}
  <div class="invalid-feedback">
    {% for error in field.errors %}
      {{ error }}
    {% endfor %}
  </div>
{% endif %}

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

معالجة بيانات الإستمارة في العرض

لمعالجة بيانات الإستمارة في العرض، يمكنك استخدام سمة request.POST للوصول إلى بيانات الإستمارة المرسلة. سمة request.POST هي كائن يشبه القاموس يحتوي على بيانات الإستمارة المرسلة.

فيما يلي مثال لكيفية معالجة بيانات الإستمارة في دالة العرض:

from django.shortcuts import render
from .forms import ContactForm

def contact(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            name = form.cleaned_data['name']
            email = form.cleaned_data['email']
            message = form.cleaned_data['message']
            # Process the form data here
            return render(request, 'success.html')
    else:
        form = ContactForm()
    return render(request, 'contact.html', {'form': form})

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

يتم بعد ذلك التحقق من صحة الإستمارة باستخدام التابع is_valid، الذي يتحقق مما إذا كانت بيانات الإستمارة صالحة وفقًا لقواعد التحقق من صحة الإستمارة. إفذا كانت الإستمارة صالحة، فيمكن لدالة العرض الوصول إلى بيانات الإستمارة التي تم تنظيفها باستخدام قاموس form.cleaned_data.

إذا كانت الإستمارة غير صالحة، فسيتم عرض الإستمارة مرة أخرى مع عرض الأخطاء للمستخدم.

ملاحظة: لا تنس تضمين علامة القالب {% csrf_token %} في الإستمارة للحماية من هجمات تزوير الطلبات عبر المواقع.

عرض أخطاء الإستمارة

لعرض أخطاء الإستمارة في جانغو، يمكنك استخدام علامة القالب {% if %} للتحقق مما إذا كانت الإستمارة تحتوي على أي أخطاء، ثم استخدام متغير القالب {{form.non_field_errors }} لعرض الأخطاء. فيما يلي مثال لكيفية القيام بذلك:

{% if form.errors %}
  <div class="alert alert-danger">
    {{ form.non_field_errors }}
  </div>
{% endif %}

سيعرض هذا الكود أي أخطاء في الإستمارة غير مرتبطة بحقل معين. و لعرض الأخطاء في حقل معين، يمكنك استخدام متغير القالب {{ field.errors }}.

{% if field.errors %}
  <div class="invalid-feedback">
    {% for error in field.errors %}
      {{ error }}
    {% endfor %}
  </div>
{% endif %}

يمكنك أيضًا تخصيص طريقة عرض الأخطاء باستخدام سمات error_css_class و required_css_class لفئة form.

حيث تتيح لك سمة error_css_class تحديد فئة CSS التي ستتم إضافتها إلى حقول الإستمارة التي تحتوي على أخطاء، بينما تسمح لك سمة required_css_class بتحديد فئة CSS التي ستتم إضافتها إلى حقول الإستمارة المطلوبة.

على سبيل المثال :

class ContactForm(forms.Form):
    name = forms.CharField(label='Your Name', error_css_class='is-invalid', required_css_class='is-required')
    email = forms.EmailField(label='Your Email', error_css_class='is-invalid', required_css_class='is-required')
    message = forms.CharField(widget=forms.Textarea, error_css_class='is-invalid', required_css_class='is-required')
    error_css_class = 'is-invalid'
    required_css_class = 'is-required'

يمكنك بعد ذلك استخدام فئات CSS لتصميم حقول الإستمارة والأخطاء في ملف CSS الخاص بك. على سبيل المثال:

.is-invalid {
  border-color: #dc3545;
}

.is-invalid ~ .invalid-feedback {
  display: block;
}

.is-required {
  color: #6c757d;
}

سيقوم كود CSS السابق بتعيين لون حدود الحقول التي بها أخطاء إلى اللون الأحمر وعرض رسائل الخطأ، بالإضافة إلى تعيين لون الحقول المطلوبة إلى اللون الرمادي الفاتح.

العمل مع تحميل الملفات في الإستمارات

للعمل مع تحميل الملفات في إستمارات جانغو، يمكنك استخدام حقل الاستمارة FileField. حيث يسمح هذا الحقل للمستخدمين بتحديد وتحميل ملف كجزء من إرسال الإستمارة.

فيما يلي مثال form تتضمن FileField:

from django import forms

class FileForm(forms.Form):
    file = forms.FileField()

لعرض FileField في القالب، يمكنك استخدام علامة القالب {{ field }}. على سبيل المثال:

<form method="post" enctype="multipart/form-data">
  {% csrf_token %}
  {{ form.file }}
  <button type="submit" class="btn btn-primary">Submit</button>
</form>

ملاحظة: لا تنس تضمين السمة enctype=”multipart/form-data” في عنصر للسماح بتحميل الملفات.

في العرض، يمكنك الوصول إلى الملف الذي تم تحميله باستخدام request.FILES. أما سمة request.FILES هي كائن يشبه القاموس يحتوي على الملفات التي تم تحميلها.

فيما يلي مثال لكيفية معالجة ملف تم تحميله في دالة العرض:

from django.shortcuts import render
from .forms import FileForm

def file_upload(request):
    if request.method == 'POST':
        form = FileForm(request.POST, request.FILES)
        if form.is_valid():
            file = request.FILES['file']
            # Process the uploaded file here
            return render(request, 'success.html')
    else:
        form = FileForm()
    return render(request, 'file_upload.html', {'form': form})

في هذا المثال، تتحقق دالة العرض أولاً مما إذا كانت طريقة الطلب هي POST، مما يشير إلى أنه تم إرسال الإستمارة. فإذا كانت طريقة الطلب هي POST، تقوم دالة العرض بإنشاء مثيل FileForm جديد وتمرير بيانات request.POST و request.FILES إليها.

يتم بعد ذلك التحقق من صحة الإستمارة باستخدام التابع is_valid، الذي يتحقق مما إذا كانت بيانات الإستمارة صالحة وفقًا لقواعد التحقق من صحة الإستمارات. إفذا كانت صالحة، فيمكن لدالة العرض الوصول إلى الملف الذي تم تحميله باستخدام سمة request.FILES['file'] .

أما إذا كانت الإستمارة غير صالحة، فسيتم عرض الإستمارة مرة أخرى مع عرض الأخطاء للمستخدم.

حقول الإستمارة الشائعة

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

• CharField: يسمح للمستخدم بإدخال سلسلة من الأحرف.
• TextField: يسمح للمستخدم بإدخال سلسلة من الأحرف الطويلة.
• IntegerField: يسمح للمستخدم بإدخال عدد صحيح.
• FloatField: يسمح للمستخدم بإدخال عدد عشري.
• BooleanField: يسمح للمستخدم بتحديد خيار نعم أو لا.
• DateField: يسمح للمستخدم بإدخال تاريخ.
• TimeField: يسمح للمستخدم بإدخال وقت.
• DateTimeField: يسمح للمستخدم بإدخال تاريخ ووقت.

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

• EmailField: يتحقق مما إذا كان إدخال المستخدم عنوان بريد إلكتروني صالحًا.
• URLField: يتحقق مما إذا كان إدخال المستخدم عنوان URL صالحًا.
• FileField: يسمح للمستخدم بتحميل ملف.
• ImageField: يسمح للمستخدم بتحميل صورة.