عرض مصدر Rails/active model basics

<noinclude>{{DISPLAYTITLE:أساسيات Active Model في ريلز}}</noinclude>
[[تصنيف:Rails]]
[[تصنيف:Rails Models]]
يجب أن يوفر لك هذا الدليل كل ما تحتاج إليه للبدء في استخدام أصناف Model. يسمح [[Rails/active model|Active Model]] لمساعدي [[Rails/action pack|Action Pack]] بالتفاعل مع كائنات [[Ruby|روبي]] الصرفة. يساعد Active Model أيضًا على إنشاء [[Rails/active record basics#.D8.A7.D9.84.D8.B3.D8.AC.D9.84 .D8.A7.D9.84.D9.81.D8.B9.D8.A7.D9.84 .D9.83.D8.A5.D8.B7.D8.A7.D8.B1 .D8.B9.D9.85.D9.84 ORM|قواعد بيانات ORM]] مخصصة للاستخدام خارج إطار ريلز.

بعد قراءة هذا الدليل، ستتعلم:
* كيف يعمل نموذج [[Rails/active record|Active Record]].
* كيف تعمل [[Rails/active record callbacks|ردود النداء]] و<nowiki/>[[Rails/active record validations|عمليات التحقق]].
* كيف تعمل المُسَلسِلات (serializers).
* كيف يتكامل [[Rails/active model|Active Model]] مع [[Rails/i18n|إطار تدويل]] ريلز (i18n).

== مقدمة ==
[[Rails/active model|Active Model]] هو مكتبة تحتوي على وحدات مختلفة تستخدم في تطوير الأصناف التي تحتاج إلى بعض الميزات الموجودة في [[Rails/active record|Active Record]]. بعض هذه الوحدات مشروحة أدناه.

=== توابع الخاصيات ===
تضيف الوحدة <code>ActiveModel::AttributeMethods</code> البادئات واللاحقة المخصصة إلى توابع صنف. تُستخدَم عن طريق تحديد البادئات واللاحقات وأي توابع ستستخدمهم على الكائن.<syntaxhighlight lang="rails">
class Person
  include ActiveModel::AttributeMethods
 
  attribute_method_prefix 'reset_'
  attribute_method_suffix '_highest?'
  define_attribute_methods 'age'
 
  attr_accessor :age
 
  private
    def reset_attribute(attribute)
      send("#{attribute}=", 0)
    end
 
    def attribute_highest?(attribute)
      send(attribute) > 100
    end
end
 
person = Person.new
person.age = 110
person.age_highest?  # => true
person.reset_age     # => 0
person.age_highest?  # => false
</syntaxhighlight>

=== ردود النداء ===
تعطي الوحدة <code>ActiveModel::Callbacks</code> ردود نداء بنمط [[Rails/active record|Active Record]]. هذا يوفر القدرة على تحديد ردود النداء التي تعمل في الأوقات المناسبة. بعد تحديد ردود النداء، يمكنك تغليفها قبل، وبعد، وحول توابع مخصصة.<syntaxhighlight lang="rails">
class Person
  extend ActiveModel::Callbacks
 
  define_model_callbacks :update
 
  before_update :reset_me
 
  def update
    run_callbacks(:update) do
      # على كائن update يُستدعَى هذا التابع عند استدعاء
    end
  end
 
  def reset_me
    # على كائن update يُستدعى هذا التابع عند استدعاء
    # before_update كما يعرف رد النداء
  end
end
</syntaxhighlight>

=== التحويلات ===
إذا عرَّف صنفٌ التابعين <code>?persisted</code> و <code>id</code>، فيمكنك تضمين الوحدة <code>ActiveModel::Conversion</code> في ذلك الصنف، واستدعاء توابع التحويل في ريلز على كائنات ذلك الصنف.<syntaxhighlight lang="rails">
class Person
  include ActiveModel::Conversion
 
  def persisted?
    false
  end
 
  def id
    nil
  end
end
 
person = Person.new
person.to_model == person  # => true
person.to_key              # => nil
person.to_param            # => nil
</syntaxhighlight>

=== التلوث ===
يصبح الكائن متلوثًا عندما يمر بتغيير واحد أو أكثر لإحدى خاصياته دون حفظها. تعطي الوحدة <code>ActiveModel::Dirty</code> القدرة على التحقق ما إذا تغير كائن أم لا. كما أن لديه خاصية تستند على توابع الوصول (accessor methods). دعنا نفترض وجود الصنف <code>Person</code> مع الخاصيتين <code>first_name</code> و <code>last_name</code>:<syntaxhighlight lang="rails">
class Person
  include ActiveModel::Dirty
  define_attribute_methods :first_name, :last_name
 
  def first_name
    @first_name
  end
 
  def first_name=(value)
    first_name_will_change!
    @first_name = value
  end
 
  def last_name
    @last_name
  end
 
  def last_name=(value)
    last_name_will_change!
    @last_name = value
  end
 
  def save
    # do save work...
    changes_applied
  end
end
</syntaxhighlight>

==== الاستعلام عن الكائن مباشرة من أجل قائمة جميع خاصياته التي تغيرت ====
<syntaxhighlight lang="rails">
person = Person.new
person.changed? # => false

person.first_name = "First Name"
person.first_name # => "First Name"

# إذا كان أي من الخاصيات تحتوي على تغييرات لم تحفظ true يعيد القيمة
person.changed? # => true

# يعيد قائمة بالخاصيات التي تغيرت قبل الحفظ
person.changed # => ["first_name"]

# للخاصيات التي تغيرت مع قيمها الأصلية Hash يعيد جدول
person.changed_attributes # => {"first_name"=>nil}

# للتغييرات، مع أسماء الخاصيات كمفاتيح Hash يعيد جدول 
# والقيم كمصفوفة للقيم القديمة والجديدة لهذا الحقل
person.changes # => {"first_name"=>[nil, "First Name"]}


</syntaxhighlight>

==== توابع الوصول المستندة على الخاصية ====
تتبع ما إذا كان قد تغيرت خاصية معينة أم لا:<syntaxhighlight lang="rails">
# attr_name_changed?
person.first_name # => "First Name"
person.first_name_changed? # => true

</syntaxhighlight>تتبع القيمة السابقة للخاصية:<syntaxhighlight lang="rails">
# attr_name_was accessor
person.first_name_was # => nil
</syntaxhighlight>تتبع كل من القيمة السابقة والحالية للخاصية التي تغيرت. يعيد التابع مصفوفة في حالة تغييرها، وإلا يعيد القيمة <code>nil</code>:<syntaxhighlight lang="rails">
# attr_name_change
person.first_name_change # => [nil, "First Name"]
person.last_name_change # => nil
</syntaxhighlight>

=== التحقق من الصحة ===
تضيف الوحدة <code>ActiveModel::Validations</code> القدرة على التحقق من صحة الكائنات كما في [[Rails/active record|Active Record]].<syntaxhighlight lang="rails">

class Person
  include ActiveModel::Validations
 
  attr_accessor :name, :email, :token
 
  validates :name, presence: true
  validates_format_of :email, with: /\A([^\s]+)((?:[-a-z0-9]\.)[a-z]{2,})\z/i
  validates! :token, presence: true
end
 
person = Person.new
person.token = "2b1f325"
person.valid?                        # => false
person.name = 'vishnu'
person.email = 'me'
person.valid?                        # => false
person.email = 'me@vishnuatrai.com'
person.valid?                        # => true
person.token = nil
person.valid?                        # => raises ActiveModel::StrictValidationFailed
</syntaxhighlight>

=== التسمية ===
تضيف الوحدة <code>ActiveModel::Naming</code> عددًا من توابع الأصناف التي تجعل من السهل إدارة التسمية والتوجيه. تحدد الوحدة تابع الصنف <code>class_name</code> الذي سيعرِّف عددًا من توابع الوصول (accessors) باستخدام بعض توابع <code>ActiveSupport::Inflector</code>.<syntaxhighlight lang="rails">
class Person
  extend ActiveModel::Naming
end
 
Person.model_name.name                # => "Person"
Person.model_name.singular            # => "person"
Person.model_name.plural              # => "people"
Person.model_name.element             # => "person"
Person.model_name.human               # => "Person"
Person.model_name.collection          # => "people"
Person.model_name.param_key           # => "person"
Person.model_name.i18n_key            # => :person
Person.model_name.route_key           # => "people"
Person.model_name.singular_route_key  # => "person"

</syntaxhighlight>

=== الوحدة Model ===
تضيف الوحدة <code>ActiveModel::Model</code> المقدرة للصنف على العمل مع [[Rails/action pack|Action Pack]] و [[Rails/action view|Action View]] مباشرةً خارج الصندوق.<syntaxhighlight lang="rails">
class EmailContact
  include ActiveModel::Model
 
  attr_accessor :name, :email, :message
  validates :name, :email, :message, presence: true
 
  def deliver
    if valid?
      # توصيل بريد إلكتروني
    end
  end
end
</syntaxhighlight>عند تضمين <code>ActiveModel::Model</code>، تحصل على بعض الميزات مثل:
* استبطان اسم نموذج (model name introspection).
* التحويلات.
* الترجمة.
* التحقق من الصحة.
كما يمنحك القدرة على تهيئة كائن بجدول <code>[[Ruby/Hash|Hash]]</code> من الخاصيات، مثل أي كائن [[Rails/active record|Active Record]]:<syntaxhighlight lang="rails">
email_contact = EmailContact.new(name: 'David',
                                 email: 'david@example.com',
                                 message: 'Hello World')
email_contact.name       # => 'David'
email_contact.email      # => 'david@example.com'
email_contact.valid?     # => true
email_contact.persisted? # => false
</syntaxhighlight>يمكن استخدام أي صنف يتضمن <code>ActiveModel::Model</code> مع <code>form_for</code>، و <code>render</code>، وأي تابع مساعد آخر [[Rails/action view|Action View]]، تمامًا مثل كائنات [[Rails/active record|Active Record]].

=== السَلسَلة ===
توفر الوحدة <code>ActiveModel::Serialization</code> عملية السَلسَلة الأساسية للكائن الخاص بك. يلزمك التصريح عن خاصيات <code>Hash</code> تحتوي على الخاصيات التي تريد إجراء عملية سَلسَلة (serialize) لها. يجب أن تكون الخاصيات سلاسل نصية، وليست رموزًا.<syntaxhighlight lang="rails">
class Person
  include ActiveModel::Serialization
 
  attr_accessor :name
 
  def attributes
    {'name' => nil}
  end
end
</syntaxhighlight>الآن يمكنك الوصول إلى [[Ruby/Hash|جدول Hash]] مُسَلسَل لكائنك باستخدام التابع <code>serializable_hash</code>:<syntaxhighlight lang="rails">
person = Person.new
person.serializable_hash   # => {"name"=>nil}
person.name = "Bob"
person.serializable_hash   # => {"name"=>"Bob"}

</syntaxhighlight>

==== <code>ActiveModel::Serializers</code> ====
كما يوفر [[Rails/active model|Active Model]] الوحدة <code>ActiveModel::Serializers::JSON</code> لإجراء عملية السَلسَلة أو إلغائها مع صيغة JSON. يتضمن هذا النموذج تلقائيًا الوحدة <code>ActiveModel::Serialization</code> الذي تحدثنا عنه آنفًا.

===== <code>ActiveModel::Serializers::JSON</code> =====
لاستخدام <code>ActiveModel::Serializers::JSON</code>، تحتاج فقط إلى تغيير الوحدة التي تضمِّنها من <code>ActiveModel::Serialization</code> إلى <code>ActiveModel::Serializers::JSON</code>.<syntaxhighlight lang="rails">
class Person
  include ActiveModel::Serializers::JSON
 
  attr_accessor :name
 
  def attributes
    {'name' => nil}
  end
end
</syntaxhighlight>التابع <code>as_json</code> مشابه للتابع <code>serializable_hash</code>، إذ يوفر [[Ruby/Hash|جدول Hash]] يمثِّل النموذج.<syntaxhighlight lang="rails">
person = Person.new
person.as_json # => {"name"=>nil}
person.name = "Bob"
person.as_json # => {"name"=>"Bob"}
</syntaxhighlight>يمكنك أيضًا تعريف الخاصيات لنموذج من سلسلة JSON نصية. ومع ذلك، تحتاج إلى تعريف التابع <code>attributes=‎</code> في الصنف الخاصة بك:<syntaxhighlight lang="rails">
class Person
  include ActiveModel::Serializers::JSON
 
  attr_accessor :name
 
  def attributes=(hash)
    hash.each do |key, value|
      send("#{key}=", value)
    end
  end
 
  def attributes
    {'name' => nil}
  end
end
</syntaxhighlight>الآن، من الممكن إنشاء نسخة من <code>Person</code> وتعيين الخاصيات باستخدام <code>from_json</code>.<syntaxhighlight lang="rails">
json = { name: 'Bob' }.to_json
person = Person.new
person.from_json(json) # => #<Person:0x00000100c773f0 @name="Bob">
person.name            # => "Bob"

</syntaxhighlight>

=== الترجمة ===
توفر الوحدة <code>ActiveModel::Translation</code> التكامل بين الكائن الخاص بك و<nowiki/>[[Rails/i18n|إطار تدويل ريلز]] (i18n).<syntaxhighlight lang="rails">
class Person
  extend ActiveModel::Translation
end
</syntaxhighlight>باستخدام التابع <code>human_attribute_name</code>، يمكنك تحويل أسماء الخاصيات إلى تنسيق أكثر قابلية للقراءة. يُعرف التنسيق القابل للقراءة في ملف(ات) المحلية الخاص بك.
* الملف config/locales/app.pt-BR.yml
<syntaxhighlight lang="text">
pt-BR:
  activemodel:
    attributes:
      person:
        name: 'Nome'
</syntaxhighlight><syntaxhighlight lang="rails">
Person.human_attribute_name('name') # => "Nome"
</syntaxhighlight>

=== اختبارات الأداة Lint ===
يتيح لك النموذج <code>ActiveModel::Lint::Tests</code> التحقق ما إذا كان كائنٌ ما متوافقًا مع واجهة [[Rails/active model|Active Model]] البرمجية:
* الملف app/models/person.rb
<syntaxhighlight lang="rails">
class Person
  include ActiveModel::Model
end
</syntaxhighlight>
* الملف test/models/person_test.rb
<syntaxhighlight lang="rails">
require 'test_helper'
 
class PersonTest < ActiveSupport::TestCase
  include ActiveModel::Lint::Tests
 
  setup do
    @model = Person.new
  end
end
</syntaxhighlight><syntaxhighlight lang="shell">
$ rails test
 
Run options: --seed 14596
 
# Running:
 
......
 
Finished in 0.024899s, 240.9735 runs/s, 1204.8677 assertions/s.
 
6 runs, 30 assertions, 0 failures, 0 errors, 0 skips
</syntaxhighlight>الكائن غير مطلوب لتنفيذ جميع واجهات برمجة التطبيقات لكي يعمل مع Action Pack. تعتزم هذه الوحدة فقط توفير الإرشاد في حال كنت تريد جميع الميزات من خارج الصندوق.

=== <code>SecurePassword</code> ===
توفر الوحدة <code>ActiveModel::SecurePassword</code> طريقةً لتخزين أي كلمة مرور بشكل آمن في نموذج مشفر (encrypted form). عند تضمين هذه الوحدة، يُوفَّر تابع الصنف <code>has_secure_password</code> الذي يعرِّف تابع الوصول <code>password</code> مع بعض عمليات التحقق من الصحة عليه.

==== المتطلبات ====
تعتمد الوحدة <code>ActiveModel::SecurePassword</code> على [https://github.com/codahale/bcrypt-ruby bcrypt]، لذا ضمِّن هذه الجوهرة في Gemfile الخاص بك لاستخدام الوحدة <code>ActiveModel::SecurePassword</code> بشكل صحيح. لجعلها تعمل، يجب أن يكون لدى النموذج تابع وصول يدعى <code>password_digest</code>. سيضيف <code>has_secure_password</code> عمليات التحقق التالية على تابع الوصول <code>password</code>:

1 - كلمة المرور يجب أن تكون موجودة.

2 - يجب أن تكون كلمة المرور مساوية لتأكيدها (يُمرَّر <code>password_confirmation</code> المعطى).

3 - الحد الأقصى لطول كلمة المرور هو 72 (مطلوب بواسطة <code>bcrypt</code> التي تعتمد <code>ActiveModel::SecurePassword</code> عليه).

==== أمثلة ====
<syntaxhighlight lang="rails">
class Person
 include ActiveModel::SecurePassword
 has_secure_password
 attr_accessor :password_digest
End

person = Person.new

# عندما تكون كلمة المرور فارغة
person.valid? # => false

# عندما لا يتطابق التأكيد مع كلمة المرور
person.password = 'aditya'
person.password_confirmation = 'nomatch'
person.valid? # => false

# عندما يتجاوز طول كلمة المرور 72
person.password = person.password_confirmation = 'a' * 100
person.valid? # => false

# password_confirmation عندما تتوفر كلمة المرور فقط بدون 
person.password = 'aditya'
person.valid? # => true

# عندما تُمرَّر جميع عمليات التحقق من الصحة
person.password = person.password_confirmation = 'aditya'
person.valid? # => true
</syntaxhighlight>

== المصادر ==
* [https://guides.rubyonrails.org/active_model_basics.html صفحة Active Model Basics في توثيق Ruby On Rails الرسمي.]