التّعامل مع مكتبة WTForms ضمن إطار عمل Flask: حقول النصوص والأعداد والتواريخ

في عالم تطوير تطبيقات الويب باستخدام لغة بايثون، يُعد إطار العمل Flask من أشهر الأُطر الخفيفة والمناسبة لبناء تطبيقات صغيرة ومتوسطة الحجم بمرونة عالية. من الجوانب الأساسية في تطوير التطبيقات هي التعامل مع نماذج الإدخال أو الـ Forms التي تسمح للمستخدمين بإدخال البيانات. هنا تأتي مكتبة WTForms كأحد الأدوات الفعالة والسهلة الاستخدام لتصميم هذه النماذج بشكل برمجي، مع توفير وسائل التحقق من صحة البيانات المدخلة بسهولة ويسر.

يهدف هذا المقال إلى استعراض مفصل وشامل للتعامل مع مكتبة WTForms ضمن بيئة Flask، مع التركيز بشكل خاص على حقول النصوص (Text Fields)، الأعداد (Integer Fields)، والتواريخ (Date Fields). سيتم شرح كيفية إنشاء النماذج، أنواع الحقول المختلفة، التحقق من صحة البيانات، والتعامل مع هذه الحقول في واجهة المستخدم وربطها مع خادم Flask.

مقدمة حول Flask و WTForms

Flask: إطار عمل ويب خفيف ومرن

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

WTForms: مكتبة إنشاء النماذج ومعالجتها

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

إنشاء نموذج باستخدام WTForms

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

الخطوة الأولى: تثبيت المكتبة

يتم تثبيت مكتبة WTForms مع امتداد Flask-WTF الذي يوفر التكامل بين Flask و WTForms باستخدام الأمر التالي:

bash
CopyEdit
pip install flask-wtf

الخطوة الثانية: إعداد تطبيق Flask مع دعم CSRF

يعتبر CSRF (Cross-Site Request Forgery) أحد المفاهيم الأمنية الهامة، لذا يوفر Flask-WTF حماية ضد هذا الهجوم بشكل مدمج.

python
CopyEdit
from flask import Flask, render_template, request
from flask_wtf import FlaskForm
from wtforms import StringField, IntegerField, DateField, SubmitField
from wtforms.validators import DataRequired, NumberRange, Length

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_secret_key_here'

الخطوة الثالثة: إنشاء نموذج يحتوي على حقول نصية، عددية وتاريخية

python
CopyEdit
class SampleForm(FlaskForm):
    name = StringField('الاسم', validators=[DataRequired(), Length(min=3, max=50)])
    age = IntegerField('العمر', validators=[DataRequired(), NumberRange(min=1, max=120)])
    birth_date = DateField('تاريخ الميلاد', format='%Y-%m-%d', validators=[DataRequired()])
    submit = SubmitField('إرسال')

شرح أنواع الحقول في WTForms

1. حقل النص (StringField)

هو الحقل الأكثر شيوعًا في النماذج، يُستخدم لإدخال نصوص حرة، مثل الاسم، العنوان، البريد الإلكتروني، وغيرها. يمكن تقييد هذا الحقل باستخدام Validators مثل DataRequired للتأكد من أن المستخدم لم يترك الحقل فارغًا، أو Length للتحكم في عدد الأحرف المقبولة.

مثال عملي على StringField

python
CopyEdit
name = StringField('الاسم', validators=[DataRequired(), Length(min=3, max=50)])

هنا، يطلب من المستخدم إدخال اسم يتراوح طوله بين 3 و50 حرفًا، ولا يسمح بترك الحقل فارغًا.

2. الحقول العددية (IntegerField و FloatField)

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

مثال على IntegerField

python
CopyEdit
age = IntegerField('العمر', validators=[DataRequired(), NumberRange(min=1, max=120)])

هنا، يجب أن يكون العمر رقمًا صحيحًا بين 1 و120، كما لا يمكن ترك الحقل فارغًا.

FloatField

بالنسبة للأعداد العشرية، تُستخدم FloatField، ولكنها ليست ضمن الموضوع الأساسي هنا، ويمكن استيرادها من wtforms بنفس الطريقة.

3. حقل التاريخ (DateField)

حقل التواريخ مهم جدًا عند التعامل مع معلومات مثل تاريخ الميلاد، تاريخ الحجز، أو غيرها من التواريخ. يوفر WTForms حقل DateField الذي يسمح بإدخال تاريخ بصيغة محددة.

تنسيق التاريخ

يجب تحديد صيغة التاريخ التي يتم قبولها، مثلاً الصيغة الشائعة YYYY-MM-DD ويتم تعيينها باستخدام الوسيط format='%Y-%m-%d'.

مثال على DateField

python
CopyEdit
birth_date = DateField('تاريخ الميلاد', format='%Y-%m-%d', validators=[DataRequired()])

التحقق من صحة البيانات (Validation)

تقدم WTForms نظامًا متكاملًا للتحقق من صحة البيانات باستخدام ما يُعرف بالـ Validators التي يمكن إضافتها إلى كل حقل. من أشهر الـ Validators:

• DataRequired(): تأكد من أن الحقل ليس فارغًا.

• Length(min, max): للتحكم في عدد الأحرف.

• NumberRange(min, max): للتحكم في نطاق الأرقام.

• Email(): للتحقق من صحة البريد الإلكتروني.

• Optional(): للسماح بترك الحقل فارغًا.

يمكن استخدام أكثر من Validator على حقل واحد كما في المثال التالي:

python
CopyEdit
name = StringField('الاسم', validators=[DataRequired(), Length(min=3, max=50)])

التعامل مع النموذج في Flask

بعد إعداد النموذج، تأتي مرحلة التعامل مع البيانات المُدخلة من قبل المستخدم ضمن تطبيق Flask. تتم هذه الخطوة عبر استدعاء النموذج في دالة عرض (View Function) والتأكد من صحة البيانات عند الإرسال.

مثال متكامل على استلام البيانات والتحقق منها

python
CopyEdit
@app.route('/form', methods=['GET', 'POST'])
def form_view():
    form = SampleForm()
    if form.validate_on_submit():
        name = form.name.data
        age = form.age.data
        birth_date = form.birth_date.data
        
        # معالجة البيانات أو حفظها في قاعدة البيانات
        return f"البيانات المدخلة: الاسم: {name}, العمر: {age}, تاريخ الميلاد: {birth_date.strftime('%Y-%m-%d')}"
    
    return render_template('form.html', form=form)

إعداد قالب HTML لعرض النموذج

يحتاج المطور إلى ملف HTML لعرض النموذج للمستخدم بطريقة جميلة وسهلة الاستخدام. يمكن استخدام Jinja2 مع Flask لعرض الحقول وتوليد عناصر النموذج تلقائيًا.

نموذج بسيط لملف form.html

html
CopyEdit
html>
<html lang="ar">
<head>
    <meta charset="UTF-8">
    <title>نموذج الإدخالtitle>
head>
<body>
    <h1>أدخل بياناتكh1>
    <form method="POST" action="">
        {{ form.hidden_tag() }}
        
        <p>
            {{ form.name.label }}<br>
            {{ form.name(size=32) }}<br>
            {% for error in form.name.errors %}
                <span style="color: red;">{{ error }}span>
            {% endfor %}
        p>
        
        <p>
            {{ form.age.label }}<br>
            {{ form.age() }}<br>
            {% for error in form.age.errors %}
                <span style="color: red;">{{ error }}span>
            {% endfor %}
        p>
        
        <p>
            {{ form.birth_date.label }}<br>
            {{ form.birth_date() }}<br>
            {% for error in form.birth_date.errors %}
                <span style="color: red;">{{ error }}span>
            {% endfor %}
        p>
        
        <p>{{ form.submit() }}p>
    form>
body>
html>

كيفية عرض أخطاء التحقق من الصحة

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

خصائص إضافية لحقول WTForms

1. تعيين قيمة افتراضية (Default Value)

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

python
CopyEdit
name = StringField('الاسم', default='أدخل اسمك هنا')

2. التحكم في سمات الحقل (Attributes)

عند عرض الحقل في القالب يمكن تعديل خصائصه مثل الحجم أو النمط.

html
CopyEdit
{{ form.name(size=40, maxlength=50) }}

3. الحقول الاختيارية

عند عدم ضرورة ملء حقل معين يمكن استخدام Optional() validator.

python
CopyEdit
from wtforms.validators import Optional

nickname = StringField('الاسم المستعار', validators=[Optional(), Length(max=30)])

التعامل مع تواريخ معقدة

استخدام مكتبة datetime

عند استخدام DateField غالبًا ما يتم التعامل مع كائنات datetime.date، مما يتيح إمكانيات برمجية متقدمة كحساب العمر أو مقارنة التواريخ.

python
CopyEdit
from datetime import date

age = (date.today() - form.birth_date.data).days // 365

مثال شامل مع شرح تفصيلي

python
CopyEdit
from flask import Flask, render_template, request
from flask_wtf import FlaskForm
from wtforms import StringField, IntegerField, DateField, SubmitField
from wtforms.validators import DataRequired, Length, NumberRange, Optional
from datetime import date

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_secret_key_here'

class RegistrationForm(FlaskForm):
    name = StringField('الاسم', validators=[DataRequired(), Length(min=3, max=50)])
    age = IntegerField('العمر', validators=[DataRequired(), NumberRange(min=1, max=120)])
    birth_date = DateField('تاريخ الميلاد', format='%Y-%m-%d', validators=[DataRequired()])
    nickname = StringField('الاسم المستعار', validators=[Optional(), Length(max=30)])
    submit = SubmitField('تسجيل')

@app.route('/register', methods=['GET', 'POST'])
def register():
    form = RegistrationForm()
    if form.validate_on_submit():
        calculated_age = (date.today() - form.birth_date.data).days // 365
        return f"مرحبا {form.name.data}, عمرك الحقيقي حسب تاريخ الميلاد هو {calculated_age} سنة."
    return render_template('register.html', form=form)

if __name__ == '__main__':
    app.run(debug=True)

مزايا استخدام WTForms مع Flask

• فصل منطق النماذج: يجعل من السهل إدارة النموذج والتحقق من صحته بشكل مستقل عن منطق التطبيق.

• حماية CSRF: توفر Flask-WTF حماية مدمجة ضد هجمات تزوير الطلبات.

• تخصيص الحقول والـ Validators: تتيح إنشاء نماذج متقدمة تناسب احتياجات التطبيق المختلفة.

• سهولة التكامل مع HTML Templates: يعزز عملية عرض النماذج للمستخدم بشكل مريح ومنسق.

جدول توضيحي لأنواع الحقول الشائعة في WTForms

الخاتمة

تمثل مكتبة WTForms إضافة قوية لإطار العمل Flask من حيث التعامل مع نماذج الإدخال بشكل برمجي ومنظم. من خلال دعم الحقول المتنوعة كحقول النصوص، الأعداد، والتواريخ، يمكن للمطور بناء نماذج متقدمة تلبي احتياجات التطبيقات العملية بكل دقة وسهولة. يوفر WTForms نظام تحقق متكامل يضمن إدخال بيانات صحيحة وآمنة، بالإضافة إلى دعم الحماية من هجمات CSRF ضمن إطار Flask-WTF.

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

يُعتبر استخدام WTForms مع Flask الخيار الأمثل للمطورين الذين يسعون لبناء تطبيقات ويب متينة، آمنة، وقابلة للصيانة بسهولة مع تجربة مستخدم متكاملة وفعالة.

المصادر:

• الوثائق الرسمية لمكتبة WTForms:
  
  https://wtforms.readthedocs.io

• الوثائق الرسمية لإطار عمل Flask-WTF:
  
  https://flask-wtf.readthedocs.io