Rails/form helpers

تعتبر الاستمارات (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="&#x2713;" />
  <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="&#x2713;" />
  <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). جرى الحديث عن ذلك بالتفصيل في دليل عمليات التحقق من Active Record.

ربط نموذج بكائن

صحيح أن هذا مريحٌ أكثر إلا أنه ليس السلوك المثالي. إذا كان لدى 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="&#x2713;" />
  <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="&#x2713;" />
  <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="&#x2713;" />
  <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 فسيرمي Active Record الخطأ:

ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750)

عند تمرير params إلى Person.new أو update. طريقة أخرى للتعامل مع هذا هي أن مساعدي الاستمارة تعدل الخاصيات. يجب أيضًا أن تكون على دراية بتداعيات الأمان المحتملة الخاصة بالسماح للمستخدمين بتعديل المفاتيح الخارجية مباشرةً.

الوسوم <option> من مجموعة من كائنات اعتباطية

يتطلب توليد الوسوم <option> باستخدام المساعد options_for_select إنشاء مصفوفة تحتوي على النص والقيمة لكل خيار. ولكن ماذا لو كان لديك نموذجًا مثل النموذج City (ربما أحد Active Record) وكنت تريد توليد وسوم <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 لتوضيح ما إذا كان المساعد مساعدًا مجردًا (barebones) أو يعمل مع كائنات نموذج (model objects). مع التواريخ والأوقات، المساعد 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 بشكل جيد مع الاستمارات التي تحدِّث أو تنشئ كائنات Active Record إذ يتوقع Active Record أن كل عنصر في params يقابل خاصية واحدة. يرسل مساعدو كائن النموذج (model object helpers) للتواريخ والأوقات المعاملات بأسماء خاصة؛ عندما يشاهد Active Record معاملات بأسماء من هذا القبيل، فإنه يعلم أنه يجب دمجها مع المعاملات الأخرى وإعطائها لبانٍ يتناسب مع نوع الحقل (العمود). فمثلًا:

<%= 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)، يلاحظ Active Record أنه يجب استخدام جميع هذه المعاملات لإنشاء الخاصية 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 ولديه نفس القيمة الافتراضية.

يحدد المعامل الأول القيمة التي يجب اختيارها ويمكن أن تكون إما نسخة من Date أو Time أو DateTime، وفي هذه الحالة سيُستخرَج المكون المقابل، أو القيمة العددية المقابلة. إليك الشيفرة التالية:

<%= select_year(2019) %>
<%= select_year(Time.now) %>

التي ستولد نفس الناتج إذا كان العام الحالي هو 2019 ويمكن استعادة القيمة التي اختارها المستخدم من قبل params[:date][:year]‎.

تحميل الملفات

إحدى المهام الشائعة في الاستمارات هي تحميل نوع ما من الملفات، سواء أكانت صورة شخص أو ملف 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]‎.

ما الذي يُحمَّل؟

الكائن في params ذي النوع Hash هو نسخة لصنف فرعي من الصنف IO. اعتمادًا على حجم الملف المراد تحميله، قد يكون في الواقع StringIO أو نسخة من File مدعومًا بملف مؤقت. في كلتا الحالتين، سيحتوي الكائن على الخاصية original_filename التي تحوي الاسم الذي سمي الملف به على حاسوب المستخدم، والخاصية content_type التي تحوي نوع MIME للملف. تحفظ الشيفرة التالية المحتوى الذي حُمِّل في ‎#{Rails.root}/public/uploads تحت نفس اسم الملف الأصلي (بافتراض أن الاستمارة هي نفسها في المثال السابق):

def upload
  uploaded_io = params[:person][:picture]
  File.open(Rails.root.join('public', 'uploads', uploaded_io.original_filename), 'wb') do |file|
    file.write(uploaded_io.read)
  end
end

بمجرد تحميل الملف، هناك العديد من المهام المحتملة، بدءًا من مكان تخزين الملفات (على القرص، أو على Amazon S3 ...إلخ) وربطها بنماذج لتغيير حجم ملفات الصور وتوليد الصور المصغرة (thumbnails). مثل هذه تعقيدات هي خارج نطاق هذا الدليل، ولكن هناك العديد من المكتبات المصممة للمساعدة في هذا الخصوص. اثنتان من أفضلها وأشهرها هما CarrierWave و Paperclip.

ملاحظة: إذا لم يحدَّد المستخدم ملفًا، فسيكون المعامل المقابل سلسلة فارغة.

التعامل مع Ajax

بخلاف الاستمارات الأخرى، فإن إنشاء استمارة تحميل ملف بشكل غير متزامن ليس بسيطًا مثل استعمال form_for مع remote: true. مع استمارة Ajax، تُجرَى عملية السَلسَلة (serialization) بواسطة جافاسكربت قيد التشغيل داخل المتصفح، ولأن جافاسكربت لا تستطيع قراءة الملفات من محرك القرص الصلب، فلا يمكن تحميل الملف آنذاك. يتمثل الحل الأكثر شيوعًا في استخدام الإطار iframe بشكل غير مرئي يعمل كهدف لإرسال الاستمارة.

تخصيص باني الاستمارة

كما ذُكر سابقًا، فإن الكائن الناتج من form_for و fields_for هو نسخة من FormBuilder (أو صنف فرعي منه). يغلف بانو الاستمارة (Form builders) فكرة عرض عناصر الاستمارة لكائن واحد. بينما يمكنك بالطبع كتابة مساعدين لاستماراتك بالطريقة المعتادة، يمكنك أيضًا إنشاء صنف فرعي من FormBuilder وإضافة المساعدين إليه. فمثلًا:

<%= form_for @person do |f| %>
  <%= text_field_with_label f, :first_name %>
<% end %>

يمكن استبدال هذه الشيفرة وكتابة الشيفرة التالية عوضًا عنها:

<%= 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 الذي يطبِّق تلقائيًا الخيار builder: LabellingFormBuilder:

def labeled_form_for(record, options = {}, &block)
  options.merge! builder: LabellingFormBuilder
  form_for record, options, &block
end

يحدِّد باني الاستمارة المستخدَم أيضًا ما يحدث عندما تستعمل:

<%= render partial: f %>

إن كان f نسخةً من FormBuilder، فهذا سيصيِّر الجزئية form مع ضبط كائن الجزئية إلى باني الاستمارة. إن كان باني الاستمارة من الصنف LabellingFormBuilder، فستصيَّر الجزئية labelling_form بدلًا من تلك.

فهم العرف المتبع في تسمية المعاملات

كما شاهدت في الأقسام السابقة، يمكن أن تكون القيم من الاستمارات في المستوى الأعلى من params أو متداخلة في جدول Hash آخر. على سبيل المثال، في الإجراء create القياسي للنموذج Person، تكون params[:person]‎ عادةً جدول Hash يحوي جميع خاصيات الشخص (person) المراد إنشاؤه. يمكن أن يحوي params أيضًا المصفوفات، ومصفوفات من الكائنات Hash وما إلى ذلك.

لا تعرف استمارات HTML بشكل أساسي أي نوع من البيانات المهيكلة (structured data)، وكل ما تولده هو الأزواج اسم-قيمة، حيث تكون الأزواج مجرد سلاسل نصية عادية. المصفوفات والجداول Hash التي تراها في تطبيقك هي نتيجة لبعض اصطلاحات تسمية المعاملات التي يستخدمها ريلز.

هياكل البيانات الأساسية

الهيكلان الأساسيان لتخزين البيانت هما المصفوفات والجدول Hash. يعكس الأخير الصياغة المستعملة للوصول إلى القيمة في params. على سبيل المثال، إذا كانت الاستمارة تحتوي على:

<input id="person_name" name="person[name]" type="text" value="Henry"/>

سيحتوي params ذي النوع Hash على:

{'person' => {'name' => 'Henry'}}

و [params[:person][:name سيعيد القيمة المرسلة في المتحكم. يمكن أن تشعيب Hash على مستويات عدة كما هو مطلوب، على سبيل المثال:

<input id="person_address_city" name="person[address][city]" type="text" value="New York"/>

سينتج هذا في params:

{'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"/>

سينتج عن ذلك params[:person][:phone_number]‎ بصفته مصفوفة تحتوي على أرقام الهاتف المدخلة.

الدمج بين هياكل البيانات الأساسية

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

<input name="addresses[][line1]" type="text"/>
<input name="addresses[][line2]" type="text"/>
<input name="addresses[][city]" type="text"/>

سيُنتج هذا في params[:addresses]‎ مصفوفة من الجداول Hash مع المفاتيح line1 و line2 و city. يقرر ريلز بدء تجميع القيم في جدول Hash جديدة كلما عثرت على اسم عنصر إدخال موجود بالفعل في الجدول الحالي.

هناك قيود، ومع ذلك، في حين أن الجداول Hash يمكن أن تكون متداخلة عشوائيًا، يُسمَح بمستوى واحد فقط من "المصفوفية" (arrayness). عادةً يمكن تبديل الجداول Hash مكان المصفوفات، على سبيل المثال، بدلًا من وجود مصفوفة من كائنات نموذج، يمكن استعمال جدول Hash من كائنات نموذج قيمة مفاتيحها هي معرف كل منها، أو فهرس مصفوفة، أو معامل آخر.

تحذير: لا تعمل معاملات المصفوفة بشكل جيد مع المساعد check_box. وفقًا لمواصفات HTML، مربعات الاختيار غير المحدَّدة (unchecked) تُرسَل بدون قيمة. ومع ذلك، غالبًا ما يكون من الملائم لمربع الاختيار أن يرسل قيمةً دائمًا. يُزيِّف المساعد check_box هذا الأمر عبر إنشاء عنصر إدخال مخفي إضافي بنفس الاسم. إذا كان مربع الاختيار غير محدد، فسيُرسَل عنصر الإدخال المخفي فقط، وإذا حُدِّد، فسيُرسَل كلا العنصرين، ولكن القيمة المُرسَلة من مربع الاختيار المُحدَّد لها الأولوية على قيمة العنصر المخفي. عند العمل مع معاملات المصفوفة، سيؤدي هذا الإرسال المكرَّر إلى إرباك ريلز لأن أسماء عناصر الإدخال المتكررة تحدِّد بداية عنصر مصفوفة جديدة. من الأفضل استخدام المساعد check_box_tag أو استخدام جدول Hash بدلًا من المصفوفات.

استخدام مساعدي الاستمارة

لم تستخدم الأقسام السابقة مساعدي الاستمارة لريلز على الإطلاق. لما كان بإمكانك صياغة أسماء عناصر الإدخال بنفسك ونقلها مباشرة إلى مساعدين مثل 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>

سيُنتِج هذا في params الناتج:

{'person' => {'name' => 'Bob', 'address' => {'23' => {'city' => 'Paris'}, '45' => {'city' => 'London'}}}}

يعرف ريلز أن جميع هذه المدخلات يجب أن تكون جزءًا من person ذي النوع Hash لأنك استدعيت fields_for في باني الاستمارة الأول. بتحديد الخيار :index، يمكنك إخبار ريلز أنه بدلًا من تسمية المدخلات person[address][city]‎، يجب أن يضيف هذا الفهرس محاطًا بالقوسين [] بين العنوان والمدينة. هذا مفيد في كثير من الأحيان لأنه من السهل تحديد مكان سجل العنوان المراد تعديله. يمكنك تمرير الأرقام مع بعض الدلالات الأخرى، السلاسل النصية أو حتى القيمة nil (مما يؤدي إلى إنشاء معامل مصفوفة). لإنشاء تداخلات أكثر تعقيدًا، يمكنك تحديد الجزء الأول من اسم عنصر الإدخال (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 value) واسم الخاصية. يمكنك أيضًا تمرير الخيار :index مباشرةً إلى المساعدين، مثل text_field، ولكن عادةً ما يكون أقل تكرارًا لتحديد ذلك على مستوى باني الاستمارة بدلًا من عناصر التحكم الفردية للإدخال. كاختصار يمكنك إضافة [] إلى الاسم وحذف الخيار :index. هذا يؤدي نفس الغرض الذي يؤديه تحديد index: address، لذا ستنتج الشيفرة التالية:

<%= fields_for 'person[address][primary][]', address do |address_form| %>
  <%= address_form.text_field :city %>
<% end %>

نفس المخرجات تمامًا الناتجة عن المثال السابق.

استمارات لموارد خارجية

يمكن أيضًا استخدام مساعدي استمارات ريلز لإنشاء استمارة لنشر البيانات إلى مورد خارجي (external resource). ومع ذلك، في بعض الأحيان، قد يكون من الضروري تعيين 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 %>

بناء استمارات معقدة

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

ضبط النموذج

يوفر Active Record دعمًا على مستوى النموذج عبر التابع 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 الذي يسمح لك بإنشاء وتحديث وإتلاف (اختياريًا) العناوين.

استمارات متداخلة

تسمح الاستمارة التالية للمستخدم بإنشاء شخص Person والعناوين المرتبطة به:

<%= 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: ذي النوع Hash غير مهمة، فهي تحتاج فقط أن تكون مختلفة لكل عنوان.

إذا حُفِظ الكائن المرتبط مسبقًا، فسيولد field_for تلقائيًا عناصر إدخال مخفية بمعرّف السجل المحفوظ. يمكنك تعطيل هذا السلوك بتمرير include_id: false إلى المساعد fields_for. قد ترغب في القيام بذلك إذا وُضِعَ عنصر الإدخال المولد تلقائيًا في موقع حيث يكون هنالك وسم <input> غير صالح أو عند استخدام العملية ORM حيث لا تملك العناصر الأبناء أيَّ معرف.

المتحكم

كالمعتاد، تحتاج إلى إدراج المعاملات في القائمة البيضاء في المتحكم قبل تمريرها إلى النموذج:

def create
  @person = Person.new(person_params)
  # ...
end
 
private
  def person_params
    params.require(:person).permit(:name, addresses_attributes: [:id, :kind, :street])
  end

حذف الكائنات

يمكنك السماح للمستخدمين بحذف الكائنات المرتبطة بتمرير الخيار allow_destroy: true إلى accepts_nested_attributes_for:

class Person < ApplicationRecord
  has_many :addresses
  accepts_nested_attributes_for :addresses, allow_destroy: true
end

إذا كان الجدول Hash لخاصيات كائنٍ يحتوي على المفتاح ‎_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

منع السجلات الفارغة

من المفيد غالبًا تجاهل مجموعات الحقول التي لم يملؤها المستخدم. يمكنك التحكم في ذلك بتمرير reject_if ذي النوع Proc إلى accepts_nested_attributes_for. سيُستدعى الكائن Proc هذا مع كل جدول Hash من الخاصيات المرسَلة عبر الاستمارة. إذا أعاد الكائن Proc القيمة false، فلن ينشئ Active Record كائنًا مقترنًا للجدول Hash هذا. يحاول المثال أدناه فقط إنشاء عنوان إذا عُيِّنت الخاصية kind:

class Person < ApplicationRecord
  has_many :addresses
  accepts_nested_attributes_for :addresses, reject_if: lambda {|attributes| attributes['kind'].blank?}
end

للسهولة، يمكنك بدلًا من ذلك تمرير الرمز ‎:all_blank الذي سيُنشِئ كائنًا من النوع Proc الذي سيرفض السجلات عندما تكون جميع الخاصيات فارغةً باستثناء أي قيمة للخاصية ‎_destroy.

إضافة حقول آليًا

بدلًا من تصيير مجموعات متعددة من الحقول في وقت مبكر، قد ترغب في إضافتها فقط عندما ينقر المستخدم على زر "إضافة عنوان جديد" (Add new address). لا توفر ريلز أي دعم مضمّن لهذا السلوك للأسف. عند توليد مجموعات جديدة من الحقول، يجب التأكد من أن مفتاح المصفوفة المقابلة فريد؛ يعد تاريخ جافاسكربت الحالي (ميلي ثانية بعد بدء توقيت يونكس) اختيارًا شائعًا.

مصادر

• صفحة Action View Form Helpers في توثيق Ruby On Rails.