RABL

RABL (Ruby API Builder Language) هو نظام قوالب روبي مخصص لـ Rails و Padrino لتوليد JSON، XML، MessagePack، PList و BSON. عند استخدام طريقة 'to_json' الخاصة بـ ActiveRecord، أجد نفسي أرغب في حل أكثر تعبيرًا وقوة لتوليد واجهات برمجة التطبيقات (APIs). ويكون ذلك صحيحًا بشكل خاص عندما يكون تمثيل JSON معقدًا أو لا يتطابق مع المخطط الدقيق المحدد في قاعدة البيانات.

على وجه الخصوص، أرغب بسهولة في:

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

أي شخص جرب طريقة 'to_json' المستخدمة في ActiveRecord لتوليد استجابة JSON قد شعر بألم هذا النهج التقييدي. RABL هو نظام قوالب عام تم إنشاؤه لحل هذه المشكلات من خلال معالجة توليد استجابة API بطريقة جديدة تمامًا.

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

تغييرات جوهرية

• الإصدار v0.8.0 (تم الإصدار في 14 فبراير 2013) يزيل الاعتماد على multi_json ويعتمد على Oj (أو JSON) كمحلل JSON. يبسط الكود، ويزيل تبعية، لكن قد ترغب في إزالة أي إشارات إلى MultiJson.

• الإصدار v0.6.14 (تم الإصدار في 28 يونيو 2012) يتطلب استخدام render_views مع RSpec لاختبار القوالب. وإلا، فإن المتحكم (controller) سيمرر ببساطة أمر render كما يفعل مع قوالب ERB.

التثبيت

تثبيت RABL كـ gem:``` gem install rabl

أو أضف إلى Gemfile الخاص بك:```ruby
# Gemfile
gem 'rabl'
# Also add either `oj` or `yajl-ruby` as the JSON parser
gem 'oj'

وقم بتشغيل bundle install لتثبيت التبعية.

إذا كنت تستخدم Rails 2.3.8 (وما فوق) أو Rails 3.X أو Padrino، فإن RABL يعمل دون أي تكوين.

هام: مع Padrino، تأكد من أن gem rabl مدرج بعد padrino gem في ملف Gemfile، وإلا فلن يتم تسجيل Rabl بشكل صحيح كمحرك قوالب.

مع Sinatra، أو أي إطار عمل آخر قائم على tilt، قم ببساطة بتسجيل:```ruby Rabl.register!

وسيتم تهيئة RABL وتكون جاهزة للاستخدام. لاستخدامها مع Sinatra، راجع دليل [Sinatra Usage](https://github.com/nesquena/rabl/wiki/Setup-for-Sinatra).

## نظرة عامة ##

يمكنك استخدام RABL لإنشاء واجهات برمجة تطبيقات تعتمد على JSON وXML من أي كائن Ruby. مع RABL، يتم اشتقاق البيانات عادةً بشكل أساسي من النماذج (غير مرتبطة بـ ORM) ويتم وصف تمثيل مخرجات API داخل قالب عرض باستخدام DSL بسيط للغة Ruby. يتيح لك ذلك الحفاظ على بياناتك منفصلة عن JSON أو XML التي ترغب في إخراجها.

بعد تثبيت RABL (الموضح أعلاه)، يمكنك إنشاء قالب عرض RABL ثم عرض القالب من تطبيقات Sinatra أو Padrino أو Rails الخاصة بك من وحدة التحكم (أو المسار) بسهولة بالغة. باستخدام [Padrino](http://padrinorb.com) كمثال، بافتراض أن لديك نموذج `Post` مملوء بمنشورات المدونة، يمكنك عرض تمثيل API (كل من JSON وXML) عن طريق إنشاء مسار:```ruby
# app/app.rb
get "/posts", :provides => [:json, :xml] do
  @user = current_user
  @posts = Post.order("id DESC")
  render "posts/index"
end

ثم يمكننا إنشاء قالب RABL التالي للتعبير عن مخرجات API الخاصة بـ @posts:```ruby

app/views/posts/index.rabl

collection @posts attributes :id, :title, :subject child(:user) { attributes :full_name } node(:read) { |post| post.read_by?(@user) }

والتي ستخرج JSON أو XML التالي عند زيارة `http://localhost:3000/posts.json````js
[{  "post" :
  {
    "id" : 5, title: "...", subject: "...",
    "user" : { full_name : "..." },
    "read" : true
  }
}]

هذه نظرة عامة أساسية ولكن هناك الكثير لتراه مثل الأجزاء الجزئية، الوراثة، العقد المخصصة، إلخ. اقرأ التفاصيل الكاملة لـ RABL أدناه.

التكوين

صُمم RABL ليتطلب القليل من التكوين أو لا يتطلبه للعمل. هذا هو الحال في معظم السيناريوهات، ولكن اعتمادًا على احتياجاتك، قد ترغب في تعيين التكوينات العامة التالية في تطبيقك (هذه الكتلة اختيارية تمامًا):```ruby

config/initializers/rabl_init.rb

require 'rabl' Rabl.configure do |config|

Commented as these are defaults

config.cache_all_output = false

config.cache_sources = Rails.env != 'development' # Defaults to false

config.cache_engine = Rabl::CacheEngine.new # Defaults to Rails cache

config.perform_caching = false

config.escape_all_output = false

config.json_engine = nil # Class with #dump class method (defaults JSON)

config.msgpack_engine = nil # Defaults to ::MessagePack

config.bson_engine = nil # Defaults to ::BSON

config.plist_engine = nil # Defaults to ::Plist::Emit

config.include_json_root = true

config.include_msgpack_root = true

config.include_bson_root = true

config.include_plist_root = true

config.include_xml_root = false

config.include_child_root = true

config.enable_json_callbacks = false

config.xml_options = { :dasherize => true, :skip_types => false }

config.view_paths = []

config.raise_on_missing_attribute = true # Defaults to false

config.replace_nil_values_with_empty_strings = true # Defaults to false

end

كل خيار يحدد سلوكًا مرتبطًا بمخرجات RABL. إذا تم تعطيل `include_json_root`، فإن ذلك يزيل العقدة الجذرية لكل كائن جذر في المخرجات، و `enable_json_callbacks` يمكّن دعم الإخراج بنمط 'jsonp' callback إذا كان الطلب الوارد يحتوي على معامل 'callback'.

إذا تم تعيين `include_child_root` إلى false، فإن الكائنات الفرعية في الرد لن تتضمن عقدة جذرية افتراضيًا. يتيح لك ذلك ضبط بنية الرد المطلوبة بشكل أدق.

إذا تم تعيين `cache_engine`، فيجب عليك تعيينه إلى فئة تحتوي على طريقة `fetch`. راجع [المحرك الافتراضي](https://github.com/nesquena/rabl/blob/master/lib/rabl/cache_engine.rb) للحصول على مثال.

إذا تم تعيين `perform_caching` إلى `true` فسيتم تنفيذ التخزين المؤقت. يمكنك تجاهل هذا الخيار إذا كنت تستخدم Rails، فهو مماثل لـ Rails `config.action_controller.perform_caching`

إذا تم تعيين `cache_sources` إلى `true`، فسيتم تخزين عمليات البحث عن القوالب مؤقتًا لتحسين الأداء. يمكن إعادة تعيين ذاكرة التخزين المؤقت يدويًا عن طريق تشغيل `Rabl.reset_source_cache!` داخل تطبيقك.

إذا تم تعيين `cache_all_output` إلى `true`، فسيتم تخزين كل قالب بما في ذلك كل قالب فردي يُستخدم كجزء من مجموعة بشكل منفصل. بالإضافة إلى ذلك، سيتم تخزين أي شيء داخل child و glue و partial بشكل منفصل. لتخزين قالب واحد فقط، راجع القسم المسمى 'Caching' أدناه.

إذا تم تعيين `escape_all_output` إلى `true` وكان ActiveSupport متاحًا، فسيتم ترميز مخرجات السمات باستخدام [ERB::Util.html_escape](http://corelib.rubyonrails.org/classes/ERB/Util.html). لن يتم ترميز العُقد المخصصة، استخدم `ERB::Util.h(value)`.

إذا تم تعيين `view_paths` إلى مسار، فسيتم التحقق من مسار العرض هذا لكل قالب rabl داخل تطبيقك. أضف إلى هذا المسار خاصة عند تضمين Rabl في محرك واستخدام مسارات العرض داخل تطبيق Rails آخر.

إذا تم تعيين `raise_on_missing_attribute` إلى `true`، فسيتم إطلاق RuntimeError كلما حاول Rabl عرض سمة غير موجودة. وإلا، سيتم ببساطة حذف السمة. تعيين هذا إلى true أثناء التطوير قد يساعد في زيادة متانة الكود الخاص بك، لكن استخدام `true` في كود الإنتاج غير موصى به.

إذا تم تعيين `replace_nil_values_with_empty_strings` إلى `true`، فسيتم تحويل جميع القيم التي تكون `nil` وعادةً ما تظهر كـ `null` في الرد إلى سلاسل فارغة.

إذا كنت ترغب في استخدام [oj](https://github.com/ohler55/oj) كمحرك ترميز JSON الأساسي، فما عليك سوى إضافته إلى ملف Gemfile الخاص بك:```ruby
# Gemfile
gem 'oj'

وسيستخدم RABL تلك المحرّك تلقائيًا لتشفير استجابات JSON الخاصة بك. قم بتعيين محرّك json_engine مخصص خاص بك والذي يُعرّف طريقة dump أو encode لتحويل بيانات Ruby إلى JSON:```ruby config.json_engine = ActiveSupport::JSON

### تكوين التنسيق ###