حلقات SPIP: التركيب اللغوي

التركيب اللغوي الاساسي

التركيب اللغوي المبسّط للحلقة هو:

<BOUCLEn(TYPE){criterion1}{criterion2}...{criterionx}>
* علامات HTML + علامات SPIP
</BOUCLEn>

حيث BOUCLE تعني حلقة تكرارية بالفرنسية.
رأينا في تفسير الحلقات والعلامات، ان «علامات HTML + علامات SPIP» تتكرر طالما تحصل الحلقة على عناصر من قاعدة البيانات (اي مرة واحدة او عدة مرات او صفر مرة).

السطر المهم هنا هو:

<BOUCLEn(TYPE){criterion1}{criterion2}...{criterionx}>

– العنصر BOUCLE هو الامر الذي يدل الى وجود حلقة من حلقات SPIP. لا يمكن تغييره اي ان كل حلقات SPIP تبدأ بالامر BOUCLE.

– العنصر n هو اسم الحلقة او رقمها. هذا العنصر يحدده المطور لكل حلقة يستخدمها (تحذير: لتسمية الحلقات يجب استخدام أحرف غير ص،وتية أو أرقام او الخط المنخفض «underscore» أي أحرف من الفئة [a-zA-Z0-9_&#93). سنرى لاحقاً انه من الممكن (لا بل من المفضل) استخدام عدة حلقات في الصفحة نفسها: لذلك يصبح من الضروري اعطاء كل حلقة اسم او رقم للتعرف عليها.

اذا قررت ترقيم حلقاتك، يصبح التركيب اللغوي (للحلقة ٥ مثلاً):

<BOUCLE5...> ... </BOUCLE5>

اما اذا قررت اعطاء اسماء لحلقاتك (ويفضل ذلك اذ تصبح الحلقات اكثر وضوحاً)، يجب ان يسبق الاسم رمز "_" (المعروف بـunderscore بالانكليزية). مثلاً:

<BOUCLE_subsections...> ... </BOUCLE_subsections>

– العنصر (TYPE) وهو النوع. هذا العنصر مهم جداً: فهو يحدد اي نوع من العناصر يجب استرجاعه من القاعدة. والتركيب اللغوي مهم بدوره: فيجب كتابة TYPE داخل هلالين (ودون مسافات) وبالحروف الكبيرة ويجب ان يكون احد انواع العناصر التي يعرفها SPIP والتي تجدها في الدليل الحالي: ARTICLES او RUBRIQUES او AUTEURS او BREVES الخ.

نحصل اذاً في المثال السابق على:

<BOUCLE_subsections(RUBRIQUES)...>
...
</BOUCLE_subsections>

– المعايير {criterion1}{criterion2}...{criterionx}... تحدد في الوقت نفسه، حسب اي معايير يجب اختيار العناصر في قاعدة البيانات (عرض الاقسام الفرعية العائدة الى القسم الحالي، عرض الاقسام الاخرى الموجودة في نفس المستوى الهرمي للقسم الحالي...)، والطريقة التي سيتم فيها ترتيب العناصر او اختيارها (ترتيب المقالات حسب تاريخها او حسب تسلسل عناوينها الابجدي... عرض اول ثلاثة مقالات فقط، عرض نصف المقالات...). وبما اننا نستطيع مزج المعايير، يمكننا بسهولة تركيب استفسارات قوية جداً من نوع "عرض احدث خمسة مقالات كتبها هذا المؤلف".

تكتب المعايير داخل أقواس مجدولة ويمكن وضع مسافات بينها. مثلاً:

<BOUCLE_same_author(ARTICLES) {id_auteur} {par date}{inverse} {0,5}>
...
</BOUCLE_same_author>

(id_auteur تعني رقم المؤلف التسلسلي، par date تعني حسب التاريخ، inverse تعني عكسي) سيتم توضيح المعايير المختلفة وتركيبها اللغوي لكل نوع من انواع الحلقات، في ما بعد (هناك بعض المعايير التي تدعم كل انواع الحلقات، واخرى مخصصة لأنواع معينة من الحلقات).

التركيب اللغوي الكامل

يمكن تزويد التركيب الموضح اعلاه بعناصر شرطية. فالحلقة السابقة تعرض تباعاً العناصر الموجودة داخل الحلقة. يتيح SPIP كذلك تحديد ما يجب عرضه قبل الحلقة وبعدها في حال تحتوي على نتيجة واحدة او عدة نتائج وما يجب عرضه في حال عدم وجود اي عنصر.

مما يعطي:

لا تظهر علامات HTML قبل (التي تبدأ بعلامة <Bn>) الا اذا كانت الحلقة تحتوي عنصراً واحداً على الاقل. تظهر هذه العلامات قبل نتائج الحلقة.

لا تظهر علامات HTML بعد (التي تنتهي بعلامة </Bn>) الا اذا كانت الحلقة تحتوي عنصراً واحداً على الاقل. تظهر هذه العلامات بعد نتائج الحلقة.

تظهر العلامات البديلة (التي تنتهي بـ<//Bn>) مكان الحلقة (وبالتالي مكان العلامات قبل والعلامات بعد) اذا كانت الحلقة لا تحتوي على اية نتيجة (اما لأن قاعدة البيانات لم تسترجع أية نتيجة او لأن الأوامر التي تستخدم تلك النتائج في الحلقة لا تعرض أي شيء).

فعلى سبيل المثال، تعطي الفقرة البرمجية التالية:

<B1>

    هذا القسم يحتوي العناصر التالية:
    
<ul>

<BOUCLE1(ARTICLES){id_rubrique}>
    <li>#TITRE
</BOUCLE1>

    </ul>
</B1>

    هذا القسم لا يحتوي اية مقالات.

<//B1>

(id_rubrique تعني رقم القسم التسلسلي، TITRE تعني العنوان)

النتائج التالية:

– في حال وجود مقال واحد:

 هذا القسم يحتوي العناصر التالية:
 <ul>
   <li>عنوان المقال</li>
</ul>

– في حال وجود عدة مقالات:

 هذا القسم يحتوي العناصر التالية:
 <ul>
   <li>عنوان المقال 1</li>
   <li>عنوان المقال 2</li>
   ...
   <li>عنوان المقال الاخير</li>
</ul>

– في حال عدم وجود اي مقال:

هذا القسم لا يحتوي اية مقالات.

لمحة تاريخية: حتى [SPIP 1.7.2]، كانت الطريقة التي يستخدمها SPIP لمعالجة الحلقات تمنع من وضع حلقة بين <Bn> و<BOUCLEn>. في المقابل، كان يمكن ادخال حلقات اضافية في القسم الاختياري الموجود بعد التعريف <BOUCLEn...>. اذا كنت فعلاً تريد ادخال حلقة في القسم الاختياري قبل، يجب استخدام الامر <INCLURE()>.

معايير بيئية متسلسلة

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

على سبيل المثال: اذا احتجنا الى حلقة من نوع: "عرض المقالات الموجودة في هذا القسم"، يجب ان نعرف اي قسم نقصد، وهذا ما نسميه البيئة.

– البيئة التي يوفرها عنوان URL.

عندما نزور صفحة من موقع يعتمد على SPIP، يحتوي عنوانها عادة على متغيّر. مثلاً:
– rubrique.php3?id_rubrique=15

فيحدد هذا المتغير (id_rubrique) البيئة الاولى: فحلقة "عرض المقالات الموجودة في هذا القسم" يجب ان تُفهم على انها "عرض المقالات الموجودة في القسم 15".

ومن الواضح، انه، مع تصميم الصفحة نفسه، اذا طلبنا العنوان:
– rubrique.php3?id_rubrique=7

يصبح تفسير الحلقة: "عرض مقالات القسم 7".

– البيئة التي توفرها الحلقات الاخرى

داخل حلقة ما، كل عنصر من الحلقة يغيّر البيئة. فإذا ادخلنا حلقات داخل بعضها البعض نحصل على بيئات متداخلة ببعضها.

ففي البنية التالية:

ما يجب فهمه هو:
– تعرض الحلقة الاولى (BOUCLE_articles) المقالات حسب القسم الموجودة فيه والذي تم تمريره كبيئة في عنوان URL (مثلاً id_rubrique=15).
– نحصل في هذه الحلقة على مقال او اكثر.
– "داخل" كل مقال نحصل على بيئة مختلفة (بيئة المقال، مثلاً id_article=199).
– اما الحلقة الثانية (BOUCLE_authors)، الموجودة داخل الحلقة الاولى، فتعتمد على بيئة الحلقة التي تحيط بها لكل مرة تنفذ فيها (فهي تنفذ لكل مقال في الحلقة الاولى): "عرض مؤلفي المقال الاول"، "عرض مؤلفي المقال الثاني" وهكذا دواليك.

نلاحظ اننا، بفضل تداخل الحلقات المتتالية، نحصل على حلقات مختلفة داخلة في بعضها البعض ومعتمدة على نتائج الحلقات التي تحيط بها. الى ان نصل الى الحلقة الاولى (اي تلك التي تحتوي سائر الحلقات) والتي تعتمد على المتغير الآتي من عنوان الصفحة.

الحلقات المدرجة والحلقات المتتالية

اذا كان باستطاعتنا ادراج حلقات داخل بعضها البعض (بالتالي كل حلقة مدرجة تعتمد على نتائج الحلقة المدرجة فيها)، يمكننا كذلك انشاء حلقات تتبع بعضها البعض. على ان الحلقات المتتالية لا تؤثر على بعضها البعض.

على سبيل المثال، تتكون صفحة قسم ما عادة من العناصر التالية:

وتعتمد الحلقة الاولى (BOUCLE_section) على المتغيّر الآتي من عنوان URL الخاص بالصفحة (id_rubrique=15 مثلاً).

اما الحلقتان التاليتان (BOUCLE_articles وBOUCLE_sub_sections)، فقد تم ادراجهما داخل الحلقة الاولى. بالتالي، اذا لم يكن هناك اي وجود للقسم رقم 15، لن تعطي الحلقة الاولى اية نتائج (وسيتم عرض الامر البديل وهو "لا يوجد اي قسم على هذا العنوان") وسيتم تجاهل الحلقتين المدرجتين كلياً. لكن اذا كان هناك قسم رقم 15، سيتم تحليل الحلقتين المدرجتين.

نلاحظ كذلك ان هاتين الحلقتين تظهران الواحدة تلو الاخرى. بالتالي، تعتمدان على الحلقة الاولى لكنهما مستقلتان عن بعضهما. فإذا لم يكن هناك اي مقال في القسم 15 (BOUCLE_articles)، سيتم عرض قائمة الاقسام الفرعية التابعة للقسم 15 في اي حال (BOUCLE_sub_sections) والعكس صحيح.

العدادات

هناك علامتان جديدتان تتيحان تعداد نتائج الحلقات.

– TOTAL_BOUCLE# تسترجع العدد الاجمالي للنتائج التي تعرضها الحلقة. وبمكن استخدامها في الحلقة او في اجزائها الاختيارية — قبل وبعد — او حتى في الجزء البديل بعد الحلقة.
على سبيل المثال، اذا اردنا ان نعرض عدد المستندات المرتبطة بمقال ما:

<BOUCLE_art(ARTICLES){id_article}>
<BOUCLE_doc(DOCUMENTS) {id_article}></BOUCLE_doc>
[هناك (#TOTAL_BOUCLE) مستند.]
<//B_doc>
</BOUCLE_art>

تنبيه: اذا لم يسترجع الجزء المركزي من الحلقة اي شيء (كما يحصل مع الحلقة <BOUCLE_doc> اعلاه التي تستخدم لعد المستندات وحسب)، لا يمكن عرض #TOTAL_BOUCLE في الجزء البديل بعد في الحلقة (<//B_doc>).

– COMPTEUR_BOUCLE# تسترجع رقم التكرار الحالي للحلقة. يمكن مثلاً، استخدامها لترقيم النتائج:

<BOUCLE_art(ARTICLES) {par date} {inverse} {0,10}>
#COMPTEUR_BOUCLE - #TITRE<br>
</BOUCLE_art>