**SPIP**
# Article validé
L’article "**المكررات SPIP - حلقة (DATA)**
(المكررات SPIP - حلقة (DATA) - SPIP)" vient d’être publié par
<multi>[ar]جورج[fr]George [en]George</multi>.
* * *
## المكررات SPIP - حلقة (DATA)
الأحد 17 أيار (مايو) 2020 , بقلم
[جورج](.././?page=auteur&id_auteur=18&)
SPIP ٣٫٠ قدم مفهوماً عاماً للحلقات يعتمد
على المكررات (iterators)
توسع استخدام حلقات (DATA) ليشمل، فضلاً عن
استفسارات SQL [1] ، اي نوع من قوائم البيانات.
مثلاً:
* جدول بيانات ناتج عن اي نوع من الدوال
(ومن بينها مكررات PHP)
* محتوى ملف محلي بتنسيقات XML وCSV وJSON وYAML
الى آخره
* قائمة ملفات في مجلد على الخادم
* استفسار من اي خدمة على النسيج
* استفسار SQL (كالذي يدعمه SPIP مثلاً)
* دليل LDAP
## كتابة حلقة `(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</code>) لجدول موجود
مسبقاً
- `csv` أو `json` أو , `yaml` لملف يخضع لهذه
التنسيقات
- `file` للممرور على اسطر ملف ما
- `glob` أو `pregfiles` للمرور على ملفات مجلد ما
(أو أكثر)
- `rss` (أو `atom`) لقراءة تدفق اي جديد
- `plugins` لعرض قائمة بالملحقات النشطة في
الموقع
- `yql` لاستفسار خدمة النسيج العائدة لياهو
Yahoo Query Language
- `sql` لإرسال استفسار خام الى خادم قاعدة
البيانات (يتم استخدام `{source sql, connecteur:query}`)
- `ics` للمرور على الرونامة (يتطلب ملحق
*icalendar*، أنظر Plugin iCalendar
(Plugin iCalendar - SPIP-Contrib))
- الى آخره
كل هذه التنسيقات متوافرة ومن السهل إضافة
غيرها وذلك بإنشاء دالة `inc_FORMAT_to_array($u)`. على
سبيل المثال، هذه دالة تحول ملف بتنسيق JSON
الى جدول بيانات
function
inc_json_to_array_dist
(
$u
)
{
if
(
is_array
(PHP: is_array - Manual)
(
$json
=
json_decode
(PHP: json_decode - Manual)
(
$u
)
)
OR
is_object
(PHP: is_object - Manual)
(
$json
)
)
return
(
array
(PHP: Arrays - Manual)
)
$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 (SPIP)
## المعيار `{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 (SPIP)
## حماية البيانات التي تتعامل معها
المكررات
تحمي حلقة `(DATA)` كل العلامات الموجودة في
داخلها بشكل آلي لأن البينات التي يتم
التعامل معها هي عادة من مصادر غير معروفة
وقد تكون خطرة. ويسري ذلك على علامات
الاستمارات (`#FORMULAIRE_xx`) التي يجب استخدامها
مع * كما هو موضح في [المقال حول العلامات مع
النجمwww.spip.net/fr_article4376.html#Balises\---|toil--es
(#BALISE* et #BALISE** - SPIP)]
<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)`
(SPIP)
يمكن أيضاً زيارة الموقع المخصص لاستخدام
حلقة DATA على العنوان
http://spip-loves-opendata.spip.net…
(http://spip-loves-opendata.spip.net/la-boucle-data)
[1] من البديهي ان المكرر التقليدي في SPIP
اسمه SQL: ينفذ الاستفسار كما حسبه SPIP ويعرف
المرور على النتائج لاسترجاعها الى الحلقة
— Envoyé par SPIP (https://www.spip.net/)
