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). جرى الحديث عن ذلك بالتفصيل في دليل عمليات التحقق من السجل الفعال.

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

صحيح أن هذا مريحٌ أكثر إلا أنه ليس السلوك المثالي. إذا كان لدى 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 فسيرمي السجل الفعال الخطأ:

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 إضافة حقول في الهواء

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