لا تكتفي هذه الحلقة باسترجاع المستندات المرفقة التي ليست داخل مادة المقال، لكنها تصل ايضاً الى صور المقال (فمنذ الاصدار ١، يتعامل النظام مع الصور على انها مستندات) والمصغرات والمستندات المدرجة في مادة المقال.
للتذكير، غالباً ما سنستخدم حلقة DOCUMENTS مع المعيارين التاليين على الاقل:
<BOUCLEn(DOCUMENTS){mode=document}{doublons}>
معايير الاختيار
تستخدم حلقة DOCUMENTS عادة داخل حلقة مقال او قسم (احياناً في خبر، الا ان الاستخدام هنا ينحصر في استرجاع الصور).
– {id_document} (الرقم التسلسلي للمستند). يسترجع المستند الذي يحمل الرقم التسلسلي id_document. وبما ان هذا الرقم فريد لكل مستند لا يسترجع هذا المعيار الا نتيجة واحدة او صفر.
– {id_article} (الرقم التسلسلي للمقال). يسترجع مستندات المقال الذي يحمل الرقم التسلسلي id_article.
– {id_rubrique} (الرقم التسلسلي للقسم). يسترجع مستندات القسم الذي يحمل الرقم التسلسلي id_rubrique.
– {id_breve} (الرقم التسلسلي للخبر). يسترجع مستندات الخبر الذي يحمل الرقم التسلسلي id_breve (لا يمكن ارفاق مستندات وسائط متعددة بالاخبار، يمكن فقط ارفاق صور. لذلك فاستخدام حلقة DOCUMENTS هنا محدد للغاية).
ملاحظة: لا يمكن هنا استخدام معيار {id_secteur}. فقد تم تصميم المستندات لتكون مرتبطة بقوة بالمقالات والاقسام وليس ليتم نداؤها بمفردها بدون هذه العناصر (لذا نستخدم في SPIP عبارة «مستندات مرفقة»).
معايير العرض
– {mode=document} او {mode=image}، يسمحان باختيار نوع المستندات التي نريد استرجاعها: مستندات وسائط متعددة او صور (والحال انه يتم التعامل مع الصور المرتبطة بالمقالات والمدرجة في مادتها على انها مستندات بوضعية mode=image).
ملاحظة. في مواقع SPIP السابقة للاصدار 1.4، كان من المعتاد عدم عرض الصور التي لم يتم ادراجها داخل مادة المقال. وفي هذه الحال، اذا قمت بإضافة حلقة DOCUMENTS في وضعية mode=image في موقع من هذا النوع، قد تظهر في الحلقة صور لم تكن مخصصة للنشر في الموقع العمومي. اذاً لا تستخدم هذه الحلقة الا في موقع تم تطويره بالاصدار 1.4 من SPIP او احدث، او توخى الحذر في استخدامها (تأكد من انه لا توجد صور غير مرغوبة مرتبطة بالمقالات القديمة).
– {distant} يتيح منذ SPIP 1.8.2 اختيار المستندات حسب موقعها البعيد او لا. اي تلك المخزنة في موقع آخر او محملة من فضاء الموقع الحالي. ويتم تحديد {distant=oui} او {distant=non} حسب الحالة. (انظر SPIP 1.8.2.
– {doublons} (اي مكرر)، يأخذ هنا اهمية خاصة: فهو لا يكتفي بمنع اعادة عرض مستندات معروضة مسبقاً في حلقة اخرى، بل يمنع كذلك اعادة عرض مستندات مدرجة مسبقاً في مادة المقال. فإذا لم نستخدم هذا المعيار، سيتم عرض كل المستندات المرتبطة بالمقال بما في ذلك تلك المعروضة داخل المادة.
– {extension=...}، يتيح اختيار المستندات حسب لاحقة اسماء ملفاتها (مثلاً «mov» او «ra» او «avi» لمشاهد الفيديو...). يمكن استخدام هذا المعيار مثلاً، لإنشاء «معرض» اي بناء حلقة لا تعرض الا المستندات من نوع الصور واخرى بتصميم مختلف لعرض باقي المستندات:
<BOUCLE_portfolio(DOCUMENTS){id_article}{extension==jpg|png|gif}{mode=document}{doublons}>
هذه الحلقة، BOUCLE_portfolio، تسترجع المستندات المرفقة بمقال والتي لم تعرض في مادته والتي تحمل اللواحق «jpg» او «png» او «gif».
– {distant}
منذ SPIP 1.8.2، يتيح تحديد المستندات حسب مكانها في الموقع نفسه او في موقع آخر. وتتم كتابة {distant=oui} او {distant=non} حسب الحالة (أنظر SPIP 1.8.2).
– {doublons} يأخذهنا اهمية خاصة: فلا يتيح عدم عرض مستندات سبق عرضها في حلقة اخرى وحسب، بل كذلك، عدم عرض المستندات التي سبق وتم دمجها في المقال. واذا نسينا اضافة هذا المعيار، سيتم عرض كل المستندات المرافقة للمقال بما فيها تلك التي سبق وظهرت داخل مادة المقال [1].
علامات هذه الحلقة
– #LOGO_DOCUMENT تعرض شعار المستند (اي المصغّر) المرفق بالمقال. واذا لم يتم تثبيت مصغّر شخصي يديوياً، يستخدم SPIP مصغّراًً افتراضياً يناسب نوع ملف المستند.
– #URL_DOCUMENT عنوان URL لملف الوسائط المتعددة. يستخدم لعرض مضغّر يمكن نقره لفتح مستند الوسائط المتعددة. ويتم استخدام الامر التالي:
[(#LOGO_DOCUMENT|#URL_DOCUMENT)]
– تعرض #DESCRIPTIF وصف المستند.
– تعرض #FICHIER SPIP 1.8.2 اسم ملف المستند وبشكل أدق عنوان URL النسبي الخاص به. يمكن تمرير هذا المرشح: [(#FICHIER|basename)]
– هناك استخدام شيق لهذه العلامة اذا جمعناها مع المرشح image_reduire، في صالة عرض لعرض مصغر عن الصورة بدلاً من شعارها. مثلاً باستخدام
[<a
href="#URL_DOCUMENT">(#FICHIER|image_reduire{500}) </a>]
– #TYPE_DOCUMENT تعرض نوع المستند (ملف كويك تايم او ريل بلاير...).
– #EXTENSION منذ SPIP ٢.٠ كما يدل اسمها، تعرض لاحقة تنسيق الملف. مثلاً:
pdf, jpeg, move, ra.
– #TAILLE تعرض حجم الملف بالبايت. في حال الملفات الكبيرة، تصبح هذه القيمة كبيرة الى حد يتعذر عرضها، لذلك يستحسن استخدام المرشح #taille_en_octets الذي يعرض الحجم بالبايت والكيلوبايت وحتى الميغابايت:
[(#TAILLE|taille_en_octets)]
– #LARGEUR (العرض) و#HAUTEUR (الارتفاع) توفران الابعاد بالنقاط.
– تعرض #MIME_TYPE نوع MIME الخاص بالملف — مثلاً image/jpeg —، أنظر Internet media type.
- #DATE هي تاريخ نشر المستند (يمكن تعديله بعد النشر) أنظر «ادارة التواريخ» لمزيد من المعلومات حول استخدام حقل #DATE
– العلامة #ID_DOCUMENT تعرض الرقم التسلسلي للمستند.
– العلامة #DISTANT تعرض «oui» او «non» اذا كان المستند بعيداً (اي موجود في موقع آخر) ام لا. مثال: #URL_DOCUMENT[(#DISTANT|=={oui}|oui)|parametre_url{nom,valeur}]
– العلامة #EMBED_DOCUMENT هي علامة تتيح إدراج المستند في الصفحة بدلاً من الإشارة اليه. هذه العلامة اصبحت قديمة لأنها حالة خاصة من القوالب (انظر استخدام القوالب) التي تتيح تصميم هذا الإدراج بمرونة وفعالية أكبر.
يمكن إتبعاع هذه العلامة لمتغيرات خاصة بالتنسيقات المستخدمة، على سبيل المثال:
[(#EMBED_DOCUMENT|autostart=true)]
ولكن الأفضل استخدام القوالب:
#MODELE{emb, autostart=true}