عرض مصدر Rails/form helpers

<noinclude>{{DISPLAYTITLE:مساعدو الاستمارة في وحدة العرض في ريلز}}</noinclude>
[[تصنيف:Rails]]
[[تصنيف:Rails View]]
تعتبر [[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 contents
<% end %>
</syntaxhighlight>عندما يستدعى بدون معاملات كما سبق، فإنه ينشئ الوسم <code>[[HTML/form|<form>]]</code> والذي، عند إرساله، سيرسل الاستمارة عبر POST إلى الصفحة الحالية. على سبيل المثال، بافتراض أن الصفحة الحالية هي ‎/home/index، ستبدو شيفرة [[HTML]] المولدة هي (أضيفت إليها بعض فواصل الأسطر لقابلية القراءة):<syntaxhighlight lang="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>
</syntaxhighlight>ستلاحظ أن شيفرة [[HTML]] تحتوي على عنصر [[HTML/input|إدخال]] من النوع <code>hidden</code>. هذا العنصر مهم، لأنه لا يمكن إرسال الاستمارة بنجاح بدونه. يجبر عنصر الإدخال المخفي ذو الاسم utf8 المتصفحات أن تراعي ترميز محارف هذه الاستمارة وأنه قد أُنشِئ لجميع الاستمارات سواء كانت طريقة الإرسال عبر "GET" أو "POST".

عنصر [[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 %>
  <%= label_tag(:q, "Search for:") %>
  <%= text_field_tag(:q) %>
  <%= submit_tag("Search") %>
<% end %>
</syntaxhighlight>سيولد هذا شيفرة [[HTML]] التالية:<syntaxhighlight lang="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>
</syntaxhighlight>'''تنويه''': لكل عنصر إدخال للاستمارة، تُنشَئ الخاصية <code>id</code> من اسمه ("q" في المثال أعلاه). يمكن أن تكون هذه المعرفات مفيدة جدًا لتنسيق العناصر عبر [[CSS]] أو معالجة عناصر تحكم الاستمارة باستخدام [[JavaScript|جافاسكربت]].

بالإضافة إلى <code>text_field_tag</code> و <code>submit_tag</code>، يوجد مساعد مماثل لكل عنصر تحكم في [[HTML]].

'''تحذير''': استخدم دائمًا الطريقة "GET" لإرسال استمارات البحث. يتيح ذلك للمستخدمين وضع إشارة حفظ (bookmark) على بحث معين للعودة إليه لاحقًا. بشكل عام، يشجعك ريلز على استخدام طريقة HTTP المناسبة لأي إجراء.

=== استعمال جدول <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">
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">'

</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 accept-charset="UTF-8" action="/people/search" method="get" class="nifty_form">'

</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 الواجهة البرمجية الكامل].

==== مربعات الاختيار ====
[[HTML/input/checkbox|مربعات الاختيار]] هي عناصر تحكم في الاستمارة تمنح المستخدم مجموعة من الخيارات التي يمكن تمكينها أو تعطيلها:<syntaxhighlight lang="html">
<%= 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") %>
</syntaxhighlight>هذا يولد ما يلي:<syntaxhighlight lang="html">
<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>

</syntaxhighlight>المعامل الأول المُمرَّر إلى <code>check_box_tag</code>، بالطبع، هو اسم عنصر الإدخال. المعامل الثاني، بطبيعة الحال، هو قيمة العنصر. ستُشمَل هذه القيمة في بيانات الاستمارة (وتكون موجودة في <code>params</code>) عند اختيار (check) مربع الاختيار.

==== أزرار الانتقاء ====
[[HTML/input/radio|أزرار الانتقاء]]، على الرغم من تشابهها مع [[HTML/input/checkbox|مربعات الاختيار]]، هي عناصر تحكم تحدد مجموعة من الخيارات لانتقاء أحدها فقط (أي أن المستخدم يمكنه اختيار خيار واحد فقط):<syntaxhighlight lang="html">
<%= 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") %>
</syntaxhighlight>تنتج:<syntaxhighlight lang="html">
<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>
</syntaxhighlight>كما هو الحال مع <code>check_box_tag</code> ، فإن المعامل الثاني في <code>radio_button_tag</code> هو قيمة عنصر الإدخال. نظرًا لأن هذين الزرين يشتركان في الاسم نفسه (age)، فسيتمكن المستخدم من تحديد أحدهما فقط، وستتضمن المعاملات <code>[‎:age]</code> إما "child" أو "adult".

'''ملاحظة''': استخدم دومًا [[HTML/label|لافتةً نصيةً]] مع مربع الاختيار وزر الانتقاء. فهي تربط نصًا بخيار محدد، وتوسع المنطقة القابلة للنقر، مما يسهل على المستخدمين النقر على المدخلات.

=== مساعدون آخرون مهمّون ===
عناصر التحكم الأخرى بالاستمارة الجديرة بالذكر هي [[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") %>
<%= 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) %>
</syntaxhighlight>ينتج:<syntaxhighlight lang="html">
<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" />

</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|نطاق المدخلات]] هي عناصر تحكم أوجدت في HTML5. إذا كنت ترغب في أن يتوافق تطبيق مع المتصفحات القديمة، فستحتاج إلى استعمال تقنية "الترقيع المتعدد" (polyfill، توفرها [[CSS]] بمفردها أو مع [[JavaScript|جافاسكربت]]). من المؤكد أنه [https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills لا يوجد نقص في الحلول لذلك]، على الرغم من أن الطريقة الشائعة في الوقت الحالي هي [https://modernizr.com/ Modernizr]، والتي توفر طريقة بسيطة لإضافة وظائف تعتمد على وجود ميزات HTML5 المكتشفة.

'''تنويه''': إذا كنت تستخدم حقول إدخال كلمة المرور (لأي غرض)، فقد ترغب في ضبط تطبيقك لمنع قراءة وتسجيل مثل هذه المعاملات. يمكنك تعلم ذلك في دليل [[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">
<%= text_field(:person, :name) %>
</syntaxhighlight>سيولد مخرجات شبيه بالمخرجات التالية:<syntaxhighlight lang="html">
<input id="person_name" name="person[name]" type="text" value="Henry"/>
</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) الخاص بك.

يوفر ريلز مساعدين لعرض أخطاء التحقق من الصحة المقترنة مع كائن نموذجٍ (model object). جرى الحديث عن ذلك بالتفصيل في دليل [[Rails/active record validations|عمليات التحقق من Active Record]].

=== ربط نموذج بكائن ===
صحيح أن هذا مريحٌ أكثر إلا أنه ليس السلوك المثالي. إذا كان لدى <code>Person</code> العديد من الخاصيات المراد تعديلها، فسنكرر حينئذٍ اسم الكائن المعدَّل عدة مرات. ما نريد القيام به هو ربط استمارة بكائن نموذج، وهو ما يفعله <code>form_for</code> بالضبط.

افترض أنَّه لدينا متحكم للتعامل مع المقالات في الملف app/controllers/articles_controller.rb:<syntaxhighlight lang="html">
def new
  @article = Article.new
end
</syntaxhighlight>العرض المقابل هو app/views/articles/new.html.erb وسيبدو باستخدام <code>form_for</code> كالتالي:<syntaxhighlight lang="html">
<%= 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 %>
</syntaxhighlight>هناك بعض الأشياء التي يجب ملاحظتها هنا:
* ‎<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 فريدة في عناصر الاستمارة. ستضاف شرطة سفلية بادئة للخاصية <code>namespace</code> في الخاصيات <code>id</code> في شيفرة HTML المولدة.
* تنتج الدالة <code>form_for</code> كائنًا بانيًا للاستمارة (المتغير <code>f</code>).
* تُستدعَى توابع إنشاء عناصر التحكم بالاستمارة في كائن باني النموذج <code>f</code>.
شيفرة HTML الناتجة هي:<syntaxhighlight lang="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>
</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) باستثناء أنه ليس من الضروري تحديد أي كائن يُعَدَّل لأن ذلك يُدار بالفعل بواسطة باني الاستمارة.

يمكنك إنشاء ربط مشابه بدون إنشاء الوسوم <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| %>
  <%= person_form.text_field :name %>
  <%= fields_for @person.contact_detail do |contact_detail_form| %>
    <%= contact_detail_form.text_field :phone_number %>
  <% end %>
<% end %>
</syntaxhighlight>الذي ينتج شيفرة [[HTML]] التالية:<syntaxhighlight lang="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>
</syntaxhighlight>الكائن المُنشَئ بواسطة <code>fields_for</code> هو باني نموذج (form builder) مثل ذلك الناتج عن <code>form_for</code> (في الحقيقة <code>form_for</code> يستدعي <code>fields_for</code> داخليًا).

=== الاعتماد على تعريف السجل ===
النموذج <code>Article</code>‎ متاح مباشرة لمستخدمي التطبيق، لذلك - ولاتباع أفضل ممارسات التطوير مع ريلز - يجب عليك أن تصرِّح على أنه مورد (resource):<syntaxhighlight lang="rails">
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|توجيه المورد في دليل التوجيه]] لمزيد من المعلومات حول إعداد الموارد واستخدامها.

عند التعامل مع موارد RESTful، يمكن أن تصبح استدعاءات <code>form_for</code> أسهل بكثير إذا كنت تعتمد على تعريف السجل. باختصار، يمكنك فقط تمرير نسخة النموذج (model) وترك الباقي على ريلز مثل اكتشاف اسم النموذج:<syntaxhighlight lang="rails">
## إنشاء مقالة جديدة
# نمط طويل
form_for(@article, url: articles_path)
# (تنفيذ نفس الأمر ولكن بنمط أقصر (استعمال تعريف السجل
form_for(@article)
 
## تعديل مقالة موجودة
# نمط طويل
form_for(@article, url: article_path(@article), html: {method: "patch"})
# نمط قصير
form_for(@article)
</syntaxhighlight>لاحظ كيف أن النمط القصير لاستدعاء <code>form_for</code> يؤدي نفس الغرض الذي يفعله استدعاء التابع نفسه في النمط الطويل، بغض النظر عن كون السجل جديدًا أو موجودًا. تعريف السجل ذكي بما فيه الكفاية لمعرفة ما إذا كان السجل جديدًا عبر استدعاء <code>?record.new_record</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)، فلا يمكنك الاعتماد على تعريف السجل في صنف فرعي بمجرد التصريح عن الصنف الأب بأنه موردٌ. سيتعين عليك حينئذٍ تحديد اسم الاستمارة مع الخيارين <code>:url</code> و <code>:method</code> بشكل صريح.

==== التعامل مع مجالات الأسماء ====
إذا أنشئت [[Rails/routing|مسارات توجيه]] ضمن مجالات أسماء (namespaced routes)، فإن <code>form_for</code> يحتوي على اختصار أنيق لذلك أيضًا. إذا كان تطبيقك يحتوي على مجال الاسم <code>admin</code>، فالسطر التالي:<syntaxhighlight lang="rails">
form_for [:admin, @article]
</syntaxhighlight>سينشئ استمارةً تُرسَل إلى <code>ArticleController</code> داخل مجال الاسم <code>admin</code> (يرسل إلى <code>admin_article_path(@article)‎</code> في حالة التحديث). إذا كان لديك عدة مستويات من مجالات الأسماء، فستكون الصياغة مشابهة لما سبق:<syntaxhighlight lang="rails">
form_for [:admin, :management, @article]
</syntaxhighlight>لمزيد من المعلومات حول توجيه المسارات في ريلز وكل ما يتعلق به، يرجى الاطلاع على [[Rails/routing|دليل التوجيه]].

=== كيف تعمل النماذج مع الطرائق PATCH أو PUT أو DELETE؟ ===
يشجع إطار ريلز تصميم RESTful لتطبيقاتك، مما يعني أنك ستجعل الكثير من طلبات HTTP عبر الطريقة "PATCH" و "DELETE" (إلى جانب "GET" و "POST"). ومع ذلك، لا تدعم معظم المتصفحات طرائقَ أخرى غير "GET" و "POST" عندما يتعلق الأمر بإرسال الاستمارات.

تعمل ريلز حول هذه المشكلة بمحاكاة طرائق أخرى عبر POST باستخدام عنصر إدخال مخفي يسمى "method_"، والذي يعيَّن ليعكس الطريقة المطلوبة:<syntaxhighlight lang="html">
form_tag(search_path, method: "patch")
</syntaxhighlight>تنتج:<syntaxhighlight lang="rails">
<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>
</syntaxhighlight>عند تحليل البيانات المرسلة، ستأخذ ريلز بعين الاعتبار المعامل <code>method_</code> الخاص وتتصرف كما لو كانت طريقة HTTP هي تلك المحددة داخلها (أي الطريقة "PATCH" في هذا المثال).

== إنشاء مربعات اختيار بسهولة ==
تتطلب [[HTML/input/checkbox|مربعات الاختيار]] في [[HTML]] كتابة مقدار لا بأس به من الشيفرة (عنصر <code>[[HTML/option|<option>]]</code> واحد لكل خيار للاختيار من بينها)، لذلك يكون من المنطقي جدًا أن يُنشَئ ديناميكيًا.

هذا ما ستبدو الشيفرة عليه:<syntaxhighlight lang="html">
<select name="city_id" id="city_id">
  <option value="1">Lisbon</option>
  <option value="2">Madrid</option>
  ...
  <option value="12">Berlin</option>
</select>
</syntaxhighlight>لديك هنا قائمة من المدن التي ستعرض أسماؤها على المستخدم. داخليًا، يريد التطبيق فقط التعامل مع المعرفات الخاصة بهم بحيث تُستخدَم كالخاصية <code>value</code> للخيار. دعونا نرى كيف يساعد ريلز هنا.

=== الوسمان [[HTML/select|<code><select></code>]] و <code>[[HTML/option|<option>]]</code> ===
المساعد الأكثر عمومية هو <code>select_tag</code>، والذي - كما يوحي الاسم - يولد ببساطة الوسم [[HTML/select|<code><select></code>]] الذي يقوم بتغليف سلسلة من الخيارات <code>[[HTML/option|<option>]]</code>:<syntaxhighlight lang="html">
<%= select_tag(:city_id, '<option value="1">Lisbon</option>...') %>
</syntaxhighlight>هذه هي البداية فقط، إذ ذلك لا ينشئ الوسوم <code>[[HTML/option|<option>]]</code> بشكل ديناميكي. يمكنك إنشاء هذه الوسوم عبر استعمال المساعد <code>options_for_select</code>:<syntaxhighlight lang="html">
<%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...]) %>
</syntaxhighlight>ينتج:<syntaxhighlight lang="html">
<%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...]) %>
 
output:
 
<option value="1">Lisbon</option>
<option value="2">Madrid</option>
...
</syntaxhighlight>نوع المعامل الأول المُمرَّر إلى <code>options_for_select</code> هو [[Ruby/Array|مصفوفة متشعبة]] كل عنصر فيها مكون من عنصرين هما: نص الخيار (اسم المدينة في حالتنا) وقيمة الخيار (معرف المدينة). قيمة الخيار هي ما سيُرسَل إلى متحكمك. غالبًا ما يكون هذا هو معرف كائن قاعدة البيانات المقابل ولكن لا يجب أن يكون كذلك.

الآن، يمكنك الجمع بين <code>select_tag</code> و <code>options_for_select</code> لإنشاء قائمة خيارات كاملة:<syntaxhighlight lang="html">
<%= select_tag(:city_id, options_for_select(...)) %>
</syntaxhighlight>يسمح المساعد <code>options_for_select</code> بتحديد خيار مسبق عبر تمرير قيمته.<syntaxhighlight lang="html">
<%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...], 2) %>

</syntaxhighlight>تنتج:<syntaxhighlight lang="html">
<option value="1">Lisbon</option>
<option value="2" selected="selected">Madrid</option>
...
</syntaxhighlight>عندما يرى ريلز أن القيمة الداخلية للخيار المراد إنشاؤه تطابق هذه القيمة، فإنها ستضيف الخاصية <code>selected</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">
<%= options_for_select(
  [
    ['Lisbon', 1, { 'data-size' => '2.8 million' }],
    ['Madrid', 2, { 'data-size' => '3.2 million' }]
  ], 2
) %>
</syntaxhighlight>يولد:<syntaxhighlight lang="html">
<option value="1" data-size="2.8 million">Lisbon</option>
<option value="2" selected="selected" data-size="3.2 million">Madrid</option>
...
</syntaxhighlight>

=== اختيار الخيارات للتعامل مع النماذج ===
في معظم الحالات، تكون عناصر التحكم في الاستمارة مرتبطة بنموذج قاعدة بيانات محدد، وكما قد تتوقع أن توفر ريلز مساعدات مصممة خصيصًا لهذا الغرض. بما يتفق مع المساعدين الآخرين في الاستمارة، عند التعامل مع النماذج، تسقط اللاحقة <code>tag_</code> من <code>select_tag</code>:<syntaxhighlight lang="rails">
# controller:
@person = Person.new(city_id: 2)

</syntaxhighlight><syntaxhighlight lang="rails">
# view:
<%= 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
<%= f.select(:city_id, ...) %>
</syntaxhighlight>يمكنك أيضًا تمرير كتلة إلى المساعد <code>select</code>:<syntaxhighlight lang="html">
<%= f.select(:city_id) do %>
  <% [['Lisbon', 1], ['Madrid', 2]].each do |c| -%>
    <%= content_tag(:option, c.first, value: c.last) %>
  <% 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> فسيرمي [[Rails/active record|Active Record]] الخطأ:<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|Active Record]]) وكنت تريد توليد وسوم <code>[[HTML/option|<option>]]</code> من مجموعة من تلك الكائنات؟ قد يكون أحد الحلول هو إنشاء مصفوفة متشعبة منهم:<syntaxhighlight lang="html">
<% cities_array = City.all.map { |city| [city.name, city.id] } %>
<%= 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) %>
</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) %>

</syntaxhighlight>كما هو الحال مع المساعدين الآخرين، إذا كنت ستستخدم المساعد <code>collection_select</code> على باني الاستمارة حُدّدت إلى الكائن <code>person@</code>، فستكون الصياغة بالشكل التالي:<syntaxhighlight lang="html">
<%= 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> لتوضيح ما إذا كان المساعد مساعدًا مجردًا (barebones) أو يعمل مع كائنات نموذج (model objects). مع التواريخ والأوقات، المساعد <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_month" name="start_date[month]"> ... </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)

</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|Active Record]] إذ يتوقع [[Rails/active record|Active Record]] أن كل عنصر في <code>params</code> يقابل خاصية واحدة. يرسل مساعدو كائن النموذج (model object helpers) للتواريخ والأوقات المعاملات بأسماء خاصة؛ عندما يشاهد [[Rails/active record|Active Record]] معاملات بأسماء من هذا القبيل، فإنه يعلم أنه يجب دمجها مع المعاملات الأخرى وإعطائها لبانٍ يتناسب مع نوع الحقل (العمود). فمثلًا:<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_2i" name="person[birth_date(2i)]"> ... </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>)، يلاحظ [[Rails/active record|Active Record]] أنه يجب استخدام جميع هذه المعاملات لإنشاء الخاصية <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 توثيق الواجهة البرمجية].

كقاعدة عامة، يجب أن تستخدم <code>date_select</code> عند العمل مع كائنات نموذج و <code>select_date</code> في حالات أخرى، مثل استمارة بحث ترشِّح النتائج حسب التاريخ.

'''ملاحظة''': في العديد من الحالات، يكون منتقو التاريخ المدمجون غير متقنين لأنهم لا يساعدون المستخدم في تحديد العلاقة بين التاريخ واليوم من الأسبوع.

=== مكونات فردية ===
تحتاج في بعض الأحيان إلى عرض مكون تاريخ واحد فقط مثل سنة أو شهر. يوفر ريلز سلسلة من المساعدين لهذا الغرض: <code>select_year</code>، و <code>select_month</code>، و <code>select_day</code>، و <code>select_hour</code>، و <code>select_minute</code>، و <code>select_second</code>. يبدو من الواضح ما هي مهمة كل واحد من هؤلاء المساعدين. بشكل افتراضي، سينشئون [[HTML/input|حقل إدخال]] له اسم يتوضع بعد مكون الوقت (على سبيل المثال، الاسم "year" للمساعد <code>select_year</code>، و "month" للمساعد <code>select_month</code> ...إلخ.) على الرغم من إمكانية تجاوز هذا الأمر عبر الخيار <code>:field_name</code>. يعمل الخيار <code>:prefix</code> بالطريقة نفسها التي يعمل فيها مع المساعد <code>select_date</code> و <code>select_time</code> ولديه نفس القيمة الافتراضية.

يحدد المعامل الأول القيمة التي يجب اختيارها ويمكن أن تكون إما نسخة من <code>Date</code> أو <code>Time</code> أو <code>DateTime</code>، وفي هذه الحالة سيُستخرَج المكون المقابل، أو القيمة العددية المقابلة. إليك الشيفرة التالية:<syntaxhighlight lang="html">
<%= select_year(2019) %>
<%= select_year(Time.now) %>

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

== تحميل الملفات ==
إحدى المهام الشائعة في الاستمارات هي تحميل نوع ما من الملفات، سواء أكانت صورة شخص أو ملف CSV يحتوي على بيانات لمعالجتها. أهم شيء يجب تذكره من خلال تحميل الملفات هو أنه '''يجب''' تعيين تشفير النموذج المصيَّر إلى القيمة "multipart/form-data". إذا كنت تستخدم <code>form_for</code>، فسيتم ذلك تلقائيًا. أمَّا إذا كنت تستخدم <code>form_tag</code>، فيجب عليك إعداده بنفسك، وفقًا للمثال التالي.

توفر الاستمارتان التاليتان إمكانية تحميل ملف:<syntaxhighlight lang="html">
<%= form_tag({action: :upload}, multipart: true) do %>
  <%= file_field_tag 'picture' %>
<% end %>
 
<%= form_for @person do |f| %>
  <%= f.file_field :picture %>
<% end %>
</syntaxhighlight>يوفر ريلز الزوج المعتاد من المساعدين: المساعد <code>file_field_tag</code> من العائلة المجرَّدة والمساعد <code>file_field</code> من عائلة كائنات النموذج (أي التي تعمل مع كائنات النموذج). الاختلاف الوحيد مع المساعدين الآخرين هو أنه لا يمكنك تعيين قيمة افتراضية لمدخلات الملف لأن هذا لن يكون له أي معنى. كما تتوقع في الحالة الأولى، يكون الملف الذي حُمِّل في <code>params [:picture]‎</code> وفي الحالة الثانية في <code>params[:person][:picture]‎</code>.

=== ما الذي يُحمَّل؟ ===
الكائن في <code>params</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code> هو نسخة لصنف فرعي من الصنف <code>[[Ruby/IO|IO]]</code>. اعتمادًا على حجم الملف المراد تحميله، قد يكون في الواقع <code>[[Ruby/StringIO|StringIO]]</code> أو نسخة من <code>[[Ruby/File|File]]</code> مدعومًا بملف مؤقت. في كلتا الحالتين، سيحتوي الكائن على الخاصية <code>original_filename</code> التي تحوي الاسم الذي سمي الملف به على حاسوب المستخدم، والخاصية <code>content_type</code> التي تحوي نوع MIME للملف. تحفظ الشيفرة التالية المحتوى الذي حُمِّل في ‎<code>#{Rails.root}/public/uploads</code> تحت نفس اسم الملف الأصلي (بافتراض أن الاستمارة هي نفسها في المثال السابق):<syntaxhighlight lang="rails">
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
</syntaxhighlight>بمجرد تحميل الملف، هناك العديد من المهام المحتملة، بدءًا من مكان تخزين الملفات (على القرص، أو على Amazon S3 ...إلخ) وربطها بنماذج لتغيير حجم ملفات الصور وتوليد الصور المصغرة (thumbnails). مثل هذه تعقيدات هي خارج نطاق هذا الدليل، ولكن هناك العديد من المكتبات المصممة للمساعدة في هذا الخصوص. اثنتان من أفضلها وأشهرها هما [https://github.com/jnicklas/carrierwave CarrierWave] و [https://github.com/thoughtbot/paperclip Paperclip].

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

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

== تخصيص باني الاستمارة ==
كما ذُكر سابقًا، فإن الكائن الناتج من <code>form_for</code> و <code>fields_for</code> هو نسخة من <code>FormBuilder</code> (أو صنف فرعي منه). يغلف بانو الاستمارة (Form builders) فكرة عرض عناصر الاستمارة لكائن واحد. بينما يمكنك بالطبع كتابة مساعدين لاستماراتك بالطريقة المعتادة، يمكنك أيضًا إنشاء صنف فرعي من <code>FormBuilder</code> وإضافة المساعدين إليه. فمثلًا:<syntaxhighlight lang="html">
<%= form_for @person do |f| %>
  <%= text_field_with_label f, :first_name %>
<% end %>
</syntaxhighlight>يمكن استبدال هذه الشيفرة وكتابة الشيفرة التالية عوضًا عنها:<syntaxhighlight lang="html">
<%= form_for @person, builder: LabellingFormBuilder do |f| %>
  <%= f.text_field :first_name %>
<% end %>
</syntaxhighlight>بتعريف الصنف <code>LabellingFormBuilder</code> بشكل مشابه لما يلي:<syntaxhighlight lang="rails">
class LabellingFormBuilder < ActionView::Helpers::FormBuilder
  def text_field(attribute, options={})
    label(attribute) + super
  end
end
</syntaxhighlight>إذا أعدت استخدام هذا بشكل متكرر، يمكنك تعريف المساعد <code>labeled_form_for</code> الذي يطبِّق تلقائيًا الخيار <code>builder: LabellingFormBuilder</code>:<syntaxhighlight lang="rails">
def labeled_form_for(record, options = {}, &block)
  options.merge! builder: LabellingFormBuilder
  form_for record, options, &block
end
</syntaxhighlight>يحدِّد باني الاستمارة المستخدَم أيضًا ما يحدث عندما تستعمل:<syntaxhighlight lang="html">
<%= render partial: f %>
</syntaxhighlight>إن كان <code>f</code> نسخةً من <code>FormBuilder</code>، فهذا سيصيِّر الجزئية <code>form</code> مع ضبط كائن الجزئية إلى باني الاستمارة. إن كان باني الاستمارة من الصنف <code>LabellingFormBuilder</code>، فستصيَّر الجزئية <code>labelling_form</code> بدلًا من تلك.

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

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

=== هياكل البيانات الأساسية ===
الهيكلان الأساسيان لتخزين البيانت هما [[Ruby/Array|المصفوفات]] و<nowiki/>[[Ruby/Hash|الجدول <code>Hash</code>]]. يعكس الأخير الصياغة المستعملة للوصول إلى القيمة في <code>params</code>. على سبيل المثال، إذا كانت الاستمارة تحتوي على:<syntaxhighlight lang="html">
<input id="person_name" name="person[name]" type="text" value="Henry"/>
</syntaxhighlight>سيحتوي <code>params</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code> على:<syntaxhighlight lang="text">
{'person' => {'name' => 'Henry'}}
</syntaxhighlight>و <code>[params[:person][:name</code> سيعيد القيمة المرسلة في المتحكم.

يمكن أن تشعيب <code>[[Ruby/Hash|Hash]]</code> على مستويات عدة كما هو مطلوب، على سبيل المثال:<syntaxhighlight lang="html">
<input id="person_address_city" name="person[address][city]" type="text" value="New York"/>
</syntaxhighlight>سينتج هذا في <code>params</code>:<syntaxhighlight lang="text">
{'person' => {'address' => {'city' => 'New York'}}}
</syntaxhighlight>يتجاهل ريلز عادةً أسماء المعاملات المكررة. إذا كان اسم المعامل يحتوي على مجموعة فارغة من الأقواس المعقوفة <code>[]</code>، فستُجمع في مصفوفة. إذا كنت تريد أن يتمكن المستخدمون من إدخال أرقام هواتف متعددة، فيمكنك وضع ذلك في الاستمارة:<syntaxhighlight lang="html">
<input name="person[phone_number][]" type="text"/>
<input name="person[phone_number][]" type="text"/>
<input name="person[phone_number][]" type="text"/>
</syntaxhighlight>سينتج عن ذلك <code>params[:person][:phone_number]‎</code> بصفته مصفوفة تحتوي على أرقام الهاتف المدخلة.

=== الدمج بين هياكل البيانات الأساسية ===
يمكننا خلط ومطابقة هذين المفهومين. قد يكون أحد عناصر [[Ruby/Hash|الجدول Hash]] هو المصفوفة كما في المثال السابق، أو يمكنك الحصول على مصفوفة من [[Ruby/Hash|الجداول Hash]]. على سبيل المثال، قد تسمح لك الاستمارة بإنشاء أي عدد من العناوين بتكرار الجزء التالي من الاستمارة:<syntaxhighlight lang="html">
<input name="addresses[][line1]" type="text"/>
<input name="addresses[][line2]" type="text"/>
<input name="addresses[][city]" type="text"/>

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

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

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

=== استخدام مساعدي الاستمارة ===
لم تستخدم الأقسام السابقة مساعدي الاستمارة لريلز على الإطلاق. لما  كان بإمكانك صياغة أسماء [[HTML/input|عناصر الإدخال]] بنفسك ونقلها مباشرة إلى مساعدين مثل <code>text_field_tag</code>، توفر ريلز أيضًا دعمًا ذا مستوى أعلى. إن الأدوات الموجودة تحت تصرفك هنا هي معامل الاسم إلى <code>form_for</code> و <code>fields_for</code> والخيار <code>:index</code> الذي يأخذه المساعدون.

قد ترغب في تصيير نموذج يحتوي على مجموعة من حقول التعديل لكل عنوان من عناوين الشخص. فمثلًا:<syntaxhighlight lang="html">
<%= 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 %>
</syntaxhighlight>بافتراض أن الشخص له عنوانين، بمُعرِّفَين 23 و 45، فهذا من شأنه أن يُنشِئ مخرجات مشابهة لما يلي:<syntaxhighlight lang="html">
<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>
</syntaxhighlight>سيُنتِج هذا في <code>params</code> الناتج:<syntaxhighlight lang="text">
{'person' => {'name' => 'Bob', 'address' => {'23' => {'city' => 'Paris'}, '45' => {'city' => 'London'}}}}
</syntaxhighlight>يعرف ريلز أن جميع هذه المدخلات يجب أن تكون جزءًا من <code>person</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code> لأنك استدعيت <code>fields_for</code> في باني الاستمارة الأول. بتحديد الخيار <code>:index</code>، يمكنك إخبار ريلز أنه بدلًا من تسمية المدخلات <code>person[address][city]‎</code>، يجب أن يضيف هذا الفهرس محاطًا بالقوسين <code>[]</code> بين العنوان والمدينة. هذا مفيد في كثير من الأحيان لأنه من السهل تحديد مكان سجل العنوان المراد تعديله. يمكنك تمرير الأرقام مع بعض الدلالات الأخرى، السلاسل النصية أو حتى القيمة <code>nil</code> (مما يؤدي إلى إنشاء معامل مصفوفة).

لإنشاء تداخلات أكثر تعقيدًا، يمكنك تحديد الجزء الأول من اسم عنصر الإدخال (<code>person[address]‎</code> في المثال السابق) بشكل صريح:<syntaxhighlight lang="html">
<%= fields_for 'person[address][primary]', address, index: address do |address_form| %>
  <%= address_form.text_field :city %>
<% end %>
</syntaxhighlight>سيُنشِئ [[HTML/input|عنصر إدخال]] مثل:<syntaxhighlight lang="html">
<input id="person_address_primary_1_city" name="person[address][primary][1][city]" type="text" value="bologna" />
</syntaxhighlight>كقاعدة عامة، يكون اسم عنصر الإدخال النهائي هو جمع الاسم المعطى مع <code>fields_for</code> أو <code>form_for</code>، وقيمة الفهرس (index value) واسم الخاصية. يمكنك أيضًا تمرير الخيار <code>:index</code> مباشرةً إلى المساعدين، مثل <code>text_field</code>، ولكن عادةً ما يكون أقل تكرارًا لتحديد ذلك على مستوى باني الاستمارة بدلًا من عناصر التحكم الفردية للإدخال.

كاختصار يمكنك إضافة <code>[]</code> إلى الاسم وحذف الخيار <code>:index</code>. هذا يؤدي نفس الغرض الذي يؤديه تحديد <code>index: address</code>، لذا ستنتج الشيفرة التالية:<syntaxhighlight lang="html">
<%= fields_for 'person[address][primary][]', address do |address_form| %>
  <%= address_form.text_field :city %>
<% end %>
</syntaxhighlight>نفس المخرجات تمامًا الناتجة عن المثال السابق.

== استمارات لموارد خارجية ==
يمكن أيضًا استخدام مساعدي استمارات ريلز لإنشاء استمارة لنشر البيانات إلى مورد خارجي (external resource). ومع ذلك، في بعض الأحيان، قد يكون من الضروري تعيين <code>Authenticity_token</code> للمصدر، إذ يمكن تنفيذ ذلك بتمرير المعامل <code>authenticity_token: 'your_external_token'‎</code> إلى خيارات <code>form_tag</code>:<syntaxhighlight lang="html">
<%= form_tag 'http://farfar.away/form', authenticity_token: 'external_token' do %>
  Form contents
<% end %>
</syntaxhighlight>في بعض الأحيان، عند إرسال البيانات إلى مورد خارجي، مثل بوابة الدفع الإلكترونية، تكون الحقول التي يمكن استخدامها في الاستمارة محدودة بواسطة واجهة برمجة تطبيقات خارجية وقد يكون إنشاء المصادقة غير مرغوب فيه لتوليد <code>authenticity_token</code>. لعدم إرسال رمز، مرر ببساطة القيمة <code>false</code> إلى الخيار <code>:authenticity_token</code>:<syntaxhighlight lang="html">
<%= form_tag 'http://farfar.away/form', authenticity_token: false do %>
  Form contents
<% end %>
</syntaxhighlight>نفس الطريقة متاحة أيضًا للمساعد <code>form_for</code>:<syntaxhighlight lang="html">
<%= form_for @invoice, url: external_url, authenticity_token: 'external_token' do |f| %>
  Form contents
<% end %>
</syntaxhighlight>أو إذا كنت لا ترغب في تصيير الحقل <code>Authenticity_token</code>:<syntaxhighlight lang="html">
<%= form_for @invoice, url: external_url, authenticity_token: false do |f| %>
  Form contents
<% end %>
</syntaxhighlight>

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

=== ضبط النموذج ===
يوفر [[Rails/active record|Active Record]] دعمًا على مستوى النموذج عبر التابع <code>accepts_nested_attributes_for</code>:<syntaxhighlight lang="rails">
class Person < ApplicationRecord
  has_many :addresses, inverse_of: :person
  accepts_nested_attributes_for :addresses
end
 
class Address < ApplicationRecord
  belongs_to :person
end
</syntaxhighlight>يُنشئ هذا <code>address_attributes = method</code> في <code>Person</code> الذي يسمح لك بإنشاء وتحديث وإتلاف (اختياريًا) العناوين.

=== استمارات متداخلة ===
تسمح الاستمارة التالية للمستخدم بإنشاء شخص <code>Person</code> والعناوين المرتبطة به:<syntaxhighlight lang="html">
<%= 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 %>
</syntaxhighlight>عندما تقبل إحدى [[Rails/association basics|الارتباطات]] الخاصيات المتداخلة، يصيِّر التابع <code>field_for</code> الكتلة المرتبطة به مرة واحدة لكل عنصر للارتباط. على وجه الخصوص، إذا لم يكن لدى الشخص عناوين، فلا يصيِّر التابع شيئًا. النمط الشائع هو أن يُنشئ المتحكم ابنًا فارغًا أو أكثر بحيث تُعرَض مجموعة واحدة على الأقل من الحقول للمستخدم. سيُنتِج المثال أدناه مجموعتين من حقول العناوين التي تصيَّر في استمارة الشخص الجديد.<syntaxhighlight lang="rails">
def new
  @person = Person.new
  2.times { @person.addresses.build }
end
</syntaxhighlight>يُنتِج <code>fields_for</code> بانيَ استمارة. سيكون اسم المعاملات هو ما يتوقعه التابع <code>accepts_nested_attributes_for</code>. على سبيل المثال، عند إنشاء مستخدم له عنوانين، ستبدو المعاملات المُرسَلة كما يلي:<syntaxhighlight lang="text">
{
  'person' => {
    'name' => 'John Doe',
    'addresses_attributes' => {
      '0' => {
        'kind' => 'Home',
        'street' => '221b Baker Street'
      },
      '1' => {
        'kind' => 'Office',
        'street' => '31 Spooner Street'
      }
    }
  }
}
</syntaxhighlight>مفاتيح <code>addresses_attributes:</code> ذي النوع <code>[[Ruby/Hash|Hash]]</code> غير مهمة، فهي تحتاج فقط أن تكون مختلفة لكل عنوان.

إذا حُفِظ الكائن المرتبط مسبقًا، فسيولد <code>field_for</code> تلقائيًا [[HTML/input/hidden|عناصر إدخال مخفية]] بمعرّف السجل المحفوظ. يمكنك تعطيل هذا السلوك بتمرير <code>include_id: false</code> إلى المساعد <code>fields_for</code>. قد ترغب في القيام بذلك إذا وُضِعَ عنصر الإدخال المولد تلقائيًا في موقع حيث يكون هنالك وسم <code>[[HTML/input|<input>]]</code> غير صالح أو عند استخدام [[Rails/active record basics#.D8.B1.D8.A8.D8.B7 .D8.A7.D9.84.D9.83.D8.A7.D8.A6.D9.86.D8.A7.D8.AA .D8.A8.D8.A7.D9.84.D8.B9.D9.84.D8.A7.D9.82.D8.A7.D8.AA|العملية ORM]] حيث لا تملك العناصر الأبناء أيَّ معرف.

=== المتحكم ===
كالمعتاد، تحتاج إلى [[Rails/action controller overview#.D8.A7.D9.84.D9.85.D8.B9.D8.A7.D9.85.D9.84.D8.A7.D8.AA .D8.A7.D9.84.D9.82.D9.88.D9.8A.D8.A9|إدراج المعاملات في القائمة البيضاء]] في المتحكم قبل تمريرها إلى النموذج:<syntaxhighlight lang="rails">
def create
  @person = Person.new(person_params)
  # ...
end
 
private
  def person_params
    params.require(:person).permit(:name, addresses_attributes: [:id, :kind, :street])
  end
</syntaxhighlight>

=== حذف الكائنات ===
يمكنك السماح للمستخدمين بحذف الكائنات المرتبطة بتمرير الخيار <code>allow_destroy: true</code> إلى <code>accepts_nested_attributes_for</code>:<syntaxhighlight lang="html">
class Person < ApplicationRecord
  has_many :addresses
  accepts_nested_attributes_for :addresses, allow_destroy: true
end
</syntaxhighlight>إذا كان [[Ruby/Hash|الجدول Hash]] لخاصيات كائنٍ يحتوي على المفتاح ‎<code>_destroy</code> مع القيمة 1 أو <code>true</code>، فسيُدمَّر آنذاك الكائن. تتيح هذه الاستمارة للمستخدمين إزالة العناوين:<syntaxhighlight lang="html">
<%= 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 %>
</syntaxhighlight>لا تنسَ تحديث القائمة البيضاء في المتحكم لديك لتشمل أيضًا الحقل <code>destroy_</code>:<syntaxhighlight lang="rails">
def person_params
  params.require(:person).
    permit(:name, addresses_attributes: [:id, :kind, :street, :_destroy])
end
</syntaxhighlight>

=== منع السجلات الفارغة ===
من المفيد غالبًا تجاهل مجموعات الحقول التي لم يملؤها المستخدم. يمكنك التحكم في ذلك بتمرير <code>reject_if</code> ذي النوع <code>[[Ruby/Proc|Proc]]</code> إلى <code>accepts_nested_attributes_for</code>. سيُستدعى الكائن <code>[[Ruby/Proc|Proc]]</code> هذا مع كل [[Ruby/Hash|جدول Hash]] من الخاصيات المرسَلة عبر الاستمارة. إذا أعاد الكائن <code>[[Ruby/Proc|Proc]]</code> القيمة <code>false</code>، فلن ينشئ [[Rails/active record|Active Record]] كائنًا مقترنًا [[Ruby/Hash|للجدول Hash]] هذا. يحاول المثال أدناه فقط إنشاء عنوان إذا عُيِّنت الخاصية <code>kind</code>:<syntaxhighlight lang="rails">
class Person < ApplicationRecord
  has_many :addresses
  accepts_nested_attributes_for :addresses, reject_if: lambda {|attributes| attributes['kind'].blank?}
end
</syntaxhighlight>للسهولة، يمكنك بدلًا من ذلك تمرير الرمز ‎<code>:all_blank</code> الذي سيُنشِئ كائنًا من النوع <code>[[Ruby/Proc|Proc]]</code> الذي سيرفض السجلات عندما تكون جميع الخاصيات فارغةً باستثناء أي قيمة للخاصية ‎<code>_destroy</code>.

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

== مصادر ==
* [https://guides.rubyonrails.org/form_helpers.html صفحة Action View Form Helpers في توثيق Ruby On Rails.]