Основи синтаксису
Цикл в спрощеному вигляді записується так:
<BOUCLEn(TYPE){criterion1}{criterion2}...{criterionX}>
* HTML код HTML + SPIP теги
</BOUCLEn>
Раніше, на сторінці Цикли і Теги {}, говорилося, що HTML код + SPIP теги виводяться рівно стільки разів, скільки записів з бази виводить цикл. Он може вивести кілька записів, одну або не вивести взагалі нічого.
Зверніть увагу на рядок у прикладі:
<BOUCLEn(TYPE){criterion1}{criterion2}...{criterionX}>
- Слово BOUCLE (французькою «цикл») визначає новий цикл в SPIP. Директива пишеться саме таким чином і ніяк інакше: всі цикли в SPIP повинні починатися з директиви BOUCLE.
- n - це ім’я (ідентифікатор) циклу. Воно має бути унікальним в поточному файлі: якщо в одному файлі у вас буде два цикли з однаковими назвами, SPIP видасть помилку при спробі виконати шаблон. Ім’я може складатися з латинських букв, цифр і нижнього підкреслення. Ім’я циклу може бути довільним, але рекомендується починати його з нижнього підкреслення і давати назву по суті. Трохи пізніше буде показано, як можна використати кілька циклів в одному шаблоні.
Якщо назва циклу складається тільки з цифр, то ви можете не використовувати нижнього підкреслення, наприклад, якщо ви хочете дати циклу ім’я 5, то він буде виглядати наступним чином:
<BOUCLE5...>
...
</BOUCLE5>Але якщо ви використовуєте букви в назві циклу, то ім’я повинно починатися з нижнього підкреслення - «_». Наприклад:
<BOUCLE_subsections...>
...
</BOUCLE_subsections>- Елемент циклу (TYPE) задає, яку саме інформацію необхідно вивести з бази даних. Порядок написання елемента має значення: TYPE повинен знаходиться в дужках, без пробілів і бути написаний великими літерами. У загальному випадку список можливих значень обмежений і складається з переліку об’єктів у CMS SPIP: ARTICLES, RUBRIQUES, AUTEURS, BREVES, etc. (Список є в цій документації) [1].
Розширимо наш приклад:
<BOUCLE_subsections(RUBRIQUES)...>
...
</BOUCLE_subsections>- Критерії записуються в фігурних дужках {criterion1}{criterion2}.... Критерії повідомляють SPIP, які саме записи необхідно вивести з бази даних в даному циклі. Критерії задають ознаки, за якими обирається інформація (записи) із бази даних. З їх допомогою можна визначати порядок виводу (сортування) елементів: статті можна сортувати за датою, за першими літерами в назві і т.д... Можна задавати кількість елементів, які будуть виведені, наприклад, перших десять або ж друга половина всіх статей у розділі.
Комбінуючи різні критерії можна досить просто конструювати цикли, які відповідають складним SQL запитам.
Приклад циклу, які виводить п’ять останніх статей поточного автора:
<BOUCLE_same_author(ARTICLES){id_auteur}{par date}{inverse}{0,5}>
...
</BOUCLE_same_author>У даній документації описані критерії для кожного виду циклів (ARTICLES, RUBRIQUES etc), але багато критерії універсальні для всіх циклів.
Повний синтаксис циклу
Повний запис циклу виглядає так:
<Bn>
* опціональний HTML код перед циклом (HTML, цикли і теги)
<BOUCLEn(TYPE){criterion1}{criterion2}...{criterionX}>
* результат циклу (HTML код + SPIP теги)
</BOUCLEn>
* опціональний HTML код після циклу (HTML, цикли і теги)
</Bn>
* заміщуючий (альтернативний) код, який виконується, якщо цикл не повернув жодного запису (HTML, цикли і теги)
<//Bn>
Опціональний код «до» (пишеться відразу після директиви <Bn>) показується, якщо цикл знайшов хоча б один запис, який відповідає заданим критеріям - коли виводиться мінімум один запис. Опціональний код виводиться перед результатами циклу.
Опціональний код «після» (закінчується директивою </Bn>) виводиться у випадку, якщо цикл повернув хоча б один запис. Код показується відразу ж після виведення циклу.
Заміщуючий (альтернативний) код (закінчується директивою <//Bn>) виводиться в тому випадку, якщо цикл не знайшов жодного запису, який відповідає заданим критеріям. У такому випадку опціональний код «до і після» не виводиться, він повністю заміщується альтернативним кодом.
Приклад циклу, який виводить всі статті в рубриці:
<B1>
Статті в розділі:
<ul>
<BOUCLE1(ARTICLES){id_rubrique}>
<li>#TITRE</li>
</BOUCLE1>
</ul>
</B1>
У розділі нема статей.
<//B1>В залежності від кількості статей в рубриці, результат циклу буде різним:
- Якщо у рубриці тільки одна стаття:
Статті в рубриці: <ul> <li>Назва статті </li> </ul>
- Якщо в розділі кілька статей:
Статті в розділі: <ul> <li>Назва першої статті</li> <li>Назва другої статті</li> ... <li>Назва останньої статті</li> </ul>
- Якщо в рубриці нема статей:
У рубриці нема статей.
У опціональний код (у той, що до і після циклу, або у заміщуючий) крім HTML тегів можна записувати інші цикли або теги SPIP. Теги, які повинні вивестися в результатах циклу, не можна використовувати для виводу (причину простіше пояснити на прикладі:
<Bn> #TITRE <BOUCLEn(ARTICLES) {id_rubrique}> #TITRE </BOUCLEn>Даний цикл виводить усі статті з рубрики. Якщо статей декілька, то SPIP не знатиме, назву якої статті вивести до циклу. Тому в поточній і більш ранніх версіях принципово неможливо виводити отримані теги окрім як в результатах циклу.
Скорочений запис циклу
Починаючи з SPIP 2.0 в деяких випадках можливо використовувати скорочений запис циклу.
Якщо ви хочете вивести тільки кількість записів, які знайшов цикл (за допомогою тегу #TOTAL_BOUCLE), код можна записати у наступний спосіб:
<BOUCLE_a(ARTICLES) />#TOTAL_BOUCLE<//B_a>замість:
<BOUCLE_a(ARTICLES) > </BOUCLE_a>#TOTAL_BOUCLE</B_a>Можна використовувати такий запис, щоб сформувати список повторюваних матеріалів (див. Критерій «doublons»):
<BOUCLE_a(ARTICLES) {criteria ...} {doublons}/>У циклі не обов’язково вказувати всі опціональні елементи.
Приклад: цикл виводить назву статті з номером 1, а якщо її немає - то вміст файлу з 404 помилкою.
<BOUCLE_main(ARTICLES) {id_article=1}>
#TITRE
</BOUCLE_main>
<INCLURE {fond=404}>
<//B_main>Як видно з прикладу, не обов’язково використовувати елементи <B_main> і </B_main>, якщо крім виведення результатів циклу необхідний тільки заміщуючий код.
Критерії і оточення
Раніше розповідалося про те, що вказує циклу, яку саме інформацію необхідно вивести з бази даних. Робота деяких критеріїв залежить від оточення, в якому знаходиться цикл.
Наприклад, якщо у нас є цикл, який виводить всі статті з поточної рубрики, то треба знати, яка саме з усіх рубрик сайту є поточною. Саме це і визначається оточенням.
Цикл:
<BOUCLE_articles(ARTICLES) {id_rubrique}>
#TITRE<br />
</BOUCLE_articles>- Використання URL для ініціалізації оточення
URL (адреси) сторінок сайту на SPIP містять змінні, якщо, звичайно, не використовується формування ЧПУ формування URL на підставі назви матеріалу.
Приклад:
spip.php?rubrique15
Змінна у посиланні (id_rubrique) визначає оточення сторінки. У цьому випадку наш цикл вивести всі статті з поточної рубрики перетворюється на вивести всі статті з рубрики за номером 15.
І якщо ви перейдете на сторінку іншої рубрики, шаблон якої містить такий самий цикл, за посиланням:.../spip.php?rubrique7
то цикл виведе усі статті з рубрики 7.
Тобто цикл бере значення для критерію id_rubrique зі свого оточення, в даному випадку з URL сторінки.
В URL ми можемо передавати практично будь-яку кількість параметрів, які потрібні для правильної роботи циклів в шаблоні. Наприклад, якщо нам необхідно вивести всі статті із рубрики, які мають ключі і створені певною мовою, то цикл буде виглядати так:
<BOUCLE_advanced(ARTICLES) {id_rubrique} {id_mot} {lang}>
#TITRE
</BOUCLE_advanced>А посилання, яке ініціалізує шаблон, може мати наступний вигляд:/spip.php?rubrique7&id_mot=1&lang=ru
Якщо нам необхідно передати кілька значень одного і того ж параметра, наприклад, треба вивести статті у яких є не один ключ, а хоча б один з декількох, то посилання буде мати наступний вигляд
/spip.php?rubrique7&id_mot[]=1&id_mot[]=6& ..... Правда, критерії циклу треба буде записати трохи інакше, але це окрема історія.
- Ініціалізація оточення іншими циклами
У випадку, якщо один цикл знаходиться всередині іншого, то оточення внутрішнього циклу ініціалізується результатами, отриманими в зовнішньому циклі.
Розглянемо докладніше приклад вкладеного циклу:
<BOUCLE_articles(ARTICLES) {id_rubrique}>
#TITRE (Назва статті)
<BOUCLE_authors(AUTEURS) {id_article}>
#NOM (Ім'я автора)
</BOUCLE_authors>
</BOUCLE_articles>Ви бачите, що:
- перший цикл (BOUCLE_articles) виводить всі статті поточної рубрики. Номер поточної рубрики цикл взяв з URL (наприклад id_rubrique=15);
- результатом виконання циклу є одна або декілька статей;
- кожен раз, коли виконується цикл BOUCLE_articles, він задає оточення для внутрішнього циклу - це дані про поточну виведену статтю (наприклад, id_article=199);
- внутрішній цикл (BOUCLE_authors) буде виконуватися кожного разу, коли BOUCLE_articles буде виводити одну статтю. А оскільки з виведенням кожної нової статті буде відповідно змінятися оточення, то BOUCLE_authors, який виводить автора поточної статті, з кожним виконанням зовнішнього циклу буде трансформуватися у «вивести автора першої статті рубрики», «вивести автора другої статті рубрики» і так далі.
За допомогою вкладених циклів можна створювати дуже корисні конструкції - внутрішній цикл використовує результати роботи зовнішнього циклу, а самий верхній отримує вихідні дані з одного або декількох параметрів, заданих в URL сторінки.
Кілька вкладених циклів
Якщо в зовнішньому циклі перебувають кілька інших циклів, то вони не впливають на оточення один одного.
Приклад:
<BOUCLE_section(RUBRIQUES){id_rubrique}>
<ul>Назва рубрики
<BOUCLE_articles(ARTICLES){id_rubrique}>
<li>Назва статті</li>
</BOUCLE_articles>
<BOUCLE_subsections(RUBRIQUES){id_rubrique}>
<li>Назва підрубрики</li>
</BOUCLE_subsections>
</ul>
</BOUCLE_section>
<ul>Рубрики за цією адресою не існує</ul>
<//B_section>Оточення зовнішнього циклу BOUCLE_section задається через URL. У посиланні міститься номер рубрики, з якої треба вивести інформацію (id_rubrique=15).
Інші цикли (BOUCLE_articles і BOUCLE_subsections) розташовані всередині першого циклу. Якщо рубрики за номером 15 не існує, то зовнішній цикл не поверне жодних результатів (виведеться заміщуючий код «Рубрики за цією адресою не існує»). Відповідно, внутрішні цикли не будуть виконані. Якщо ж рубрика 15 існує, то внутрішні цикли виконаються.
Обидва внутрішніх цикли залежать від зовнішнього (їх оточення ініціалізується зовнішнім циклом), але в той же час повністю незалежні один від одного. Навіть якщо один цикл не виконається (наприклад в рубриці не буде статей), то виконається другий.
Лічильники
Щоб визначити і вивести кількість знайдених та виведених елементів використовуються два теги:
- #TOTAL_BOUCLE виводить загальну кількість записів, які знайшов (і вивів) цикл. Тег можна використовувати в будь-якій частині циклу - в опціональному коді до і після результатів циклу, в заміщуючому коді і, власне, в результатах. Зазвичай тег використовується до або після виведення результатів циклу, тому що, якщо його помістити в основну частину циклу, то він виведеться стільки разів, скільки разів виконається цикл.
Приклад - виведення кількості файлів, доданих до статті:
<BOUCLE_art(ARTICLES){id_article}>
<BOUCLE_doc(DOCUMENTS) {id_article}></BOUCLE_doc>
[Всього (#TOTAL_BOUCLE) файлів.]
<//B_doc>
</BOUCLE_art>
Зауваження: якщо в результатах циклу немає ніякого коду, як у прикладі вище (
<BOUCLE_doc>), тоді тег#TOTAL_BOUCLEтреба перемістити в іншу частину головного циклу (між</BOUCLE_doc>і<//B_doc>).
- #COMPTEUR_BOUCLE показує, скільки разів виконався цикл. Він збільшується на одиницю з кожним виконанням циклу. Початкове значення #COMPTEUR_BOUCLE - 1. Його можна використовувати для нумерації результатів виведення:
<BOUCLE_art(ARTICLES) {par date} {inverse} {0,10}>
#COMPTEUR_BOUCLE - #TITRE<br>
</BOUCLE_art>
Дуже часто тег використовують, щоб задавати різні стилі однаковим блокам. Наприклад, в розділі є чотири підрозділи. Назва кожного підрозділу має бути різним кольором. Для цього ми створюємо 4 різних класи: title1, title2, title3, title4.
Тоді наш цикл буде виглядати так:
<BOUCLE_subrubriques(RUBRIQUES) {id_parent=#ID_PARENT}>
<div class="title#COMPTEUR_BOUCLE">#TITRE</div>
</BOUCLE_subrubriques>а результат виконання:
<div class="title1">Перший підрозділ</div>
<div class="title2">Другий підрозділ</div>
<div class="title3">Третій підрозділ</div>
<div class="title4">Четвертий підрозділ</div>