الدليل الكامل لإضافة Auto-Populate في مُنشيء النماذج السهل

إذا كانت نماذج ووردبريس لديك تجبر الزائر على كتابة معلومات أنت تملكها مسبقًا في كل مرة، فإن ملحق Auto-Populate (التعبئة التلقائية) في مُنشيء النماذج السهل يحل هذه المشكلة بالضبط. يتيح لك هذا الملحق تعبئة حقول النموذج تلقائيًا ودون تدخل الزائر، من ثلاثة مصادر مختلفة: مجموعة بيانات (ملف CSV)، أو الردود السابقة لنفس النموذج، أو واجهة API خارجية.

نطاق هذا التوثيق: كُتب هذا الدليل بعد مراجعة الكود الفعلي لملحق Auto-Populate وملفات الترجمة العربية الرسمية للإضافة (مجلد languages/)، ولم يتم تخمين أي مصطلح. عبارات مثل «مُنشيء النماذج السهل» و«الملحقات» و«تنصيب» و«مجموعات البيانات» هي بالضبط ما تراه في لوحة التحكم المُعرَّبة لديك. إذا بدت تسمية مختلفة قليلًا في نسختك المثبَّتة، فالسبب هو اختلاف إصدار الإضافة أو ملف الترجمة المحدَّث.

إجابة سريعة (لمحركات البحث والذكاء الاصطناعي)

• Auto-Populate هي ملحق خاص بنسخة Pro فقط في مُنشيء النماذج السهل يُعبّئ حقول النموذج تلقائيًا.
• تدعم ثلاثة مصادر بيانات: مجموعة بيانات (ملف CSV مرفوع)، والردود السابقة لنفس النموذج، وواجهة API خارجية (REST).
• يتم التفعيل من مسار مُنشيء النماذج السهل ← الملحقات بنقرة واحدة على زر تنصيب، دون الحاجة لخطوة “حفظ” منفصلة.
• بعد التفعيل، تظهر صفحتا إعدادات جديدتان: مجموعة بيانات الملء التلقائي وتكاملات التعبئة التلقائية.
• بالنسبة لوضع API الخارجي، يتم التفعيل على نموذج معيّن بالكامل من داخل معالج «تكاملات التعبئة التلقائية» (اختيار النموذج المستهدف في الخطوة 3 + الحفظ)؛ ولا يوجد مفتاح منفصل لتغيير الوضع داخل منشئ النماذج نفسه.
• تتطلب هذه الميزة ترخيص Pro فعّالًا؛ وبدونه تبقى صفحات إعداداتها مقفلة.

ما هي Auto-Populate ومن يجب أن يستخدمها؟

وفقًا للوصف الرسمي للملحق في صفحة الملحقات الخاصة بالمكوّن الإضافي:

«يتيح لك ملحق التعبئة التلقائية تعبئة حقول النموذج تلقائيًا من مجموعة بيانات أو من الردود المُرسَلة سابقًا أو من واجهات API خارجية.»

بدلًا من أن تطلب من الزائر إعادة كتابة معلومات تملكها مسبقًا — في ملف CSV، أو في قاعدة بيانات النموذج نفسه، أو في نظام خارجي مثل CRM — يكفي أن يُدخل قيمة تعريفية واحدة (رقم الهوية، رمز العميل، رقم الطلب، أو البريد الإلكتروني)؛ فتُعبَّأ بقية الحقول تلقائيًا.

هذا الملحق مناسب لـ:

• المواقع التي لديها قائمة جاهزة من العملاء أو الموظفين أو أكواد الخصم وتريد تعبئة النموذج منها عبر CSV.
• النماذج التي يتكرر زيارتها من نفس الأشخاص، ولا ترغب في أن يعيدوا كتابة معلومات سبق تقديمها.
• المواقع التي تُخزَّن فيها بيانات النموذج المطلوبة في نظام خارجي (CRM أو ERP أو أي واجهة REST API).

كيف تعمل Auto-Populate؟ (ثلاثة أوضاع)

الطريقة	مصدر البيانات	مثال استخدام
مجموعة بيانات الملء التلقائي	ملف CSV تقوم برفعه بنفسك	قوائم الموظفين، العملاء، أكواد الخصم، الطلاب
التعبئة من الردود السابقة	الردود السابقة لنفس النموذج في قاعدة بيانات ووردبريس	عميل سابق يُدخل بريده الإلكتروني فتُستكمل بياناته
تكاملات التعبئة التلقائية	واجهة API خارجية (REST)	استعلام فوري من خدمة خارجية مثل نظام CRM الخاص بشركتك

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

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

• ترخيص Pro فعّال وصالح لمُنشيء النماذج السهل. فبدون ترخيص Pro فعّال أو غير منتهٍ، تعرض كلتا صفحتَي إعدادات التعبئة التلقائية رسالة “Pro Version Required” أو تنبيه انتهاء صلاحية، ولا تُفتحان.
• يجب أن تكون نسخة النواة الأساسية للإضافة 4.0 أو أحدث.
• لطريقة مجموعة البيانات: ملف CSV بترميز UTF-8 يحتوي على أسماء الأعمدة في الصف الأول.
• لطريقة API: عنوان نقطة نهاية (Endpoint) حقيقية تُعيد بيانات بصيغة JSON، مع معلومات المصادقة إن لزم الأمر.

كيف أثبّت وأفعّل Auto-Populate؟

مثل بقية ملحقات مُنشيء النماذج السهل، تكون التعبئة التلقائية معطّلة افتراضيًا:

1. من قائمة ووردبريس، اذهب إلى مُنشيء النماذج السهل ← الملحقات.
2. ابحث عن بطاقة «ملحق التعبئة التلقائية» (وصفها هو نفس ما ذُكر أعلاه: تعبئة تلقائية من مجموعة بيانات أو الردود السابقة أو API خارجي).
3. انقر على زر التنصيب. سيؤدي ذلك إلى تنزيل الملفات اللازمة للملحق وتفعيلها في نفس الوقت — لا حاجة لخطوة “حفظ الإعدادات” منفصلة.
4. بعد التفعيل، يتحول نفس الزر إلى «إزالة!»؛ انقر عليه مجددًا لإلغاء تفعيل الملحق.

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

كيف أنشئ مجموعة بيانات (ملف CSV) وأديرها؟

1. اذهب إلى مُنشيء النماذج السهل ← مجموعة بيانات الملء التلقائي.
2. استخدم زر رفع ملف CSV لاختيار ورفع ملف CSV (بترميز UTF-8، مع أسماء الأعمدة في الصف الأول).
3. تظهر مجموعة البيانات الجديدة في جدول «مجموعات البيانات».

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

• إعادة التسمية.
• النسخ/التكرار — ينشئ نسخة جديدة بلاحقة _copy.
• الحذف.
• تعديل القيم مباشرة داخل الجدول — انقر على أي قيمة لتعديلها مباشرة في الجدول؛ وتُطبَّق التغييرات فورًا على الردود الجديدة للنموذج دون الحاجة لإعادة رفع ملف CSV.

أعمدة مجموعة البيانات هي بالضبط أسماء رؤوس الأعمدة (Header) في ملف CSV الخاص بك، وتظهر بنفس الأسماء عند ربط الحقول في منشئ النماذج.

كيف أفعّل Auto-Populate على نموذج باستخدام مجموعة بيانات؟

• افتح النموذج المطلوب في منشئ النماذج.

• في الإعدادات العامة للنموذج (وليس حقلًا معينًا)، فعّل خيار «تمكين تعبئة تلقائية».

• يظهر عندها قائمة منسدلة، خيارها الأول محدَّد مسبقًا بنص «تعبئة تلقائية من النماذج المرسلة سابقاً» — أي إذا تركت هذا الخيار كما هو، يُفعَّل وضع «الردود السابقة» (القسم التالي). لاستخدام مجموعة بيانات، اختر من القائمة نفسها أحد الخيارات بصيغة «مجموعة بيانات: اسم‌المجموعة».
• عند اختيار مجموعة بيانات، يظهر قسم لتعريف شرط البحث:
  • اختر حقلًا من النموذج ليكون «حقل البحث» (مثلًا حقل يُدخل فيه الزائر رقم الموظف أو رقم الهوية). الحقول القابلة للاختيار هي فقط: نص، تاريخ، بريد إلكتروني، رقم، هاتف، رابط (URL)، كلمة مرور، تحديد (Select)، مربع اختيار (Check Box)، راديو (Radio)، والجوال.
  • أمامه، اختر عمود مجموعة البيانات الذي يجب أن تُطابَق القيمة المُدخَلة معه.
  • استخدم زر “+” لإضافة أكثر من شرط بحث واحد (مثلًا التطابق في آنٍ واحد على رقم الهوية وتاريخ الميلاد).

• لكل حقل تريد تعبئته تلقائيًا، افتح إعدادات ذلك الحقل وفعّل خيار «تفعيل التعبئة التلقائية لتعبئة هذا الحقل آلياً»، ثم اختر عمود مجموعة البيانات الخاص به.

• احفظ النموذج.

كيف تعمل التعبئة التلقائية من الردود السابقة للنموذج؟

يُفعَّل هذا الوضع عندما تُشغّل خيار «تمكين تعبئة تلقائية» في إعدادات النموذج وتترك القائمة المنسدلة على خيارها الافتراضي — «تعبئة تلقائية من النماذج المرسلة سابقاً» — دون اختيار مجموعة بيانات.

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

استخدام شائع: الزوار المتكررون لنموذج ما (نموذج طلب خدمة أو اشتراك مثلًا) والذين سبق أن قدّموا بياناتهم ولا داعي لإعادة كتابتها من الصفر.

الفرق الأساسي عن وضع مجموعة البيانات: هنا لا حاجة لأي ملف أو بيانات خارجية؛ فمصدر البيانات هو “ذاكرة” النموذج نفسه.

كيف أنشئ اتصال API خارجي؟ (تكاملات التعبئة التلقائية)

هذه الطريقة مخصصة للحالات التي لا تكون فيها البيانات المطلوبة في CSV أو في الردود السابقة للنموذج، بل في نظام خارجي (CRM أو ERP أو أي واجهة REST API أخرى) ويجب جلبها في الوقت الفعلي.

اذهب إلى مُنشيء النماذج السهل ← تكاملات التعبئة التلقائية وانقر على «إضافة اتصال API جديد». يتكون معالج هذا القسم من 4 خطوات:

الخطوة 1 — المعلومات الأساسية:

• اسم الاتصال: اسم تختاره (مثل «استعلام العميل»)
• طريقة HTTP: GET أو POST أو PUT أو PATCH
• رابط نقطة نهاية API: عنوان الـ API؛ يمكنك استخدام النمط {{field_id}} داخل الرابط ليحل محله مباشرة قيمة أحد حقول النموذج (مثل https://example.com/api/users/{{national_code}})
• قالب متن الطلب (JSON): فقط لطرق POST/PUT/PATCH؛ قالب JSON يمكن استخدام {{field_id}} بداخله أيضًا

الخطوة 2 — المصادقة:

خيارات نوع المصادقة المتوفرة: بدون مصادقة، API Key، Bearer Token، Basic Auth (بصيغة username:password)، أو ترويسة مخصصة. كما يمكنك إضافة ترويسات مخصصة (مفتاح/قيمة).

الخطوة 3 — ربط الحقول:

• النموذج المستهدف: النموذج الذي يُطبَّق عليه هذا الاتصال.
• حقول البحث (حقول التشغيل): حقل (أو حقول) النموذج التي تُرسَل قيمتها إلى الـ API؛ ولكل منها يمكن تحديد اسم API Parameter مخصص (وإذا تُرِك فارغًا، يُستخدَم اسم الحقل نفسه كاسم للمعامل افتراضيًا).
• مسار بيانات الاستجابة: إذا كانت البيانات المطلوبة داخل مفتاح متداخل في استجابة JSON (مثل data.results)، أدخل مساره بصيغة Dot Notation. وإذا تُرِك فارغًا، تُعتبَر الاستجابة كاملةً هي المصدر.
• تعيينات الحقول: اربط كل حقل من استجابة الـ API بحقل من النموذج.
• مدة التخزين المؤقت (بالدقائق): مدة تخزين الاستجابة مؤقتًا (0 تعني بلا تخزين مؤقت).

الخطوة 4 — الاختبار والحفظ:

• أدخل قيمة تجريبية لحقل (أو حقول) البحث وانقر على اختبار الاتصال لمراجعة الاستجابة الفعلية من الـ API وربط الحقول قبل النشر.
• بعد التأكد من نجاح الاختبار، احفظ الاتصال بالنقر على حفظ.

كيف يُفعَّل اتصال API على نموذج؟

بخلاف وضع مجموعة البيانات، لا يوجد هنا أي مفتاح أو قائمة منسدلة منفصلة داخل منشئ النماذج لتفعيل وضع API. يتم التفعيل بالكامل من داخل معالج «تكاملات التعبئة التلقائية» نفسه:

1. في الخطوة 3 من المعالج (ربط الحقول)، اختر النموذج المطلوب من قائمة النموذج المستهدف.
2. حدّد حقول البحث وتعيينات الحقول في نفس الخطوة (حسب القسم السابق).
3. بالنقر على حفظ في الخطوة 4، يكتب الملحق تلقائيًا الإعدادات اللازمة (تفعيل وضع API، معرّف الاتصال، حقول البحث، والحقول المستهدفة) مباشرة على بنية ذلك النموذج.
4. الآن إذا فتحت نفس النموذج في منشئ النماذج، تظهر بطاقة كبيرة بعبارة “API AutoFill Integration is Active” مرة واحدة فقط على مستوى إعدادات النموذج (وليس لكل حقل على حدة)، مع رابط مباشر إلى صفحة التكاملات. هذه البطاقة مجرد تأكيد لإعدادات محفوظة مسبقًا، وليست مفتاحًا قابلًا للتغيير.
5. تحصل الحقول المحددة كوجهة في تعيينات الحقول لذلك الاتصال على شارة صغيرة بعبارة «تعبئة تلقائية عبر واجهة برمجة تطبيقات (API) خارجية» في منشئ النماذج، لتوضيح أي الحقول ستُعبَّأ تلقائيًا.

ملاحظة لغوية: نص بطاقة التأكيد (“API AutoFill Integration is Active”) والوصف الذي تحته غير موجودَين حاليًا في ملف الترجمة العربية؛ لذلك يظهران بالإنجليزية بنفس الشكل حتى في اللوحة المُعرَّبة.

كيف يتصرف Auto-Populate في الواجهة الأمامية، وما دور التخزين المؤقت؟

السلوك من جهة الزائر متماثل في جميع الأوضاع الثلاثة (مجموعة البيانات، الردود السابقة، وAPI خارجي):

1. عندما يُدخل الزائر قيمة في «حقل البحث» ويغادره — عبر Tab أو Enter أو بالنقر خارج الحقل (Blur) — يرسل المتصفح طلبًا إلى نقطة النهاية الداخلية wp-json/Emsfb/v1/autofill/get.
2. حسب الوضع المختار، يبحث الخادم عن قيمة مطابقة في مجموعة البيانات، أو في الردود السابقة، أو (عبر استدعاء الـ API فعليًا) في استجابة الخدمة الخارجية.
3. عند إيجاد تطابق، تُعبَّأ الحقول المرتبطة فورًا (دون إعادة تحميل الصفحة)، مع عرض مؤشر تحميل قصير داخل الحقل نفسه.
4. إذا لم يتطابق أي شيء، يعرض النموذج رسالة مناسبة وتبقى الحقول فارغة.

في وضع API الخارجي، إذا كانت مدة التخزين المؤقت أكبر من صفر، تُخزَّن الاستجابة مؤقتًا خلال تلك الفترة الزمنية، لتسريع تحميل النموذج وتجنّب تجاوز حد معدل الطلبات (Rate Limit) لدى الخدمة الخارجية.

ملاحظات أمنية وأفضل الممارسات

• استخدم دائمًا عناوين HTTPS لنقطة نهاية الـ API لضمان تشفير البيانات أثناء النقل.
• حافظ على سرية مفاتيح الـ API والرموز؛ فهذه القيم تُخزَّن في إعدادات ووردبريس لديك.
• للبيانات كثيرة الطلب، اضبط مدة التخزين المؤقت على قيمة أكبر من صفر لتقليل عدد الطلبات إلى الـ API وتسريع تحميل النموذج.
• انتبه إلى أن طلبات API الخارجي تُنفَّذ بمهلة زمنية (Timeout) ثابتة مدتها 30 ثانية وغير قابلة للتعديل من داخل المعالج؛ تأكد أن الـ API الخاص بك يستجيب ضمن هذه المهلة، وإلا سيفشل الطلب.
• في النماذج الحساسة (كالاختبارات أو الاستبيانات)، لا تقم أبدًا بتعبئة إجابة صحيحة أو معلومات سرّية تلقائيًا في حقل مرئي للزائر عبر التعبئة التلقائية.

الأخطاء الشائعة وحلولها

الخطأ	السبب المحتمل	الحل
ظهور “Pro Version Required” عند فتح صفحات التعبئة التلقائية	ترخيص Pro غير مفعّل أو منتهي الصلاحية	فعّل أو جدّد ترخيص Pro
زر التنصيب يعرض فقط رسالة تحديث	نواة مُنشيء النماذج السهل أقدم من الحد الأدنى المطلوب لهذا الملحق	حدّث نواة المكوّن الإضافي إلى أحدث إصدار
الحقول لا تُعبَّأ، وتظهر رسالة “لم يتم العثور على بيانات”	القيمة المُدخَلة لا تطابق أي صف في مجموعة البيانات أو أي رد سابق أو استجابة API	راجع قيمة الاختبار وشرط البحث؛ وفي وضع مجموعة البيانات تحقق من اسم العمود المختار مجددًا
خطأ اتصال (كود 500 أو خطأ شبكة) في وضع API	عنوان نقطة النهاية غير صالح أو الخادم غير متاح	تحقق من الرابط وأعد الاختبار عبر زر اختبار الاتصال
كود حالة HTTP 400 فأعلى من الـ API	الخدمة الخارجية نفسها أعادت خطأ (مثل 404 أو 401)	راجع نقطة النهاية والمعاملات وبيانات المصادقة
خطأ تحليل (Parse) للاستجابة	الـ API أعاد استجابة ليست بصيغة JSON (مثل HTML)	تأكد أن نقطة النهاية تُعيد فعليًا بيانات JSON
نجاح استدعاء API لكن الحقول المرتبطة لا تُعبَّأ	مسار بيانات الاستجابة خاطئ أو تعيينات الحقول لا تطابق مفاتيح الاستجابة الفعلية	قارن مسار الاستجابة ومفاتيح تعيينات الحقول الدقيقة مع الاستجابة الخام للـ API

قائمة تحقق قبل النشر

•  مُنشيء النماذج السهل بإصدار 4.0 أو أحدث.
•  ترخيص Pro مفعّل وصالح.
•  ملحق «التعبئة التلقائية» مثبَّت ومفعَّل من صفحة الملحقات.
•  لوضع مجموعة البيانات: تم رفع ملف CSV بترميز UTF-8 وبرؤوس صحيحة، وتم فحص قيم تجريبية.
•  لوضع API: تم اختبار الاتصال بقيمة حقيقية عبر زر اختبار الاتصال.
•  حقل (حقول) البحث والحقول المستهدفة مرتبطة بشكل صحيح في منشئ النماذج.
•  تم اختبار النموذج المنشور فعليًا (في الواجهة الأمامية) بقيمة تجريبية، وتم التأكد من تعبئة الحقول تلقائيًا.
•  لوضع API: تم ضبط مدة التخزين المؤقت بما يناسب الحاجة الفعلية، وتم التأكد أن الـ API يستجيب ضمن مهلة الـ Timeout الثابتة (30 ثانية) الخاصة بالمعالج.

الأسئلة الشائعة

هل تتوفر Auto-Populate في النسخة المجانية من مُنشيء النماذج السهل؟

لا. هذا الملحق متاح فقط في نسخة Pro؛ وبدون ترخيص Pro فعّال، تبقى صفحات إعداداته مقفلة.

هل يمكنني استخدام مجموعة بيانات وAPI خارجي معًا في نفس النموذج؟

لا. إعداد التعبئة التلقائية على مستوى النموذج هو وضع واحد فقط (مجموعة بيانات/الردود السابقة أو API خارجي)؛ ويجب اختيار أحد هذه الأوضاع لكل نموذج.

هل يتطلب تغيير قيم مجموعة البيانات إعادة رفع ملف CSV؟

لا؛ يمكنك تعديل القيم مباشرة في جدول «مجموعات البيانات»، وتُطبَّق التغييرات فورًا على الردود الجديدة.

ما أنواع الحقول التي يمكن اختيارها كـ«حقل بحث»؟

الحقول النصية، البريد الإلكتروني، التاريخ، الرقم، الهاتف، الرابط (URL)، كلمة المرور، تحديد (Select)، مربع اختيار (Check Box)، راديو (Radio)، والجوال.

هل تدعم تكاملات التعبئة التلقائية المصادقة؟

نعم؛ تُدعَم API Key وBearer Token وBasic Auth والترويسات المخصصة جميعها.

كيف يُفعَّل وضع API الخارجي على نموذج معيّن؟

بالكامل من داخل معالج «تكاملات التعبئة التلقائية» — باختيار النموذج المستهدف في خطوة ربط الحقول والنقر على حفظ. لا يوجد أي مفتاح أو قائمة منسدلة منفصلة لهذا الغرض داخل منشئ النماذج؛ فمنشئ النماذج يعرض فقط بطاقة تأكيد وشارة على الحقول.

كيف يتم تفعيل ملحق Auto-Populate نفسه، وهل يوجد مفتاح تشغيل/إيقاف؟

لا. يتم تفعيل هذا الملحق بنقرة واحدة على زر تنصيب الموجود على بطاقته، ضمن مُنشيء النماذج السهل ← الملحقات. يحدث التثبيت والتفعيل في آنٍ واحد، ولا حاجة لخطوة «حفظ» منفصلة.