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:
<BOUCLE_articles(ARTICLES){id_rubrique}{par date}{inverse}>
displays the articles of a section sorted by date, beginning with the most recent, while:
<BOUCLE_articles(ARTICLES){id_rubrique}{par titre}>
displays them in alphabetical order of their titles, and finally:
<BOUCLE_articles(ARTICLES){id_rubrique}{par num titre}>
displays them in the numbered order of their title.
<BOUCLE_articles(ARTICLES){id_rubrique}{par multi titre}>
In the case of a multilingual site, the {par multi criterion} is used to sort by alphabetical order in each language. Without the addition of "multi" the loop returns the same ranking for each language.
Sorting by more than one category: 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.
Note: When using multiple sort criteria, the{inverse}criterion applies only to the sorting criterion placed just before it.The notation
{!par ...}reverses a particular sort criterion. For example:{!par date} {par num titre}sort by descending date and then by ascending numbers in the title for results with the same date.
{par_ordre_liste field, #LISTE} (as of SPIP 4.1)
Allows you to explicitly order the results according to a field.
It can optionally be combined with the {… IN …} criterion, they have different scopes:
{… IN …} is primarily used to select contents, the order is not always maintained.
par_ordre_liste field ... is used to order the selection reliably.
It can also be combined with other {par...}in any order
The following example selects all items and arranges them in a predefined order. Items not present in the list will be ordered after:
<BOUCLE_articles(ARTICLES) {par_ordre_liste id_article, #LISTE{5,15,10}}>
The following example does the same thing, but limited to the 3 ordered items:
<BOUCLE_articles(ARTICLES) {id_article IN 5,10,15} {par_ordre_liste id_article, #LISTE{5,15,10}}>
Comparison, equality
{criterion < valeur}
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:
<BOUCLE_art(ARTICLES){id_article=5}>
displays article number 5 (useful for placing a particular article prominently, for example).
<BOUCLE_art(ARTICLES){id_secteur=2}>
displays all the articles of sector 2.
- A tag available in the context of the loop. For example:
<BOUCLE_art(ARTICLES){id_article=5}>
<BOUCLE_titre(ARTICLES) {titre=#TITRE}>
...
</BOUCLE_titre>
</BOUCLE_art>
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:
<BOUCLE_art(ARTICLES){titre==^[aA]}>
selects the articles with titles beginning with “a” or “A”.
Negation We can use the notation: {xxx != yyy} and {xxx !== yyy}, where the ! indicates the negation (logical operator NOT). Thus:
<BOUCLE_art(ARTICLES){titre!==^[aA]}>
selects articles with titles not beginning with either “a” or “A”.
<BOUCLE_art(ARTICLES){id_secteur != 2}>
selects articles not belonging to sector number 2.
display according to date
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:
<BOUCLE_art(ARTICLES){id_secteur=2}{id_rubrique!=3}{age<30}>
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:
<BOUCLE_article_main(ARTICLES){id_article}>
<h1>#TITRE</h1>
<BOUCLE_next(ARTICLES){id_rubrique}{age_relatif<=0}{exclus}{par date}{0,1}>
Next article: #TITRE
</BOUCLE_next>
</BOUCLE_article_main>
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
- {branche} limits the results — for loops with a #ID_RUBRIQUE — to the current branch (the current section and its sub-sections). For example:
<BOUCLE_articles(ARTICLES) {branche}>
...will return all articles in the current section and its sub-sections,
<BOUCLE_articles(ARTICLES) {!branche}>
...will return all articles that are not in the current section or its sub-sections,
One can use the criterion {branche?} optional to apply it only if a section is selected in the context (a bounding loop or the url provided a section_id).
For example:
<BOUCLE_articles(ARTICLES) {branche?}>
retournera tous les articles de la rubrique actuelle et de ces sous-rubriques si il y a un id_rubrique dans le contexte, sinon, tous les articles du site.
- {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.
- {doublons xxxx} , 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}.
- {exclus} allows you to exclude from the result the element (article, brief, section, etc.) in which you are already located. For example, when displaying the articles contained in the same section, you do not want to display a link to the article you are already in.
- {xxxxINa,b,c,d} , limits the results to those where the criterion xxxx is a, b, c or d.
The results are sorted in the order indicated (unless another sorting criterion is explicitly requested). It is also possible to select strings, for example with {titre IN 'Chine', 'Japon'}.
Tags are allowed in the arguments to IN, most notably the ENV tag, to which parsing filters are applied to ensure that the SQL query will be written correctly. As an exception, SPIP will test whether the argument to ENV designates an array (coming, for example, from form entries whose attribute name ends with []).If this is the case, and if the analysis filters have been deactivated by suffixing this tag with a double star, then each element of the table will be considered as an IN argument, with SPIP applying the security filters on each of them.
The forum plug-in-dist template inc-forum_previsu.html fournit un exemple d’utilisation avec une boucle MOTS ayant le critère {id_mot IN #ENV**{ajouter_mot}}: this loop selects only those keywords that belong to a dynamically specified set. Here, this set will have been built by the form of this plug-in-dist inc-choix_mots.html, which uses attributes "name=ajouter_mot[]".
- {a, b} où a et 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 (note that 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, spip.php?page=petition&id_article=13&debut_signatures=200 with a template (petition.html) containing, for example,
<BOUCLE_signatures(SIGNATURES){id_article}{debut_signatures,100}>
you will obtain a list of 100 signatures beginning at the 201st [reminder].
If you call the page instead with the URL : spip.php?page=petition&id_article=13&debut_signatures=300
the 100 signatures will begin at the 301st [reminder].
- {a, n-b}, 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.
{5, n} will display the results from 6th to last.
Caution:
si "a" et "b" are to be replaced by numbers, it is the letter "n" to be used when necessary.
- {n-a, b}is the counterpart of {a, n-b}. We limit to b results by starting the display at the ae result before the end of the loop.
For example: {n-20,10} will show 10 results, starting from the 20th result before the end of the loop.
Caution:
criteria {a, n}, {a, n-b} and {n-a, b} will not work if used with the {pagination} criterion and return inconsistent results!
- {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 lists with several columns. To obtain a display on two columns, it is sufficient to create a first loop, displayed in a table cell, with the criterion {1/2} (the first half of the results), then a second loop in a second box, with the {2/2} criteria (the second half of the results).
Caution! Using the {doublons} criterion at the same time can lead to mistakes. For example:
<BOUCLE_one(ARTICLES){id_rubrique}{1/2}{doublons}>
<li> #TITRE
</BOUCLE_one>
<BOUCLE_two(ARTICLES){id_rubrique}{2/2}{doublons}>
<li> #TITRE
</BOUCLE_two>
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:
<BOUCLE_authors(AUTEURS){id_article}{", "}>
Miscellaneous
{logo} allows you to select only those articles (or sections, etc.) that have a logo.
The reverse criterion {!logo} lists the objects that do not have a logo.
It also works in the loop (HIERARCHIE).