3.11 استخدام توجيهات القالب

3.11 استخدام توجيهات القالب

استخدم توجيهات القالب Template Directives للتحكم في كيفية معالجة القوالب التي تدعم سلاسل الاستبدال.

3.11.1 حول توجيهات القالب

تعرف على توجيهات القالب Template Directives.

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

لتحديد ما إذا كانت السمة تدعم توجيهات القالب، تتضمن تعليمات مصمم الصفحات النص “يدعم توجيهات القالب من جانب العميل” أو “يدعم توجيهات القالب من جانب الخادم”.

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

3.11.2 توجيهات حالة الشرط

استخدم if التوجيه لإظهار النص بشكل مشروط استنادًا إلى ما إذا كان العنصر أو العمود يحتوي على قيمة.

بناء الجملة:

{if [!][?|=]NAME/}
TRUE_TEMPLATE_TEXT
{elseif [!][?|=]NAME2/}
ELSE_TRUE_TEMPLATE_TEXT
{else/}
FALSE_TEMPLATE_TEXT
{endif/}

حيث:

• NAME هو عنصر أو اسم عمود أو سمة مكون قالب.
• إذا كانت القيمة صحيحة، فسيتم إخراج النص التالي.
• القيمة تكون خاطئة إذا كانت سلسلة فارغة أو ‘ F‘ أو ‘ N‘ أو ‘ 0‘.
• أية قيمة ليست خاطئة فهي صحيحة.
• إذا كان NAME تم وضع علامة تعجب (!) قبله، فسيتم إلغاء المنطق ومعالجة نص القالب التالي إذا كانت القيمة خاطئة.
• تكون القيمة خاطئة إذا كانت عبارة عن سلسلة فارغة بعد تقليم المسافات البادئة واللاحقة.

يتعامل تعليمة ifالشرط مع كلٍّ من الاختبارات الفارغة (أو غير الفارغة) واختبارات الصواب/الخطأ المنطقية (باستخدام قواعد قيم الصواب/الخطأ الحرفية مثل ‘ Y'/'N') في آنٍ واحد. يؤدي هذا إلى حدوث ارتباك في حالات نادرة، حيث يكون الهدف هو اختبار القيمة غير الفارغة، ولكن القيمة الفعلية هي ‘N’، وهي قيمة غير فارغة، ولكنها تُعتبر خاطئة. '?'يمكن استخدام عامل البادئة الاختياري لاختبار ما '='إذا كانت القيمة فارغة بشكل صريح.

يوضح الجدول التالي ملخصًا لتوجيهات الحالة المتاحة.

توجيه الحالة	وصف	تعبير PL/SQL
{if MYITEM/}	MYITEMيجب أن يحتوي على قيمة ولا يمكن أن تكون القيمة ‘F’أو ‘N’أو أو ‘0’.	:MYITEM is not null and upper( :MYITEM ) not in ( 'F', 'N', '0' )
{if ?MYITEM/}	MYITEMيجب أن يحتوي على قيمة.	:MYITEM is not null
{if !MYITEM/}	MYITEMيمكن أن يكون فارغًا أو يحتوي على ‘F’أو ‘N’أو ‘0’.	:MYITEM is null or upper( :MYITEM ) in ( 'F', 'N', '0' )
{if !?MYITEM/}	MYITEMفارغ.	:MYITEM is null
{if =MYITEM/}	MYITEMفارغ أو لا يحتوي على ‘F’أو ‘N’أو ‘0’.	:MYITEM is null or upper( :MYITEM ) not in ( 'F', 'N', '0' )
{if !=MYITEM/}	MYITEMيحتوي على قيمة تساوي ‘F’أو ‘N’أو أو ‘0’.	upper( :MYITEM ) in ( 'F', 'N', '0' )
{if MYITEM%assigned/}	&COLUMN_NAME.مفيد عند الحاجة إلى إخراج متسق لعدة صفوف من البيانات. عند تعيين قيمة مثل MYITEM، قد تكون فارغة لبعض الصفوف بعد تطبيق الاستبدالات. %assignedفي هذه الحالة، يكون الشرط صحيحًا لجميع الصفوف.	غير متوفر

يمكن أن يكون هناك صفر أو أكثر elseifمن التوجيهات. elseif التوجيهان else اختياريان. يجب أن تكون التوجيهات بالترتيب الموضح.

مثال

يحتوي تقرير البطاقات على عمود باسم DESCRIPTION. ستعرض سمة تعبير HTML التالية الوصف إذا لم يكن فارغًا (سلسلة نصية فارغة)، وإلا “لا يوجد وصف”.

{if DESCRIPTION/}&DESCRIPTION.{else/}No description.{endif/}

3.11.3 توجيهات حالة الحالة

استخدم caseالتوجيه لإظهار النص استنادًا إلى قيمة عنصر أو عمود.

بناء الجملة:

{case NAME/}
{when STRING1/}
TEMPLATE_TEXT1
{when STRING2/}
TEMPLATE_TEXT2
{otherwise/}
TEMPLATE_TEXT
{endcase/}

هذه NAMEسمة عنصر أو اسم عمود أو مكون قالب. تُقارن القيمة بالسلاسل النصية بعد كل whenتوجيه، وإذا كانت متساوية، يُخرج النص التالي. إذا لم whenيتطابق أي توجيه، يُخرج النص الذي يلي otherwiseالتوجيه، إن وُجد. تُحذف المسافات البادئة واللاحقة من القيمة وكل سلسلة نصية قبل المقارنة. المقارنة حساسة لحالة الأحرف.

مثال

يعرض هذا المثال، باستخدام جدول العينة، EMPالتعويضات بشكل مختلف حسب الوظيفة JOB. بالنسبة لمندوبي المبيعات، يُظهر كلاً من الراتب والعمولة. بالنسبة لرئيس الشركة، يُظهر “–” بدلاً من الراتب، وبالنسبة لجميع الوظائف الأخرى، يُظهر الراتب فقط.

{case JOB/}
{when SALESMAN/}
&SAL. (&COMM.)
{when PRESIDENT/}
--
{otherwise/}
&SAL.
{endcase/}

3.11.4 توجيهات الحلقة

استخدم loop directiveلتكرار النص مرة واحدة لكل عنصر في عنصر متعدد القيم (مفصول بالأحرف) أو قيمة العمود.

بناء الجملة

{loop ["SEP"] NAME/}
TEMPLATE_TEXT
{endloop/}

اسم NAME عنصر أو عمود يحتوي على قيم متعددة، مفصولة بالحرف المُعطى بـ SEP. الفاصل الافتراضي هو ” :“. إذا SEPكان أكثر من حرف، فسيتم التعامل معه كتعبير عادي.

يمكن للنص القالب داخل الحلقة استخدام هذه الاستبدالات:

• APEX$ITEM– هذه هي قيمة العنصر الحالي في القائمة.
• APEX$I– هذا هو الفهرس المبني على 1 للعنصر الحالي في القائمة.

مثال

يأخذ المثال التالي عمودًا يسمى TAGS“يحتوي على قائمة منفصلة بفاصلة (,) من العلامات مثل “apples,cherries,pears” ويحولها إلى قائمة HTML يمكن تنسيقها بشكل جيد باستخدام CSS.

<ul class="tags">{loop "," TAGS/}
  <li class="tag-item">&APEX$ITEM.</li>
{endloop/}</ul>

3.11.5 مع وتطبيق التوجيهات

استخدم withالتوجيه لتعيين قيم لعناصر نائبة لمكون القالب المحدد في apply التوجيه.

بناء الجملة

{with/}
PLACEHOLDER1:=EXPRESSION1
PLACEHOLDER2:=EXPRESSION2
{apply TEMPLATE_INTERNAL_NAME/}

تتضمن المتطلبات عند استخدام هذا التوجيه ما يلي:

• استخدم withالتوجيه لتعيين قيم لعناصر نائبة لمكون القالب الإضافي المحدد في apply التوجيه.
• تستخدم مكونات القالب عرضًا من جانب الخادم.
• يتم دعم استخدام توجيهات القالب داخل تعبيرات القيمة.

مثال

{with/}
TYPE:=IMAGE
IMAGE:=&IMAGE_URL.
ALT:={if DESCRIPTION/}&DESCRIPTION.{else/}No description.{endif/}
{apply THEME$AVATAR/}

في هذا المثال، THEME$AVATARهو الاسم الداخلي لمكوّن قالب مُثبّت في التطبيق. يحتوي هذا القالب على ثلاثة عناصر نائبة، و TYPE، IMAGEو ALT ، والتي تُعيّن لها القيم.

3.11.6 الاستبدالات المضمنة لتوجيهات القالب

تعرف على سلاسل الاستبدال المضمنة المتوفرة لتوجيهات القالب.

ملحوظة:تدعم توجيهات القالب في مكونات القالب الإضافية عددًا من الاستبدالات المضمنة. لمعرفة المزيد، راجع تعليمات العنصر.

سلسلة الاستبدال	وصف
APEX$ITEM	متوفر ضمن تعليمة حلقة. يحدد قيمة العنصر الحالي في القائمة.
APEX$I	متوفر ضمن تعليمة حلقة. يحدد الفهرس 1 للعنصر الحالي في القائمة.
APEX$DOM_ID	يُولّد قيمة عشوائية فريدة DOM IDللتنفيذ الحالي لمقطع توجيه القالب. مثال على الاستخدام:<h1 id="#APEX$DOM_ID#_heading">#HEADING#</h1><someelement aria-labelledby="#APEX$DOM_ID#_heading">