الفرق بين المراجعتين ل"Rails/form helpers"
جميل-بيلوني (نقاش | مساهمات) |
|||
سطر 1: | سطر 1: | ||
− | مساعدو | + | مساعدو الاستمارة في وحدة العرض في ريلز |
− | تعتبر | + | تعتبر [[HTML/form|الاستمارات]] (forms) في تطبيقات الويب واجهة أساسية للتفاعل مع المستخدم وجلب بيانات منه. ومع ذلك، يمكن أن تصبح عملية إنشاء استمارةٍ وصيانتها عمليةً مملةً بسبب الحاجة إلى التحكم بالتسمية وبخاصياتها الكثيرة. |
− | تخلَّص ريلز من هذا التعقيد بتوفير مساعدين للعرض لإنشاء | + | تخلَّص ريلز من هذا التعقيد بتوفير مساعدين للعرض لإنشاء الاستمارات بسهولة. ومع ذلك، بما أن للمساعدين حالات استخدام مختلفة، يحتاج المطورون إلى معرفة الاختلافات بين توابع كل مساعد قبل استخدامها. |
بعد قراءة هذا الدليل، ستتعلم: | بعد قراءة هذا الدليل، ستتعلم: | ||
− | * كيفية إنشاء | + | * كيفية إنشاء استمارات للبحث ونوع مماثل من الاستمارات العامة التي لا تمثل أي نموذج (model) محدد في تطبيقك. |
− | * كيفية عمل استمارات | + | * كيفية عمل استمارات مركزية النموذج (model-centric forms) لإنشاء وتعديل سجلات محددة في قاعدة بيانات. |
* كيفية إنشاء مربعات اختيار من أنواع متعددة من البيانات. | * كيفية إنشاء مربعات اختيار من أنواع متعددة من البيانات. | ||
* مساعدو التاريخ والوقت الذين يوفرهم ريلز. | * مساعدو التاريخ والوقت الذين يوفرهم ريلز. | ||
* ما الذي يجعل نموذج تحميل الملف مختلفًا. | * ما الذي يجعل نموذج تحميل الملف مختلفًا. | ||
− | * كيفية نشر | + | * كيفية نشر الاستمارات إلى الموارد الخارجية وتحديد الإعداد <code>authenticity_token</code>. |
− | * كيفية بناء | + | * كيفية بناء استمارات معقدة. |
− | '''ملاحظة''': ليس المقصود من هذا الدليل أن يكون توثيقًا كاملًا لمساعدي | + | '''ملاحظة''': ليس المقصود من هذا الدليل أن يكون توثيقًا كاملًا لمساعدي الاستمارات المتاحة وكل ما يتعلق بها. يرجى زيارة توثيق [http://api.rubyonrails.org/v5.2.2/ الواجهة البرمجية لريلز] للاطلاع على المرجع الكامل. |
− | == التعامل مع | + | '''تنويه''': استعملنا المصطلح "استمارة" ترجمةً للكلمة form، والمصطلح "نموذج" ترجمةً للكلمة model لكي لا يحدث لبسٌ بينهما، إذ تترجم form في كثير من الأحيان في الموسوعة إلى "نموذج". انتبه إلى أنَّ هذه الترجمة قد لا تُطبَّق على بقية توثيق ريلز. |
− | مساعد | + | |
+ | == التعامل مع الاستمارات الأساسية == | ||
+ | مساعد الاستمارة الأساسي هو <code>form_tag</code>.<syntaxhighlight lang="rails"> | ||
<%= form_tag do %> | <%= form_tag do %> | ||
Form contents | Form contents | ||
<% end %> | <% end %> | ||
− | </syntaxhighlight>عندما يستدعى بدون معاملات | + | </syntaxhighlight>عندما يستدعى بدون معاملات كما سبق، فإنه ينشئ الوسم <code>[[HTML/form|<form>]]</code> والذي، عند إرساله، سيرسل الاستمارة عبر POST إلى الصفحة الحالية. على سبيل المثال، بافتراض أن الصفحة الحالية هي /home/index، ستبدو شيفرة [[HTML]] المولدة هي (أضيفت إليها بعض فواصل الأسطر لقابلية القراءة):<syntaxhighlight lang="html"> |
<form accept-charset="UTF-8" action="/" method="post"> | <form accept-charset="UTF-8" action="/" method="post"> | ||
<input name="utf8" type="hidden" value="✓" /> | <input name="utf8" type="hidden" value="✓" /> | ||
سطر 26: | سطر 28: | ||
Form contents | Form contents | ||
</form> | </form> | ||
− | </syntaxhighlight>ستلاحظ أن شيفرة [[HTML]] تحتوي على عنصر [[HTML/input|إدخال]] من النوع <code>hidden</code>. هذا العنصر مهم، لأنه لا يمكن إرسال | + | </syntaxhighlight>ستلاحظ أن شيفرة [[HTML]] تحتوي على عنصر [[HTML/input|إدخال]] من النوع <code>hidden</code>. هذا العنصر مهم، لأنه لا يمكن إرسال الاستمارة بنجاح بدونه. يجبر عنصر الإدخال المخفي ذو الاسم utf8 المتصفحات أن تراعي ترميز محارف هذه الاستمارة وأنه قد أُنشِئ لجميع الاستمارات سواء كانت طريقة الإرسال عبر "GET" أو "POST". |
− | عنصر [[HTML/input|الإدخال]] الثاني ذو الاسم <code>Authenticity_token</code> هو ميزة أمان في ريلز تسمى "حماية هجمات تزوير الطلب عبر الموقع" (cross-site request forgery protection)، يولده كل مساعد | + | عنصر [[HTML/input|الإدخال]] الثاني ذو الاسم <code>Authenticity_token</code> هو ميزة أمان في ريلز تسمى "حماية هجمات تزوير الطلب عبر الموقع" (cross-site request forgery protection)، يولده كل مساعد لكل استمارة لا ترسل عبر GET (بشرط تفعيل ميزة الأمان هذه). يمكنك قراءة المزيد حول هذا الأمر في [[Rails/security|دليل تأمين تطبيقات ريلز]]. |
− | === | + | === استمارة بحث عامة === |
− | + | إحدى الاستمارات الأساسية التي تراها على الويب هي استمارة البحث. تحتوي هذه الاستمارة على: | |
− | * عنصر | + | * عنصر استمارة يرسل عبر الطريقة "GET". |
* عنصر تسمية لحقل الإدخال. | * عنصر تسمية لحقل الإدخال. | ||
* عنصر إدخال نصي. | * عنصر إدخال نصي. | ||
* عنصر إرسال. | * عنصر إرسال. | ||
− | لإنشاء | + | لإنشاء هذه الاستمارة، سيُستخدَم المساعدين <code>form_tag</code> و <code>label_tag</code> و <code>text_field_tag</code> و <code>submit_tag</code> على التوالي كالتالي:<syntaxhighlight lang="html"> |
<%= form_tag("/search", method: "get") do %> | <%= form_tag("/search", method: "get") do %> | ||
<%= label_tag(:q, "Search for:") %> | <%= label_tag(:q, "Search for:") %> | ||
سطر 49: | سطر 51: | ||
<input name="commit" type="submit" value="Search" /> | <input name="commit" type="submit" value="Search" /> | ||
</form> | </form> | ||
− | </syntaxhighlight>'''تنويه''': لكل عنصر إدخال | + | </syntaxhighlight>'''تنويه''': لكل عنصر إدخال للاستمارة، تُنشَئ الخاصية <code>id</code> من اسمه ("q" في المثال أعلاه). يمكن أن تكون هذه المعرفات مفيدة جدًا لتنسيق العناصر عبر [[CSS]] أو معالجة عناصر تحكم الاستمارة باستخدام [[JavaScript|جافاسكربت]]. |
بالإضافة إلى <code>text_field_tag</code> و <code>submit_tag</code>، يوجد مساعد مماثل لكل عنصر تحكم في [[HTML]]. | بالإضافة إلى <code>text_field_tag</code> و <code>submit_tag</code>، يوجد مساعد مماثل لكل عنصر تحكم في [[HTML]]. | ||
− | '''تحذير''': استخدم دائمًا الطريقة "GET" لإرسال | + | '''تحذير''': استخدم دائمًا الطريقة "GET" لإرسال استمارات البحث. يتيح ذلك للمستخدمين وضع إشارة حفظ (bookmark) على بحث معين للعودة إليه لاحقًا. بشكل عام، يشجعك ريلز على استخدام طريقة HTTP المناسبة لأي إجراء. |
− | === استعمال جدول <code>[[Ruby/Hash|Hash]]</code> مع استدعائات مساعد | + | === استعمال جدول <code>[[Ruby/Hash|Hash]]</code> مع استدعائات مساعد الاستمارة === |
− | يقبل المساعد <code>form_tag</code> تمرير وسيطين: مسار الإجراء وجدول <code>[[Ruby/Hash|Hash]]</code> يحوي الخيارات المتعلقة بالعملية. يحدد ذلك الجدول طريقة إرسال | + | يقبل المساعد <code>form_tag</code> تمرير وسيطين: مسار الإجراء وجدول <code>[[Ruby/Hash|Hash]]</code> يحوي الخيارات المتعلقة بالعملية. يحدد ذلك الجدول طريقة إرسال الاستمارة وخيارات [[HTML]] الأخرى مثل الصنف (الخاصية <code>class</code>). |
كما هو الحال مع المساعد <code>link_to</code>، لا يتوجب أن يكون وسيط المسار سلسلة نصية فقط، بل يمكن أن يكون جدول <code>[[Ruby/Hash|Hash]]</code> من معاملات URL يمكن التعرف عليها من خلال [[Rails/routing|آلية التوجيه]] في ريلز، والتي بدورها تحول الجدول إلى عنوان URL صالح. ومع ذلك، نظرًا لأن كلا المعاملين الممررين إلى <code>form_tag</code> هما من النوع <code>[[Ruby/Hash|Hash]]</code>، يمكنك بسهولة أن تواجه مشكلة إذا كنت ترغب في استعمالهما مع بعضهما بعضًا. على سبيل المثال، دعنا نقول أنك كتبت الشيفرة التالية:<syntaxhighlight lang="rails"> | كما هو الحال مع المساعد <code>link_to</code>، لا يتوجب أن يكون وسيط المسار سلسلة نصية فقط، بل يمكن أن يكون جدول <code>[[Ruby/Hash|Hash]]</code> من معاملات URL يمكن التعرف عليها من خلال [[Rails/routing|آلية التوجيه]] في ريلز، والتي بدورها تحول الجدول إلى عنوان URL صالح. ومع ذلك، نظرًا لأن كلا المعاملين الممررين إلى <code>form_tag</code> هما من النوع <code>[[Ruby/Hash|Hash]]</code>، يمكنك بسهولة أن تواجه مشكلة إذا كنت ترغب في استعمالهما مع بعضهما بعضًا. على سبيل المثال، دعنا نقول أنك كتبت الشيفرة التالية:<syntaxhighlight lang="rails"> | ||
سطر 62: | سطر 64: | ||
# => '<form accept-charset="UTF-8" action="/people/search?method=get&class=nifty_form" method="post">' | # => '<form accept-charset="UTF-8" action="/people/search?method=get&class=nifty_form" method="post">' | ||
− | </syntaxhighlight>هنا، يضاف <code>method</code> و <code>class</code> إلى سلسلة الاستعلام الخاصة بعنوان URL المُنشَأ لأنه حتى لو كنت تقصد كتابة جدولين من النوع <code>[[ | + | </syntaxhighlight>هنا، يضاف <code>method</code> و <code>class</code> إلى سلسلة الاستعلام الخاصة بعنوان URL المُنشَأ لأنه حتى لو كنت تقصد كتابة جدولين من النوع <code>[[Ruby/Hash|Hash]]</code>، فأنت بذلك حددت واحدًا فقط. بناءً على ما سبق، عليك أن تخبر روبي أي الجدولين هو للمعامل الأول وأيهما للثاني وذلك عن طريق تغليف الجدول الأولى (أو كليهما) بالأقواس المعقوصة. سيؤدي هذا إلى إنشاء شيفرة [[HTML]] التي تريدها بالضبط:<syntaxhighlight lang="rails"> |
form_tag({controller: "people", action: "search"}, method: "get", class: "nifty_form") | form_tag({controller: "people", action: "search"}, method: "get", class: "nifty_form") | ||
# => '<form accept-charset="UTF-8" action="/people/search" method="get" class="nifty_form">' | # => '<form accept-charset="UTF-8" action="/people/search" method="get" class="nifty_form">' | ||
سطر 68: | سطر 70: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | === مساعدون لتوليد عناصر | + | === مساعدون لتوليد عناصر الاستمارة === |
− | يوفر ريلز سلسلة من المساعدين لتوليد مختلف عناصر | + | يوفر ريلز سلسلة من المساعدين لتوليد مختلف عناصر الاستمارة مثل [[HTML/input/checkbox|مربعات الاختيار]] و<nowiki/>[[HTML/input/text|حقول نصية]] و<nowiki/>[[HTML/input/radio|أزرار الانتقاء]]. ينشئ هؤلاء المساعدون الأساسيون، مع أسماء تنتهي بـ <code>_tag</code> (مثل <code>text_field_tag</code> و <code>check_box_tag</code>)، عنصر <code>[[HTML/input|<input>]]</code> وحيد فقط. المعامل الأول المُمرَّر إليهم هو دائما اسم عنصر الإدخال. عند إرسال الاستمارة، سيُمرر الاسم مع بيانات الاستمارة، وسوف يشق طريقه إلى <code>params</code> في المتحكم مرفقًا بالقيمة التي أدخلها المستخدم لهذا الحقل. على سبيل المثال، إذا كانت الاستمارة تحتوي على <code><%= text_field_tag(:query) %></code>، فستتمكن من الحصول على قيمة هذا الحقل في المتحكم باستخدام <code>params [: query]</code>. |
عند تسمية المدخلات، يستخدم ريلز اصطلاحات معينة تجعل من الممكن إرسال المعاملات مع قيم غير أساسية (non-scalar values) مثل [[Ruby/Array|المصفوفات]] أو [[Ruby/Hash|جداول Hash]]، والتي يمكن الوصول إليها أيضًا في <code>params</code>. يمكنك قراءة المزيد عنها في الفصل السابع من هذا الدليل. للحصول على تفاصيل حول الاستخدام الدقيق لهؤلاء المساعدين، يرجى الرجوع إلى توثيق [http://api.rubyonrails.org/v5.2.2/classes/ActionView/Helpers/FormTagHelper.html الواجهة البرمجية الكامل]. | عند تسمية المدخلات، يستخدم ريلز اصطلاحات معينة تجعل من الممكن إرسال المعاملات مع قيم غير أساسية (non-scalar values) مثل [[Ruby/Array|المصفوفات]] أو [[Ruby/Hash|جداول Hash]]، والتي يمكن الوصول إليها أيضًا في <code>params</code>. يمكنك قراءة المزيد عنها في الفصل السابع من هذا الدليل. للحصول على تفاصيل حول الاستخدام الدقيق لهؤلاء المساعدين، يرجى الرجوع إلى توثيق [http://api.rubyonrails.org/v5.2.2/classes/ActionView/Helpers/FormTagHelper.html الواجهة البرمجية الكامل]. | ||
==== مربعات الاختيار ==== | ==== مربعات الاختيار ==== | ||
− | [[HTML/input/checkbox|مربعات الاختيار]] هي عناصر تحكم في | + | [[HTML/input/checkbox|مربعات الاختيار]] هي عناصر تحكم في الاستمارة تمنح المستخدم مجموعة من الخيارات التي يمكن تمكينها أو تعطيلها:<syntaxhighlight lang="html"> |
<%= check_box_tag(:pet_dog) %> | <%= check_box_tag(:pet_dog) %> | ||
<%= label_tag(:pet_dog, "I own a dog") %> | <%= label_tag(:pet_dog, "I own a dog") %> | ||
سطر 85: | سطر 87: | ||
<label for="pet_cat">I own a cat</label> | <label for="pet_cat">I own a cat</label> | ||
− | </syntaxhighlight>المعامل الأول المُمرَّر إلى <code>check_box_tag</code>، بالطبع، هو اسم عنصر الإدخال. المعامل الثاني، بطبيعة الحال، هو قيمة العنصر. ستُشمَل هذه القيمة في بيانات | + | </syntaxhighlight>المعامل الأول المُمرَّر إلى <code>check_box_tag</code>، بالطبع، هو اسم عنصر الإدخال. المعامل الثاني، بطبيعة الحال، هو قيمة العنصر. ستُشمَل هذه القيمة في بيانات الاستمارة (وتكون موجودة في <code>params</code>) عند اختيار (check) مربع الاختيار. |
==== أزرار الانتقاء ==== | ==== أزرار الانتقاء ==== | ||
سطر 103: | سطر 105: | ||
=== مساعدون آخرون مهمون === | === مساعدون آخرون مهمون === | ||
− | عناصر التحكم الأخرى | + | عناصر التحكم الأخرى بالاستمارة الجديرة بالذكر هي [[HTML/textarea|مربع نصي متعدد الأسطر]]، و<nowiki/>[[HTML/input/password|حقول كلمة المرور]]، و<nowiki/>[[HTML/input/hidden|الحقول المخفية]]، و<nowiki/>[[HTML/input/search|حقول البحث]]، و<nowiki/>[[HTML/input/tel|حقول رقم الهاتف]]، و<nowiki/>[[HTML/input/date|حقول التاريخ]]، و<nowiki/>[[HTML/input/time|حقول الوقت]]، و<nowiki/>[[HTML/input/color|حقول اللون]]، و<nowiki/>[[HTML/input/datetime-local|حقول التوقيت المحلي]]، و<nowiki/>[[HTML/input/month|حقول الشهر]]، و<nowiki/>[[HTML/input/week|حقول الأسبوع]]، و<nowiki/>[[HTML/input/url|حقول عنوان URL]]، و<nowiki/>[[HTML/input/email|حقول البريد الإلكتروني]]، و<nowiki/>[[HTML/input/number|حقول الأرقام]] و<nowiki/>[[HTML/input/range|حقول المجالات]]:<syntaxhighlight lang="html"> |
<%= text_area_tag(:message, "Hi, nice site", size: "24x6") %> | <%= text_area_tag(:message, "Hi, nice site", size: "24x6") %> | ||
<%= password_field_tag(:password) %> | <%= password_field_tag(:password) %> | ||
سطر 138: | سطر 140: | ||
</syntaxhighlight>لا يتم عرض المدخلات المخفية للمستخدم ولكن بدلًا من ذلك يحتفظ بالبيانات مثل أي إدخال نصي. يمكن تغيير القيم الموجودة داخلها باستخدام جافاسكربت. | </syntaxhighlight>لا يتم عرض المدخلات المخفية للمستخدم ولكن بدلًا من ذلك يحتفظ بالبيانات مثل أي إدخال نصي. يمكن تغيير القيم الموجودة داخلها باستخدام جافاسكربت. | ||
− | '''تحذير''': حقول [[HTML/input/search|البحث]]، و<nowiki/>[[HTML/input/tel|رقم الهاتف]]، و<nowiki/>[[HTML/input/date|التاريخ]]، و<nowiki/>[[HTML/input/time|الوقت]]، و<nowiki/>[[HTML/input/color|اللون]]، و<nowiki/>[[HTML/input/datetime-local|التاريخ والوقت المحلي]]، و<nowiki/>[[HTML/input/month|الشهر]]، و<nowiki/>[[HTML/input/week|الأسبوع]]، و<nowiki/>[[HTML/input/url|عنوان URL]]، و<nowiki/>[[HTML/input/email|البريد الإلكتروني]]، و<nowiki/>[[HTML/input/number|العدد]] و<nowiki/>[[HTML/input/range|نطاق المدخلات]] | + | '''تحذير''': حقول [[HTML/input/search|البحث]]، و<nowiki/>[[HTML/input/tel|رقم الهاتف]]، و<nowiki/>[[HTML/input/date|التاريخ]]، و<nowiki/>[[HTML/input/time|الوقت]]، و<nowiki/>[[HTML/input/color|اللون]]، و<nowiki/>[[HTML/input/datetime-local|التاريخ والوقت المحلي]]، و<nowiki/>[[HTML/input/month|الشهر]]، و<nowiki/>[[HTML/input/week|الأسبوع]]، و<nowiki/>[[HTML/input/url|عنوان URL]]، و<nowiki/>[[HTML/input/email|البريد الإلكتروني]]، و<nowiki/>[[HTML/input/number|العدد]] و<nowiki/>[[HTML/input/range|نطاق المدخلات]] هي عناصر تحكم أوجدت في HTML5. إذا كنت ترغب في أن يتوافق تطبيق مع المتصفحات القديمة، فستحتاج إلى استعمال تقنية "الترقيع المتعدد" (polyfill، توفرها [[CSS]] بمفردها أو مع [[JavaScript|جافاسكربت]]). من المؤكد أنه [https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills لا يوجد نقص في الحلول لذلك]، على الرغم من أن الطريقة الشائعة في الوقت الحالي هي [https://modernizr.com/ Modernizr]، والتي توفر طريقة بسيطة لإضافة وظائف تعتمد على وجود ميزات HTML5 المكتشفة. |
'''تنويه''': إذا كنت تستخدم حقول إدخال كلمة المرور (لأي غرض)، فقد ترغب في ضبط تطبيقك لمنع قراءة وتسجيل مثل هذه المعاملات. يمكنك تعلم ذلك في دليل [[Rails/security|تأمين تطبيقات ريلز]]. | '''تنويه''': إذا كنت تستخدم حقول إدخال كلمة المرور (لأي غرض)، فقد ترغب في ضبط تطبيقك لمنع قراءة وتسجيل مثل هذه المعاملات. يمكنك تعلم ذلك في دليل [[Rails/security|تأمين تطبيقات ريلز]]. | ||
− | == التعامل مع كائنات النموذج | + | == التعامل مع كائنات النموذج == |
− | === مساعدو كائن النموذج | + | === مساعدو كائن النموذج === |
− | من المهام الشائعة الخاصة | + | من المهام الشائعة الخاصة بالاستمارة هو تعديل أو إنشاء كائن نموذج (Model Object). على الرغم من إمكانية استخدام المساعدين <code>tag_*</code> لأداء هذه المهمة، إلا أنه حل طويل ومضجر بعض الشيء، إذ يجب لكل وسم التأكد من استخدام اسم المعامل الصحيح وتعيين القيمة الافتراضية لعنصر الإدخال بشكل مناسب. يوفر ريلز مساعدين مصممين خصيصًا لهذه المهمة. هؤلاء المساعدون يفتقرون إلى اللاحقة <code>tag_</code>، مثل <code>text_field</code> و <code>text_area</code>. |
بالنسبة إلى هؤلاء المساعدين، يكون المعامل الأول هو اسم متغير نسخة والثاني هو اسم تابع (عادةً خاصية) لاستدعائه مع ذلك الكائن. سيعين ريلز قيمة [[HTML/input|عنصر الإدخال]] إلى القيمة التي يعيدها ذلك التابع للكائن ثم سيعيِّن اسمًا مناسبًا للعنصر. إذا كان المتحكم الخاصة بك قد عرَّف <code>@person</code> واسم ذلك الشخص هو "هنري" (Henry) مثلًا، فإن النموذج الذي يحتوي على:<syntaxhighlight lang="html"> | بالنسبة إلى هؤلاء المساعدين، يكون المعامل الأول هو اسم متغير نسخة والثاني هو اسم تابع (عادةً خاصية) لاستدعائه مع ذلك الكائن. سيعين ريلز قيمة [[HTML/input|عنصر الإدخال]] إلى القيمة التي يعيدها ذلك التابع للكائن ثم سيعيِّن اسمًا مناسبًا للعنصر. إذا كان المتحكم الخاصة بك قد عرَّف <code>@person</code> واسم ذلك الشخص هو "هنري" (Henry) مثلًا، فإن النموذج الذي يحتوي على:<syntaxhighlight lang="html"> | ||
سطر 151: | سطر 153: | ||
</syntaxhighlight>سيولد مخرجات شبيه بالمخرجات التالية:<syntaxhighlight lang="html"> | </syntaxhighlight>سيولد مخرجات شبيه بالمخرجات التالية:<syntaxhighlight lang="html"> | ||
<input id="person_name" name="person[name]" type="text" value="Henry"/> | <input id="person_name" name="person[name]" type="text" value="Henry"/> | ||
− | </syntaxhighlight>عند إرسال | + | </syntaxhighlight>عند إرسال الاستمارة، ستُخَزَّن القيمة التي أدخلها المستخدم في <code>[params[:person][:name</code>. إنَّ <code>params[:person]</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code> مناسبٌ لتمريره إلى <code>Person.new</code>، أو إلى <code>@person.update</code> إذا كان <code>person@</code> نسخةً من <code>Person</code>. في حين أن اسم الخاصية يستعمل بشكل شائع مع المعامل الثاني المُمرَّر إلى هؤلاء المساعدين، فهذا ليس إلزاميًا. في المثال أعلاه، طالما أنَّ الكائنات <code>person</code> لها اسم (name) وتابع <code>name=</code>، فإن ريلز ستكون سعيدة. |
'''تحذير''': يجب عليك تمرير اسم متغير نسخة، أي <code>:person</code> أو <code>"person"</code>، وليس نسخةً فعلية لكائن النموذج (model object) الخاص بك. | '''تحذير''': يجب عليك تمرير اسم متغير نسخة، أي <code>:person</code> أو <code>"person"</code>، وليس نسخةً فعلية لكائن النموذج (model object) الخاص بك. | ||
سطر 158: | سطر 160: | ||
=== ربط نموذج بكائن === | === ربط نموذج بكائن === | ||
− | صحيح أن هذا مريحٌ أكثر إلا أنه ليس السلوك المثالي. إذا كان لدى <code>Person</code> العديد من الخاصيات المراد تعديلها، فسنكرر حينئذٍ اسم الكائن المعدَّل عدة مرات. ما نريد القيام به هو ربط | + | صحيح أن هذا مريحٌ أكثر إلا أنه ليس السلوك المثالي. إذا كان لدى <code>Person</code> العديد من الخاصيات المراد تعديلها، فسنكرر حينئذٍ اسم الكائن المعدَّل عدة مرات. ما نريد القيام به هو ربط استمارة بكائن نموذج، وهو ما يفعله <code>form_for</code> بالضبط. |
افترض أنَّه لدينا متحكم للتعامل مع المقالات في الملف app/controllers/articles_controller.rb:<syntaxhighlight lang="html"> | افترض أنَّه لدينا متحكم للتعامل مع المقالات في الملف app/controllers/articles_controller.rb:<syntaxhighlight lang="html"> | ||
سطر 172: | سطر 174: | ||
</syntaxhighlight>هناك بعض الأشياء التي يجب ملاحظتها هنا: | </syntaxhighlight>هناك بعض الأشياء التي يجب ملاحظتها هنا: | ||
* <code>@article</code> هو الكائن الفعلي الذي يجري تعديله. | * <code>@article</code> هو الكائن الفعلي الذي يجري تعديله. | ||
− | * هناك [[Ruby/Hash|جدول Hash]] واحد من الخيارات. تُمرر خيارات التوجيه في <code>:url</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code>، وتُمرر خيارات [[HTML]] في <code>:html</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code>. كما يمكنك توفير الخيار <code>:namespace</code> لنموذجك لضمان كون الخاصيات id فريدة في عناصر | + | * هناك [[Ruby/Hash|جدول Hash]] واحد من الخيارات. تُمرر خيارات التوجيه في <code>:url</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code>، وتُمرر خيارات [[HTML]] في <code>:html</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code>. كما يمكنك توفير الخيار <code>:namespace</code> لنموذجك لضمان كون الخاصيات id فريدة في عناصر الاستمارة. ستضاف شرطة سفلية بادئة للخاصية <code>namespace</code> في الخاصيات <code>id</code> في شيفرة HTML المولدة. |
− | * تنتج الدالة <code>form_for</code> كائنًا بانيًا | + | * تنتج الدالة <code>form_for</code> كائنًا بانيًا للاستمارة (المتغير <code>f</code>). |
− | * تُستدعَى توابع إنشاء عناصر التحكم | + | * تُستدعَى توابع إنشاء عناصر التحكم بالاستمارة في كائن باني النموذج <code>f</code>. |
شيفرة HTML الناتجة هي:<syntaxhighlight lang="html"> | شيفرة HTML الناتجة هي:<syntaxhighlight lang="html"> | ||
<form class="nifty_form" id="new_article" action="/articles" accept-charset="UTF-8" method="post"> | <form class="nifty_form" id="new_article" action="/articles" accept-charset="UTF-8" method="post"> | ||
سطر 183: | سطر 185: | ||
<input type="submit" name="commit" value="Create" data-disable-with="Create" /> | <input type="submit" name="commit" value="Create" data-disable-with="Create" /> | ||
</form> | </form> | ||
− | </syntaxhighlight>الاسم الذي مُرِّر إلى <code>form_for</code> يتحكم في المفتاح المستخدم في <code>params</code> للوصول إلى قيم | + | </syntaxhighlight>الاسم الذي مُرِّر إلى <code>form_for</code> يتحكم في المفتاح المستخدم في <code>params</code> للوصول إلى قيم الاستمارة. الاسم في حالتنا هذه هو <code>article</code> وحتى كل عناصر الإدخال لها الأسماء <code>article[attribute_name]</code> الخاصة بالنموذج. وبناءً على ذلك، ستكون <code>params[:article]</code> في الإجراء <code>create</code> جدول <code>[[Ruby/Hash|Hash]]</code> يحوي المفتاح <code>title:</code> و <code>body:</code>. يمكنك قراءة المزيد حول أهمية أسماء عناصر الإدخال في القسم "[[Rails/form helpers#.D9.81.D9.87.D9.85 .D8.A7.D9.84.D8.B9.D8.B1.D9.81 .D8.A7.D9.84.D9.85.D8.AA.D8.A8.D8.B9 .D9.81.D9.8A .D8.AA.D8.B3.D9.85.D9.8A.D8.A9 .D8.A7.D9.84.D9.85.D8.B9.D8.A7.D9.85.D9.84.D8.A7.D8.AA|فهم العرف المتبع في تسمة المعاملات]]". |
− | توابع المساعد التي تستدعى مع باني النموذج تتشابه مع مساعدي كائن النموذج (model object) باستثناء أنه ليس من الضروري تحديد أي كائن يُعَدَّل لأن ذلك يُدار بالفعل بواسطة باني | + | توابع المساعد التي تستدعى مع باني النموذج تتشابه مع مساعدي كائن النموذج (model object) باستثناء أنه ليس من الضروري تحديد أي كائن يُعَدَّل لأن ذلك يُدار بالفعل بواسطة باني الاستمارة. |
− | يمكنك إنشاء ربط مشابه بدون إنشاء الوسوم <code>[[HTML/form|<form>]]</code> بالفعل مع المساعد <code>field_for</code>. هذا مفيد لتعديل كائنات نموذج إضافي (additional model objects) مع نفس | + | يمكنك إنشاء ربط مشابه بدون إنشاء الوسوم <code>[[HTML/form|<form>]]</code> بالفعل مع المساعد <code>field_for</code>. هذا مفيد لتعديل كائنات نموذج إضافي (additional model objects) مع نفس الاستمارة. على سبيل المثال، إذا كان لديك النموذج <code>Person</code> مع النموذج <code>ContactDetail</code> المرتبط، فيمكنك إنشاء استمارة لإنشاء كليهما بالشكل التالي:<syntaxhighlight lang="html"> |
<%= form_for @person, url: {action: "create"} do |person_form| %> | <%= form_for @person, url: {action: "create"} do |person_form| %> | ||
<%= person_form.text_field :name %> | <%= person_form.text_field :name %> | ||
سطر 204: | سطر 206: | ||
=== الاعتماد على تعريف السجل === | === الاعتماد على تعريف السجل === | ||
− | النموذج <code>Article</code> | + | النموذج <code>Article</code> متاح مباشرة لمستخدمي التطبيق، لذلك - ولاتباع أفضل ممارسات التطوير مع ريلز - يجب عليك أن تصرِّح على أنه مورد (resource):<syntaxhighlight lang="rails"> |
resources :articles | resources :articles | ||
</syntaxhighlight>'''تنبيه''': التصريح عن مورد له عدد من الآثار الجانبية. اطلع على قسم [[Rails/routing#.D8.AA.D9.88.D8.AC.D9.8A.D9.87 .D8.A7.D9.84.D9.85.D9.88.D8.B1.D8.AF: .D8.A7.D9.84.D8.A7.D9.81.D8.AA.D8.B1.D8.A7.D8.B6.D9.8A .D9.81.D9.8A .D8.B1.D9.8A.D9.84.D8.B2|توجيه المورد في دليل التوجيه]] لمزيد من المعلومات حول إعداد الموارد واستخدامها. | </syntaxhighlight>'''تنبيه''': التصريح عن مورد له عدد من الآثار الجانبية. اطلع على قسم [[Rails/routing#.D8.AA.D9.88.D8.AC.D9.8A.D9.87 .D8.A7.D9.84.D9.85.D9.88.D8.B1.D8.AF: .D8.A7.D9.84.D8.A7.D9.81.D8.AA.D8.B1.D8.A7.D8.B6.D9.8A .D9.81.D9.8A .D8.B1.D9.8A.D9.84.D8.B2|توجيه المورد في دليل التوجيه]] لمزيد من المعلومات حول إعداد الموارد واستخدامها. | ||
− | عند التعامل مع موارد RESTful، يمكن أن تصبح استدعاءات <code>form_for</code> أسهل بكثير إذا كنت تعتمد على تعريف السجل. باختصار، يمكنك فقط تمرير نسخة النموذج (model) وترك الباقي على ريلز مثل اكتشاف اسم النموذج | + | عند التعامل مع موارد RESTful، يمكن أن تصبح استدعاءات <code>form_for</code> أسهل بكثير إذا كنت تعتمد على تعريف السجل. باختصار، يمكنك فقط تمرير نسخة النموذج (model) وترك الباقي على ريلز مثل اكتشاف اسم النموذج:<syntaxhighlight lang="rails"> |
## إنشاء مقالة جديدة | ## إنشاء مقالة جديدة | ||
# نمط طويل | # نمط طويل | ||
سطر 220: | سطر 222: | ||
# نمط قصير | # نمط قصير | ||
form_for(@article) | form_for(@article) | ||
− | </syntaxhighlight>لاحظ كيف أن النمط القصير لاستدعاء <code>form_for</code> يؤدي نفس الغرض الذي يفعله استدعاء التابع نفسه في النمط الطويل، بغض النظر عن كون السجل جديدًا أو موجودًا. تعريف السجل ذكي بما فيه الكفاية لمعرفة ما إذا كان السجل جديدًا عبر استدعاء <code>?record.new_record</code>. كما أنه يحدد المسار الصحيح لإرسال | + | </syntaxhighlight>لاحظ كيف أن النمط القصير لاستدعاء <code>form_for</code> يؤدي نفس الغرض الذي يفعله استدعاء التابع نفسه في النمط الطويل، بغض النظر عن كون السجل جديدًا أو موجودًا. تعريف السجل ذكي بما فيه الكفاية لمعرفة ما إذا كان السجل جديدًا عبر استدعاء <code>?record.new_record</code>. كما أنه يحدد المسار الصحيح لإرسال الاستمارة إليه والاسم استنادًا على صنف الكائن. |
− | سيعيّن ريلز أيضًا الصنف <code>class</code> والمعرف <code>id</code> للنموذج تلقائيًا بشكل مناسب: | + | سيعيّن ريلز أيضًا الصنف <code>class</code> والمعرف <code>id</code> للنموذج تلقائيًا بشكل مناسب: الاستمارة التي تنشئ مقالًا سيكون لها الصنف والمعرف <code>new_article</code>. إذا كنت تعدل مقالة ذات المعرف 23، فسيُعيَّن الصنف إلى <code>edit_article</code> والمعرف إلى <code>edit_article_23</code>. سيتم حذف هاتين الخاصيتين للإختصار في بقية هذا الدليل. |
− | '''تحذير''': عندما تستخدم STI ([[Rails/association basics#.D9.88.D8.B1.D8.A7.D8.AB.D8.A9 .D8.A7.D9.84.D8.AC.D8.AF.D9.88.D9.84 .D8.A7.D9.84.D9.88.D8.AD.D9.8A.D8.AF|وراثة الجدول الوحيد]]) مع نماذجك (models)، فلا يمكنك الاعتماد على تعريف السجل في صنف فرعي بمجرد التصريح عن الصنف الأب بأنه موردٌ. سيتعين عليك حينئذٍ تحديد اسم | + | '''تحذير''': عندما تستخدم STI ([[Rails/association basics#.D9.88.D8.B1.D8.A7.D8.AB.D8.A9 .D8.A7.D9.84.D8.AC.D8.AF.D9.88.D9.84 .D8.A7.D9.84.D9.88.D8.AD.D9.8A.D8.AF|وراثة الجدول الوحيد]]) مع نماذجك (models)، فلا يمكنك الاعتماد على تعريف السجل في صنف فرعي بمجرد التصريح عن الصنف الأب بأنه موردٌ. سيتعين عليك حينئذٍ تحديد اسم الاستمارة مع الخيارين <code>:url</code> و <code>:method</code> بشكل صريح. |
==== التعامل مع مجالات الأسماء ==== | ==== التعامل مع مجالات الأسماء ==== | ||
إذا أنشئت [[Rails/routing|مسارات توجيه]] ضمن مجالات أسماء (namespaced routes)، فإن <code>form_for</code> يحتوي على اختصار أنيق لذلك أيضًا. إذا كان تطبيقك يحتوي على مجال الاسم <code>admin</code>، فالسطر التالي:<syntaxhighlight lang="rails"> | إذا أنشئت [[Rails/routing|مسارات توجيه]] ضمن مجالات أسماء (namespaced routes)، فإن <code>form_for</code> يحتوي على اختصار أنيق لذلك أيضًا. إذا كان تطبيقك يحتوي على مجال الاسم <code>admin</code>، فالسطر التالي:<syntaxhighlight lang="rails"> | ||
form_for [:admin, @article] | form_for [:admin, @article] | ||
− | </syntaxhighlight>سينشئ | + | </syntaxhighlight>سينشئ استمارةً تُرسَل إلى <code>ArticleController</code> داخل مجال الاسم <code>admin</code> (يرسل إلى <code>admin_article_path(@article)</code> في حالة التحديث). إذا كان لديك عدة مستويات من مجالات الأسماء، فستكون الصياغة مشابهة لما سبق:<syntaxhighlight lang="rails"> |
form_for [:admin, :management, @article] | form_for [:admin, :management, @article] | ||
</syntaxhighlight>لمزيد من المعلومات حول توجيه المسارات في ريلز وكل ما يتعلق به، يرجى الاطلاع على [[Rails/routing|دليل التوجيه]]. | </syntaxhighlight>لمزيد من المعلومات حول توجيه المسارات في ريلز وكل ما يتعلق به، يرجى الاطلاع على [[Rails/routing|دليل التوجيه]]. | ||
=== كيف تعمل النماذج مع الطرائق PATCH أو PUT أو DELETE؟ === | === كيف تعمل النماذج مع الطرائق PATCH أو PUT أو DELETE؟ === | ||
− | يشجع إطار ريلز تصميم RESTful لتطبيقاتك، مما يعني أنك ستجعل الكثير من طلبات HTTP عبر الطريقة "PATCH" و "DELETE" (إلى جانب "GET" و "POST"). ومع ذلك، لا تدعم معظم المتصفحات طرائقَ أخرى غير "GET" و "POST" عندما يتعلق الأمر بإرسال | + | يشجع إطار ريلز تصميم RESTful لتطبيقاتك، مما يعني أنك ستجعل الكثير من طلبات HTTP عبر الطريقة "PATCH" و "DELETE" (إلى جانب "GET" و "POST"). ومع ذلك، لا تدعم معظم المتصفحات طرائقَ أخرى غير "GET" و "POST" عندما يتعلق الأمر بإرسال الاستمارات. |
تعمل ريلز حول هذه المشكلة بمحاكاة طرائق أخرى عبر POST باستخدام عنصر إدخال مخفي يسمى "method_"، والذي يعيَّن ليعكس الطريقة المطلوبة:<syntaxhighlight lang="html"> | تعمل ريلز حول هذه المشكلة بمحاكاة طرائق أخرى عبر POST باستخدام عنصر إدخال مخفي يسمى "method_"، والذي يعيَّن ليعكس الطريقة المطلوبة:<syntaxhighlight lang="html"> | ||
سطر 248: | سطر 250: | ||
== إنشاء مربعات اختيار بسهولة == | == إنشاء مربعات اختيار بسهولة == | ||
− | تتطلب [[HTML/input/checkbox|مربعات الاختيار]] في [[HTML]] | + | تتطلب [[HTML/input/checkbox|مربعات الاختيار]] في [[HTML]] كتابة مقدار لا بأس به من الشيفرة (عنصر <code>[[HTML/option|<option>]]</code> واحد لكل خيار للاختيار من بينها)، لذلك يكون من المنطقي جدًا أن يُنشَئ ديناميكيًا. |
هذا ما ستبدو الشيفرة عليه:<syntaxhighlight lang="html"> | هذا ما ستبدو الشيفرة عليه:<syntaxhighlight lang="html"> | ||
سطر 285: | سطر 287: | ||
</syntaxhighlight>عندما يرى ريلز أن القيمة الداخلية للخيار المراد إنشاؤه تطابق هذه القيمة، فإنها ستضيف الخاصية <code>selected</code> إلى ذلك الخيار لتحديده. | </syntaxhighlight>عندما يرى ريلز أن القيمة الداخلية للخيار المراد إنشاؤه تطابق هذه القيمة، فإنها ستضيف الخاصية <code>selected</code> إلى ذلك الخيار لتحديده. | ||
− | '''تحذير''': عندما ينعدم الخيار <code>include_blank:</code> أو <code>prompt:</code>، فستعين قيمة <code>include_blank:</code> إلى القيمة <code>true</code> إذا كانت | + | '''تحذير''': عندما ينعدم الخيار <code>include_blank:</code> أو <code>prompt:</code>، فستعين قيمة <code>include_blank:</code> إلى القيمة <code>true</code> إذا كانت قيمة الخاصية <code>[[HTML/select#required|required]]</code> هي <code>true</code>، والخاصية <code>[[HTML/select#size|size]]</code> هي 1،والخاصية <code>[[HTML/select#multiple|multiple]]</code> ليست <code>true</code>. |
يمكنك إضافة خاصيات عشوائية إلى الخيارات باستخدام جدول <code>[[Ruby/Hash|Hash]]</code>:<syntaxhighlight lang="html"> | يمكنك إضافة خاصيات عشوائية إلى الخيارات باستخدام جدول <code>[[Ruby/Hash|Hash]]</code>:<syntaxhighlight lang="html"> | ||
سطر 298: | سطر 300: | ||
<option value="2" selected="selected" data-size="3.2 million">Madrid</option> | <option value="2" selected="selected" data-size="3.2 million">Madrid</option> | ||
... | ... | ||
− | </syntaxhighlight> | + | </syntaxhighlight> |
− | في معظم | + | === اختيار الخيارات للتعامل مع النماذج === |
− | #controller: | + | في معظم الحالات، تكون عناصر التحكم في الاستمارة مرتبطة بنموذج قاعدة بيانات محدد، وكما قد تتوقع أن توفر ريلز مساعدات مصممة خصيصًا لهذا الغرض. بما يتفق مع المساعدين الآخرين في الاستمارة، عند التعامل مع النماذج، تسقط اللاحقة <code>tag_</code> من <code>select_tag</code>:<syntaxhighlight lang="rails"> |
+ | # controller: | ||
@person = Person.new(city_id: 2) | @person = Person.new(city_id: 2) | ||
− | #view: | + | |
+ | </syntaxhighlight><syntaxhighlight lang="rails"> | ||
+ | # view: | ||
<%= select(:person, :city_id, [['Lisbon', 1], ['Madrid', 2], ...]) %> | <%= select(:person, :city_id, [['Lisbon', 1], ['Madrid', 2], ...]) %> | ||
+ | </syntaxhighlight>لاحظ أن المعامل الثالث، مصفوفة الخيارات، هو نفس نوع الوسيط المُمرَّر إلى <code>options_for_select</code>. ميزة واحدة هنا هي أنه لا داعي للقلق بشأن التحديد المسبق للمدينة الصحيحة إذا كانت مدينة المستخدم معروفة مسبقًا. ريلز سيقوم بذلك نيابة عنك من خلال القراءة من الخاصية <code>person.city_id@</code>. | ||
− | + | كما هو الحال مع المساعدين الآخرين، إذا كنت ستستخدم المساعد <code>select</code> في أداة إنشاء الاستمارات التي حُدِّدَ نطاقها إلى الكائن <code>@person</code>، فستكون الصياغة كالتالي:<syntaxhighlight lang="rails"> | |
− | + | # select on a form builder | |
− | كما هو الحال مع المساعدين الآخرين، إذا كنت ستستخدم المساعد | ||
− | #select on a form builder | ||
<%= f.select(:city_id, ...) %> | <%= f.select(:city_id, ...) %> | ||
− | + | </syntaxhighlight>يمكنك أيضًا تمرير كتلة إلى المساعد <code>select</code>:<syntaxhighlight lang="html"> | |
− | يمكنك أيضًا تمرير | ||
− | |||
<%= f.select(:city_id) do %> | <%= f.select(:city_id) do %> | ||
− | + | <% [['Lisbon', 1], ['Madrid', 2]].each do |c| -%> | |
− | + | <%= content_tag(:option, c.first, value: c.last) %> | |
− | + | <% end %> | |
− | |||
− | |||
− | |||
− | |||
<% end %> | <% end %> | ||
+ | </syntaxhighlight>'''تحذير''': إذا كنت تستخدم <code>select</code> (أو مساعدين مشابهين له مثل <code>collection_select</code>، أو <code>select_tag</code>) لتعيين [[Rails/association basics#.D8.A7.D8.B1.D8.AA.D8.A8.D8.A7.D8.B7 .D8.A7.D9.84.D8.A7.D9.86.D8.AA.D9.85.D8.A7.D8.A1 .28belongs to.29|الارتباط <code>belongs_to</code>]]، فيجب عليك تمرير اسم المفتاح الخارجي (هو <code>city_id</code> في المثال أعلاه)، وليس اسم الارتباط نفسه. إذا قمت بتحديد <code>city</code> بدلًا من <code>city_id</code> فسيرمي السجل الفعال الخطأ:<syntaxhighlight lang="text"> | ||
+ | ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) | ||
+ | </syntaxhighlight>عند تمرير <code>params</code> إلى <code>Person.new</code> أو <code>update</code>. طريقة أخرى للتعامل مع هذا هي أن مساعدي الاستمارة تعدل الخاصيات. يجب أيضًا أن تكون على دراية بتداعيات الأمان المحتملة الخاصة بالسماح للمستخدمين بتعديل المفاتيح الخارجية مباشرةً. | ||
− | + | === الوسوم <code>[[HTML/option|<option>]]</code> من مجموعة من كائنات اعتباطية === | |
− | + | يتطلب توليد الوسوم <code>[[HTML/option|<option>]]</code> باستخدام المساعد <code>options_for_select</code> إنشاء مصفوفة تحتوي على [[HTML/option#label|النص]] و<nowiki/>[[HTML/option#value|القيمة]] لكل خيار. ولكن ماذا لو كان لديك نموذجًا مثل النموذج <code>City</code> (ربما أحد [[Rails/active record basics|السجلات الفعالة]]) وكنت تريد توليد وسوم <code>[[HTML/option|<option>]]</code> من مجموعة من تلك الكائنات؟ قد يكون أحد الحلول هو إنشاء مصفوفة متشعبة منهم:<syntaxhighlight lang="html"> | |
− | == | ||
− | يتطلب | ||
− | |||
<% cities_array = City.all.map { |city| [city.name, city.id] } %> | <% cities_array = City.all.map { |city| [city.name, city.id] } %> | ||
− | |||
<%= options_for_select(cities_array) %> | <%= options_for_select(cities_array) %> | ||
− | + | </syntaxhighlight>هذا حل صالح تمامًا، ولكن ريلز يوفر بديلًا أسهل وأوضح وذلك عبر المساعد <code>options_from_collection_for_select</code>. يتوقع هذا المساعد تمرير مجموعة من الكائنات العشوائية إليه بالإضافة إلى وسيطين آخرين هما: أسماء الدوال لقراءة قيمة ونص الخيار على التوالي:<syntaxhighlight lang="html"> | |
− | هذا حل صالح تمامًا، ولكن ريلز يوفر | ||
− | |||
<%= options_from_collection_for_select(City.all, :id, :name) %> | <%= options_from_collection_for_select(City.all, :id, :name) %> | ||
− | + | </syntaxhighlight>كما يوحي الاسم، هذا يولد فقط الوسوم <code>[[HTML/option|<option>]]</code>. لتوليد مربع تحديد كامل، ستحتاج إلى استخدامه بالتزامن مع المساعد <code>select_tag</code>، تمامًا كما تفعل مع <code>options_for_select</code>. عند العمل مع كائنات النموذج، تمامًا مثلما يجمع <code>select</code> بين <code>select_tag</code> و <code>options_for_select</code>، يجمع <code>collection_select</code> بين <code>select_tag</code> و <code>options_from_collection_for_select</code>.<syntaxhighlight lang="rails"> | |
− | كما يوحي الاسم، هذا يولد فقط | ||
− | |||
<%= collection_select(:person, :city_id, City.all, :id, :name) %> | <%= collection_select(:person, :city_id, City.all, :id, :name) %> | ||
− | كما هو الحال مع المساعدين الآخرين، إذا كنت ستستخدم المساعد collection_select على | + | </syntaxhighlight>كما هو الحال مع المساعدين الآخرين، إذا كنت ستستخدم المساعد <code>collection_select</code> على باني الاستمارة حُدّدت إلى الكائن <code>person@</code>، فستكون الصياغة بالشكل التالي:<syntaxhighlight lang="html"> |
− | + | <%= f.collection_select(:city_id, City.all, :id, :name) %> | |
− | <%= f.collection_select(:city_id, City.all, :id, :name) %> | + | </syntaxhighlight>'''ملاحظة''': يجب أن تملك الأزواج التي مُرِّرَتْ إلى <code>options_for_select</code> اسمًا أولًا ومُعرِّفًا ثانيًا، ولكن مع <code>options_from_collection_for_select</code> الوسيط الأول هو التابع <code>value</code> والثاني هو التابع <code>text</code>. |
− | |||
− | |||
− | |||
− | ملاحظة: يجب أن | ||
− | |||
− | |||
− | |||
− | |||
− | < | ||
− | |||
− | |||
− | |||
− | |||
− | = | + | === اختيار المنطقة الزمنية والبلد === |
− | + | للاستفادة من دعم المنطقة الزمنية في ريلز، يجب عليك أن تسأل المستخدمين عن المنطقة الزمنية الموجودين فيها. سيتطلب القيام بذلك توليد خيارات تحديد من قائمة كائنات معرفة سابقًا من النوع <code>TimeZone</code> باستخدام <code>collection_select</code>، ولكن يمكنك ببساطة استخدام المساعد <code>time_zone_select</code> الذي يفعل لك ذلك:<syntaxhighlight lang="html"> | |
− | + | <%= time_zone_select(:person, :time_zone) %> | |
− | + | </syntaxhighlight>هناك أيضًا المساعد <code>time_zone_options_for_select</code> الذي يوفر طريقة يدوية للقيام بنفس الأمر وبالتالي يوفر قابلية للتخصيص. اقرأ [http://api.rubyonrails.org/v5.2.2/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-time_zone_options_for_select توثيق الواجهة البرمجية] للتعرف على الوسائط التي تمرَّر إلى هذين التابعين. | |
− | |||
− | + | اعتاد ريلز على احتوائه على المساعد <code>country_select</code> لتحديد بلد معين من بين مجموعة من البلدان، ولكن جمِّع ذلك في [https://github.com/stefanpenner/country_select الإضافة <code>country_select</code>]. عند استخدام هذه الإضافة، يجب أن تدرك أن استبعاد أو إدراج أسماء بلدان معينة من القائمة يمكن أن يكون خِلافِيًّا (وكان هذا هو السبب وراء استبعاد المساعد من ريلز وتحويله إلى إضافة). | |
− | |||
− | + | == استخدام حقول التاريخ والوقت في الاستمارة == | |
− | + | يمكنك اختيار عدم استخدام مساعدي الاستمارة الذين ينشؤون حقول HTML5 لإدخال التاريخ والوقت واستخدام مساعدي التاريخ والوقت البدلاء. يختلف مساعدو التاريخ والوقت هؤلاء عن جميع المساعدين الآخرين في ناحيتين مهمتين هما: | |
− | + | * لا يمكن تمثيل التواريخ والأوقات من خلال عنصر إدخال واحد فقط. بدلًا من ذلك لديك عدة عناصر، واحد لكل مكون (السنة، الشهر، اليوم، وما إلى ذلك) وبالتالي لا توجد قيمة واحدة في <code>params</code> الخاص بك تمثل التاريخ أو الوقت. | |
+ | * يستخدم المساعدون الآخرون اللاحقة <code>_tag</code> لتوضيح ما إذا كان المساعد مساعدًا مجردًا أو يعمل على كائنات نموذج. مع التواريخ والأوقات، المساعد <code>select_date</code> و <code>select_time</code> و <code>select_datetime</code> هم مساعدون مجردون، و <code>date_select</code>، و <code>time_select</code> و <code>datetime_select</code> هم مساعدو كائنات نموذج مكافئة. | ||
+ | ستُنشِئ كلا هاتين العائلتين من المساعدين سلسلة من مربعات الاختيار للعناصر المختلفة (السنة، الشهر، اليوم، ...إلخ). | ||
+ | === المساعدون المجردون === | ||
+ | تأخذ مجموعة المساعدين <code>select_*</code> كوسيطهم الأول نسخة من <code>Date</code> أو <code>Time</code> أو <code>DateTime</code> التي تُستخدَم كقيمة محددة حاليًا. يمكنك حذف هذا المعامل، وفي هذه الحالة يُستخدم التاريخ الحالي. فمثلًا:<syntaxhighlight lang="rails"> | ||
+ | <%= select_date Date.today, prefix: :start_date %> | ||
+ | </syntaxhighlight>يولد (مع حذف قيم الخيار الفعلية للإيجاز):<syntaxhighlight lang="rails"> | ||
<select id="start_date_year" name="start_date[year]"> ... </select> | <select id="start_date_year" name="start_date[year]"> ... </select> | ||
− | |||
<select id="start_date_month" name="start_date[month]"> ... </select> | <select id="start_date_month" name="start_date[month]"> ... </select> | ||
− | |||
<select id="start_date_day" name="start_date[day]"> ... </select> | <select id="start_date_day" name="start_date[day]"> ... </select> | ||
− | + | </syntaxhighlight>تؤدي المدخلات الواردة أعلاه إلى ظهور <code>params[:start_date]</code> كجدول <code>[[Ruby/Hash|Hash]]</code> مع المفاتيح <code>year:</code>، و <code>month:</code>، و <code>day:</code>. للحصول على الكائن <code>Date</code> أو <code>Time</code> أو <code>DateTime</code>، يجب عليك استخراج هذه القيم وتمريرها إلى الباني المناسب مثل:<syntaxhighlight lang="rails"> | |
− | تؤدي | ||
− | |||
Date.civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, params[:start_date][:day].to_i) | Date.civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, params[:start_date][:day].to_i) | ||
− | الخيار:prefix هو المفتاح المستخدم | + | </syntaxhighlight>الخيار <code>:prefix</code> هو المفتاح المستخدم لاستعادة جدول <code>[[Ruby/Hash|Hash]]</code> لمكونات التاريخ من <code>params</code>. هنا، ضُبِط إلى <code>start_date</code>؛ إذا حُذِف، فسيُحدَد افتراضيَّا إلى <code>date</code>. |
− | |||
− | |||
− | |||
− | |||
− | < | ||
− | |||
− | |||
+ | === مساعدو كائن النموذج === | ||
+ | لا يعمل <code>select_date</code> بشكل جيد مع الاستمارات التي تحدِّث أو تنشئ كائنات [[Rails/active record basics|سجل فعال]] إذ يتوقع [[Rails/active record basics|السجل الفعال]] أن كل عنصر في <code>params</code> يقابل خاصية واحدة. يرسل مساعدو كائن النموذج (model object helpers) للتواريخ والأوقات المعاملات بأسماء خاصة؛ عندما يشاهد [[Rails/active record basics|السجل الفعال]] معاملات بأسماء من هذا القبيل، فإنه يعلم أنه يجب دمجها مع المعاملات الأخرى وإعطائها لبانٍ يتناسب مع نوع الحقل (العمود). فمثلا:<syntaxhighlight lang="html"> | ||
+ | <%= date_select :person, :birth_date %> | ||
+ | </syntaxhighlight>ينتج (مع حذف قيم الخيار الفعلية للإيجاز):<syntaxhighlight lang="html"> | ||
<select id="person_birth_date_1i" name="person[birth_date(1i)]"> ... </select> | <select id="person_birth_date_1i" name="person[birth_date(1i)]"> ... </select> | ||
− | |||
<select id="person_birth_date_2i" name="person[birth_date(2i)]"> ... </select> | <select id="person_birth_date_2i" name="person[birth_date(2i)]"> ... </select> | ||
− | |||
<select id="person_birth_date_3i" name="person[birth_date(3i)]"> ... </select> | <select id="person_birth_date_3i" name="person[birth_date(3i)]"> ... </select> | ||
+ | </syntaxhighlight>مما يؤدي إلى <code>params</code> مثل:<syntaxhighlight lang="json"> | ||
+ | {'person' => {'birth_date(1i)' => '2008', 'birth_date(2i)' => '11', 'birth_date(3i)' => '22'}} | ||
+ | </syntaxhighlight>عندما يُمرَّر هذا إلى <code>Person.new</code> (أو <code>update</code>)، يلاحظ السجل الفعَّال أنه يجب استخدام جميع هذه المعاملات لإنشاء الخاصية <code>birth_date</code> واستخدام المعلومات اللاحقة لتحديد الترتيب الذي يجب أن يمرر هذه المعاملات إلى دوال مثل <code>Date.civil</code>. | ||
− | + | === خيارات مشتركة === | |
− | + | تستخدم كلا عائلتي المساعدين نفس مجموعة الدوال الأساسية لتوليد وسوم <code>[[HTML/select|<select>]]</code> فردية، وبالتالي يقبل كلاهما نفس الخيارات إلى حد كبير. على وجه الخصوص، ستولد ريلز بشكل افتراضي في خيارات سنة 5 سنوات على جانبي السنة الحالية. إذا لم يكن هذا نطاقًا مناسبًا، فستتجاوز الخيارات <code>start_year:</code> و <code>end_year:</code> هذا. للحصول على قائمة شاملة بالخيارات المتاحة، ارجع إلى [http://api.rubyonrails.org/v5.2.2/classes/ActionView/Helpers/DateHelper.html توثيق الواجهة البرمجية]. | |
− | |||
− | |||
− | |||
− | |||
− | == | ||
− | تستخدم | ||
− | كقاعدة عامة، يجب أن تستخدم date_select عند العمل مع كائنات نموذج و select_date في حالات أخرى، مثل نموذج بحث يقوم بتصفية النتائج حسب التاريخ. | + | كقاعدة عامة، يجب أن تستخدم <code>date_select</code> عند العمل مع كائنات نموذج و <code>select_date</code> في حالات أخرى، مثل نموذج بحث يقوم بتصفية النتائج حسب التاريخ. |
− | ملاحظة: في العديد من الحالات، يكون ملتقطو التاريخ المدمجون غير متقنين لأنهم لا يساعدون المستخدم في تحديد العلاقة بين التاريخ واليوم من الأسبوع. | + | '''ملاحظة''': في العديد من الحالات، يكون ملتقطو التاريخ المدمجون غير متقنين لأنهم لا يساعدون المستخدم في تحديد العلاقة بين التاريخ واليوم من الأسبوع. |
− | == | + | === المكونات الفردية === |
تحتاج في بعض الأحيان إلى عرض مكون تاريخ واحد فقط مثل سنة أو شهر. يوفر ريلز سلسلة من المساعدين لهذا، واحد لكل مكون select_year ،select_month ،select_day ،select_hour ،select_minute ،select_second. هؤلاء المساعدين هي واضحة إلى حد ما. بشكل افتراضي، سينشئ حقل إدخال مسمى بعد مكون الوقت (على سبيل المثال، "year" لـselect_year، و "month" لـ select_month إلخ.) على الرغم من إمكانية تجاوز هذا الخيار: field_name. يعمل الخيار prefix: بالطريقة نفسها التي يعمل بها لـ select_date و select_time ولديه نفس القيمة الافتراضية. | تحتاج في بعض الأحيان إلى عرض مكون تاريخ واحد فقط مثل سنة أو شهر. يوفر ريلز سلسلة من المساعدين لهذا، واحد لكل مكون select_year ،select_month ،select_day ،select_hour ،select_minute ،select_second. هؤلاء المساعدين هي واضحة إلى حد ما. بشكل افتراضي، سينشئ حقل إدخال مسمى بعد مكون الوقت (على سبيل المثال، "year" لـselect_year، و "month" لـ select_month إلخ.) على الرغم من إمكانية تجاوز هذا الخيار: field_name. يعمل الخيار prefix: بالطريقة نفسها التي يعمل بها لـ select_date و select_time ولديه نفس القيمة الافتراضية. | ||
مراجعة 14:53، 29 يناير 2019
مساعدو الاستمارة في وحدة العرض في ريلز
تعتبر الاستمارات (forms) في تطبيقات الويب واجهة أساسية للتفاعل مع المستخدم وجلب بيانات منه. ومع ذلك، يمكن أن تصبح عملية إنشاء استمارةٍ وصيانتها عمليةً مملةً بسبب الحاجة إلى التحكم بالتسمية وبخاصياتها الكثيرة.
تخلَّص ريلز من هذا التعقيد بتوفير مساعدين للعرض لإنشاء الاستمارات بسهولة. ومع ذلك، بما أن للمساعدين حالات استخدام مختلفة، يحتاج المطورون إلى معرفة الاختلافات بين توابع كل مساعد قبل استخدامها.
بعد قراءة هذا الدليل، ستتعلم:
- كيفية إنشاء استمارات للبحث ونوع مماثل من الاستمارات العامة التي لا تمثل أي نموذج (model) محدد في تطبيقك.
- كيفية عمل استمارات مركزية النموذج (model-centric forms) لإنشاء وتعديل سجلات محددة في قاعدة بيانات.
- كيفية إنشاء مربعات اختيار من أنواع متعددة من البيانات.
- مساعدو التاريخ والوقت الذين يوفرهم ريلز.
- ما الذي يجعل نموذج تحميل الملف مختلفًا.
- كيفية نشر الاستمارات إلى الموارد الخارجية وتحديد الإعداد
authenticity_token
. - كيفية بناء استمارات معقدة.
ملاحظة: ليس المقصود من هذا الدليل أن يكون توثيقًا كاملًا لمساعدي الاستمارات المتاحة وكل ما يتعلق بها. يرجى زيارة توثيق الواجهة البرمجية لريلز للاطلاع على المرجع الكامل.
تنويه: استعملنا المصطلح "استمارة" ترجمةً للكلمة form، والمصطلح "نموذج" ترجمةً للكلمة model لكي لا يحدث لبسٌ بينهما، إذ تترجم form في كثير من الأحيان في الموسوعة إلى "نموذج". انتبه إلى أنَّ هذه الترجمة قد لا تُطبَّق على بقية توثيق ريلز.
التعامل مع الاستمارات الأساسية
مساعد الاستمارة الأساسي هو form_tag
.
<%= form_tag do %>
Form contents
<% end %>
عندما يستدعى بدون معاملات كما سبق، فإنه ينشئ الوسم <form>
والذي، عند إرساله، سيرسل الاستمارة عبر POST إلى الصفحة الحالية. على سبيل المثال، بافتراض أن الصفحة الحالية هي /home/index، ستبدو شيفرة HTML المولدة هي (أضيفت إليها بعض فواصل الأسطر لقابلية القراءة):
<form accept-charset="UTF-8" action="/" method="post">
<input name="utf8" type="hidden" value="✓" />
<input name="authenticity_token" type="hidden" value="J7CBxfHalt49OSHp27hblqK20c9PgwJ108nDHX/8Cts=" />
Form contents
</form>
ستلاحظ أن شيفرة HTML تحتوي على عنصر إدخال من النوع hidden
. هذا العنصر مهم، لأنه لا يمكن إرسال الاستمارة بنجاح بدونه. يجبر عنصر الإدخال المخفي ذو الاسم utf8 المتصفحات أن تراعي ترميز محارف هذه الاستمارة وأنه قد أُنشِئ لجميع الاستمارات سواء كانت طريقة الإرسال عبر "GET" أو "POST".
عنصر الإدخال الثاني ذو الاسم Authenticity_token
هو ميزة أمان في ريلز تسمى "حماية هجمات تزوير الطلب عبر الموقع" (cross-site request forgery protection)، يولده كل مساعد لكل استمارة لا ترسل عبر GET (بشرط تفعيل ميزة الأمان هذه). يمكنك قراءة المزيد حول هذا الأمر في دليل تأمين تطبيقات ريلز.
استمارة بحث عامة
إحدى الاستمارات الأساسية التي تراها على الويب هي استمارة البحث. تحتوي هذه الاستمارة على:
- عنصر استمارة يرسل عبر الطريقة "GET".
- عنصر تسمية لحقل الإدخال.
- عنصر إدخال نصي.
- عنصر إرسال.
لإنشاء هذه الاستمارة، سيُستخدَم المساعدين form_tag
و label_tag
و text_field_tag
و submit_tag
على التوالي كالتالي:
<%= form_tag("/search", method: "get") do %>
<%= label_tag(:q, "Search for:") %>
<%= text_field_tag(:q) %>
<%= submit_tag("Search") %>
<% end %>
سيولد هذا شيفرة HTML التالية:
<form accept-charset="UTF-8" action="/search" method="get">
<input name="utf8" type="hidden" value="✓" />
<label for="q">Search for:</label>
<input id="q" name="q" type="text" />
<input name="commit" type="submit" value="Search" />
</form>
تنويه: لكل عنصر إدخال للاستمارة، تُنشَئ الخاصية id
من اسمه ("q" في المثال أعلاه). يمكن أن تكون هذه المعرفات مفيدة جدًا لتنسيق العناصر عبر CSS أو معالجة عناصر تحكم الاستمارة باستخدام جافاسكربت.
بالإضافة إلى text_field_tag
و submit_tag
، يوجد مساعد مماثل لكل عنصر تحكم في HTML.
تحذير: استخدم دائمًا الطريقة "GET" لإرسال استمارات البحث. يتيح ذلك للمستخدمين وضع إشارة حفظ (bookmark) على بحث معين للعودة إليه لاحقًا. بشكل عام، يشجعك ريلز على استخدام طريقة HTTP المناسبة لأي إجراء.
استعمال جدول Hash
مع استدعائات مساعد الاستمارة
يقبل المساعد form_tag
تمرير وسيطين: مسار الإجراء وجدول Hash
يحوي الخيارات المتعلقة بالعملية. يحدد ذلك الجدول طريقة إرسال الاستمارة وخيارات HTML الأخرى مثل الصنف (الخاصية class
).
كما هو الحال مع المساعد link_to
، لا يتوجب أن يكون وسيط المسار سلسلة نصية فقط، بل يمكن أن يكون جدول Hash
من معاملات URL يمكن التعرف عليها من خلال آلية التوجيه في ريلز، والتي بدورها تحول الجدول إلى عنوان URL صالح. ومع ذلك، نظرًا لأن كلا المعاملين الممررين إلى form_tag
هما من النوع Hash
، يمكنك بسهولة أن تواجه مشكلة إذا كنت ترغب في استعمالهما مع بعضهما بعضًا. على سبيل المثال، دعنا نقول أنك كتبت الشيفرة التالية:
form_tag(controller: "people", action: "search", method: "get", class: "nifty_form")
# => '<form accept-charset="UTF-8" action="/people/search?method=get&class=nifty_form" method="post">'
هنا، يضاف method
و class
إلى سلسلة الاستعلام الخاصة بعنوان URL المُنشَأ لأنه حتى لو كنت تقصد كتابة جدولين من النوع Hash
، فأنت بذلك حددت واحدًا فقط. بناءً على ما سبق، عليك أن تخبر روبي أي الجدولين هو للمعامل الأول وأيهما للثاني وذلك عن طريق تغليف الجدول الأولى (أو كليهما) بالأقواس المعقوصة. سيؤدي هذا إلى إنشاء شيفرة HTML التي تريدها بالضبط:
form_tag({controller: "people", action: "search"}, method: "get", class: "nifty_form")
# => '<form accept-charset="UTF-8" action="/people/search" method="get" class="nifty_form">'
مساعدون لتوليد عناصر الاستمارة
يوفر ريلز سلسلة من المساعدين لتوليد مختلف عناصر الاستمارة مثل مربعات الاختيار وحقول نصية وأزرار الانتقاء. ينشئ هؤلاء المساعدون الأساسيون، مع أسماء تنتهي بـ _tag
(مثل text_field_tag
و check_box_tag
)، عنصر <input>
وحيد فقط. المعامل الأول المُمرَّر إليهم هو دائما اسم عنصر الإدخال. عند إرسال الاستمارة، سيُمرر الاسم مع بيانات الاستمارة، وسوف يشق طريقه إلى params
في المتحكم مرفقًا بالقيمة التي أدخلها المستخدم لهذا الحقل. على سبيل المثال، إذا كانت الاستمارة تحتوي على <%= text_field_tag(:query) %>
، فستتمكن من الحصول على قيمة هذا الحقل في المتحكم باستخدام params [: query]
.
عند تسمية المدخلات، يستخدم ريلز اصطلاحات معينة تجعل من الممكن إرسال المعاملات مع قيم غير أساسية (non-scalar values) مثل المصفوفات أو جداول Hash، والتي يمكن الوصول إليها أيضًا في params
. يمكنك قراءة المزيد عنها في الفصل السابع من هذا الدليل. للحصول على تفاصيل حول الاستخدام الدقيق لهؤلاء المساعدين، يرجى الرجوع إلى توثيق الواجهة البرمجية الكامل.
مربعات الاختيار
مربعات الاختيار هي عناصر تحكم في الاستمارة تمنح المستخدم مجموعة من الخيارات التي يمكن تمكينها أو تعطيلها:
<%= check_box_tag(:pet_dog) %>
<%= label_tag(:pet_dog, "I own a dog") %>
<%= check_box_tag(:pet_cat) %>
<%= label_tag(:pet_cat, "I own a cat") %>
هذا يولد ما يلي:
<input id="pet_dog" name="pet_dog" type="checkbox" value="1" />
<label for="pet_dog">I own a dog</label>
<input id="pet_cat" name="pet_cat" type="checkbox" value="1" />
<label for="pet_cat">I own a cat</label>
المعامل الأول المُمرَّر إلى check_box_tag
، بالطبع، هو اسم عنصر الإدخال. المعامل الثاني، بطبيعة الحال، هو قيمة العنصر. ستُشمَل هذه القيمة في بيانات الاستمارة (وتكون موجودة في params
) عند اختيار (check) مربع الاختيار.
أزرار الانتقاء
أزرار الانتقاء، على الرغم من تشابهها مع مربعات الاختيار، هي عناصر تحكم تحدد مجموعة من الخيارات لانتقاء أحدها فقط (أي أن المستخدم يمكنه اختيار خيار واحد فقط):
<%= radio_button_tag(:age, "child") %>
<%= label_tag(:age_child, "I am younger than 21") %>
<%= radio_button_tag(:age, "adult") %>
<%= label_tag(:age_adult, "I'm over 21") %>
تنتج:
<input id="age_child" name="age" type="radio" value="child" />
<label for="age_child">I am younger than 21</label>
<input id="age_adult" name="age" type="radio" value="adult" />
<label for="age_adult">I'm over 21</label>
كما هو الحال مع check_box_tag
، فإن المعامل الثاني في radio_button_tag
هو قيمة عنصر الإدخال. نظرًا لأن هذين الزرين يشتركان في الاسم نفسه (age)، فسيتمكن المستخدم من تحديد أحدهما فقط، وستتضمن المعاملات [: age] إما "child" أو "adult".
ملاحظة: استخدم دومًا لافتةً نصيةً مع مربع الاختيار وزر الانتقاء. فهي تربط نصًا بخيار محدد، وتوسع المنطقة القابلة للنقر، مما يسهل على المستخدمين النقر على المدخلات.
مساعدون آخرون مهمون
عناصر التحكم الأخرى بالاستمارة الجديرة بالذكر هي مربع نصي متعدد الأسطر، وحقول كلمة المرور، والحقول المخفية، وحقول البحث، وحقول رقم الهاتف، وحقول التاريخ، وحقول الوقت، وحقول اللون، وحقول التوقيت المحلي، وحقول الشهر، وحقول الأسبوع، وحقول عنوان URL، وحقول البريد الإلكتروني، وحقول الأرقام وحقول المجالات:
<%= text_area_tag(:message, "Hi, nice site", size: "24x6") %>
<%= password_field_tag(:password) %>
<%= hidden_field_tag(:parent_id, "5") %>
<%= search_field(:user, :name) %>
<%= telephone_field(:user, :phone) %>
<%= date_field(:user, :born_on) %>
<%= datetime_local_field(:user, :graduation_day) %>
<%= month_field(:user, :birthday_month) %>
<%= week_field(:user, :birthday_week) %>
<%= url_field(:user, :homepage) %>
<%= email_field(:user, :address) %>
<%= color_field(:user, :favorite_color) %>
<%= time_field(:task, :started_at) %>
<%= number_field(:product, :price, in: 1.0..20.0, step: 0.5) %>
<%= range_field(:product, :discount, in: 1..100) %>
ينتج:
<textarea id="message" name="message" cols="24" rows="6">Hi, nice site</textarea>
<input id="password" name="password" type="password" />
<input id="parent_id" name="parent_id" type="hidden" value="5" />
<input id="user_name" name="user[name]" type="search" />
<input id="user_phone" name="user[phone]" type="tel" />
<input id="user_born_on" name="user[born_on]" type="date" />
<input id="user_graduation_day" name="user[graduation_day]" type="datetime-local" />
<input id="user_birthday_month" name="user[birthday_month]" type="month" />
<input id="user_birthday_week" name="user[birthday_week]" type="week" />
<input id="user_homepage" name="user[homepage]" type="url" />
<input id="user_address" name="user[address]" type="email" />
<input id="user_favorite_color" name="user[favorite_color]" type="color" value="#000000" />
<input id="task_started_at" name="task[started_at]" type="time" />
<input id="product_price" max="20.0" min="1.0" name="product[price]" step="0.5" type="number" />
<input id="product_discount" max="100" min="1" name="product[discount]" type="range" />
لا يتم عرض المدخلات المخفية للمستخدم ولكن بدلًا من ذلك يحتفظ بالبيانات مثل أي إدخال نصي. يمكن تغيير القيم الموجودة داخلها باستخدام جافاسكربت.
تحذير: حقول البحث، ورقم الهاتف، والتاريخ، والوقت، واللون، والتاريخ والوقت المحلي، والشهر، والأسبوع، وعنوان URL، والبريد الإلكتروني، والعدد ونطاق المدخلات هي عناصر تحكم أوجدت في HTML5. إذا كنت ترغب في أن يتوافق تطبيق مع المتصفحات القديمة، فستحتاج إلى استعمال تقنية "الترقيع المتعدد" (polyfill، توفرها CSS بمفردها أو مع جافاسكربت). من المؤكد أنه لا يوجد نقص في الحلول لذلك، على الرغم من أن الطريقة الشائعة في الوقت الحالي هي Modernizr، والتي توفر طريقة بسيطة لإضافة وظائف تعتمد على وجود ميزات HTML5 المكتشفة.
تنويه: إذا كنت تستخدم حقول إدخال كلمة المرور (لأي غرض)، فقد ترغب في ضبط تطبيقك لمنع قراءة وتسجيل مثل هذه المعاملات. يمكنك تعلم ذلك في دليل تأمين تطبيقات ريلز.
التعامل مع كائنات النموذج
مساعدو كائن النموذج
من المهام الشائعة الخاصة بالاستمارة هو تعديل أو إنشاء كائن نموذج (Model Object). على الرغم من إمكانية استخدام المساعدين tag_*
لأداء هذه المهمة، إلا أنه حل طويل ومضجر بعض الشيء، إذ يجب لكل وسم التأكد من استخدام اسم المعامل الصحيح وتعيين القيمة الافتراضية لعنصر الإدخال بشكل مناسب. يوفر ريلز مساعدين مصممين خصيصًا لهذه المهمة. هؤلاء المساعدون يفتقرون إلى اللاحقة tag_
، مثل text_field
و text_area
.
بالنسبة إلى هؤلاء المساعدين، يكون المعامل الأول هو اسم متغير نسخة والثاني هو اسم تابع (عادةً خاصية) لاستدعائه مع ذلك الكائن. سيعين ريلز قيمة عنصر الإدخال إلى القيمة التي يعيدها ذلك التابع للكائن ثم سيعيِّن اسمًا مناسبًا للعنصر. إذا كان المتحكم الخاصة بك قد عرَّف @person
واسم ذلك الشخص هو "هنري" (Henry) مثلًا، فإن النموذج الذي يحتوي على:
<%= text_field(:person, :name) %>
سيولد مخرجات شبيه بالمخرجات التالية:
<input id="person_name" name="person[name]" type="text" value="Henry"/>
عند إرسال الاستمارة، ستُخَزَّن القيمة التي أدخلها المستخدم في [params[:person][:name
. إنَّ params[:person]
ذي النوع Hash
مناسبٌ لتمريره إلى Person.new
، أو إلى @person.update
إذا كان person@
نسخةً من Person
. في حين أن اسم الخاصية يستعمل بشكل شائع مع المعامل الثاني المُمرَّر إلى هؤلاء المساعدين، فهذا ليس إلزاميًا. في المثال أعلاه، طالما أنَّ الكائنات person
لها اسم (name) وتابع name=
، فإن ريلز ستكون سعيدة.
تحذير: يجب عليك تمرير اسم متغير نسخة، أي :person
أو "person"
، وليس نسخةً فعلية لكائن النموذج (model object) الخاص بك.
يوفر ريلز مساعدين لعرض أخطاء التحقق من الصحة المقترنة مع كائن نموذجٍ (model object). جرى الحديث عن ذلك بالتفصيل في دليل عمليات التحقق من السجل الفعال.
ربط نموذج بكائن
صحيح أن هذا مريحٌ أكثر إلا أنه ليس السلوك المثالي. إذا كان لدى Person
العديد من الخاصيات المراد تعديلها، فسنكرر حينئذٍ اسم الكائن المعدَّل عدة مرات. ما نريد القيام به هو ربط استمارة بكائن نموذج، وهو ما يفعله form_for
بالضبط.
افترض أنَّه لدينا متحكم للتعامل مع المقالات في الملف app/controllers/articles_controller.rb:
def new
@article = Article.new
end
العرض المقابل هو app/views/articles/new.html.erb وسيبدو باستخدام form_for
كالتالي:
<%= form_for @article, url: {action: "create"}, html: {class: "nifty_form"} do |f| %>
<%= f.text_field :title %>
<%= f.text_area :body, size: "60x12" %>
<%= f.submit "Create" %>
<% end %>
هناك بعض الأشياء التي يجب ملاحظتها هنا:
-
@article
هو الكائن الفعلي الذي يجري تعديله. - هناك جدول Hash واحد من الخيارات. تُمرر خيارات التوجيه في
:url
ذي النوعHash
، وتُمرر خيارات HTML في:html
ذي النوعHash
. كما يمكنك توفير الخيار:namespace
لنموذجك لضمان كون الخاصيات id فريدة في عناصر الاستمارة. ستضاف شرطة سفلية بادئة للخاصيةnamespace
في الخاصياتid
في شيفرة HTML المولدة. - تنتج الدالة
form_for
كائنًا بانيًا للاستمارة (المتغيرf
). - تُستدعَى توابع إنشاء عناصر التحكم بالاستمارة في كائن باني النموذج
f
.
شيفرة HTML الناتجة هي:
<form class="nifty_form" id="new_article" action="/articles" accept-charset="UTF-8" method="post">
<input name="utf8" type="hidden" value="✓" />
<input type="hidden" name="authenticity_token" value="NRkFyRWxdYNfUg7vYxLOp2SLf93lvnl+QwDWorR42Dp6yZXPhHEb6arhDOIWcqGit8jfnrPwL781/xlrzj63TA==" />
<input type="text" name="article[title]" id="article_title" />
<textarea name="article[body]" id="article_body" cols="60" rows="12"></textarea>
<input type="submit" name="commit" value="Create" data-disable-with="Create" />
</form>
الاسم الذي مُرِّر إلى form_for
يتحكم في المفتاح المستخدم في params
للوصول إلى قيم الاستمارة. الاسم في حالتنا هذه هو article
وحتى كل عناصر الإدخال لها الأسماء article[attribute_name]
الخاصة بالنموذج. وبناءً على ذلك، ستكون params[:article]
في الإجراء create
جدول Hash
يحوي المفتاح title:
و body:
. يمكنك قراءة المزيد حول أهمية أسماء عناصر الإدخال في القسم "فهم العرف المتبع في تسمة المعاملات".
توابع المساعد التي تستدعى مع باني النموذج تتشابه مع مساعدي كائن النموذج (model object) باستثناء أنه ليس من الضروري تحديد أي كائن يُعَدَّل لأن ذلك يُدار بالفعل بواسطة باني الاستمارة.
يمكنك إنشاء ربط مشابه بدون إنشاء الوسوم <form>
بالفعل مع المساعد field_for
. هذا مفيد لتعديل كائنات نموذج إضافي (additional model objects) مع نفس الاستمارة. على سبيل المثال، إذا كان لديك النموذج Person
مع النموذج ContactDetail
المرتبط، فيمكنك إنشاء استمارة لإنشاء كليهما بالشكل التالي:
<%= form_for @person, url: {action: "create"} do |person_form| %>
<%= person_form.text_field :name %>
<%= fields_for @person.contact_detail do |contact_detail_form| %>
<%= contact_detail_form.text_field :phone_number %>
<% end %>
<% end %>
الذي ينتج شيفرة HTML التالية:
<form class="new_person" id="new_person" action="/people" accept-charset="UTF-8" method="post">
<input name="utf8" type="hidden" value="✓" />
<input type="hidden" name="authenticity_token" value="bL13x72pldyDD8bgtkjKQakJCpd4A8JdXGbfksxBDHdf1uC0kCMqe2tvVdUYfidJt0fj3ihC4NxiVHv8GVYxJA==" />
<input type="text" name="person[name]" id="person_name" />
<input type="text" name="contact_detail[phone_number]" id="contact_detail_phone_number" />
</form>
الكائن المُنشَئ بواسطة fields_for
هو باني نموذج (form builder) مثل ذلك الناتج عن form_for
(في الحقيقة form_for
يستدعي fields_for
داخليًا).
الاعتماد على تعريف السجل
النموذج Article
متاح مباشرة لمستخدمي التطبيق، لذلك - ولاتباع أفضل ممارسات التطوير مع ريلز - يجب عليك أن تصرِّح على أنه مورد (resource):
resources :articles
تنبيه: التصريح عن مورد له عدد من الآثار الجانبية. اطلع على قسم توجيه المورد في دليل التوجيه لمزيد من المعلومات حول إعداد الموارد واستخدامها.
عند التعامل مع موارد RESTful، يمكن أن تصبح استدعاءات form_for
أسهل بكثير إذا كنت تعتمد على تعريف السجل. باختصار، يمكنك فقط تمرير نسخة النموذج (model) وترك الباقي على ريلز مثل اكتشاف اسم النموذج:
## إنشاء مقالة جديدة
# نمط طويل
form_for(@article, url: articles_path)
# (تنفيذ نفس الأمر ولكن بنمط أقصر (استعمال تعريف السجل
form_for(@article)
## تعديل مقالة موجودة
# نمط طويل
form_for(@article, url: article_path(@article), html: {method: "patch"})
# نمط قصير
form_for(@article)
لاحظ كيف أن النمط القصير لاستدعاء form_for
يؤدي نفس الغرض الذي يفعله استدعاء التابع نفسه في النمط الطويل، بغض النظر عن كون السجل جديدًا أو موجودًا. تعريف السجل ذكي بما فيه الكفاية لمعرفة ما إذا كان السجل جديدًا عبر استدعاء ?record.new_record
. كما أنه يحدد المسار الصحيح لإرسال الاستمارة إليه والاسم استنادًا على صنف الكائن.
سيعيّن ريلز أيضًا الصنف class
والمعرف id
للنموذج تلقائيًا بشكل مناسب: الاستمارة التي تنشئ مقالًا سيكون لها الصنف والمعرف new_article
. إذا كنت تعدل مقالة ذات المعرف 23، فسيُعيَّن الصنف إلى edit_article
والمعرف إلى edit_article_23
. سيتم حذف هاتين الخاصيتين للإختصار في بقية هذا الدليل.
تحذير: عندما تستخدم STI (وراثة الجدول الوحيد) مع نماذجك (models)، فلا يمكنك الاعتماد على تعريف السجل في صنف فرعي بمجرد التصريح عن الصنف الأب بأنه موردٌ. سيتعين عليك حينئذٍ تحديد اسم الاستمارة مع الخيارين :url
و :method
بشكل صريح.
التعامل مع مجالات الأسماء
إذا أنشئت مسارات توجيه ضمن مجالات أسماء (namespaced routes)، فإن form_for
يحتوي على اختصار أنيق لذلك أيضًا. إذا كان تطبيقك يحتوي على مجال الاسم admin
، فالسطر التالي:
form_for [:admin, @article]
سينشئ استمارةً تُرسَل إلى ArticleController
داخل مجال الاسم admin
(يرسل إلى admin_article_path(@article)
في حالة التحديث). إذا كان لديك عدة مستويات من مجالات الأسماء، فستكون الصياغة مشابهة لما سبق:
form_for [:admin, :management, @article]
لمزيد من المعلومات حول توجيه المسارات في ريلز وكل ما يتعلق به، يرجى الاطلاع على دليل التوجيه.
كيف تعمل النماذج مع الطرائق PATCH أو PUT أو DELETE؟
يشجع إطار ريلز تصميم RESTful لتطبيقاتك، مما يعني أنك ستجعل الكثير من طلبات HTTP عبر الطريقة "PATCH" و "DELETE" (إلى جانب "GET" و "POST"). ومع ذلك، لا تدعم معظم المتصفحات طرائقَ أخرى غير "GET" و "POST" عندما يتعلق الأمر بإرسال الاستمارات.
تعمل ريلز حول هذه المشكلة بمحاكاة طرائق أخرى عبر POST باستخدام عنصر إدخال مخفي يسمى "method_"، والذي يعيَّن ليعكس الطريقة المطلوبة:
form_tag(search_path, method: "patch")
تنتج:
<form accept-charset="UTF-8" action="/search" method="post">
<input name="_method" type="hidden" value="patch" />
<input name="utf8" type="hidden" value="✓" />
<input name="authenticity_token" type="hidden" value="f755bb0ed134b76c432144748a6d4b7a7ddf2b71" />
...
</form>
عند تحليل البيانات المرسلة، ستأخذ ريلز بعين الاعتبار المعامل method_
الخاص وتتصرف كما لو كانت طريقة HTTP هي تلك المحددة داخلها (أي الطريقة "PATCH" في هذا المثال).
إنشاء مربعات اختيار بسهولة
تتطلب مربعات الاختيار في HTML كتابة مقدار لا بأس به من الشيفرة (عنصر <option>
واحد لكل خيار للاختيار من بينها)، لذلك يكون من المنطقي جدًا أن يُنشَئ ديناميكيًا.
هذا ما ستبدو الشيفرة عليه:
<select name="city_id" id="city_id">
<option value="1">Lisbon</option>
<option value="2">Madrid</option>
...
<option value="12">Berlin</option>
</select>
لديك هنا قائمة من المدن التي ستعرض أسماؤها على المستخدم. داخليًا، يريد التطبيق فقط التعامل مع المعرفات الخاصة بهم بحيث تُستخدَم كالخاصية value
للخيار. دعونا نرى كيف يساعد ريلز هنا.
الوسمان <select>
و <option>
المساعد الأكثر عمومية هو select_tag
، والذي - كما يوحي الاسم - يولد ببساطة الوسم <select>
الذي يقوم بتغليف سلسلة من الخيارات <option>
:
<%= select_tag(:city_id, '<option value="1">Lisbon</option>...') %>
هذه هي البداية فقط، إذ ذلك لا ينشئ الوسوم <option>
بشكل ديناميكي. يمكنك إنشاء هذه الوسوم عبر استعمال المساعد options_for_select
:
<%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...]) %>
ينتج:
<%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...]) %>
output:
<option value="1">Lisbon</option>
<option value="2">Madrid</option>
...
نوع المعامل الأول المُمرَّر إلى options_for_select
هو مصفوفة متشعبة كل عنصر فيها مكون من عنصرين هما: نص الخيار (اسم المدينة في حالتنا) وقيمة الخيار (معرف المدينة). قيمة الخيار هي ما سيُرسَل إلى متحكمك. غالبًا ما يكون هذا هو معرف كائن قاعدة البيانات المقابل ولكن لا يجب أن يكون كذلك.
الآن، يمكنك الجمع بين select_tag
و options_for_select
لإنشاء قائمة خيارات كاملة:
<%= select_tag(:city_id, options_for_select(...)) %>
يسمح المساعد options_for_select
بتحديد خيار مسبق عبر تمرير قيمته.
<%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...], 2) %>
تنتج:
<option value="1">Lisbon</option>
<option value="2" selected="selected">Madrid</option>
...
عندما يرى ريلز أن القيمة الداخلية للخيار المراد إنشاؤه تطابق هذه القيمة، فإنها ستضيف الخاصية selected
إلى ذلك الخيار لتحديده.
تحذير: عندما ينعدم الخيار include_blank:
أو prompt:
، فستعين قيمة include_blank:
إلى القيمة true
إذا كانت قيمة الخاصية required
هي true
، والخاصية size
هي 1،والخاصية multiple
ليست true
.
يمكنك إضافة خاصيات عشوائية إلى الخيارات باستخدام جدول Hash
:
<%= options_for_select(
[
['Lisbon', 1, { 'data-size' => '2.8 million' }],
['Madrid', 2, { 'data-size' => '3.2 million' }]
], 2
) %>
يولد:
<option value="1" data-size="2.8 million">Lisbon</option>
<option value="2" selected="selected" data-size="3.2 million">Madrid</option>
...
اختيار الخيارات للتعامل مع النماذج
في معظم الحالات، تكون عناصر التحكم في الاستمارة مرتبطة بنموذج قاعدة بيانات محدد، وكما قد تتوقع أن توفر ريلز مساعدات مصممة خصيصًا لهذا الغرض. بما يتفق مع المساعدين الآخرين في الاستمارة، عند التعامل مع النماذج، تسقط اللاحقة tag_
من select_tag
:
# controller:
@person = Person.new(city_id: 2)
# view:
<%= select(:person, :city_id, [['Lisbon', 1], ['Madrid', 2], ...]) %>
لاحظ أن المعامل الثالث، مصفوفة الخيارات، هو نفس نوع الوسيط المُمرَّر إلى options_for_select
. ميزة واحدة هنا هي أنه لا داعي للقلق بشأن التحديد المسبق للمدينة الصحيحة إذا كانت مدينة المستخدم معروفة مسبقًا. ريلز سيقوم بذلك نيابة عنك من خلال القراءة من الخاصية person.city_id@
.
كما هو الحال مع المساعدين الآخرين، إذا كنت ستستخدم المساعد select
في أداة إنشاء الاستمارات التي حُدِّدَ نطاقها إلى الكائن @person
، فستكون الصياغة كالتالي:
# select on a form builder
<%= f.select(:city_id, ...) %>
يمكنك أيضًا تمرير كتلة إلى المساعد select
:
<%= f.select(:city_id) do %>
<% [['Lisbon', 1], ['Madrid', 2]].each do |c| -%>
<%= content_tag(:option, c.first, value: c.last) %>
<% end %>
<% end %>
تحذير: إذا كنت تستخدم select
(أو مساعدين مشابهين له مثل collection_select
، أو select_tag
) لتعيين الارتباط belongs_to
، فيجب عليك تمرير اسم المفتاح الخارجي (هو city_id
في المثال أعلاه)، وليس اسم الارتباط نفسه. إذا قمت بتحديد city
بدلًا من city_id
فسيرمي السجل الفعال الخطأ:
ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750)
عند تمرير params
إلى Person.new
أو update
. طريقة أخرى للتعامل مع هذا هي أن مساعدي الاستمارة تعدل الخاصيات. يجب أيضًا أن تكون على دراية بتداعيات الأمان المحتملة الخاصة بالسماح للمستخدمين بتعديل المفاتيح الخارجية مباشرةً.
الوسوم <option>
من مجموعة من كائنات اعتباطية
يتطلب توليد الوسوم <option>
باستخدام المساعد options_for_select
إنشاء مصفوفة تحتوي على النص والقيمة لكل خيار. ولكن ماذا لو كان لديك نموذجًا مثل النموذج City
(ربما أحد السجلات الفعالة) وكنت تريد توليد وسوم <option>
من مجموعة من تلك الكائنات؟ قد يكون أحد الحلول هو إنشاء مصفوفة متشعبة منهم:
<% cities_array = City.all.map { |city| [city.name, city.id] } %>
<%= options_for_select(cities_array) %>
هذا حل صالح تمامًا، ولكن ريلز يوفر بديلًا أسهل وأوضح وذلك عبر المساعد options_from_collection_for_select
. يتوقع هذا المساعد تمرير مجموعة من الكائنات العشوائية إليه بالإضافة إلى وسيطين آخرين هما: أسماء الدوال لقراءة قيمة ونص الخيار على التوالي:
<%= options_from_collection_for_select(City.all, :id, :name) %>
كما يوحي الاسم، هذا يولد فقط الوسوم <option>
. لتوليد مربع تحديد كامل، ستحتاج إلى استخدامه بالتزامن مع المساعد select_tag
، تمامًا كما تفعل مع options_for_select
. عند العمل مع كائنات النموذج، تمامًا مثلما يجمع select
بين select_tag
و options_for_select
، يجمع collection_select
بين select_tag
و options_from_collection_for_select
.
<%= collection_select(:person, :city_id, City.all, :id, :name) %>
كما هو الحال مع المساعدين الآخرين، إذا كنت ستستخدم المساعد collection_select
على باني الاستمارة حُدّدت إلى الكائن person@
، فستكون الصياغة بالشكل التالي:
<%= f.collection_select(:city_id, City.all, :id, :name) %>
ملاحظة: يجب أن تملك الأزواج التي مُرِّرَتْ إلى options_for_select
اسمًا أولًا ومُعرِّفًا ثانيًا، ولكن مع options_from_collection_for_select
الوسيط الأول هو التابع value
والثاني هو التابع text
.
اختيار المنطقة الزمنية والبلد
للاستفادة من دعم المنطقة الزمنية في ريلز، يجب عليك أن تسأل المستخدمين عن المنطقة الزمنية الموجودين فيها. سيتطلب القيام بذلك توليد خيارات تحديد من قائمة كائنات معرفة سابقًا من النوع TimeZone
باستخدام collection_select
، ولكن يمكنك ببساطة استخدام المساعد time_zone_select
الذي يفعل لك ذلك:
<%= time_zone_select(:person, :time_zone) %>
هناك أيضًا المساعد time_zone_options_for_select
الذي يوفر طريقة يدوية للقيام بنفس الأمر وبالتالي يوفر قابلية للتخصيص. اقرأ توثيق الواجهة البرمجية للتعرف على الوسائط التي تمرَّر إلى هذين التابعين.
اعتاد ريلز على احتوائه على المساعد country_select
لتحديد بلد معين من بين مجموعة من البلدان، ولكن جمِّع ذلك في الإضافة country_select
. عند استخدام هذه الإضافة، يجب أن تدرك أن استبعاد أو إدراج أسماء بلدان معينة من القائمة يمكن أن يكون خِلافِيًّا (وكان هذا هو السبب وراء استبعاد المساعد من ريلز وتحويله إلى إضافة).
استخدام حقول التاريخ والوقت في الاستمارة
يمكنك اختيار عدم استخدام مساعدي الاستمارة الذين ينشؤون حقول HTML5 لإدخال التاريخ والوقت واستخدام مساعدي التاريخ والوقت البدلاء. يختلف مساعدو التاريخ والوقت هؤلاء عن جميع المساعدين الآخرين في ناحيتين مهمتين هما:
- لا يمكن تمثيل التواريخ والأوقات من خلال عنصر إدخال واحد فقط. بدلًا من ذلك لديك عدة عناصر، واحد لكل مكون (السنة، الشهر، اليوم، وما إلى ذلك) وبالتالي لا توجد قيمة واحدة في
params
الخاص بك تمثل التاريخ أو الوقت. - يستخدم المساعدون الآخرون اللاحقة
_tag
لتوضيح ما إذا كان المساعد مساعدًا مجردًا أو يعمل على كائنات نموذج. مع التواريخ والأوقات، المساعدselect_date
وselect_time
وselect_datetime
هم مساعدون مجردون، وdate_select
، وtime_select
وdatetime_select
هم مساعدو كائنات نموذج مكافئة.
ستُنشِئ كلا هاتين العائلتين من المساعدين سلسلة من مربعات الاختيار للعناصر المختلفة (السنة، الشهر، اليوم، ...إلخ).
المساعدون المجردون
تأخذ مجموعة المساعدين select_*
كوسيطهم الأول نسخة من Date
أو Time
أو DateTime
التي تُستخدَم كقيمة محددة حاليًا. يمكنك حذف هذا المعامل، وفي هذه الحالة يُستخدم التاريخ الحالي. فمثلًا:
<%= select_date Date.today, prefix: :start_date %>
يولد (مع حذف قيم الخيار الفعلية للإيجاز):
<select id="start_date_year" name="start_date[year]"> ... </select>
<select id="start_date_month" name="start_date[month]"> ... </select>
<select id="start_date_day" name="start_date[day]"> ... </select>
تؤدي المدخلات الواردة أعلاه إلى ظهور params[:start_date]
كجدول Hash
مع المفاتيح year:
، و month:
، و day:
. للحصول على الكائن Date
أو Time
أو DateTime
، يجب عليك استخراج هذه القيم وتمريرها إلى الباني المناسب مثل:
Date.civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, params[:start_date][:day].to_i)
الخيار :prefix
هو المفتاح المستخدم لاستعادة جدول Hash
لمكونات التاريخ من params
. هنا، ضُبِط إلى start_date
؛ إذا حُذِف، فسيُحدَد افتراضيَّا إلى date
.
مساعدو كائن النموذج
لا يعمل select_date
بشكل جيد مع الاستمارات التي تحدِّث أو تنشئ كائنات سجل فعال إذ يتوقع السجل الفعال أن كل عنصر في params
يقابل خاصية واحدة. يرسل مساعدو كائن النموذج (model object helpers) للتواريخ والأوقات المعاملات بأسماء خاصة؛ عندما يشاهد السجل الفعال معاملات بأسماء من هذا القبيل، فإنه يعلم أنه يجب دمجها مع المعاملات الأخرى وإعطائها لبانٍ يتناسب مع نوع الحقل (العمود). فمثلا:
<%= date_select :person, :birth_date %>
ينتج (مع حذف قيم الخيار الفعلية للإيجاز):
<select id="person_birth_date_1i" name="person[birth_date(1i)]"> ... </select>
<select id="person_birth_date_2i" name="person[birth_date(2i)]"> ... </select>
<select id="person_birth_date_3i" name="person[birth_date(3i)]"> ... </select>
مما يؤدي إلى params
مثل:
{'person' => {'birth_date(1i)' => '2008', 'birth_date(2i)' => '11', 'birth_date(3i)' => '22'}}
عندما يُمرَّر هذا إلى Person.new
(أو update
)، يلاحظ السجل الفعَّال أنه يجب استخدام جميع هذه المعاملات لإنشاء الخاصية birth_date
واستخدام المعلومات اللاحقة لتحديد الترتيب الذي يجب أن يمرر هذه المعاملات إلى دوال مثل Date.civil
.
خيارات مشتركة
تستخدم كلا عائلتي المساعدين نفس مجموعة الدوال الأساسية لتوليد وسوم <select>
فردية، وبالتالي يقبل كلاهما نفس الخيارات إلى حد كبير. على وجه الخصوص، ستولد ريلز بشكل افتراضي في خيارات سنة 5 سنوات على جانبي السنة الحالية. إذا لم يكن هذا نطاقًا مناسبًا، فستتجاوز الخيارات start_year:
و end_year:
هذا. للحصول على قائمة شاملة بالخيارات المتاحة، ارجع إلى توثيق الواجهة البرمجية.
كقاعدة عامة، يجب أن تستخدم date_select
عند العمل مع كائنات نموذج و select_date
في حالات أخرى، مثل نموذج بحث يقوم بتصفية النتائج حسب التاريخ.
ملاحظة: في العديد من الحالات، يكون ملتقطو التاريخ المدمجون غير متقنين لأنهم لا يساعدون المستخدم في تحديد العلاقة بين التاريخ واليوم من الأسبوع.
المكونات الفردية
تحتاج في بعض الأحيان إلى عرض مكون تاريخ واحد فقط مثل سنة أو شهر. يوفر ريلز سلسلة من المساعدين لهذا، واحد لكل مكون select_year ،select_month ،select_day ،select_hour ،select_minute ،select_second. هؤلاء المساعدين هي واضحة إلى حد ما. بشكل افتراضي، سينشئ حقل إدخال مسمى بعد مكون الوقت (على سبيل المثال، "year" لـselect_year، و "month" لـ select_month إلخ.) على الرغم من إمكانية تجاوز هذا الخيار: field_name. يعمل الخيار prefix: بالطريقة نفسها التي يعمل بها لـ select_date و select_time ولديه نفس القيمة الافتراضية.
يحدد المعامل الأول القيمة التي يجب تحديدها ويمكن أن تكون إما مثيلًا للتاريخ، أو الوقت، أو التاريخ، وفي هذه الحالة سيًزال المكون ذو الصلة، أو قيمة رقمية. فمثلا:
<%= select_year(2009) %>
<%= select_year(Time.now) %>
ستنتج نفس الناتج إذا كان العام الحالي هو 2009 ويمكن استرداد القيمة التي اختارها المستخدم من قبل params[:date][:year].
5 تحميل الملفات
تتمثل إحدى المهام الشائعة في تحميل نوع ما من الملفات، سواء أكانت صورة شخص أو ملف CSV يحتوي على بيانات لمعالجتها. أهم شيء يجب تذكره من خلال تحميل الملفات هو أنه يجب تعيين تشفير النموذج المقدم على "multipart/form-data". إذا كنت تستخدم form_for، فسيتم ذلك تلقائيًا. إذا كنت تستخدم form_tag، فيجب عليك إعداده بنفسك، وفقًا للمثال التالي.
يقوم النموذجان التاليان بتحميل ملف.
<%= form_tag({action: :upload}, multipart: true) do %>
<%= file_field_tag 'picture' %>
<% end %>
<%= form_for @person do |f| %>
<%= f.file_field :picture %>
<% end %>
يوفر ريلز الزوج المعتاد من المساعدين: المجردة file_field_tag و file_field النموذجية. الاختلاف الوحيد مع المساعدين الآخرين هو أنه لا يمكنك تعيين قيمة افتراضية لمدخلات الملف لأن هذا لن يكون له أي معنى. كما تتوقع في الحالة الأولى، يكون الملف الذي حُمِّل في params [:picture] وفي الحالة الثانية في params [: person] [: picture].
5.1 ما يُحمَّل
الكائن في تجزئة params هو مثيل لفئة فرعية من IO. اعتمادًا على حجم الملف الذي حُمِّل، قد يكون في الواقع StringIO أو مثيلًا للملف مدعومًا بملف مؤقت. في كلتا الحالتين، سيحتوي الكائن على سمة original_filename تحتوي على الاسم الذي يحتوي عليه الملف على كمبيوتر المستخدم وسمة content_type تحتوي على نوع MIME للملف الذي حُمِّل. يحفظ المقتطف التالي المحتوى الذي حُمِّل في # {ريلز.root} / public / uploads تحت نفس الاسم مثل الملف الأصلي (بافتراض أن النموذج هو النموذج الموجود في المثال السابق).
def upload
uploaded_io = params[:person][:picture]
File.open(ريلز.root.join('public', 'uploads', uploaded_io.original_filename), 'wb') do |file|
file.write(uploaded_io.read)
end
end
بمجرد تحميل الملف، هناك العديد من المهام المحتملة، بدءًا من مكان تخزين الملفات (على القرص ، Amazon S3 ، إلخ) وربطها بنماذج لتغيير حجم ملفات الصور وتوليد الصور المصغرة. تعقيدات هذا خارج نطاق هذا الدليل، ولكن هناك العديد من المكتبات المصممة للمساعدة في ذلك. اثنان من تلك المعروفة أكثر هما CarrierWave و Paperclip.
ملاحظة: إذا لم يحدد المستخدم ملفًا، فسيكون المعامل المقابل سلسلة فارغة.
5.2 التعامل مع Ajax
بخلاف النماذج الأخرى، فإن إنشاء نموذج تحميل غير متزامن ليس بسيطًا مثل توفير form_for مع remote: true. مع نموذج Ajax، يُجرى التسلسل بواسطة JavaScript قيد التشغيل داخل المتصفح، ولأن JavaScript لا تستطيع قراءة الملفات من محرك القرص الصلب، فلا يمكن تحميل الملف. يتمثل الحل الأكثر شيوعًا في استخدام إطار iframe غير مرئي يعمل كهدف لإرسال النموذج.
6 تخصيص بناة النموذج
كما ذُكر سابقًا فإن الكائن الناتج من form_for و fields_for هو مثيل FormBuilder (أو فئة فرعية منه). يغلف بناة النماذج فكرة عرض عناصر النموذج لكائن واحد. بينما يمكنك بالطبع كتابة مساعدين لنماذجك بالطريقة المعتادة، يمكنك أيضًا تصنيف فئة FormBuilder وإضافة المساعدون هناك. فمثلا:
<%= form_for @person do |f| %>
<%= text_field_with_label f, :first_name %>
<% end %>
can be replaced with
<%= form_for @person, builder: LabellingFormBuilder do |f| %>
<%= f.text_field :first_name %>
<% end %>
بتعريف فئة LabellingFormBuilder مشابهة لما يلي:
class LabellingFormBuilder < ActionView::Helpers::FormBuilder
def text_field(attribute, options={})
label(attribute) + super
end
end
إذا أعدت استخدام هذا بشكل متكرر، يمكنك تعريف مساعد labeled_form_for يطبق تلقائيًا المُنشِئ : LabellingFormBuilder:
def labeled_form_for(record, options = {}, &block)
options.merge! builder: LabellingFormBuilder
form_for record, options, &block
end
يحدد منشئ النماذج المستخدَم أيضًا ما يحدث عندما تقوم بذلك
<%= render partial: f %>
فهم العرف المتبع في تسمية المعاملات
كما شاهدت في الأقسام السابقة، يمكن أن تكون القيم من النماذج في المستوى الأعلى من تجزئة المعاملات أو متداخلة في تجزئة أخرى. على سبيل المثال، في حدث إنشاء المعيار لنموذج Person، تكون المعاملات [:person] عادةً علامة تجزئة لجميع سمات الشخص المراد إنشاؤه. يمكن لتجزئة المعاملات أيضًا أن تحتوي على المصفوفات، ومصفوفات التجزئة وما إلى ذلك.
لا تعرف نماذج HTML بشكل أساسي أي نوع من البيانات المنظمة ، وكل ما تولده هو أزواج اسم-قيمة، حيث تكون الأزواج مجرد سلاسل عادية. المصفوفات و التجزئة التي تراها في تطبيقك هي نتيجة لبعض اصطلاحات تسمية المعاملات التي يستخدمها ريلز.
7.1 الهياكل الأساسية
الهيكلان الأساسيان هما المصفوفات والتجزئة. تعكس التجزئات بنية الجُمل المستخدمة للوصول إلى القيمة في المعاملات. على سبيل المثال، إذا كان النموذج يحتوي على:
<input id="person_name" name="person[name]" type="text" value="Henry"/>
ستحتوي تجزئة المعاملات على:
{'person' => {'name' => 'Henry'}}
و[params [:person] [:name سيسترد القيمة المرسلة في المتحكم.
يمكن أن تتداخل التجزئات على العديد من المستويات كما هو مطلوب، على سبيل المثال:
<input id="person_address_city" name="person[address][city]" type="text" value="New York"/>
سينتج هذا
{'person' => {'address' => {'city' => 'New York'}}}
يتجاهل ريلز عادةً أسماء المعاملات المكررة. إذا كان اسم المعامل يحتوي على مجموعة فارغة من الأقواس المربعة []، فستُجمع في مصفوفة. إذا كنت تريد أن يتمكن المستخدمون من إدخال أرقام هواتف متعددة، فيمكنك وضع ذلك في النموذج:
<input name="person[phone_number][]" type="text"/>
<input name="person[phone_number][]" type="text"/>
<input name="person[phone_number][]" type="text"/>
سيؤدي ذلك إلى ظهور المعاملات [person] [:phone_number:] بصفتها مصفوفة تحتوي على أرقام الهاتف المدخلة.
7.2 دمجهم
يمكننا خلط وتطابق هذين المفهومين. قد يكون أحد عناصر التجزئة هو المصفوفة كما في المثال السابق، أو يمكنك الحصول على مجموعة من التجزئة. على سبيل المثال، قد يسمح لك نموذج بإنشاء أي عدد من العناوين بتكرار جزء النموذج التالي
<input name="addresses[][line1]" type="text"/>
<input name="addresses[][line2]" type="text"/>
<input name="addresses[][city]" type="text"/>
سيُنتج هذا في المعاملات [:addresses] مصفوفة من التجزئات باستخدام المفاتيح line1 و line2 والمدينة. يقرر ريلز بدء تجميع القيم في تجزئة جديدة كلما واجهت اسم إدخال موجود بالفعل في التجزئة الحالية.
هناك قيود، ومع ذلك، في حين أن التجزئات يمكن أن تكون متداخلة عشوائيًا، يُسمَح بمستوى واحد فقط من "التصفيف". عادةً يمكن استبدال المصفوفات التجزئات، على سبيل المثال، بدلاً من وجود مصفوفة من كائنات النموذج، يمكن أن يحتوى على تجزئة لكائنات نموذجية مقفولة بمعرّفها، أو فهرس مصفوفة، أو معامل آخر.
تحذير: لا تعمل معاملات المصفوفة بشكل جيد مع المساعد check_box. وفقًا لمربعات تحديد مواصفات HTML التي لم تُحدَّد، لا ترسل أي قيمة. ومع ذلك، غالبًا ما يكون من الملائم اختيار مربع اختيار لإرسال قيمة دائمًا. يزيف المساعد check_box هذا عن طريق إنشاء إدخال مخفي إضافي بنفس الاسم. إذا كان مربع الاختيار غير محدد، فسيُرسَل الإدخال المخفي فقط، وإذا حُدِّد، فسيُرسَلان كليهما، ولكن القيمة المُرسَلة من مربع الاختيار لها الأولوية. عند العمل مع معاملات المصفوفة، سيؤدي هذا الإرسال المكرَّر إلى إرباك ريلز لأن أسماء المدخلات المتكررة هي كيفية تحديد متى تبدأ عنصر صفيف جديد. من الأفضل استخدام check_box_tag أو استخدام التجزئة بدلاً من المصفوفات.
7.3 استخدام مساعدي النموذج
لم تستخدم الأقسام السابقة مساعدي نموذج ريلز على الإطلاق. بينما يمكنك صياغة أسماء المدخلات بنفسك ونقلها مباشرة إلى المساعدين مثل text_field_tag توفر ريلز أيضًا دعمًا أعلى مستوى. إن الأدوات الموجودة تحت تصرفك هنا هي معامل الاسم إلى form_for و fields_for وخيار index: الذي يأخذه المساعدون.
قد ترغب في عرض نموذج يحتوي على مجموعة من حقول التعديل لكل عنوان من عناوين الشخص. فمثلا:
<%= form_for @person do |person_form| %>
<%= person_form.text_field :name %>
<% @person.addresses.each do |address| %>
<%= person_form.fields_for address, index: address.id do |address_form|%>
<%= address_form.text_field :city %>
<% end %>
<% end %>
<% end %>
بافتراض أن الشخص له عنوانين، بمُعرِّفَين 23 و 45، فهذا من شأنه أن يُنشِئ مخرجات مشابهة لهذه:
<form accept-charset="UTF-8" action="/people/1" class="edit_person" id="edit_person_1" method="post">
<input id="person_name" name="person[name]" type="text" />
<input id="person_address_23_city" name="person[address][23][city]" type="text" />
<input id="person_address_45_city" name="person[address][45][city]" type="text" />
</form>
سيُنتِج هذا معاملات مجزئة تشبه:
{'person' => {'name' => 'Bob', 'address' => {'23' => {'city' => 'Paris'}, '45' => {'city' => 'London'}}}}
يعرف ريلز أن جميع هذه المدخلات يجب أن تكون جزءًا من تجزئة الشخص لأنك استدعيت fields_for في مُنشِئ النموذج الأول. بتحديد خيار index: يمكنك إخبار ريلز أنه بدلاً من تسمية المدخلات person[address][city]، يجب أن يضيف هذا المؤشر محاطًا بـ [] بين العنوان والمدينة. هذا مفيد في كثير من الأحيان لأنه من السهل تحديد مكان تسجيل العنوان الذي يجب تعديله. يمكنك تمرير الأرقام مع بعض الدلالات الأخرى، السلاسل أو حتى لا شيء (مما يؤدي إلى إنشاء معامل مصفوفة).
لإنشاء تداخلات أكثر تعقيدًا، يمكنك تحديد الجزء الأول من اسم الإدخال (person[address] في المثال السابق) بشكل صريح:
<%= fields_for 'person[address][primary]', address, index: address do |address_form| %>
<%= address_form.text_field :city %>
<% end %>
سيُنشِئ المدخلات مثل
<input id="person_address_primary_1_city" name="person[address][primary][1][city]" type="text" value="bologna" />
كقاعدة عامة، يكون اسم الإدخال النهائي هو سلسلة الاسم المعطى إلى fields_for/form_for، وقيمة الفهرس واسم السمة. يمكنك أيضًا تمرير أحد خيارات :index مباشرةً إلى المساعدين، مثل text_field ، ولكن عادةً ما يكون أقل تكرارًا لتحديد ذلك على مستوى منشئ النموذج بدلاً من عناصر التحكم الفردية للإدخال.
كاختصار يمكنك إلحاق [] بالاسم وحذف خيار index:. هذا هو نفس تحديد index:، عنوان ذلك
<%= fields_for 'person[address][primary][]', address do |address_form| %>
<%= address_form.text_field :city %>
<% end %>
ينتج نفس الإخراج بالضبط مثل المثال السابق.
8 نماذج لمصادر خارجية
يمكن أيضًا استخدام مساعدي نماذج ريلزلإنشاء نموذج لنشر البيانات إلى مصدر خارجي. ومع ذلك، في بعض الأحيان، قد يكون من الضروري تعيين Authenticity_token للمصدر، يمكن ذلك بتمرير المعامل authenticity_token: 'your_external_token إلى خيارات form_tag:
<%= form_tag 'http://farfar.away/form', authenticity_token: 'external_token' do %>
Form contents
<% end %>
في بعض الأحيان، عند إرسال البيانات إلى مصدر خارجي، مثل بوابة الدفع، تكون الحقول التي يمكن استخدامها في النموذج محدودة بواسطة واجهة برمجة تطبيقات خارجية وقد يكون إنشاء المصادقة غير مرغوب فيه لتوليد authenticity_token. لعدم إرسال رمز، مرر ببساطة false إلى الخيار: authenticity_token:
<%= form_tag 'http://farfar.away/form', authenticity_token: false do %>
Form contents
<% end %>
نفس الطريقة متاحة أيضًا للنموذج form_for:
<%= form_for @invoice, url: external_url, authenticity_token: 'external_token' do |f| %>
Form contents
<% end %>
أو إذا كنت لا ترغب في عرض حقل Authenticity_token:
<%= form_for @invoice, url: external_url, authenticity_token: false do |f| %>
Form contents
<% end %>
9 بناء نماذج معقدة
تنمو العديد من التطبيقات إلى أبعد من النماذج البسيطة التي تعدل كائنًا واحدًا. على سبيل المثال، عند إنشاء Person، قد ترغب في السماح للمستخدم (على نفس النموذج) بإنشاء سجلات عناوين متعددة (المنزل، العمل، إلخ). عند تعديل هذا الشخص في وقت لاحق، ينبغي أن يكون المستخدم قادرًا على إضافة العناوين أو إزالتها أو تعديلها حسب الضرورة.
9.1 تكوين النموذج
يوفر السجل النشط دعمًا لمستوى النموذج عبر دالة accepts_nested_attributes_for:
class Person < ApplicationRecord
has_many :addresses, inverse_of: :person
accepts_nested_attributes_for :addresses
end
class Address < ApplicationRecord
belongs_to :person
end
يُنشئ هذا address_attributes = method في Person الذي يسمح لك بإنشاء وتحديث و (اختياريًا) إتلاف العناوين.
9.2 النماذج المتداخلة
يسمح النموذج التالي للمستخدم بإنشاء شخص والعناوين المرتبطة به.
<%= form_for @person do |f| %>
Addresses:
<ul>
<%= f.fields_for :addresses do |addresses_form| %>
<li>
<%= addresses_form.label :kind %>
<%= addresses_form.text_field :kind %>
<%= addresses_form.label :street %>
<%= addresses_form.text_field :street %>
...
</li>
<% end %>
</ul>
<% end %>
عندما تقبل إحدى الجمعيات الصفات المتداخلة field_for تعرض وحدتها المغلقة مرة واحدة لكل عنصر في الجمعية. على وجه الخصوص، إذا لم يكن لدى الشخص عناوين فإنه لا يعرض شيئًا. النمط الشائع هو أن يُنشئ المتحكم طفلًا فارغًا أو أكثر بحيث تُعرَض مجموعة واحدة على الأقل من الحقول للمستخدم. سيُنتِج المثال أدناه مجموعتين من حقول العناوين في نموذج الشخص الجديد.
def new
@person = Person.new
2.times { @person.addresses.build }
end
يحصل fields_for على باني نموذج. سيكون اسم المعاملات هو ما تتوقعه accepts_nested_attributes_for. على سبيل المثال، عند إنشاء مستخدم له عنوانين، ستبدو المعاملات المُرسَلة كما يلي:
{
'person' => {
'name' => 'John Doe',
'addresses_attributes' => {
'0' => {
'kind' => 'Home',
'street' => '221b Baker Street'
},
'1' => {
'kind' => 'Office',
'street' => '31 Spooner Street'
}
}
}
}
مفاتيح التجزئة addresses_attributes: غير مهمة، فهي تحتاج فقط أن تكون مختلفة لكل عنوان.
إذا حُفظ الكائن المرتبط بالفعل، فسيولد تلقائيًا field_for ًإدخالا مخفيًا بمعرّف السجل المحفوظ. يمكنك تعطيل هذا بتمرير include_id: false إلى fields_for. قد ترغب في القيام بذلك إذا وُضِعَ الإدخال المُنشَئ تلقائيًا في موقع حيث تكون علامة الإدخالHTML غير صالحة أو عند استخدام ORM حيث لا يوجد لدى الأطفال معرف.
9.3 المُتحكم
كالمعتاد، تحتاج إلى إدراج المعاملات في القائمة البيضاء في المتحكم قبل تمريرها إلى النموذج:
def create
@person = Person.new(person_params)
# ...
end
private
def person_params
params.require(:person).permit(:name, addresses_attributes: [:id, :kind, :street])
end
9.4 حذف الكائنات
يمكنك السماح للمستخدمين بحذف الكائنات المرتبطة بتمرير allow_destroy: true to accepts_nested_attributes_for
class Person < ApplicationRecord
has_many :addresses
accepts_nested_attributes_for :addresses, allow_destroy: true
end
إذا كانت تجزئة السمات لكائن تحتوي على key _destroy مع قيمة 1 أو true ، فسيُدمَّر الكائن. يتيح هذا النموذج للمستخدمين إزالة العناوين:
<%= form_for @person do |f| %>
Addresses:
<ul>
<%= f.fields_for :addresses do |addresses_form| %>
<li>
<%= addresses_form.check_box :_destroy%>
<%= addresses_form.label :kind %>
<%= addresses_form.text_field :kind %>
...
</li>
<% end %>
</ul>
<% end %>
لا تنس تحديث القائمة البيضاء في المتحكم لديك ليشمل أيضًا الحقل destroy_:
def person_params
params.require(:person).
permit(:name, addresses_attributes: [:id, :kind, :street, :_destroy])
end
9.5 منع السجلات الفارغة
من المفيد غالبًا تجاهل مجموعات الحقول التي لم يملئها المستخدم. يمكنك التحكم في ذلك بتمرير: reject_if proc إلى accepts_nested_attributes_for. سيُستدعى proc هذا مع كل تجزئة من السمات المرسَلة من النموذج. إذا أعاد برس القيمة false، فلن ينشئ السجل النشط عنصرًا مقترنًا لهذه التجزئة. يحاول المثال أدناه فقط إنشاء عنوان إذا عُيِّنت سمة النوع.
class Person < ApplicationRecord
has_many :addresses
accepts_nested_attributes_for :addresses, reject_if: lambda {|attributes| attributes['kind'].blank?}
end
كوسيلة راحة، يمكنك بدلًا من ذلك تمرير الرمز: all_blank الذي سيُنشِئ proc والذي سيرفض السجلات حيث تكون جميع الخصائص فارغة باستثناء أي قيمة لـ _destroy.
9.6 إضافة حقول في الهواء
بدلاً من عرض مجموعات متعددة من الحقول في وقت مبكر، قد ترغب في إضافتها فقط عندما ينقر المستخدم على زر "إضافة عنوان جديد". لا توفر ريلز أي دعم مضمّن لهذا. عند إنشاء مجموعات جديدة من الحقول، يجب التأكد من أن مفتاح المصفوفة المرتبط فريد - يعد تاريخ جافا سكريبت الحالي (ميلي ثانية بعد الحقبة) اختيارًا شائعًا.