تخطى إلى المحتوى
Home » المقالات » دليل المبتدئين لـ Salesforce Apex: فهم الـ Enumerators

دليل المبتدئين لـ Salesforce Apex: فهم الـ Enumerators

أهلاً يا coding crew! رجعتلكم ببوست جديد في سلسلة “Beginner’s Guide to Salesforce Apex”. في البوستات اللي فاتت شرحنا أساسيات الـ primitive data types والـ collections في Apex (بالإنجليزي). دلوقتي جاهزين ندخل على عالم الـ enumerators السحري. هنفهم يعني إيه، وإزاي نستخدمها، وليه هي مهمة جداً في Salesforce Apex. فاربطوا الأحزمة، ويلا نكمل رحلة تعلم Apex بأمثلة سهلة وسيناريوهات من الحياة الحقيقية. 🚀

مقدمة عن الـ Enumerators

الـ Enumerators، واللي بنقولها كمان enums، ميزة قوية في Salesforce Apex بتخليكم تعرّفوا مجموعة من الـ constants ليها أسامي.

الـ Enums مفيدة لما يبقى عندكم مجموعة قيم ثابتة بتمثل حالات أو تصنيفات أو أنواع معينة جوه الـ application بتاعكم. لما تستخدموا الـ enums، الكود بيبقى أوضح وأكتر تنظيماً وفرصة الغلط فيه أقل.

إزاي نعرّف Enumerator

عشان تعرّفوا enumerator، استخدموا الـ keyword اللي اسمها enum، وبعدها اسم الـ enumeration، وبعدين مجموعة الـ constants بأساميها جوه أقواس معقوفة {}:

public enum DaysOfWeek { //DaysOfWeek is the enumerator name
    MONDAY, 
    TUESDAY, 
    WEDNESDAY, 
    THURSDAY, 
    FRIDAY, 
    SATURDAY, 
    SUNDAY
}

في المثال ده عرّفنا enum اسمه DaysOfWeek بيمثل أيام الأسبوع. الـ enum فيه سبع قيم، كل واحدة بتمثل يوم مختلف.

استخدام الـ Enumerators في Apex

بعد ما فهمنا الأساسيات، تعالوا نشوف إزاي نستخدم الـ enums في كود Apex. الـ Enums في Apex ممكن تستخدموها بطرق كتير، زي إنكم تدوا بيها قيم للـ variables، أو تستخدموها في الـ switch statements، أو حتى تلفوا عليها بـ loop.

استخدام الـ enumerators عشان ندي قيم للـ variables

في المثال ده بندي قيمة FRIDAY لـ variable اسمه today.

//FRIDAY is one of the value pre-defined in the enumerator. 
//You can use any of the pre-defined value ONLY
DaysOfWeek today = DaysOfWeek.FRIDAY;
system.debug('Check today Value: '+today);
صورة من الـ Developer Console بتوضح استخدام Enumerator عشان ندي قيمة لـ variable

ملاحظات على استخدام الـ enumerators عشان ندي قيم للـ variables

لما تستخدموا Enumerator variable، مينفعش تدوله قيمة مش موجودة في مجموعة القيم المعرّفة. لو حاولتوا، هيطلعلكم error شبه ده:

//DaysOfWeek doesn't have TestDayName value
DaysOfWeek today = DaysOfWeek.TestDayName; 
system.debug('Check today Value: '+today);
رسالة error في الـ Developer Console لما نستخدم قيمة مش موجودة في الـ Enumerator
صورة لرسالة الـ error في الـ Developer Console

ولو حاولتوا تدوا الـ Enumerator variable قيمة من data type تاني على طول، زي String مثلاً، هيطلعلكم الـ error ده:

//trying to assign directly a string value
DaysOfWeek today = 'Invalid_Day_Name'; 
system.debug('Check today Value: '+today);
رسالة error في الـ Developer Console لما ندي Enumerator variable قيمة String
صورة لرسالة الـ error في الـ Developer Console

استخدام الـ enumerators في الـ switch statements

الـ Enums بتشتغل حلو جداً مع الـ switch statements. بصوا على المثال ده:

DaysOfWeek today = DaysOfWeek.FRIDAY;
switch on today {
    when MONDAY{
        System.debug('It\'s Monday');
    }
    when TUESDAY{
        System.debug('It\'s Tuesday');
    }
    when WEDNESDAY{
        System.debug('It\'s Wednesday');
    }
    when THURSDAY{
        System.debug('It\'s Thursday');
    }
    when FRIDAY{
        System.debug('It\'s Friday');
    }
    when SATURDAY{
        System.debug('It\'s Saturday');
    }
    when SUNDAY{
        System.debug('It\'s Sunday');
    }
    when else{
        System.debug('Invalid day of the week');
    }
}

في المثال ده عرّفنا DaysOfWeek variable اسمه today وإدّيناه القيمة DaysOfWeek.FRIDAY. وبعدين استخدمنا switch statement عشان نشيك على قيمة today ونطبع رسالة بتقول النهارده إيه.

صورة من الـ Developer Console بتوضح استخدام Enumerator في switch case

ملاحظات على استخدام الـ enumerators مع الـ switch statements

  1. الـ expression اللي بعد switch on في الـ switch statement لازم يكون من نفس نوع الـ enum: في المثال اللي فات استخدمنا today واللي نوعه “DaysOfWeek“
  2. مينفعش تحطوا في الـ when أي قيمة برة القيم المعرّفة في الـ enum: في المثال اللي فات استخدمنا “Monday” و”TUESDAY” وهكذا… لو استخدمتوا قيمة برة الـ enum زي “TestDayName”، هيطلعلكم الـ error ده في الـ developer console:
switch on today {
    when TestDayName{
        System.debug('It\'s Monday');
    }
    when TUESDAY{
        System.debug('It\'s Tuesday');
    }
    when WEDNESDAY{
صورة من الـ Developer Console لرسالة error بسبب قيمة Enumerator غلط في الـ Switch Case
صورة لرسالة الـ error في الـ Developer Console

إزاي نعمل Loop على الـ enums

تقدروا كمان تستخدموا الـ method اللي اسمها values() بتاعة الـ enum class عشان تجيبوا array فيها كل القيم الممكنة، وتلفوا عليها بـ for loop زي المثال ده:

for (DaysOfWeek dayValue : DaysOfWeek.values()) {
    System.debug('Check Day Name : '+ dayValue);
}

في المثال ده بنستخدم الـ method اللي اسمها values() بتاعة الـ DaysOfWeek enum عشان نجيب array فيها كل القيم المعرّفة. وبعدين بنستخدم for loop عشان نلف على كل قيمة في الـ array، ونطبع كل day باستخدام System.debug().

لما نشغل الكود ده، الـ output في الـ Developer Console هيبقى كده:

صورة من الـ Developer Console بتوضح إزاي نلف على قيم الـ Enumerator ونطبعها

ليه الـ Enumerators مهمة

أكيد دلوقتي بتسألوا ليه الـ enumerators مهمة كده في Salesforce Apex. دي شوية أسباب:

1. الـ Type-safety:

  • الـ Enums بتوفر type safety، لأنها بتضمن إن القيم الصح بس هي اللي ممكن تتحط في الـ variables، أو تتبعت كـ arguments للـ methods، أو تتستخدم في الـ Switch Cases.
  • مثلاً: لما حاولنا نستخدم قيمة enum غلط في الـ switch case، طلعلنا error لما شغلنا الكود في الـ developer console.
  • ومثال تاني: لما حاولنا نستخدم قيمة enum غلط وإحنا بندي قيمة لـ variable، طلعلنا error لما شغلنا الكود في الـ developer console.

2. سهولة الصيانة (Maintainability)

  • الـ Enumerators بتسهل صيانة الكود، لأن تعريف القيم الثابتة بيبقى في مكان واحد.
  • لو محتاجين تضيفوا قيمة جديدة للـ enum، بتضيفوها في مكان واحد، وهتبقى متاحة أوتوماتيك في كل الكود.
  • وده بيقلل فرصة الأخطاء اللي بتحصل من قيم متكررة أو مش متطابقة.

3. تنظيم الكود

استخدام الـ enumerators في الكود بيساعد في تنظيمه، لأنه بيجمع الـ constants اللي ليها علاقة ببعض مع بعض، فالكود يبقى أسهل في الصيانة والقراية.

4. وضوح الكود (Readability)

الـ Enums بتخلي الكود أوضح، لأنها بتدي أسامي ليها معنى للقيم الثابتة. مثلاً:

  • ساعات بتتعاملوا مع external system بيستخدم قيم خاصة بيه عشان يمثل الـ status بتاع الـ object، زي [0,1,2]، ومش بإيدكم تغيروا القيم دي. في الحالة دي، برضه فكرة كويسة تستخدموا enum بأسامي ليها معنى في كود الـ Apex، عشان الكود يبقى أوضح ويشرح نفسه.
  • عشان تربطوا القيم اللي جاية من الـ external system بالـ enum بتاعكم، تقدروا تعملوا mapping بين القيم الخارجية والقيم اللي بتقابلها في الـ enum. مثلاً، نفترض إن الـ external system بيستخدم 0 و1 و2 عشان يمثل الـ status بتاع object، وعايزين تربطوهم بالـ ObjectStatus enum اللي قيمه ACTIVE وINACTIVE وDELETED. تقدروا تعملوا mapping كده:
public enum ObjectStatus {
    ACTIVE,
    INACTIVE,
    DELETED
}

public static ObjectStatus mapExternalStatus(Integer externalStatus) {
    Map<Integer, ObjectStatus> statusMap = new Map<Integer, ObjectStatus>{
        0 => ObjectStatus.ACTIVE,
        1 => ObjectStatus.INACTIVE,
        2 => ObjectStatus.DELETED
    };
    return statusMap.get(externalStatus);
}

في المثال ده عملنا static method اسمها mapExternalStatus بتاخد Integer parameter بيمثل قيمة الـ status الخارجية. الـ method بتستخدم Map عشان تربط القيم الخارجية بالقيم اللي بتقابلها في الـ enum، وبترجع القيمة المقابلة.

عشان تستخدموا الـ method دي، هتجيبوا الأول قيمة الـ status من الـ external system، وبعدين تنادوا mapExternalStatus عشان تحولها للقيمة اللي بتقابلها في الـ enum. مثلاً:

// Assume externalStatusValue is retrieved from the external system
Integer externalStatusValue = 1;

ObjectStatus status = mapExternalStatus(externalStatusValue);
if (status == ObjectStatus.ACTIVE) {
    // Do something if the object is active
    System.debug('ACTIVE!!');
} else if (status == ObjectStatus.INACTIVE) {
    // Do something if the object is inactive
    System.debug('INACTIVE!!');
} else if (status == ObjectStatus.DELETED) {
    // Do something if the object is deleted
    System.debug('DELETED!!');
}
صورة من الـ Developer Console لمثال تحويل قيمة جاية من external system لقيمة enumerator واضحة
الـ Developer Console طبع Inactive لأننا افترضنا إن القيمة اللي جاية من الـ external system هي 1، ودي بتقابل الـ status بتاع Inactive

Enumerators جاهزة من Salesforce

Salesforce بيوفر كذا Enumerator جاهز تقدروا تستخدموه في كود الـ Apex. الـ Enumerators دي معمولة عشان تسهل عليكم التعامل مع قيم شائعة في Salesforce، زي الـ record types والـ user roles.

تعالوا نشوف الأمثلة دي:

1. الـ TriggerOperation Enum

الـ TriggerOperation Enumerators بنستخدمها في الـ Apex triggers عشان نعرف نوع الـ DML operation اللي بتحصل على الـ record. مفيدة لما تكتبوا logic مخصوص لكل نوع DML operation، زي before insert وafter insert وbefore update وafter update وbefore delete وafter delete وbefore undelete وafter undelete.

من طرق استخدام الـ TriggerOperation Enumerators إنكم تعملوا switch case على الـ property اللي اسمها Trigger.operationType. كده تقدروا تنادوا الـ trigger handler operation المناسبة لكل DML operation بتحصل على الـ record، سواء كانت before insert أو after insert أو before update أو after update أو before delete أو after delete أو before undelete أو after undelete.

trigger AccountTrigger on Account (after insert, after update) {

    switch on Trigger.operationType{
        when AFTER_INSERT{
            //do after insert stuff
        }
        when AFTER_UPDATE{
            //Do after update stuff
        } 

    }
}

2. System.RoundingMode

الـ System.RoundingMode هو Enumerator في Salesforce Apex بيمثل طرق التقريب المختلفة للأرقام العشرية. القيم الـ Decimal في Apex ممكن تتقرب لفوق، أو لتحت، أو لأقرب قيمة، حسب طريقة التقريب اللي بتحددوها.

بصوا على الـ resources عشان تشوفوا كل القيم الممكنة للـ enumerator ده.

Decimal value = 0.5;
Decimal halfUp = value.setScale(0, System.RoundingMode.HALF_UP);
Decimal halfDown = value.setScale(0, System.RoundingMode.HALF_DOWN);

System.debug('Original value: ' + value); // Output: Original value: 0.5
System.debug('HALF_UP value: ' + halfUp); // Output: HALF_UP value: 1
System.debug('HALF_DOWN value: ' + halfDown); // Output: HALF_DOWN value: 0
صورة من الـ Developer Console لنتيجة استخدام System.RoundingMode
الـ Output في الـ Developer Console

الـ Enumerator Methods

1. الـ values Method

الـ method اللي اسمها values() بنستخدمها عشان نجيب array فيها كل قيم الـ Enumerator بنفس الترتيب اللي اتعرّفت بيه.

enum FruitType {
    APPLE,
    BANANA,
    ORANGE,
    PINEAPPLE
}

System.debug(FruitType.values()); 
صورة من الـ Developer Console لنتيجة الـ values() method
الـ Output في الـ Developer Console للـ Enum Values() Method

الـ method دي ممكن تستخدموها عشان تلفوا على كل القيم الممكنة للـ Enumerator وتعملوا حاجة معينة، زي إنكم تبنوا picklist values مخصوصة لـ custom LWC أو Visualforce page.

2. الـ valueOf(string enumStr) Method

الـ method دي بنستخدمها عشان نحول string لقيمة Enumerator.

public enum Fruit {APPLE,BANANA,ORANGE}
Fruit fruitEnum = Fruit.valueOf('banana');
System.debug('Check Enum : '+fruitEnum); 
صورة من الـ Developer Console لنتيجة الـ valueOf() method
الـ Output في الـ Developer Console للـ Enum valueOf() Method

الـ method اللي اسمها valueOf() ممكن تفيدكم في مواقف كتير محتاجين فيها تحولوا string لقيمة Enumerator. مثلاً، لو بتاخدوا input من المستخدم لقيمة Enumerator، تقدروا تستخدموا valueOf() عشان تتأكدوا إن الـ input ده قيمة صحيحة في الـ Enumerator.

public enum Fruit {APPLE,BANANA,ORANGE}
Fruit fruitEnum = Fruit.valueOf('watermelon');
System.debug('Check Enum : '+fruitEnum); 
رسالة error في الـ Developer Console لما valueOf() تاخد قيمة مش موجودة في الـ Enum
صورة لرسالة الـ error في الـ Developer Console

3. الـ name Method

بترجع اسم قيمة الـ Enumerator كـ string.

enum DaysOfWeek {
    MONDAY,
    TUESDAY,
    WEDNESDAY,
    THURSDAY,
    FRIDAY,
    SATURDAY,
    SUNDAY
}

DaysOfWeek today = DaysOfWeek.SATURDAY;
String dayName = today.name(); // Returns "SATURDAY"
System.debug('Day Name Text Value: '+dayName);
صورة من الـ Developer Console لنتيجة الـ name() method
الـ Output في الـ Developer Console للـ Enum name() Method

الـ method دي مفيدة في مواقف كتير محتاجين فيها نتعامل مع اسم قيمة الـ Enumerator، زي إننا نعرض قيم الـ Enumerator في الـ user interface:

  • لما تبنوا custom user interface فيه input field أو picklist معتمد على Enumerator، تقدروا تستخدموا name() عشان تجيبوا اسم كل قيمة وتعرضوه للمستخدم.
  • مثلاً، لو عندكم Enumerator لأنواع الفاكهة، تقدروا تستخدموا name() عشان تعرضوا اسم كل فاكهة في picklist.

4. الـ ordinal Method

بترجع ترتيب قيمة الـ Enumerator في لستة القيم، والعد بيبدأ من صفر.

enum Months {
    JANUARY,
    FEBRUARY,
    MARCH,
    APRIL,
    MAY,
    JUNE,
    JULY,
    AUGUST,
    SEPTEMBER,
    OCTOBER,
    NOVEMBER,
    DECEMBER
}

Months currentMonth = Months.JUNE;
Integer monthNumber = currentMonth.ordinal(); // Returns 5
System.debug('check monthNumber: '+monthNumber);
صورة من الـ Developer Console لنتيجة الـ ordinal() method
الـ Output في الـ Developer Console للـ Enum ordinal() Method

الـ method دي مفيدة في مواقف كتير، زي:

  1. ترتيب قيم الـ Enumerator: لو عندكم لستة قيم معتمدة على Enumerator ومحتاجين ترتبوها حسب مكانها، تقدروا تستخدموا ordinal() عشان تقارنوا أماكن القيم وترتبوها.
  2. حسابات معتمدة على مكان القيمة: لو مكان قيمة الـ Enumerator ليه معنى معين، تقدروا تستخدموا ordinal() عشان تعملوا حسابات على أساس المكان ده.

الخلاصة

زي ما شفتوا، الـ enumerators (enums) أداة قوية بتساعدكم تخلوا الكود أوضح، وأسهل في الصيانة، وفيه type-safety. أتمنى البوست ده يكون وضحلكم يعني إيه enumerators، وإزاي تستخدموها، وليه هي مهمة.

متنسوش تتمرنوا على استخدام الـ enums في الـ Salesforce Apex projects بتاعتكم، وكملوا دوروا على طرق جديدة تخلوا بيها الكود أحسن. وخليكم متابعين لمواضيع تانية حلوة في سلسلة “Beginner’s Guide to Salesforce Apex”. Happy coding! 🚀

مصادر مفيدة (Resources)

  1. Enums Apex Developer Guide
  2. Enum Methods
  3. TriggerOperation Enum
  4. Rounding Mode

Join the conversation

لن يتم نشر عنوان بريدك الإلكتروني. الحقول الإلزامية مشار إليها بـ *