المكتبة التقنية ←

سلوك واجهة قابل لإعادة الاستخدام باستخدام data-*

English version

Custom HTML attributes can be a useful way to mark which controls should share a behavior. The attribute describes intent; your JavaScript implements the behavior.

For a text item, an illustrative marker is:

data-auto-upper="Y"

A delegated listener can recognize marked text inputs:

document.addEventListener('change', function (event) {
  const input = event.target;
  if (input instanceof HTMLInputElement &&
      input.matches('[data-auto-upper="Y"]')) {
    input.value = input.value.toUpperCase();
  }
});

Check the rendered markup of the specific APEX item type. The attribute must reach the element your code targets. Do not assume that every plug-in or composite item renders the same structure.

Separate presentation from business rules

This example changes a browser value. It does not validate the value on the server, persist it, or automatically synchronize every APEX item implementation. If uppercase is a business requirement, normalize and validate it in the server-side write path too.

Prefer the native placeholder property when all you need is a placeholder. Use a small documented set of custom markers for behavior that is genuinely shared. Test keyboard use, screen readers, and partial refreshes.

Editorial correction: data- attributes do not activate APEX behavior by themselves. A server process changing session state on page load is also different from reacting to a user's later typing.*

النسخة العربية

Custom HTML Attributes طريقة مفيدة لتحديد العناصر اللي هتشترك في سلوك واحد. الـAttribute بيوصف المطلوب، وJavaScript هو اللي بينفذ السلوك.

مثلًا، تقدر تضيف العلامة دي لعنصر نصي:

data-auto-upper="Y"

وتستخدم Event Listener عام يتعرف على العناصر دي ويحول قيمتها إلى حروف كبيرة عند التغيير:

document.addEventListener('change', function (event) {
  const input = event.target;
  if (input instanceof HTMLInputElement &&
      input.matches('[data-auto-upper="Y"]')) {
    input.value = input.value.toUpperCase();
  }
});

راجع الـHTML الناتج من نوع الـItem المستخدم؛ لازم الـAttribute يوصل للعنصر اللي الكود بيستهدفه. ما تفترضش إن كل Plugin أو Item مركب له نفس بنية الـDOM.

افصل الواجهة عن قواعد العمل

المثال يغير قيمة داخل المتصفح. لا يحفظها في قاعدة البيانات ولا يحقق منها على السيرفر، ولا يضمن مزامنة كل أنواع APEX Items. لو تحويل الحروف قاعدة عمل، طبّق التطبيع والتحقق في مسار الحفظ على السيرفر أيضًا.

لو محتاج Placeholder فقط، استخدم الخاصية الأصلية. وخلي الـCustom Markers قليلة وموثقة للسلوك المتكرر فعلًا. اختبر الكيبورد وقارئ الشاشة والـPartial Refresh.

تصحيح تحريري: data- لا تفعّل سلوكًا داخل APEX وحدها، وتغيير Session State في Page Load مختلف عن التفاعل مع كتابة المستخدم بعد تحميل الصفحة.*