Criteria applicable to all loops

Some criteria can be applied to (nearly) all types of loop. They are used to restrict the number of results displayed or to control the sort order. You can combine several of these criteria without any problem.

Sort Order

{par sort_criterion} gives the sort order of the displayed results. The sort criterion corresponds to one of the tags which is drawn from the database for each type of loop. So, for example, articles can be sorted using {par date}, {par date_redac} or {par titre}. (Note that while tags are referenced using capital letters, sort criteria are all in lower case.)

Special case: {par hasard} gives a randomly ordered list.

Inverting the sort order: {inverse} causes the results to be displayed in reverse order. For example {par date} gives a list beginning with the oldest articles; {par date}{inverse} will show the newest articles first.

Ordering by numbers: Text elements (the title, for example) are sorted alphabetically. However, in order to force a desired display order, you can place a number at the beginning of the title. For example: "1. My first article", "2. The second one", "3. Third …", etc. If these titles were to be sorted alphabetically, the order would be "1, 10, 11, 2, 3…". To force a numeric sort use:

{par num criterion}

Examples:

displays the articles of a section sorted by date, beginning with the most recent, while:

displays them in alphabetical order of their titles, and finally:

displays them in the numbered order of their title (note: the option {par num titre} does not work with versions of MySQL older than 3.23).

Sorting by more than one category: From [SPIP 1.8], it is possible to sort on several criteria at once with: {par criterion1, criterion2}. Results will be sorted by criterion1 and then, for results which have the same value for criterion1, by criterion2. Any number of criteria may be used. Example: {par date, titre} will sort results by date and title.

Comparison, equality

{criterion < value} To compare with a given value you can use ">", "<", "=", ">=", "<=". All of the sort criteria (as they are retrieved from the database) can also be used in order to limit the number of results. For example:

displays article number 5 (useful for placing a particular article prominently, for example).

displays all the articles of sector 2 (sections which are at the root of the structure, i.e. are not sub-sections, are also called "sectors").

-  From [SPIP 1.8], you may also use a tag as the object of the comparison. Example:

will find all the articles which have the same title as article 5.

Note: Only simple tags may be used. It is not possible to apply a filter or to include optional text.

In particular, if you wish to use #ENV — or any other tag which takes parameters —, this notation must be used : {titre = #ENV{titre}} and not: {titre = [(#ENV{titre})]}.

Regular expressions are very powerful, (but markedly more complicated to use). A double equals sign "==" is used to define a comparison using a regular expression. For example:

selects the articles with titles beginning with “a” or “A”.

Negation is indicated by this notation: {xxx != yyy}, where the ! indicates the negation (logical operator NOT). Thus:

selects articles with titles not beginning with either “a” or “A”.

selects articles not belonging to sector number 2.

To make date comparisons easier, these criteria are also available:
-  age and age_redac which correspond respectively to the number of days since the article’s set publication date and since it was really first published (the two can only differ if you have enabled "publication of post-dated articles"). Thus {age<30} selects elements published within the last month;
-  the criteria mois, mois_redac, annee, annee_redac, allow comparisons to be made against fixed dates. Thus {annee<=2000} will display elements published before the end of the year 2000.

Several criteria can be combined in order to make a very specific selection. For example:

displays articles of sector 2 which have been published within the last 30 days, with the exception of those belonging to section 3.

Hint: The age criterion is handy for displaying articles or news items having a date set “in the future” (on condition that in Precise configuration of the site, the option Publication of post-dated articles has been selected). For example, this can be used to give prominence to future events: {age<0} will select the articles or news items with a date set in the future.

Age with respect to a certain date: the age criterion is calculated with respect to today’s date (so {age<30} corresponds to elements published less than a month earlier than today). The criterion age_relatif compares an element’s date to a “current” date which is given by the context. For example, within an ARTICLES loop, the date is known for each of the loop’s results, and thus a selection can be made with respect to this date (and no longer according to today’s date).

In this code:

the BOUCLE_next will display just one article from the same section, sorted by date, whose publication date is the same or newer than the "main article"; in other words, the next article, published after the main article, from the same section.

For more information on dates see Managing dates.

Restricting the results


-  {doublons} or {unique} (these two criteria are exactly the same) make it possible to prevent the display of results which have already been returned by other loops on the same page, and which are themselves marked with the {doublons} criterion.

Note: From [SPIP 1.2] up to [SPIP 1.7.2], only the ARTICLES, RUBRIQUES, DOCUMENTS and SITES loops could use this criterion.


-  {doublons xxxx} from [SPIP 1.8], it is possible, in the same template, to use several {doublons} criteria independently of each other, by giving them a name. Loops with the criterion {doublons red} will not have any effect on those with {doublons blue}.

N.B. {doublons red} et {doublons} constitute two different criteria: the articles excluded by the first will be present in the first loop of the second.

-  {xxxx IN a,b,c,d,...} from [SPIP 1.8], limits the results to those where the criterion xxxx is a, b, c or d.

In the absence of any other sort order, the results will be returned in the order of the values listed.

Examples:
<BOUCLE_aa(ARTICLES){id_article IN 1,4,2,3}> -> 1 4 2 in this order;
<BOUCLE_aa(ARTICLES){id_article IN 1,4,2,3}{inverse}> -> 2 4 1 (article 3 has not been published);
<BOUCLE_aa(ARTICLES){id_article IN 1,4,2,3}{par id_article}> -> 1 2 4;
and even: <BOUCLE_aa(RUBRIQUES){titre in English documentation, Chinese Documentation}>#ID_RUBRIQUE</BOUCLE_aa>

-  {a,b} where a and b are numbers. This criterion makes it possible to limit the number of results. a is the number of the result at which display should begin (N.B. the first result is numbered zero: 0); b is the number of results to display.

Thus, {0,10} displays the first ten results; {4,2} displays the 5th and 6th results.

-  {debut_xxx,b} is a sophisticated variant of the previous criterion. It makes it possible for the starting point of the results to be passed by a variable in the URL. This variable replaces the a of the previous example. Its working is a little complicated; luckily it does not often need to be used.

The variable name passed by the URL must necessarily begin with the prefix debut_xxx, where xxx is an expression chosen by the webmaster. Thus for a page having the URL,

petition.php3?id_article=13&debut_signatures=200

with a template (petition.html) containing, for example,

you will obtain a list of 100 signatures beginning at the 201st.

If you call the page instead with the URL :

petition.php3?id_article=13&debut_signatures=300

the 100 signatures will begin at the 301st.

-  {a,n-b} from [SPIP 1.8], is another variant of {a,b}. a is the number of the result from which display should begin; b indicates the number of results not to show at the end of the loop.

{0,n-10} will show all the results except the last 10.

-  {n-a,b} from [SPIP 1.8], is the counterpart to {a, n-b}. Display is limited to b results after the ath result of the loop.

For example: {n-20,10} will show 10 results, starting from the 20th result before the end of the loop.

-  {a/b} where a and b are numbers. This criterion makes it possible to display a chosen portion a of the results with respect to a total number of portions b. For example, {1/3} displays the first third of the results.

This criterion is especially useful for presenting a list in several columns. To obtain a two-column display, you create a first loop in a table cell, with the criterion {1,2} (the first half of the results), and then a second loop in an adjacent cell, with the criterion {2,2} (the second half of the results).

Caution! Using the {doublons} criterion at the same time can lead to mistakes. For example:

will not display all the articles in the section! Let us imagine that the section contains 20 articles in total. BOUCLE_one will display the first half of the articles, that’s to say the first 10, and will prohibit (because of {doublons}) their reuse. BOUCLE_two will now display only the second half of the section’s articles which have not already been displayed by BOUCLE_one, in other words the second half only of the 10 following articles: the last 5 articles of the section. In such an operation you will thus "lose" 5 articles.

Inserting text between results

{"between"} makes it possible to insert HTML text and tags (here the text between) between the loop’s results. For example, to separate a list of authors with commas and spaces, use this code:

Optional criteria

Optional criteria make multipurpose loops possible. Adding a question mark to a restriction criterion indicates that this criterion is only to be taken into account if it has been passed in the context. This can greatly simplify the loops for the dist/backend.html template, for example.

The following loop would show the 10 most recent articles from all the site, or just articles in English (backend.php3?lang=en) or articles only from section 7 and its subsections (backend.php3?id_rubrique=7) depending on the URL used to call the page:

Author Paolo Published : Updated : 26/10/12

Translations : عربي, català, Deutsch, English, Español, français, italiano, Nederlands