تقديم نموذج

في هذا المثال، نوضح كيفية تقديم نموذج باستخدام واجهة برمجة التطبيقات OneEntry.

✅ هدف السيناريو:

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

✅ ما تحتاجه:

• عنوان URL لمشروع صالح و APP_TOKEN للمصادقة مع واجهة برمجة التطبيقات OneEntry.
• نموذج مُعد مسبقًا في OneEntry يتم التعرف عليه بواسطة علامة (مثل 'contact_us').
• حقول نموذج مُعدة مسبقًا.

📌 مهم:

• التعامل مع الأخطاء المحتملة أثناء طلبات واجهة برمجة التطبيقات بشكل سلس لتوفير ملاحظات للمستخدمين.
• الحفاظ على خصوصية البيانات وأمانها، خاصة عند التعامل مع معلومات حساسة مثل عناوين البريد الإلكتروني.
• الحفاظ على تزامن حقول النموذج وعلاماتها مع تكوين الخلفية لتجنب عدم التطابق.
• هذه الأمثلة لا تتضمن معالجة الأخطاء.
• يمكنك إدارة الأخطاء باستخدام كتلة try-catch أو من خلال استخدام بناء مثل await Promise.catch((error) => error).

السيناريو

1. استيراد defineOneEntry من SDK وتحديد عنوان URL و token

مثال:

import { defineOneEntry } from 'oneentry';

const PROJECT_URL = 'your-project-url';
const APP_TOKEN = 'your-app-token';

2. إنشاء عميل API باستخدام دالة defineOneEntry()

مثال:

const { Forms, FormData } = defineOneEntry(PROJECT_URL, {
  token: APP_TOKEN,
});

3. الحصول على النموذج باستخدام Forms.getFormByMarker()

مثال:

const formData = await Forms.getFormByMarker('contact_us');

النتيجة:

{
  "id": 3,
  "attributeSetId": 2,
  "type": "data",
  "localizeInfos": {
    "title": "اتصل بنا",
    "titleForSite": "",
    "successMessage": "رسالة حول معالجة البيانات بنجاح",
    "unsuccessMessage": "رسالة حول معالجة البيانات بشكل غير ناجح",
    "urlAddress": "",
    "database": "0",
    "script": "0"
  },
  "version": 5,
  "position": 1,
  "identifier": "contact_us",
  "processingType": "script",
  "templateId": null,
  "attributes": [
    {
      "type": "string",
      "marker": "first_name",
      "isLogin": null,
      "isSignUp": null,
      "position": 1,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {
        "requiredValidator": {
          "strict": true
        }
      },
      "localizeInfos": {
        "title": "الاسم الأول"
      },
      "additionalFields": [],
      "isNotificationEmail": null,
      "isNotificationPhoneSMS": null,
      "isNotificationPhonePush": null
    },
    {
      "type": "string",
      "marker": "email",
      "isLogin": null,
      "isSignUp": null,
      "position": 2,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {
        "requiredValidator": {
          "strict": true
        },
        "emailInspectionValidator": true
      },
      "localizeInfos": {
        "title": "البريد الإلكتروني"
      },
      "additionalFields": [],
      "isNotificationEmail": null,
      "isNotificationPhoneSMS": null,
      "isNotificationPhonePush": null
    },
    {
      "type": "string",
      "marker": "surname",
      "isLogin": null,
      "isSignUp": null,
      "position": 3,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {
        "stringInspectionValidator": {
          "stringMax": 0,
          "stringMin": 0,
          "stringLength": 0
        }
      },
      "localizeInfos": {
        "title": "اللقب"
      },
      "additionalFields": [],
      "isNotificationEmail": null,
      "isNotificationPhoneSMS": null,
      "isNotificationPhonePush": null
    },
    {
      "type": "list",
      "marker": "topic",
      "isLogin": null,
      "isSignUp": null,
      "position": 4,
      "settings": {},
      "isVisible": true,
      "listTitles": [
        {
          "title": "مقالة",
          "value": "article",
          "extended": {
            "type": null,
            "value": null
          },
          "position": 1
        },
        {
          "title": "مقالة-2",
          "value": "article-2",
          "extended": {
            "type": null,
            "value": null
          },
          "position": 2
        }
      ],
      "validators": {
        "requiredValidator": {
          "strict": true
        }
      },
      "localizeInfos": {
        "title": "الموضوع"
      },
      "additionalFields": [],
      "isNotificationEmail": null,
      "isNotificationPhoneSMS": null,
      "isNotificationPhonePush": null
    },
    {
      "type": "text",
      "marker": "text",
      "isLogin": null,
      "isSignUp": null,
      "position": 5,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {},
      "localizeInfos": {
        "title": "النص"
      },
      "additionalFields": [],
      "isNotificationEmail": null,
      "isNotificationPhoneSMS": null,
      "isNotificationPhonePush": null
    },
    {
      "type": "spam",
      "marker": "spam",
      "isLogin": null,
      "isSignUp": null,
      "position": 6,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {},
      "localizeInfos": {
        "title": "أنت لست روبوتًا؟"
      },
      "additionalFields": [],
      "isNotificationEmail": null,
      "isNotificationPhoneSMS": null,
      "isNotificationPhonePush": null
    },
    {
      "type": "button",
      "marker": "send",
      "isLogin": null,
      "isSignUp": null,
      "position": 7,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {},
      "localizeInfos": {
        "title": "إرسال"
      },
      "additionalFields": [],
      "isNotificationEmail": null,
      "isNotificationPhoneSMS": null,
      "isNotificationPhonePush": null
    }
  ],
  "moduleFormConfigs": [
    {
      "id": 2,
      "moduleIdentifier": "content",
      "isGlobal": false,
      "isClosed": false,
      "viewOnlyUserData": false,
      "commentOnlyUserData": false,
      "entityIdentifiers": [
        {
          "id": "services",
          "isNested": false
        }
      ]
    }
  ]
}

4. الحصول على إعدادات إضافية لتقديم النموذج

مثال:

const moduleFormConfig = formData?.moduleFormConfigs?.[0];

5. الحصول على بيانات الحقول من نموذج الواجهة الأمامية

مثال:

[
  {
    "marker": "first_name",
    "value": "Firstname"
  },
  {
    "marker": "surname",
    "value": "Surname"
  },
  {
    "marker": "email",
    "value": "your@email.com"
  },
  {
    "marker": "topic",
    "value": [
      "article"
    ]
  },
  {
    "marker": "text",
    "value": [
      {
        "plainValue": "Some text"
      }
    ]
  }
]

6. تحويل البيانات للاستخدام مع نموذج OneEntry

مثال:

const transformedFormData = fieldsData.map((field: any) => {
  const { marker, value } = field;
  const formField = formFields.find(
    (field: { marker: string }) => field.marker === marker,
  );
  const { type } = formField;

  return {
    marker,
    type,
    value,
  }
});

النتيجة:

[
  {
    "marker": "first_name",
    "type": "string",
    "value": "Firstname"
  },
  {
    "marker": "surname",
    "type": "string",
    "value": "Surname"
  },
  {
    "marker": "email",
    "type": "string",
    "value": "your@email.com"
  },
  {
    "marker": "topic",
    "type": "list",
    "value": [
      "article"
    ]
  },
  {
    "marker": "text",
    "type": "text",
    "value": [
      {
        "plainValue": "Some text"
      }
    ]
  }
]

7. نشر FormsData باستخدام FormData.postFormsData()

مثال:

const formResponse = await FormData.postFormsData({
  formIdentifier: 'contact_us',
  formData: transformedFormData,
  formModuleConfigId: moduleFormConfig?.id || 0,
  moduleEntityIdentifier: moduleFormConfig?.entityIdentifiers?.[0]?.id || '',
  replayTo: null,
  status: 'sent',
});

النتيجة:

{
  "formData": {
    "formIdentifier": "contact_us",
    "time": "2025-11-17T12:51:20.172Z",
    "formData": [
      {
        "marker": "first_name",
        "type": "string",
        "value": "Firstname"
      },
      {
        "marker": "surname",
        "type": "string",
        "value": "Surname"
      },
      {
        "marker": "email",
        "type": "string",
        "value": "your@email.com"
      },
      {
        "marker": "topic",
        "type": "list",
        "value": [
          "article"
        ]
      },
      {
        "marker": "text",
        "type": "text",
        "value": [
          {
            "plainValue": "Some text"
          }
        ]
      }
    ],
    "entityIdentifier": "services",
    "fingerprint": "UQ_rrofe2",
    "isUserAdmin": false,
    "formModuleId": 2,
    "userIdentifier": null,
    "parentId": null,
    "id": 120
  },
  "actionMessage": "رسالة حول معالجة البيانات بنجاح"
}

المثال النهائي

// 1. استيراد defineOneEntry من SDK وتحديد PROJECT_URL و APP_TOKEN
import { defineOneEntry } from 'oneentry';

const PROJECT_URL = 'your-project-url';
const APP_TOKEN = 'your-app-token';

// 2. إنشاء عميل API 
const { Forms, FormData } = defineOneEntry(PROJECT_URL, {
  token: APP_TOKEN,
});

// 3. الحصول على النموذج وترتيب الحقول حسب الموضع
const formData = await Forms.getFormByMarker('contact_us');
const formFields = formData?.attributes.slice().sort(
  (a: { position: number }, b: { position: number }) =>
    a.position - b.position,
);

// 4. يحتوي هذا على إعدادات إضافية لتقديم النموذج
const moduleFormConfig = formData?.moduleFormConfigs?.[0];

// 5. الحصول على بيانات الحقول من نموذج الواجهة الأمامية
const fieldsData = [
  {
    marker: 'first_name',
    value: 'Firstname',
  },
  {
    marker: 'surname',
    value: 'Surname',
  },
  {
    marker: 'email',
    value: 'your@email.com',
  },
  {
    marker: 'topic',
    value: [
      'article',
    ],
  },
  {
    marker: 'text',
    value: [
      {
        plainValue: 'Some text',
      },
    ],
  },
];

// 6. تحويل البيانات للاستخدام مع نموذج OneEntry 
const transformedFormData = fieldsData.map((field: any) => {
  const { marker, value } = field;
  const formField = formFields.find(
    (field: { marker: string }) => field.marker === marker,
  );
  const { type } = formField;

  return {
    marker,
    type,
    value,
  };
});

// 7. نشر FormsData باستخدام FormData.postFormsData()
const formResponse = await FormData.postFormsData({
  formIdentifier: 'contact_us',
  formData: transformedFormData,
  formModuleConfigId: moduleFormConfig?.id || 0,
  moduleEntityIdentifier: moduleFormConfig?.entityIdentifiers?.[0]?.id || '',
  replayTo: null,
  status: 'sent',
});
console.log(formResponse);