عرض مصدر Rails/layouts and rendering

<noinclude>{{DISPLAYTITLE:تخطيط الصفحات والتصيير في ريلز}}</noinclude>
[[تصنيف:Rails]]
[[تصنيف:Rails View]]
يغطي هذا الدليل ميزات التخطيط الأساسية لوحدتي [[Rails/action controller overview|التحكم]] و<nowiki/>[[Rails/action view overview|العرض]]. بعد قراءة هذا الدليل، ستتعلم:
* كيفية استخدام توابع التصيير المختلفة المضمنة ‎في ريلز.
* كيفية إنشاء تخطيطات (layouts) تحتوي على أقسام محتوى متعددة.
* كيفية استخدام الأجزاء مع واجهات العرض.
* كيفية استخدام تخطيطات متداخلة (قوالب فرعية).

== نظرة عامة: كيف تتراكب قطع الأحجية معًا ==
يركز هذا الدليل على التفاعل بين [[Rails/action controller overview|المتحكم]] و<nowiki/>[[Rails/action view overview|العرض]] في نمط التصميم '''M'''odel-'''V'''iew-'''C'''ontroller. كما تعلم، فإنَّ المتحكم مسؤول عن تنظيم العملية الكاملة للتعامل مع الطلب في ريلز، على الرغم من أنه عادة لا يتعامل مع أي شيفرة ثقيلة في النموذج. ولكن بعد ذلك، عندما يحين وقت إرسال رد مرة أخرى إلى المستخدم، يسلم المتحكم بعض الأشياء إلى وحدة العرض. إنه التبادل الذي هو موضوع هذا الدليل.

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

== إنشاء الردود ==
من وجهة نظر المتحكم، هناك ثلاث طرق لإنشاء استجابة HTTP:
# استدعاء <code>render</code> لإنشاء استجابة كاملة لإرسالها مرة أخرى إلى المتصفح، أو
# استدعاء <code>redirect_to</code> لإرسال شيفرة إعادة التوجيه HTTP إلى المتصفح، أو
# استدعاء <code>head</code> لإنشاء استجابة تتكون من ترويسات HTTP فقط لإرسالها مرة أخرى إلى المتصفح.

=== التصيير افتراضيًا: العرف فوق الضبط في الإجراء ===
كنت سمعت أن ريلز يعزز العرف (convention) على الضبط (configuration). التصيير الافتراضي هو مثال ممتاز على هذا. بشكل افتراضي، يصيِّر المتحكم في ريلز تلقائيًا العرض بأسماء تتوافق مع [[Rails/routing|المسارات الموجهة]] الصالحة. مثلًا، إذا كان لديك هذه الشيفرة في الصنف <code>BooksController</code> الخاصة بك:<syntaxhighlight lang="rails">
class BooksController < ApplicationController
end
</syntaxhighlight>وما يلي في ملف مساراتك الموجهة:<syntaxhighlight lang="rails">
resources :books
</syntaxhighlight>ولديك ملف العرض app/views/books/index.html.erb الذي يحوي:<syntaxhighlight lang="html">
<h1>Books are coming soon!</h1>
</syntaxhighlight>ستصيِّر ريلز العرض app/views/books/index.html.erb عند الانتقال إلى books/ وستشاهد العبارة "Books are coming soon!‎" على شاشتك.

ومع ذلك، لا تكون هذه الشاشة مفيدةً إلا قليلًا، لذلك ستُنشئ قريبًا النموذج <code>Book</code> الخاص بك وتضيف الإجراء <code>index</code> إلى <code>BooksController</code>:<syntaxhighlight lang="rails">
class BooksController < ApplicationController
  def index
    @books = Book.all
  end
end
</syntaxhighlight>لاحظ أننا لا نملك تصييرًا صريحًا في نهاية إجراء الفهرسة (index) وفقًا لمبدأ "العرف فوق الضبط" (convention over configuration). القاعدة هي أنك إذا لم تصيِّر صراحةً شيئًا في نهاية إجراء المتحكم، فسيبحث ريلز تلقائيًا عن القالب <code>action_name.html.erb</code> في مسار عرض المتحكم ويصيِّره. في هذه الحالة، سيصيِّر ريلز الملف app/views/books/index.html.erb.

إذا أردنا إظهار خصائص جميع الكتب في عرضنا، فيمكننا القيام بذلك باستخدام [[Rails/action view overview#.D8.A7.D9.84.D9.82.D8.A7.D9.84.D8.A8 ERB|القالب ERB]] على هذا النحو:<syntaxhighlight lang="html">
<h1>Listing Books</h1>
 
<table>
  <thead>
    <tr>
      <th>Title</th>
      <th>Content</th>
      <th colspan="3"></th>
    </tr>
  </thead>
 
  <tbody>
    <% @books.each do |book| %>
      <tr>
        <td><%= book.title %></td>
        <td><%= book.content %></td>
        <td><%= link_to "Show", book %></td>
        <td><%= link_to "Edit", edit_book_path(book) %></td>
        <td><%= link_to "Destroy", book, method: :delete, data: { confirm: "Are you sure?" } %></td>
      </tr>
    <% end %>
  </tbody>
</table>
 
<br>
 
<%= link_to "New book", new_book_path %>
</syntaxhighlight>'''ملاحظة''': يجرى التصيير الفعلي بواسطة أصناف مشتعبة من النموذج <code>[http://api.rubyonrails.org/v5.2.2/classes/ActionView/Template/Handlers.html ActionView::Template::Handlers]</code>. لا يتعمق هذا الدليل في هذه العملية، ولكن من المهم معرفة أن امتداد الملف في عرضك يتحكم في اختيار معالج القالب.

=== استخدام التابع <code>render</code> ===
في معظم الحالات، ينفِّقذ التابع <code>ActionController::Base.render</code> المهام الشاقَّة في تصيير محتوى التطبيق الخاص بك لاستخدامه من قبل المستعرض. هناك مجموعة متنوعة من الطرق لتخصيص سلوك التابع <code>render</code>. يمكنك تصيير العرض الافتراضي لقالب ريلز، أو قالب محدد، أو ملف، أو شيفرة مضمنة، أو لا شيء على الإطلاق. تستطيع تصيير نص أو JSON أو XML. يمكنك تحديد نوع المحتوى أو حالة HTTP للاستجابة المصيَّرة أيضًا.

'''فائدة''': إذا كنت تريد رؤية النتائج الدقيقة لاستدعاء <code>render</code> دون الحاجة إلى فحصها في متصفح، فيمكنك استدعاء <code>render_to_string</code>. يأخذ هذا التابع بالضبط نفس الخيارات التي يقبلها التابع <code>render</code>، لكنه يعيد سلسلة نصية بدلًا من إعادة إرسال استجابة إلى المتصفح.

==== عرض شكل الحدث ====
إذا أردت تصيير العرض الذي يطابق قالبًا مختلفًا داخل وحدة التحكم نفسها، فيمكنك استخدام <code>render</code> مع اسم العرض نفسه:<syntaxhighlight lang="rails">
def update
  @book = Book.find(params[:id])
  if @book.update(book_params)
    redirect_to(@book)
  else
    render "edit"
  end
end
</syntaxhighlight>في حالة فشل استدعاء <code>update</code>، يؤدي استدعاء الإجراء <code>update</code> في هذا المتحكم إلى تصيير القالب edit.html.erb المنتمي إلى نفس المتحكم.

إذا فَضَّلْتَ ذلك، فيمكنك استخدام رمز بدلًا من سلسلة نصية لتحديد الإجراء المطلوب تصييره:<syntaxhighlight lang="rails">
def update
  @book = Book.find(params[:id])
  if @book.update(book_params)
    redirect_to(@book)
  else
    render :edit
  end
end
</syntaxhighlight>

==== تصيير قالب إجراء من متحكم آخر ====
ماذا لو أردتَ تصيير قالبٍ من متحكم مختلف تمامًا عن ذلك الذي يحتوي على شيفرة الإجراء؟ يمكنك أيضًا فِعل ذلك باستخدام التابع <code>render</code> الذي يقبل المسار الكامل (نسبة إلى <code>app/views</code>) للقالب لتصييره. على سبيل المثال، إذا كنت تُشغِّل شيفرة في المتحكم <code>AdminProductsController</code> توجد في المسار app/controllers/admin، فيمكنك تصيير نتائج الإجراء على قالب في المسار app/views/products بالشكل التالي:<syntaxhighlight lang="rails">
render "products/show"
</syntaxhighlight>يعرف ريلز أن هذا العرض ينتمي إلى متحكم مختلف بسبب محرف الخط المائل المضمن في السلسلة النصية. إذا كنت تريد أن تكون صريحًا، فيمكنك استخدام الخيار <code>:template</code> (الذي كان مطلوبًا في ريلز 2.2 والإصدارات الأقدم):<syntaxhighlight lang="rails">
render template: "products/show"
</syntaxhighlight>

==== تصيير ملف عشوائي ====
يمكن للتابع <code>render</code> أيضًا استخدام عرض يقع خارج تطبيقك كليًّا:<syntaxhighlight lang="rails">
render file: "/u/apps/warehouse_app/current/app/views/products/show"
</syntaxhighlight>يأخذ الخيار <code>:file</code> مسار نظام ملفات مطلق. بالطبع، يجب أن يكون لديك حقوق العرض الذي تريد استخدامه لتصيير محتواه.

'''ملاحظة''': يمكن أن يؤدي استخدام الخيار <code>:file</code> بالتزامن مع إدخالات المستخدمين إلى مشاكل أمنية إذ يمكن للمهاجم استخدام هذا الإجراء للوصول إلى ملفات أمنية حساسة في نظام ملفاتك.

'''ملاحظة''': افتراضيًّا، يصيَّر الملف باستخدام التخطيط الحالي.

'''فائدة''': إذا كنت تُشغَّل ريلز على نظام ويندوز ، يجب استخدام الخيار <code>:file</code> لتصيير ملف، لأن أسماء الملفات في ويندوز لا تملك نفس تنسيق أسماء الملفات في الأنظمة الشبيهة بيونكس.

==== التغليف ====
الطرق الثلاث أعلاه للتصيير (تصيير قالب آخر داخل المتحكم، وتصيير قالب داخل متحكم آخر وتصيير ملف عشوائي موجود في نظام الملفات) هي في الواقع حالات مختلفة لنفس الإجراء.

في الواقع، في الصنف <code>BooksController</code> داخل الإجراء <code>update</code> حيث نريد تصيير قالب التعديل (edit template)، إذا لم يُحَدَّث الكتاب (<code>book</code>) بنجاح، فإن جميع إستدعاءات التابع <code>render</code> التالية ستصيِّر القالب edit.html.erb في المسار views/books:<syntaxhighlight lang="rails">
render :edit
render action: :edit
render "edit"
render "edit.html.erb"
render action: "edit"
render action: "edit.html.erb"
render "books/edit"
render "books/edit.html.erb"
render template: "books/edit"
render template: "books/edit.html.erb"
render "/path/to/rails/app/views/books/edit"
render "/path/to/rails/app/views/books/edit.html.erb"
render file: "/path/to/rails/app/views/books/edit"
render file: "/path/to/rails/app/views/books/edit.html.erb"
</syntaxhighlight>أيٌّ منهم تستخدمه هو في الحقيقة مسألة أسلوب وتوافق، ولكن القاعدة الأساسية هي استخدام أبسط طريقة منطقية للشيفرة التي تكتبها.

==== استخدام <code>render</code> مع الخيار <code>:inline</code> ====
يمكن استخدام التابع <code>render</code> بدون عرض تمامًا، وذلك إذا كنت ترغب في استخدام الخيار <code>:inline</code> لتزويد [[Rails/action view overview#.D8.A7.D9.84.D9.82.D8.A7.D9.84.D8.A8 ERB|القالب ERB]] كجزء من استدعاء الدالة. هذا صحيح تمامًا:<syntaxhighlight lang="rails">
render inline: "<% products.each do |p| %><p><%= p.name %></p><% end %>"
</syntaxhighlight>'''تحذير''': نادرًا ما يكون هناك أي سبب وجيه لاستخدام هذا الخيار. مزج القالب ERB مع المتحكم الخاص بك يُغير اتجاه النمط MVC في ريلز وسيجعل من الصعب على مطورين آخرين تتبع منطق المشروع الخاص بك. استخدم طريقة عرض قالب ERB منفصلة بدلًا من ذلك.

بشكل افتراضي، يستخدم التصيير المضمَّن [[Rails/action view overview#.D8.A7.D9.84.D9.82.D8.A7.D9.84.D8.A8 ERB|القالب ERB]]. يمكنك إجباره على استخدام [[Rails/action view overview#Builder|القالب Builder]] بدلًا من ذلك باستخدام الخيار <code>:type</code>:<syntaxhighlight lang="rails">
render inline: "xml.p {'Horrid coding practice!'}", type: :builder
</syntaxhighlight>

==== تصيير النصوص ====
يمكنك إرسال نص مجرد - بدون تنسيق على الإطلاق - إلى المتصفح مرة أخرى باستخدام الخيار <code>:plain</code> مع التابع <code>render</code>:<syntaxhighlight lang="rails">
render plain: "OK"
</syntaxhighlight>'''فائدة''': تصيير النص المجرد مفيدٌ للغاية عندما ترد على طلبات Ajax أو خدمة الويب التي تتوقع شيئًا غير شيفرة HTML.

'''ملاحظة''': بشكل افتراضي، إذا استخدمت الخيار <code>:plain</code>، فسيُصيَّر النص بدون استخدام التخطيط الحالي. إذا كنت تريد أن يضع ريلز النص في التخطيط الحالي، فأنت بحاجة إلى إضافة الخيار <code>layout: true</code> واستخدام اللاحقة ‎<code>.text.erb</code> لملف التخطيط.

==== تصيير شيفرة HTML ====
يمكنك إرسال سلسلة HTML نصية مرة أخرى إلى المتصفح باستخدام الخيار <code>:html</code> مع التابع <code>render</code>:<syntaxhighlight lang="rails">
render html: helpers.tag.strong('Not Found')
</syntaxhighlight>'''فائدة''': هذا الخيار مفيد عند تصيير قطعة صغير من شيفرة HTML. ومع ذلك، قد ترغب في النظر في نقلها إلى ملف قالب إذا كانت الشيفرة معقدةً.

'''ملاحظة''': عند استخدام الخيار <code>:html</code>، ستُهْرَب كيانات HTML إذا لم تكن السلسلة النصية مكونة (composed) مع واجهات برمجة التطبيقات html_safe-aware.

==== تصيير بيانات بتنسيق JSON ====
إنَّ JSON هو تنسيق بيانات [[JavaScript|جافاسكربت]] تستخدمه العديد من مكتبات Ajax. يحتوي ريلز على دعم مُضمَّن لتحويل الكائنات إلى JSON وتصييرها مجددًا للمتصفح:<syntaxhighlight lang="rails">
render json: @product
</syntaxhighlight>'''تنويه''': لا تحتاج إلى استدعاء <code>to_json</code> في الكائن الذي تريد تصييره. إذا كنت تستخدم الخيار <code>:json</code> ، فسيستدعي التابع <code>render</code> التابعَ <code>to_json</code> لك تلقائيًا.

==== تصيير بيانات بتنسيق XML ====
يحتوي ريلز أيضًا على دعم مضمن لتحويل الكائنات إلى XML وتصييره مرة أخرى للمستدعِي:<syntaxhighlight lang="rails">
render xml: @product
</syntaxhighlight>'''تنويه''': لا تحتاج إلى استدعاء <code>to_xml</code> في الكائن الذي تريد تصييره. إذا كنت تستخدم الخيار <code>:xml</code>، فسوف يستدعي التابع <code>render</code> تلقائيًا <code>to_xml</code> نيابةً عنك.

==== تصيير شيفرات جافاسكربت الصرفة (VanillaJS) ====
بإمكان ريلز أن تصيِّر شيفرات جافاسكربت الصرفة (تدعى vanilla JavaScript أو VanillaJS اختصارًا):<syntaxhighlight lang="rails">
render js: "alert('Hello Rails');"
</syntaxhighlight>سيرسل هذا السلسلة النصية المعطاة إلى المتصفح باستخدام نوع MIME text/javascript.

==== تصيير محتوى خام ====
يمكنك إعادة إرسال محتوى خام إلى المتصفح، دون تعيين أي نوع للمحتوى، باستخدام الخيار <code>:body</code> مع التابع <code>render</code>:<syntaxhighlight lang="rails">
render body: "raw"
</syntaxhighlight>'''تنويه''': يجب استخدام هذا الخيار فقط إذا كنت لا تهتم بنوع محتوى الرد (الاستجابة). استخدام الخيار <code>:plain</code> أو <code>:html</code> قد يكون أكثر ملاءمة معظم الأوقات.

'''ملاحظة''': ما لم يُستبدَل، فإن ردك المُعاد من استعمال الخيار هذا مع التابع <code>render</code> سيكون من النوع text/plain، لأن هذا هو نوع المحتوى الافتراضي لرد Action Dispatch.

==== خيارات أخرى ====
يقبل التابع <code>render</code> عمومًا -إضافةً للخيارات السابقة- خمسةَ خيارات هي:
# <code>:content_type</code>
# <code>:layout</code>
# <code>:location</code>
# <code>:status</code>
# <code>:formats</code>

===== الخيار <code>:content_type</code> =====
بشكل افتراضي، ستخدم (serve) ريلز نتائجَ عملية التصيير مع النوع MIME text/html للمحتوى (أو النوع MIME application/json إذا كنت تستخدم الخيار <code>:json</code> أو النوع MIME application/json إن كنت تستعمل الخيار <code>:xml</code>). هناك أوقات قد ترغب في تغيير هذا، ويمكنك فعل ذلك عن طريق الخيار <code>:content_type</code> بالشكل التالي:<syntaxhighlight lang="rails">
render file: filename, content_type: "application/rss"
</syntaxhighlight>

===== الخيار <code>:layout</code> =====
مع معظم خيارات التابع <code>render</code>، يُعرض المحتوى المصيَّر كجزء من التخطيط الحالي. ستتعلم المزيد حول التخطيطات وكيفية استخدامها لاحقًا في هذا الدليل.

يمكنك استخدام الخيار <code>:layout</code> لإخبار ريلز باستخدام ملف معين كتخطيط للإجراء الحالي:<syntaxhighlight lang="rails">
render layout: "special_layout"
</syntaxhighlight>يمكنك أيضًا إخبار ريلز بالتصيير دون تخطيط على الإطلاق:<syntaxhighlight lang="rails">
render layout: false
</syntaxhighlight>

===== الخيار <code>:location</code> =====
يمكنك استخدام الخيار <code>:location</code> لضبط الترويسة HTTP Location:<syntaxhighlight lang="rails">
render xml: photo, location: photo_url(photo)
</syntaxhighlight>

===== الخيار <code>:status</code> =====
سينشئ ريلز تلقائيًا استجابةً باستخدام رمز حالة HTTP الصحيحة (تكون في معظم الحالات هي "200 OK"). يمكنك استخدام الخيار <code>:status</code> لتغيير هذا السلوك:<syntaxhighlight lang="rails">
render status: 500
render status: :forbidden
</syntaxhighlight>يفهم ريلز كلًا من رمز الحالة الذي هو عددٌ صحيحٌ والرمز المقابل الموضح في الجدول التالي:
{| class="wikitable"
!صنف الرد (الاستجابة)
!رمز حالة HTTP
!الرمز
|-
|Informational
|100
|‎:continue
|-
|
|101
|‎:switching_protocols
|-
|
|102
|‎:processing
|-
|Success
|200
|‎:ok
|-
|
|201
|‎:created
|-
|
|202
|‎:accepted
|-
|
|203
|‎:non_authoritative_information
|-
|
|204
|‎:no_content
|-
|
|205
|‎:reset_content
|-
|
|206
|‎:partial_content
|-
|
|207
|‎:multi_status
|-
|
|208
|‎:already_reported
|-
|
|226
|‎:im_used
|-
|Redirection
|300
|‎:multiple_choices
|-
|
|301
|‎:moved_permanently
|-
|
|302
|‎:found
|-
|
|303
|‎:see_other
|-
|
|304
|‎:not_modified
|-
|
|305
|‎:use_proxy
|-
|
|307
|‎:temporary_redirect
|-
|
|308
|‎:permanent_redirect
|-
|Client Error
|400
|‎:bad_request
|-
|
|401
|‎:unauthorized
|-
|
|402
|‎:payment_required
|-
|
|403
|‎:forbidden
|-
|
|404
|‎:not_found
|-
|
|405
|‎:method_not_allowed
|-
|
|406
|‎:not_acceptable
|-
|
|407
|‎:proxy_authentication_required
|-
|
|408
|‎:request_timeout
|-
|
|409
|‎:conflict
|-
|
|410
|‎:gone
|-
|
|411
|‎:length_required
|-
|
|412
|‎:precondition_failed
|-
|
|413
|‎:payload_too_large
|-
|
|414
|‎:uri_too_long
|-
|
|415
|‎:unsupported_media_type
|-
|
|416
|‎:range_not_satisfiable
|-
|
|417
|‎:expectation_failed
|-
|
|421
|‎:misdirected_request
|-
|
|422
|‎:unprocessable_entity
|-
|
|423
|‎:locked
|-
|
|424
|‎:failed_dependency
|-
|
|426
|‎:upgrade_required
|-
|
|428
|‎:precondition_required
|-
|
|429
|‎:too_many_requests
|-
|
|431
|‎:request_header_fields_too_large
|-
|
|451
|‎:unavailable_for_legal_reasons
|-
|Server Error
|500
|‎:internal_server_error
|-
|
|501
|‎:not_implemented
|-
|
|502
|‎:bad_gateway
|-
|
|503
|‎:service_unavailable
|-
|
|504
|‎:gateway_timeout
|-
|
|505
|‎:http_version_not_supported
|-
|
|506
|‎:variant_also_negotiates
|-
|
|507
|‎:insufficient_storage
|-
|
|508
|‎:loop_detected
|-
|
|510
|‎:not_extended
|-
|
|511
|‎:network_authentication_required
|}
'''ملاحظة''': إذا حاولت تصيير محتوى مع رمز حالة انعدام المحتوى (non-content status code، أي 100-199 أو 204 أو 205 أو 304) ، فسيُحذَف من الاستجابة.

===== الخيار <code>:format</code> =====
يستخدم ريلز التنسيق المحدد في الطلب (أو <code>:html</code> بشكل افتراضي). يمكنك تغيير هذا بتمرير الخيار <code>:formats</code> مع [[Ruby/Symbol|رمز]] أو [[Ruby/Array|مصفوفة]]:<syntaxhighlight lang="rails">
render formats: :xml
render formats: [:json, :xml]

</syntaxhighlight>في حالة عدم وجود قالب بالتنسيق المحدد، فسيرمى الخطأ <code>ActionView::MissingTemplate</code>.

==== البحث عن التخطيطات ====
للعثور على التخطيط الحالي، تبحث ريلز أولًا عن ملف في app/views/layouts بنفس الاسم الأساسي للمتحكم. على سبيل المثال، سيؤدي استخدام [[Rails/action view|Action View]] من الصنف <code>PhotosController</code> إلى استخدام app/views/layouts/photos.html.erb (أو app/views/layouts/photos.builder). إذا لم يكن هناك تخطيط محدد لهذا المتحكم، فستستخدم ريلز app/views/layouts/application.html.erb أو app/views/layouts/application.builder. إذا لم يكن هناك تخطيط ‎<code>.erb</code>، فسوف يستخدم ريلز التخطيط ‎<code>.builder</code> إذا كان موجودًا. توفر ريلز أيضًا عدة طرق لتعيين تخطيطات محددة بدقة أكبر لمتحكمات وأحداث فردية.

===== تحديد التخطيطات للمتحكمات =====
يمكنك تخطي العرف المتعلق بالتخطيط الافتراضي في متحكماتك الخاصة عبر استعمال التصريح <code>layout</code>. فمثلا:<syntaxhighlight lang="rails">
class ProductsController < ApplicationController
  layout "inventory"
  #...
end
</syntaxhighlight>باستخدام هذا التصريح، ستستخدم جميع العروض المصيَّرة بواسطة <code>ProductsController</code> الملف app/views/layouts/inventory.html.erb كتخطيط لها.

لتعيين تخطيط محدد للتطبيق بالكامل، استخدم التصريح <code>layout</code> في الصنف <code>ApplicationController</code> الخاصة بك:<syntaxhighlight lang="rails">
class ApplicationController < ActionController::Base
  layout "main"
  #...
end
</syntaxhighlight>باستخدام هذا التصريح، ستَستخدم جميعُ العروض في التطبيق الملف app/views/layouts/main.html.er تخطيطًا لها.

===== اختيار التخطيطات في وقت التشغيل =====
يمكنك استخدام [[Ruby/Symbol|رمز]] لتأجيل اختيار التخطيط حتى تتم معالجة الطلب:<syntaxhighlight lang="rails">
class ProductsController < ApplicationController
  layout :products_layout
 
  def show
    @product = Product.find(params[:id])
  end
 
  private
    def products_layout
      @current_user.special? ? "special" : "products"
    end
 
end
</syntaxhighlight>الآن، إذا كان المستخدم الحالي مستخدمًا خاصًا، فسيحصل على تخطيط خاص عند عرض أحد المنتجات.

يمكنك حتى استخدام تابع مضمن، مثل <code>[[Ruby/Proc|Proc]]</code>، لتحديد التخطيط. على سبيل المثال، إذا قمت بتمرير كائن من النوع <code>[[Ruby/Proc|Proc]]</code>، فستُعطَى الكتلة التي تعطيها الكائن <code>[[Ruby/Proc|Proc]]</code> النسخة <code>controller</code>، بحيث يمكن تحديد التخطيط بناءً على الطلب الحالي:<syntaxhighlight lang="rails">
class ProductsController < ApplicationController
  layout Proc.new { |controller| controller.request.xhr? ? "popup" : "application" }
end
</syntaxhighlight>

===== التخطيطات الشرطية =====
تدعم التخطيطات المحددة على مستوى المتحكم خيارين هما: <code>:only</code> و <code>:except</code>. تأخذ هذه الخيارات إما اسم تابع، أو مصفوفة من أسماء تابع، يقابل أسماء تابع في المتحكم:<syntaxhighlight lang="rails">
class ProductsController < ApplicationController
  layout "product", except: [:index, :rss]
end
</syntaxhighlight>باستخدام هذا التعريف، سيُستخدَم التخطيط <code>product</code> لكل شيء باستثناء التابعين <code>rss</code> و <code>index</code>.

===== وراثة التخطيط =====
تتوالى (cascade) تصريحات التخطيط لأسفل في التسلسل الهرمي، وتحل تصريحات التخطيط الأكثر تحديدًا دائمًا مكان التصريحات الأكثر عامية. فمثلًا:
* الملف application_controller.rb
<syntaxhighlight lang="rails">
class ApplicationController < ActionController::Base
  layout "main"
end
</syntaxhighlight>
* الملف articles_controller.rb
<syntaxhighlight lang="rails">
class ArticlesController < ApplicationController
end
</syntaxhighlight>
* الملف special_articles_controller.rb
<syntaxhighlight lang="rails">
class SpecialArticlesController < ArticlesController
  layout "special"
end
</syntaxhighlight>
* الملف old_articles_controller.rb
<syntaxhighlight lang="rails">
class OldArticlesController < SpecialArticlesController
  layout false
 
  def show
    @article = Article.find(params[:id])
  end
 
  def index
    @old_articles = Article.older
    render layout: "old"
  end
  # ...
end
</syntaxhighlight>في هذا التطبيق:
* بشكل عام، ستصيَّر العروض في التخطيط <code>main</code>.
* سيستخدم <code>ArticlesController.index</code> التخطيط <code>main</code>.
* سيستخدم <code>SpecialArticlesController.index</code> التخطيط <code>special</code>.
* لن يستخدم <code>OldArticlesController.show</code> أي تخطيط على الإطلاق.
* سيستخدم <code>OldArticlesController.index</code> التخطيط <code>old</code>.

===== وراثة القالب =====
كما هو الحال مع منطق "وراثة التخطيط"، إذا لم يُعثَر على قالب أو جزء منه في المسار التقليدي، فسيبحث المتحكم عن قالب أو جزء منه ليصيِّره في سلسلة الوراثة الخاصة به. فمثلًا:<syntaxhighlight lang="rails">
# app/controllers/application_controller في
class ApplicationController < ActionController::Base
end
 
# app/controllers/admin_controller في
class AdminController < ApplicationController
end
 
# app/controllers/admin/products_controller في
class Admin::ProductsController < AdminController
  def index
  end
end
</syntaxhighlight>سيكون ترتيب البحث للإجراء index/products.index هو:
* /app/views/admin/products
* /app/views/admin
* /app/views/application
وهذا يجعل app/views/application/ مكانًا رائعًا لجزئياتك (partials) المشتركة، والتي يمكن تصييرها في [[Rails/action view overview#.D8.A7.D9.84.D9.82.D8.A7.D9.84.D8.A8 ERB|القالب ERB]] كالتالي:<syntaxhighlight lang="html">
<%# app/views/admin/products/index.html.erb %>
<%= render @products || "empty_list" %>
 
<%# app/views/application/_empty_list.html.erb %>
There are no items in this list <em>yet</em>.

</syntaxhighlight>

===== تجنب أخطاء التصيير المضاعف =====
عاجلًا أم آجلًا، سيشاهد معظم مطوري ريلز رسالة الخطأ "Can only render or redirect once per action" (أي لا يمكن عرض أو إعادة التوجيه إلا مرة واحدة لكل إجراء). في حين أن هذا أمر مزعج، فإنه من السهل نسبيًا إصلاحه. عادة ما يحدث ذلك بسبب سوء فهم أساسي للطريقة التي تعمل التابع <code>render</code> بها.

على سبيل المثال، إليك بعض الشيفرات التي ستؤدي إلى ظهور هذا الخطأ:<syntaxhighlight lang="rails">
def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show"
  end
  render action: "regular_show"
end
</syntaxhighlight>إذا كان الاستدعاء <code>‎@book.special?</code>‎ يعيد القيمة <code>true</code>، سيبدأ ريلز عملية التصيير لتفريغ المتغير <code>book@</code> في العرض <code>special_show</code>. ولكن هذا لن يوقف بقية الشيفرة في الإجراء <code>show</code> من العمل، وعندما تصل ريلز إلى نهاية الإجراء، فإنه سيبدأ في بتصيير العرض <code>regular_show</code>، وإلقاء خطأ. الحل بسيط: تأكد من استدعاء <code>render</code> أو <code>redirect</code> مرةً واحدةً في الوقت ذاته في الشيفرة نفسها. شيء آخر يمكن أن يساعد هو استعمال <code>and return</code>. وإليك نسخة مصححة من المثال السابق:<syntaxhighlight lang="rails">
def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show" and return
  end
  render action: "regular_show"
end
</syntaxhighlight>تأكد من استخدام <code>and return</code> بدلًا من <code>return &&</code> لأن الأخيرة لن تعمل نتيجة أسبقية المعامل في لغة [[Ruby|روبي]].

لاحظ أنَّ التصيير الضمني الذي قام به المتحكم <code>ActionController</code> يكتشف إذا استُدعي <code>render</code>، لذلك ستعمل الشيفرة التالية دون أخطاء:<syntaxhighlight lang="rails">
def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show"
  end
end
</syntaxhighlight>هذا سيصيِّر كتابًا (<code>book</code>) مع ضبط <code>special?‎</code> مع القالب <code>special_show</code>، بينما ستصيَّر الكتب الأخرى باستخدام القالب <code>show</code> الافتراضي.

=== استخدام <code>redirect_to</code> ===
هناك طريقة أخرى لمعالجة الاستجابات العائدة من طلبية HTTP وهي <code>redirect_to</code>. كما شاهدت، يخبر التابع <code>render</code> ريلز أي عرض (أو أصل آخر) سيُستخدَم في إنشاء استجابة. يفعل التابع <code>redirect_to</code> شيئًا مختلفًا تمامًا؛ فهو يخبر المتصفح بإرسال طلبية جديدة لعنوان URL مختلف. على سبيل المثال، يمكنك إعادة التوجيه من أي مكان توجد فيه في شيفرتك إلى فهرس الصور في تطبيقك باستخدام هذا الاستدعاء:<syntaxhighlight lang="rails">
redirect_to photos_url
</syntaxhighlight>يمكنك استخدام <code>redirect_back</code> لإعادة المستخدم إلى الصفحة التي جاء منها للتو. يُسحَب هذا الموقع من الترويسة <code>HTTP_REFERER</code> التي لا يُضمَن أن يضبطها المتصفح، لذلك يجب تمرير <code>fallback_location</code> لاستخدامه في هذه الحالة.<syntaxhighlight lang="rails">
redirect_back(fallback_location: root_path)
</syntaxhighlight>'''ملاحظة''': لا يتوقف كل من <code>redirect_to</code> و <code>redirect_back</code> ويعودان فورًا من تنفيذ التابع، ولكن ببساطة يعينان استجابات HTTP. ستنفَّذ التعليمات البرمجية التي بعدهما في تابعٍ. يمكنك إيقاف التنفيذ عن طريق استعمال <code>return</code> بصراحة أو باستعمال آلية إيقاف أخرى، إذا لزم الأمر.

==== الحصول على رمز حالة مختلف لإعادة التوجيه ====
يستخدم ريلز رمز الحالة HTTP 302 الذي يشير إلى إعادة توجيه مؤقتة (temporary redirect)، عندما تستدعي <code>redirect_to</code>. إذا كنت ترغب في استخدام رمز حالة مختلف، ربما 301، أو إعادة توجيه دائمة، فيمكنك استخدام الخيار <code>:status</code>:<syntaxhighlight lang="rails">
redirect_to photos_path, status: 301
</syntaxhighlight>تمامًا مثل الخيار <code>:status</code> للتابع <code>render</code>، يقبل الخيار <code>:status</code> في التابع <code>redirect_to</code> تسميات الترويسة [[Ruby/Numeric|الرقمية]] أو [[Ruby/Symbol|الرمزية]].

==== الفرق بين <code>render</code> و <code>redirect_to</code> ====
يعتقد المطورون عديمو الخبرة أحيانًا أنَّ التابع <code>redirect_to</code> هو شيء شبيه بالأمر <code>goto</code>، الذي ينقل التنفيذ من مكان إلى آخر في شيفرة ريلز وهذا خطأ بالتأكيد. تتوقف آنذاك شيفرتك عن العمل وتنتظر طلبًا جديدًا للمتصفح؛ ما يحدث هو فقط أنك أخبرت المتصفح بالطلب الذي يجب أن تقدمه بعد ذلك، عن طريق إرسال رمز الحالة HTTP 302.

فكر في الإجراءين التاليين لمعرفة الفرق:<syntaxhighlight lang="rails">
def index
  @books = Book.all
end
 
def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    render action: "index"
  end
end
</syntaxhighlight>مع الشيفرة في هذا النموذج، من المحتمل أن يكون هناك مشكلة إذا كان المتغير <code>book@</code> فارغًا. تذكر أن <code>render :action</code> لا يُشغِّل أي شيفرة في الإجراء المستهدف، لذلك لن يقوم أي شيء بإعداد المتغير <code>books@</code> الذي قد يتطلبه العرض <code>index</code> على الأرجح. إحدى طرق حل هذه المشكلة هي إعادة التوجيه بدلاً من التصيير:<syntaxhighlight lang="rails">
def index
  @books = Book.all
end
 
def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    redirect_to action: :index
  end
end
</syntaxhighlight>باستخدام هذه الشيفرة، سيقدم المتصفح طلبًا جديدًا للصفحة index، وستُشغَّل الشيفرة في التابع <code>index</code>، وسيكون كل شيء على ما يرام.

الجانب السلبي الوحيد لهذه الشيفرة هو أنه يتطلب رحلة ذهابًا وإيابًا إلى المتصفح: طَلَبَ المتصفح الإجراء <code>show</code> مع ‎/books/1، فوجد المتحكم أنه لا توجد كتب، لذلك يرسل المتحكم استجابة لإعادة التوجيه بالرمز ‎302 إلى المتصفح لإخباره بالذهاب إلى /books/؛ يمتثل المتصفح ويرسل طلبًا جديدًا مرةً أخرى إلى المتحكم يطلب فيه الإجراء <code>index</code>، ثم يحصل المتحكم على جميع الكتب من قاعدة البيانات ويصيِّر القالب <code>index</code>، ويعيد إرساله إلى المتصفح الذي يعرضه على شاشتك.

في تطبيق صغير، قد لا يمثل وقت التأخير المضاف في هذه الحالة مشكلةً، إلا أنه أمر يجب التفكير فيه إذا كان وقت الاستجابة مصدر قلق. يمكننا أن نوضح طريقةً واحدةً للتعامل مع هذا الأمر بالشكل التالي:<syntaxhighlight lang="rails">
def index
  @books = Book.all
end
 
def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    @books = Book.all
    flash.now[:alert] = "Your book was not found"
    render "index"
  end
end
</syntaxhighlight>سيكشف هذا عن عدم وجود كتب مع المعرّف المحدد، وينشر (populate) متغير النسخة ‎<code>@books</code> بكافة الكتب في النموذج، ثم يصيِّر القالب index.html.erb مباشرة ويعيده إلى المتصفح برسالة تنبيه (flash alert message) تخبر المستخدم بما قد حدث.

=== استخدام <code>head</code> لإنشاء استجابات من الترويسات فقط ===
يمكن استخدام التابع <code>head</code> لإرسال ردود مع ترويسات فقط للمتصفح. يقبل التابع <code>head</code> عددًا أو رمزًا (اطلع على الجدول المرجعي الموجود في قسم [[Rails/layouts and rendering#.D8.A7.D9.84.D8.AE.D9.8A.D8.A7.D8.B1 :status|الخيار <code>:status</code>]]) الذي يمثل رمز حالة HTTP. يفسَر وسيط الخيارات (options argument) على أنه جدول <code>[[Ruby/Hash|Hash]]</code> يحوي أسماء وقيم الترويسة. على سبيل المثال، يمكنك إعادة ترويسة خطأٍ فقط عبر:<syntaxhighlight lang="rails">
head :bad_request
</syntaxhighlight>سُينتج هذا الترويسة التالية:<syntaxhighlight lang="rails">
HTTP/1.1 400 Bad Request
Connection: close
Date: Sun, 24 Jan 2010 12:15:53 GMT
Transfer-Encoding: chunked
Content-Type: text/html; charset=utf-8
X-Runtime: 0.013483
Set-Cookie: _blog_session=...snip...; path=/; HttpOnly
Cache-Control: no-cache

</syntaxhighlight>أو يمكنك استخدام ترويسات HTTP أخرى لنقل معلومات أخرى عبر:<syntaxhighlight lang="rails">
head :created, location: photo_path(@photo)
</syntaxhighlight>التي ستنتج:<syntaxhighlight lang="rails">
HTTP/1.1 201 Created
Connection: close
Date: Sun, 24 Jan 2010 12:16:44 GMT
Transfer-Encoding: chunked
Location: /photos/1
Content-Type: text/html; charset=utf-8
X-Runtime: 0.083496
Set-Cookie: _blog_session=...snip...; path=/; HttpOnly
Cache-Control: no-cache
</syntaxhighlight>

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

=== مساعدو وسم الأصول ===
يوفر مساعدو وسم الأصول (Asset tag helpers) توابعًا لتوليد شيفرة [[HTML]] تربط عروضًا بتغذية (feed)، وشيفرة جافاسكربت، وأوراق الأنماط، والصور، ومقاطع الفيديو، وتسجيلات الصوت. يوجد ستة مساعدين لوسوم الأصول في ريلز هي:
* <code>auto_discovery_link_tag</code>
* <code>javascript_include_tag</code>
* <code>stylesheet_link_tag</code>
* <code>image_tag</code>
* <code>video_tag</code>
* <code>audio_tag</code>
يمكنك استخدام هذه الوسوم في التخطيطات أو عروض أخرى، على الرغم من أنَّ <code>auto_discovery_link_tag</code> و <code>javascript_include_tag</code> و <code>stylesheet_link_tag</code> تستخدم بشكل شائع ضمن <code>[[HTML/head|<head>]]</code> في أي تخطيط.

'''تحذير''': لا يتحقق مساعدو وسم الأصول من وجود الأصول في المواقع المحددة، إذ يفترضون ببساطة أنك تعرف ما تفعله ويولدون الرابط.

==== ربط التغذيات مع المساعد <code>auto_discovery_link_tag</code> ====
ينشئ المساعد <code>auto_discovery_link_tag</code> شيفرة [[HTML]] يمكن لمعظم المتصفحات وقارئات التغذية استخدامها للكشف عن وجود تغذية RSS أو Atom أو JSON. يأخذ المساعد نوع الرابط (<code>‎:rss</code>، أو ‎<code>:atom</code>، أو ‎<code>:json</code>)، وجدول <code>[[Ruby/Hash|Hash]]</code> من الخيارات التي تُمَرَّر إلى <code>url_for</code>، وجدول <code>[[Ruby/Hash|Hash]]</code> من الخيارات للوسم:<syntaxhighlight lang="rails">
<%= auto_discovery_link_tag(:rss, {action: "feed"},
  {title: "RSS Feed"}) %>
</syntaxhighlight>هناك ثلاثة خيارات متاحة للوسم يمكن استعمالها مع المساعد <code>auto_discovery_link_tag</code> هي:
*<code>:rel</code> تحدد القيمة <code>rel</code> في الرابط. القيمة الافتراضية هي "alternate".
*<code>:type</code> يحدد النوع MIME الواضح. سينشئ ريلز نوع MIME مناسبًا تلقائيًا.
*<code>:title</code> يحدد عنوان الرابط. القيمة الافتراضية هي الأحرف الكبيرة للقيمة <code>:type</code> مثل "ATOM" أو "RSS".

==== ربط ملفات جافاسكربت مع <code>javascript_include_tag</code> ====
يعيد المساعد <code>javascript_include_tag</code> الوسم [[HTML/script|<code><script></code>]] الخاص بلغة [[HTML]] لكل مصدر معطى.

إذا كنت تستخدم ريلز مع تمكين [[Rails/asset pipeline|خط أنابيب الأصول]]، سينشئ هذا المساعد رابطًا إلى /assets/javascripts/ بدلاً من public/javascripts الذي كان مستخدَمًا في الإصدارات السابقة من ريلز. ثم هذا الرابط يُخدَم بواسطة خطا أنابيب الأصول (asset pipeline).

يوضع ملف جافاسكربت داخل أحد تطبيقات ريلز أو محرك ريلز في أحد المواقع الثلاثة:
* <code>app/assets</code>، أو
* <code>lib/assets</code>، أو
* <code>vendor/assets</code>.
شُرحَت هذه المواقع بالتفصيل في قسم تنظيم الأصول في دليل [[Rails/asset pipeline|خط أنابيب الأصول]].

تستطيع تحديد مسار كامل يتعلق بجذر المستند، أو عنوان URL، إذا أردت ذلك. على سبيل المثال، للارتباط بملف JavaScript موجود داخل مجلد يسمى javascripts داخل app/assets، أو lib/assets، أو vendor/assets، يمكنك القيام بذلك:<syntaxhighlight lang="html">
<%= javascript_include_tag "main" %>
</syntaxhighlight>بعد ذلك، سيولد ريلز الوسم <code>[[HTML/script|<script>]]</code> التالي:<syntaxhighlight lang="html">
<script src='/assets/main.js'></script>
</syntaxhighlight>ثم يُقدَّم الطلب إلى هذا الأصل بواسطة الجوهرة Sprockets.

لتضمين ملفات متعددة مثل app/assets/javascripts/main.js و app/assets/javascripts/columns.js في الوقت نفسه، جرب ما يلي:<syntaxhighlight lang="html">
<%= javascript_include_tag "main", "columns" %>
</syntaxhighlight>لتضمين app/assets/javascripts/main.js و app/assets/javascripts/photos/columns.js:<syntaxhighlight lang="html">
<%= javascript_include_tag "main", "/photos/columns" %>
</syntaxhighlight>لتضمين <nowiki>http://example.com/main.js</nowiki>:<syntaxhighlight lang="html">
<%= javascript_include_tag "http://example.com/main.js" %>
</syntaxhighlight>

=== ربط ملفات [[CSS]] باستخدام <code>stylesheet_link_tag</code> ===
يُعيد المساعد <code>stylesheet_link_tag</code> الوسم <code>[[HTML/link|<link>]]</code> لكل مصدر معطى.

إذا كنت تستخدم ريلز مع تمكين [[Rails/asset pipeline|خط أنابيب الأصول]]، فسينشئ هذا المساعد رابطًا إلى /assets/stylesheets/ ثم يُعالَج هذا الرابط بعد ذلك بواسطة الجوهرة Sprockets. يمكن تخزين ملف ورقة الأنماط في أحد المواقع الثلاثة:
* app/assets، أو
* lib/assets، أو 
* vendor/assets.
تستطيع تحديد مسار كامل نسبةً إلى جذر المستند، أو عنوان URL، على سبيل المثال، للارتباط بملف ورقة أنماط موجود داخل مجلد يسمى stylesheets داخل المجلد app/assets، أو lib/assets، أو vendor/assets، يمكنك القيام بذلك:<syntaxhighlight lang="html">
<%= stylesheet_link_tag "main" %>
</syntaxhighlight>لتضمين app/assets/stylesheets/main.css و app/assets/stylesheets/columns.css:<syntaxhighlight lang="html">
<%= stylesheet_link_tag "main", "columns" %>
</syntaxhighlight>لتضمين app/assets/stylesheets/main.css و app/assets/stylesheets/photos/columns.css:<syntaxhighlight lang="html">
<%= stylesheet_link_tag "main", "photos/columns" %>
</syntaxhighlight>لتضمين <nowiki>http://example.com/main.css</nowiki>:<syntaxhighlight lang="html">
<%= stylesheet_link_tag "http://example.com/main.css" %>
</syntaxhighlight>بشكل افتراضي، يُنشئ <code>stylesheet_link_tag</code> روابط مع <code>media="screen" rel="stylesheet"‎</code>. يمكنك تجاوز أيَّا من هذه القيم الافتراضية عن طريق تحديد الخيار المناسب (<code>:media</code>، أو ):<syntaxhighlight lang="html">
<%= stylesheet_link_tag "main_print", media: "print" %>
</syntaxhighlight>

==== ربط الصور باستخدام <code>image_tag</code> ====
ينشئ المساعد <code>image_tag</code> الوسم <code>[[HTML/img|<img /‎>]]</code> إلى الملف المحدد. بشكل افتراضي، تُحمَّل الملفات من public/images.

'''تحذير''': لاحظ أنه يجب عليك تحديد امتداد الصورة.<syntaxhighlight lang="html">
<%= image_tag "header.png" %>
</syntaxhighlight>يمكنك توفير مسار للصورة إذا أردت:<syntaxhighlight lang="html">
<%= image_tag "icons/delete.gif" %>
</syntaxhighlight>يمكنك توفير جدول <code>[[Ruby/Hash|Hash]]</code> من خيارات [[HTML]] الإضافية:<syntaxhighlight lang="html">
<%= image_tag "icons/delete.gif", {height: 45} %>
</syntaxhighlight>يمكنك توفير نص بديل للصورة يُستخدَم إذا أوقف المستخدِم تشغيل الصور في المتصفح. إذا لم تُحدد نص بديل بشكل صريح، فسيُعيَّن افتراضيًا باسم الملف بأحرف كبيرة وبدون اللاحقة. على سبيل المثال، قد تعيد هاتان الصورتان نفس الشيفرة:<syntaxhighlight lang="html">
<%= image_tag "home.gif" %>
<%= image_tag "home.gif", alt: "Home" %>
</syntaxhighlight>يمكنك أيضًا تحديد حجم خاص للصورة عبر التنسيق "{width} x {height}":<syntaxhighlight lang="html">
<%= image_tag "home.gif", size: "50x20" %>
</syntaxhighlight>بالإضافة إلى الخيارات الخاصة المذكورة أعلاه، يمكنك توفير جدول <code>[[Ruby/Hash|Hash]]</code> في النهاية لخيارات HTML القياسية، مثل <code>:class</code>، أو <code>:id</code>، أو <code>:name</code>:<syntaxhighlight lang="html">
<%= image_tag "home.gif", alt: "Go Home",
                          id: "HomeImage",
                          class: "nav_bar" %>
</syntaxhighlight>

==== ربط مقاطع الفيديو مع <code>video_tag</code> ====
ينشئ المساعد <code>video_tag</code> الوسم <code>[[HTML/video|<video>]]</code> الذي وفرته HTML5 لتضمين مقاطع الفيديو. بشكل افتراضي، تُحمَّل الملفات الفيديو من المجلد public/videos.<syntaxhighlight lang="html">
<%= video_tag "movie.ogg" %>
</syntaxhighlight>يُنتِج:<syntaxhighlight lang="html">
<video src="/videos/movie.ogg" />
</syntaxhighlight>مثل <code>image_tag</code>، يمكنك توفير مسار، إما مطلق، أو نسبي إلى المجلد public/videos. بالإضافة إلى ذلك، يمكنك تحديد الحجم عبر التنسيق "‎#{width}x#{height‎}‎" تمامًا مثل <code>image_tag</code>. يمكن أن تحتوي [[HTML/video|وسوم الفيديو]] أيضًا على أي من خيارات [[HTML]] المحددة في النهاية (مثل الخيار <code>:class</code>، أو <code>:id</code>، أو <code>:name</code>).

يدعم وسم الفيديو أيضًا جميع خيارات <code>[[HTML/video|<video>]]</code> من خلال وضع خيارات HTML هذه ضمن جدول <code>[[Ruby/Hash|Hash]]</code> من ضمنها:
* <code>poster: "image_name.png"‎</code>، يوفر صورة لعرضها في واجهة الفيديو قبل بدء تشغيله.
* <code>autoplay: true</code>، يبدأ تشغيل الفيديو عند تحميل الصفحة.
* <code>loop: true</code>، يكرر الفيديو بمجرد انتهاء تشغليه.
* <code>controls: true</code>، يوفر عناصر التحكم التي يوفرها المتصفح للمستخدم للتفاعل مع الفيديو.
* <code>autobuffer: true</code>، سيحمِّل الفيديو الملف مسبقًا للمستخدم أثناء تحميل الصفحة.
يمكنك أيضًا تحديد عدة مقاطع فيديو لتشغيلها بتمرير مصفوفة من مقاطع الفيديو إلى <code>video_tag</code>:<syntaxhighlight lang="html">
<%= video_tag ["trailer.ogg", "movie.ogg"] %>
</syntaxhighlight>هذا سينتج:<syntaxhighlight lang="html">
<video>
  <source src="/videos/trailer.ogg">
  <source src="/videos/movie.ogg">
</video>
</syntaxhighlight>

==== ربط الملفات الصوتية مع <code>audio_tag</code> ====
ينشئ المساعد <code>audio_tag</code> الوسم <code>[[HTML/audio|<audio>]]</code>  على الملف المحدد. بشكل افتراضي، تُحمَّل الملفات من المجلد public/audios.<syntaxhighlight lang="html">
<%= audio_tag "music.mp3" %>
</syntaxhighlight>يمكنك توفير مسار للملف الصوتي إذا كنت ترغب بذلك بالشكل:<syntaxhighlight lang="html">
<%= audio_tag "music/first_song.mp3" %>
</syntaxhighlight>يمكنك أيضًا توفير مجموعة متنوعة من الخيارات، مثل <code>:class</code> و <code>:id</code> ...إلخ.

مثل المساعد <code>video_tag</code>، يحتوي <code>audio_tag</code> على خيارات خاصة هي:
* <code>autoplay: true</code>، يبدأ تشغيل الصوت عند تحميل الصفحة.
* <code>controls: true</code>، يوفر عناصر التحكم التي يوفرها المتصفح للمستخدم للتفاعل مع الصوت.
* <code>autobuffer: true</code>، سيحمل ملف الصوت الملف للمستخدم أثناء تحميل الصفحة.

=== فهم <code>yield</code> ===
في سياق أي تخطيط، يعرِّف <code>yield</code> قسمًا حيث يجب إدراج المحتوى من العرض. تتمثل أبسط طريقة لاستخدام هذا في الحصول على <code>yield</code> واحدٍ يُدرَج فيه محتويات العرض قيد التصيير حاليًا:<syntaxhighlight lang="html">
<html>
  <head>
  </head>
  <body>
  <%= yield %>
  </body>
</html>
</syntaxhighlight>يمكنك أيضًا استعمال <code>yield</code> أكثر من مرة ضمن التخطيط:<syntaxhighlight lang="html">
<html>
  <head>
  <%= yield :head %>
  </head>
  <body>
  <%= yield %>
  </body>
</html>
</syntaxhighlight>سيصيَّر دائمًا الجسم الرئيسي في <code>yield</code> غير المسمى. لتصيير محتوى إلى <code>yield</code> محدد، تستطيع استخدم التابع <code>content_for</code>.

=== استخدام التابع <code>content_for</code> ===
يسمح لك التابع <code>content_for</code> بإدراج محتوى في كتلة <code>yield</code> محددة في تخطيطك. على سبيل المثال، قد يعمل هذا العرض مع التخطيط التي شاهدته للتو:<syntaxhighlight lang="html">
<% content_for :head do %>
  <title>A simple page</title>
<% end %>
 
<p>Hello, Rails!</p>
</syntaxhighlight>ستكون نتيجة تصيير هذه الصفحة في التخطيط المعطى هي شيفرة [[HTML]] التالية:<syntaxhighlight lang="html">
<html>
  <head>
  <title>A simple page</title>
  </head>
  <body>
  <p>Hello, Rails!</p>
  </body>
</html>
</syntaxhighlight>التابع <code>content_for</code> مفيد للغاية عندما يحتوي تخطيطك على مناطق مميزة مثل الأقسام الجانبية (sidebars) والتذييلات التي يجب أن تُدرَج كتلها الخاصة بها. كما يفيد أيضًا في إدراج الوسوم التي تحمّل ملفات [[JavaScript|جافاسكربت]] أو ملفات [[CSS]] الخاصة بالصفحة في رأس تخطيط آخر عام.

=== استخدام الجزئيات ===
القوالب الجزئية - عادة ما تسمى "الجزئيات" (partials) - هي أداة أخرى لتجزئة عملية التصيير إلى أجزاء أكثر قابلية للإدارة. باستخدام جزئية، يمكنك نقل الشيفرة لتصيير جزء معين من الاستجابة لملفها الخاص.

==== تسمية الجزئيات ====
لتصيير جزئية كجزء من عرض، فاستخدم التابع <code>render</code> في العرض:<syntaxhighlight lang="html">
<%= render "menu" %>
</syntaxhighlight>سيؤدي ذلك إلى تصيير ملف يدعى ‎_menu.html.erb في تلك النقطة داخل العرض قيد التصيير. لاحظ الشرطة السفلية البادئة لاسم الملف: تبدأ أسماء الجزئيات بشرطة سفلية لتمييزها عن العروض العادية، رغم أنه يشار إليها بدون الشرطة السفلية. هذا صحيح حتى عند سحب جزء من مجلد آخر:<syntaxhighlight lang="html">
<%= render "shared/menu" %>
</syntaxhighlight>ستسحب (pull) هذه الشيفرة في الجزئية من app/views/shared/_menu.html.erb.

==== استخدام الجزئيات لتبسيط العروض ====
إحدى الطرق لاستخدام الجزئيات هي معاملتهم بشكل مكافئ للمهام الفرعية (subroutines): كطريقة لنقل التفاصيل خارج العرض بحيث يمكنك التحكم بزمام الأمور بسهولة أكبر. على سبيل المثال، قد يكون لديك عرض يبدو كالتالي:<syntaxhighlight lang="html">
<%= render "shared/ad_banner" %>
<h1>Products</h1>
<p>Here are a few of our fine products:</p>
...
<%= render "shared/footer" %>
</syntaxhighlight>هنا، يمكن أن تحتوي كل من الجزئية ‎_ad_banner.html.erb و ‎_footer.html.erb على محتوى مشترك من قبل العديد من الصفحات في تطبيقك. لست بحاجة إلى الاطلاع على تفاصيل هذه الأقسام عند التركيز على صفحة معينة.

كما هو موضح في الأقسام السابقة من هذا الدليل، تعدُّ <code>yield</code> أداةً قويةً جدًا لتنظيف تخطيطاتك. ضع في اعتبارك أنها شيفرة [[Ruby|روبي]] صرفة، لذلك يمكنك استخدامها في كل مكان تقريبا. على سبيل المثال، يمكننا استخدام الجزئيات لتقليل تعريفات تخطيط نموذج لعدة مصادر متشابهة:
* الملف users/index.html.erb
<syntaxhighlight lang="html">
<%= render "shared/search_filters", search: @q do |f| %>
  <p>
    Name contains: <%= f.text_field :name_contains %>
  </p>
<% end %>
</syntaxhighlight>
* الملف roles/index.html.erb
<syntaxhighlight lang="html">
<%= render "shared/search_filters", search: @q do |f| %>
  <p>
    Title contains: <%= f.text_field :title_contains %>
  </p>
<% end %>
</syntaxhighlight>
* الملف shared/_search_filters.html.erb
<syntaxhighlight lang="html">
<%= form_for(search) do |f| %>
  <h1>Search form:</h1>
  <fieldset>
    <%= yield f %>
  </fieldset>
  <p>
    <%= f.submit "Search" %>
  </p>
<% end %>
</syntaxhighlight>بالنسبة للمحتوى الذي جرى مشاركته بين جميع الصفحات في تطبيقك، يمكنك استخدام الجزئيات مباشرة من التخطيطات.

==== التخطيطات الجزئية ====
بإمكان الجزئية استخدام ملف تخطيط خاص بها فقط، تمامًا كما يمكن للعرض استخدام تخطيط محدد خاص به. على سبيل المثال، يمكنك استدعاء جزئية بالشكل التالي:<syntaxhighlight lang="html">
<%= render partial: "link_area", layout: "graybar" %>
</syntaxhighlight>سيبحث هذا عن جزئية اسمها ‎_link_area.html.erb ويصيِّرها باستخدام التخطيط ‎_graybar.html.erb. لاحظ أن التخطيط الخاص بالجزئيات يتبع نفس نمط تسمية الجزئيات نفسها (البدء بشرطة سفلية)، ويوضع في نفس المجلد مع الجزئية التي ينتمي إليها (وليس في مجلد التخطيطات الرئيسي).

لاحظ أيضًا التحديد <code>:‎partial</code> الصريح هذا مطلوب عند تمرير خيارات إضافية مثل الخيار <code>:layout</code>.

==== تمرير متغيرات محلية ====
يمكنك أيضًا تمرير متغيرات محلية إلى الجزئيات، مما يجعلها أكثر قوة ومرونة. على سبيل المثال، يمكنك استخدام هذه التقنية لتقليل التكرار بين الصفحات الجديدة والمعدلَّة، مع الاحتفاظ بقليل من المحتوى المميز:
* الملف new.html.erb
<syntaxhighlight lang="html">
<h1>New zone</h1>
<%= render partial: "form", locals: {zone: @zone} %>
</syntaxhighlight>
* الملف edit.html.erb
<syntaxhighlight lang="html">
<h1>Editing zone</h1>
<%= render partial: "form", locals: {zone: @zone} %>
</syntaxhighlight>
* الملف form.html.erb_
<syntaxhighlight lang="html">
<%= form_for(zone) do |f| %>
  <p>
    <b>Zone name</b><br>
    <%= f.text_field :name %>
  </p>
  <p>
    <%= f.submit %>
  </p>
<% end %>
</syntaxhighlight>رغم أن الجزئية نفسها ستصيِّر في كلا العرضين، فسيعيد مساعد إرسال [[Rails/action view|Action View]] القيمة "Create Zone" للإجراء <code>new</code> والقيمة "Update Zone" للإجراء <code>edit</code>.

لتمرير متغير محلي إلى جزئية في حالات محددة فقط، استخدم <code>local_assigns</code>.
* الملف index.html.erb
<syntaxhighlight lang="html">
<%= render user.articles %>
</syntaxhighlight>
* الملف show.html.erb
<syntaxhighlight lang="html">
<%= render article, full: true %>
</syntaxhighlight>
* الملف article.html.erb_
<syntaxhighlight lang="html">
<h2><%= article.title %></h2>
 
<% if local_assigns[:full] %>
  <%= simple_format article.body %>
<% else %>
  <%= truncate article.body %>
<% end %>
</syntaxhighlight>تمكن هذه الطريقة استخدام الجزئية دون الحاجة إلى التصريح عن جميع المتغيرات المحلية.

تحتوي كل جزئية أيضًا على متغير محلي بنفس اسم الجزئية (باستثناء الشرطة السفلية البادئة). يمكنك تمرير كائن إلى هذا المتغير المحلي عبر الخيار <code>:object</code>:<syntaxhighlight lang="html">
<%= render partial: "customer", object: @new_customer %>
</syntaxhighlight>داخل الجزئية <code>customer</code>، سيشير المتغير <code>customer</code> إلى <code>‎@new_customer</code> من العرض الرئيسي.

إذا كان لديك نسخةً لنموذج لتصييره إلى جزئية، فيمكنك استخدام صيغة مختصرة بالشكل التالي:<syntaxhighlight lang="html">
<%= render @customer %>
</syntaxhighlight>بافتراض أن متغير النسخة ‎<code>@customer</code> يحتوي على نسخة للنموذج <code>Customer</code>، سيستخدم هذا ‎_customer.html.erb لتصييره ثم سيمرر المتغير المحلي <code>customer</code> إلى الجزئية التي ستشير إلى متغير النسخة ‎<code>@customer</code> في العرض الأصلي.

==== تصيير المجموعات ====
الجزئيات مفيدة للغاية في تصيير المجموعات. عند تمريرك مجموعة إلى جزئية عبر الخيار <code>:collection</code>، ستُدرَج الجزئية مرة واحدة لكل عضو في المجموعة:
* الملف index.html.erb
<syntaxhighlight lang="html">
<h1>Products</h1>
<%= render partial: "product", collection: @products %>

</syntaxhighlight>
* الملف product.html.erb_
<syntaxhighlight lang="html">
<p>Product Name: <%= product.name %></p>
</syntaxhighlight>عندما تُستدعى جزئية ما مع مجموعة متعددة، فإن النسخ الفردية للجزئية يكون لها حق الوصول إلى عضو المجموعة الذي يجري تصييره عبر متغير مسمى بعد الجزئية. في هذه الحالة، الجزئية هي <code>product_</code>، وضمن الجزئية <code>product_</code>، يمكنك الإشارة إلى <code>product</code> للحصول على النسخة التي يجري تصييرها.

هناك أيضا اختزال لهذه العملية. بافتراض أن ‎<code>@products</code> عبارة عن مجموعة من نسخ من <code>product</code>، يمكنك ببساطة كتابة هذا في الملف index.html.erb للحصول على النتيجة نفسها:<syntaxhighlight lang="html">
<h1>Products</h1>
<%= render @products %>
</syntaxhighlight>يحدد ريلز اسم الجزئية المراد استخدامها من خلال النظر إلى اسم النموذج في المجموعة. في الواقع، يمكنك حتى إنشاء مجموعة غير متجانسة وعرضها بهذه الطريقة، وسوف يختار ريلز الجزئية المناسبة لكل عضو في المجموعة:
* الملف index.html.erb
<syntaxhighlight lang="html">
<h1>Contacts</h1>
<%= render [customer1, employee1, customer2, employee2] %>
</syntaxhighlight>
* الملف customers/_customer.html.erb
<syntaxhighlight lang="html">
<p>Customer: <%= customer.name %></p>
</syntaxhighlight>
* الملف employees/_employee.html.erb
<syntaxhighlight lang="html">
<p>Employee: <%= employee.name %></p>
</syntaxhighlight>في هذه الحالة، سيستخدم ريلز الجزئية <code>customer</code> أو الجزئية <code>employee</code> بما بناسب كل عضو في المجموعة.

إذا كانت المجموعة فارغة، سيعيد التابع render القيمة <code>nil</code>، لذلك يجب أن يكون من السهل توفير محتوى بديل.<syntaxhighlight lang="html">
<h1>Products</h1>
<%= render(@products) || "There are no products available." %>
</syntaxhighlight>

==== المتغيرات المحلية ====
لاستخدام اسم متغير محلي مخصص داخل الجزئية، حدد الخيار <code>:as</code> أثناء استدعاء الجزئية:<syntaxhighlight lang="html">
<%= render partial: "product", collection: @products, as: :item %>
</syntaxhighlight>باستخدام هذا التغيير، يمكنك الوصول إلى نسخة للمجموعة ‎<code>@products</code> باعتباره المتغير المحلي <code>item</code> داخل الجزئية.

يمكنك أيضًا تمرير متغيرات محلية عشوائية إلى أي جزئية تصييرها مع الخيار المحليين <code>locals: {}‎</code>:<syntaxhighlight lang="html">
<%= render partial: "product", collection: @products,
           as: :item, locals: {title: "Products Page"} %>
</syntaxhighlight>في هذه الحالة، ستحصل الجزئية على حق الوصول إلى المتغير المحلي <code>title</code> ذي القيمة "Products Page".

'''تنويه''': يجعل ريلز أيضًا متغير عداد (counter variable) متاحًا داخل جزئية تستدعى بواسطة المجموعة، يسمى بعد عنوان الجزئية متبوعًا بالعبارة <code>counter_</code>. على سبيل المثال، عند عرض مجموعة باسم <code>products@</code>، يمكن للجزئية product.html.erb_ الوصول إلى المتغير <code>product_counter</code> الذي يفهرس عدد العناصر التي صُيِّرَت داخل العرض المرفق.

يمكنك أيضًا تحديد جزئية ثانية لتصييرها بين نسخ الجزئية الرئيسية باستخدام الخيار <code>:spacer_template</code>.

==== قوالب الفصل ====
<syntaxhighlight lang="html">
<%= render partial: @products, spacer_template: "product_ruler" %>
</syntaxhighlight>ستصيِّر ريلز الجزئية <code>product_ruler_</code> (دون تمرير بيانات إليها) بين كل زوج من الجزئيات <code>product_</code>.

==== مجموعة التخطيطات الجزئية ====
عند تصيير المجموعات، يمكن أيضًا استخدام الخيار <code>:layout</code>:<syntaxhighlight lang="html">
<%= render partial: "product", collection: @products, layout: "special_layout" %>
</syntaxhighlight>سيُصيَّر التخطيط مع الجزئية لكل عنصر في المجموعة. سيتوفر المتغيران <code>object</code> و <code>object_counter</code> الحاليان في التخطيط أيضًا، تمامًا كما هما داخل الجزئية.

=== استخدام التخطيطات المتداخلة ===
قد تجد أن تطبيقك يتطلب تخطيطًا يختلف قليلًا عن تخطيط تطبيقك العادي لدعم متحكم معين. بدلًا من تكرار التخطيط الرئيسي وتعديله، يمكنك القيام بذلك باستخدام التخطيطات المتداخلة (nested layouts، تسمى أحيانًا القوالب الفرعية [sub-templates]). هنا مثال:

لنفترض أن لديك التخطيط <code>ApplicationController</code> التالي:
* الملف app/views/layouts/application.html.erb
<syntaxhighlight lang="html">
<html>
<head>
  <title><%= @page_title or "Page Title" %></title>
  <%= stylesheet_link_tag "layout" %>
  <style><%= yield :stylesheets %></style>
</head>
<body>
  <div id="top_menu">Top menu items here</div>
  <div id="menu">Menu items here</div>
  <div id="content"><%= content_for?(:content) ? yield(:content) : yield %></div>
</body>
</html>
</syntaxhighlight>في الصفحات المولدة بواسطة <code>NewsController</code>، تريد إخفاء القائمة العلوية وإضافة قائمة يمينية:
* الملف app/views/layouts/news.html.erb
<syntaxhighlight lang="html">
<% content_for :stylesheets do %>
  #top_menu {display: none}
  #right_menu {float: right; background-color: yellow; color: black}
<% end %>
<% content_for :content do %>
  <div id="right_menu">Right menu items here</div>
  <%= content_for?(:news_content) ? yield(:news_content) : yield %>
<% end %>
<%= render template: "layouts/application" %>

</syntaxhighlight>انتهينا! ستَستخدم العروض <code>News</code> التخطيط الجديد، الذي يخفي القائمة العلوية ويضيف قائمة يمينية جديدة في العنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code> ذي المعرف <code>content</code>.

هناك عدة طرق للحصول على نتائج مشابهة مع أنظمة التخطيط الفرعية المختلفة باستخدام هذه التقنية. لاحظ أنه لا يوجد حد في مستويات التداخل. يمكن استخدام التابع <code>ActionView::render</code> عبر <code>render template: 'layouts/news'‎</code> لتأسيس تخطيط جديدة في التخطيط <code>News</code>. إذا كنت متأكدًا من أنك لن تفرِّع (subtemplate) قالبًا من التخطيط <code>News</code>، فيمكنك تبديل <code>yield</code> مكان <code>content_for?(:news_content) ? yield(:news_content) : yield</code> ببساطة.

== مصادر ==
* [https://guides.rubyonrails.org/layouts_and_rendering.html صفحة Layouts and Rendering in Rails في توثيق Ruby On Rails الرسمي.]