المكررات SPIP - حلقة (DATA)

كتابة حلقة (DATA) وتنسيقها

انها حلقة يمكنها ان تجري اي جدول بيانات. اما كتابتها فهي كالتالي:

<BOUCLE_example(DATA){source format, données}>
	#BALISES
</BOUCLE_example>

يحدد المعيار {source format, data} البيانات التي ستمر عليها الحلقة.

يتطلب تحديد مصدر (source) البيانات عنصرين:
— قسم البيانات data: يمكن ان يكون هذا العنصر من أنواع مختلفة:
– جدول بيانات، مثلاً #ENV*
– مسار ملف على القرص الثابت، مثلاً sources/definitions.csv
– عنوان URL لملف او خدمة نسيج، مثلاً http://per.sonn.es/bases/phobia.fr.yaml
– أو حتى اي سلسلة يمكن للتنسيق ان يحولها الى جدول بيانات، مثلاً "select * from flickr.photos.search where text='spip'"

— قسم التنسيق format احد الأنواع التالية:
– table (او array او code>tableau) لجدول موجود مسبقاً
– csv أو json أو , yaml لملف يخضع لهذه التنسيقات
– file للممرور على اسطر ملف ما
– glob أو pregfiles للمرور على ملفات مجلد ما (أو أكثر)
– rss (أو atom) لقراءة تدفق اي جديد
– plugins لعرض قائمة بالملحقات النشطة في الموقع
– yql لاستفسار خدمة النسيج العائدة لياهو Yahoo Query Language
– sql لإرسال استفسار خام الى خادم قاعدة البيانات (يتم استخدام {source sql, connecteur:query})
– ics للمرور على الرونامة (يتطلب ملحق icalendar، أنظر Plugin iCalendar)
– الى آخره

كل هذه التنسيقات متوافرة ومن السهل إضافة غيرها وذلك بإنشاء دالة inc_FORMAT_to_array($u). على سبيل المثال، هذه دالة تحول ملف بتنسيق JSON الى جدول بيانات

function inc_json_to_array_dist($u) {
  if (is_array($json = json_decode($u))
  OR is_object($json))
    return (array) $json;
}

يمكن تحديد حلقة DATA جديدة في ملف inc/my_source_to_array.php

function inc_my_source_to_array_dist($data,$param1='',$param2='') {
     // $data يحتوي على محتوى الملف (محلي | بعيد) أو قيمة المتغير في المعيار.
    // $param1, $param2... هي معاملات اختيارية
...
}

ثم عرضها:

<BOUCLE_example(DATA){source my_source,test}>
	#VALEUR
</BOUCLE_example>

مفيد: يتم حفظ نتيجة حلقة DATA في ذاكرة كاش. يمكن إزالة هذا التصرف من خلال معيار {datacache 0}.

ترشيح وفرز وتصفح ودمج

المرسحات. مثل حلقات SQL، يمكن ترشيح حلقات (DATA) بواسطة معايير من نوع {value=x}. العوامل المتوافرة هي = و> و< و>= و<= و== (عبارة منطقية) وLIKE.

الا ان هذا الترشيح لا ينفذ في البداية خلال الاستفسار مثل حلقات SQL بل في النهاية على جدول البيانات المسترجع.

الفرز. الفرز من نوع {par xx} ممكن في هذه الحلقات كما البديل {!par xx} للفرز العكسي.

التصفح. يعمل التصفح بشكل طبيعي وكذلك معيار الخطوة/الحد {a,b}

الدمج. يعمل معيار {fusion /x/y} بشكل طبيعي. مثلاً، في ملف يحتوي دليل عناوين بتنسيق CSV، اذا كان عنوان البريد الالكتروني في الحقل رقم ٣، يمكن اقتصار الاستفسار على سجل واحد لكل عنوان بريد من خلال الحلقة التالية:

 <BOUCLE_csv(DATA){source csv, addresses.csv}{fusion /3}{par /0}{'<br>'}> 
 	#VALEUR{0} : #VALEUR{3} 
 </BOUCLE_csv> 

يتم تطبيق الدمج بعد الفرز واسترجاع أول عنصر يتم العثور عليه. هكذا اذا تم فرز جدول حسب التاريخ المعكوس {!par date} ثم دمجه على عنوان البريد، فالسجل المسترجع لكل عنوان بريد يكون أحدث سجل.

المعيار {liste ...}

لتبسيط كتابة جداول البيانات، اذا كان قائمة عادية من العناصر المسترجعة يديوياً، تتقبل حلقة (DATA) معيار {liste ...} الذي يتيح إنشاء جدول بيانات يفرق بينها بواسطة فواصل.

الحلقة:

<BOUCLE_i(DATA){liste 3,4,5}{"<br>"}>
	<BOUCLE_j(DATA){liste 6,7,8}{" "}>
		[(#VALEUR|mult{#_i:VALEUR})]
	</BOUCLE_j>
</BOUCLE_i>

النتيجة :

١٨ ٢١ ٢٤
٢٤ ٢٨ ٣٢
٣٠ ٣٥ ٤٠

ملاحظة: استخدمنا #_i:VALEUR داخل الحقة j للدلالة على القيمة التي تم حسابها في الحلقة i.

أنظر أيضاً Deux itérateurs simples : les listes et les énumérations

المعيار {enum ...}

<BOUCLE_enumere(DATA){enum 2,10,2}>
      #VALEUR
</BOUCLE_enumere>

النتيجة:

٢ ٤ ٦ ٨ ١٠

<BOUCLE_enum(DATA){enum g,m}{", "}>
	#VALEUR
</BOUCLE_enum>

Résultat :

g, h, i, j, k, l, m

val1 et val2 هما قيمتان رقميتان أو حرفان. يتكفل SPIP بتحديد أيهما الأصغر، وستقوم هذه الحلقة بتعداد القيم الموجودة بين val1 وval2. في الشكل الأول اذا لم يتم تحديد الوثبة تكون ١ افتراضياً.

أنظر أيضاً Deux itérateurs simples : les listes et les énumérations

حماية البيانات التي تتعامل معها المكررات

تحمي حلقة (DATA) كل العلامات الموجودة في داخلها بشكل آلي لأن البينات التي يتم التعامل معها هي عادة من مصادر غير معروفة وقد تكون خطرة. ويسري ذلك على علامات الاستمارات (#FORMULAIRE_xx) التي يجب استخدامها مع * كما هو موضح في [المقال حول العلامات مع النجمwww.spip.net/fr_article4376.html#Balises---toil--es]

<BOUCLE_foreach_protect(DATA){liste a,b,c,d,e}>
	#FORMULAIRE_XXX*{#VALEUR}
</BOUCLE_foreach_protect>

ملاحظة: اذا تم الستخدام الملحق «Bonux»، يكفي استخدام الحلقة (POUR) التي لا تتطلب هذا الشرط.

<BOUCLE_Foreach_non_protect(POUR){liste a,b,c,d,e}>
	#FORMULAIRE_XXX{#VALEUR}
</BOUCLE_Foreach_protect>

هناك الهديد من الأمثلة حول حلقة (DATA)

يمكن أيضاً زيارة الموقع المخصص لاستخدام حلقة DATA على العنوان
http://spip-loves-opendata.spip.net...