Using models

Sample uses

Here are a few usage ideas to illustrate the functionality of the model system. Here are a few that we have thought of. If you find others, please feel free to share them by submitting your models on SPIP Zone/SPIP Contrib’, which now has a dedicated section.

-  Changing the layout of images inserted by shortcuts. This was difficult to do in previous versions of SPIP and was a much requested feature. It is now a very simple task indeed: you need only to copy the template dist/modeles/img.html to a subdirectory called modeles/ in your squelettes directory and then modify that copy. The same can be done for the <doc1> and <emb1> shortcuts, although the latter has quite complex code.
N.B.: to make minor adjustments it is often simpler to edit the CSS style for the classes spip_documents_xx than to work on the model template.

-  Display a CSV table (Excel). Simply load the file, then call it with this <emb12>to display the data from the CSV file as an HTML table!

-  Associating a syndicated site with an article.
You could have a modeles/site_box.html — used with a shortcut <site1|box> — which will display the title of the syndicated site with the list of its most recent articles. Parameters could be used to indicate the number of articles to display, whether a summary should be shown or not, etc.

-  Displaying a “stamp” thumbnail.
With SPIP’s image processing features you can create a stamp thumbnail of photos (see Un site dûment timbré). With the resulting code in a model template modeles/stamp.html you could create a shortcut <stamp12> which will display a stamp thumbnail of image 12. [3]

It’s easy enough to imagine similar models for displaying images in sepia, of a reduced size, etc. We imagine that a wide variety of such items will soon become available as plugins.

-  Creating a composite article. Suppose you need an article which comprises the standfirst from article 1 and the text from article 2. Nothing easier. Create two models, one which returns the standfirst of the first article, the other which returns the text of the other article. In the composite article we place in the standfirst field: <article1|chapo>, and in the text field: <article2|texte>. To which filters, tags, etc. can be added as desired.

-  Placing the text of an article in several sections. By making models such as <article1|chapo>, <article1|texte> etc., you can insert a copy of one article into another without duplicating the content. This means that you have a kind of container article which can be placed in a different section, and which can also bear a different title, or additional elements.

-  Take a poll. The Formidable plugin, which makes it possible to create forms and use them in articles with shortcuts such as <formulaire|formidable|id=34>, was written using models.

-  Display a random quote. If you have a collection of quotes stored as news items, the shortcut <citation|aleatoire> could pick one at random (use the criterion {par hasard}{0,1} with a BREVES loop) and display it in a frame next to the current paragraph.

-  Inserting a document in another language than the language of the article. Because models function as inclusions, the parameter lang=xx is always available in them. If one of your documents is bilingual (using, for example a block with <multi> in the introduction), you can display a description in English within an article in Japanese by calling <doc1|left|lang=en>. If the template of the model contains language shortcuts (<:xxx:>), they will be interpreted in the language passed in the parameter.

-  Display a graph. A data table is passed to the model, which then proceeds to create the graph and insert it into the text flow.

-  A subtitle in the form of an image. Why not use something like <imagetypo|texte=My subtitle>?

In practice

To avoid collision with HTML tags, a model cannot be called by a shortcut like <modele> !

To call a simple model without parameters you need to:

1. either assign a numerical identifier: <the_model1>;
2. or follow its name with a pipe: | : <the_model|>)

In the first case, the passed identifier will be retrievable within the template the_model.html with #ENV{id} or else #ENV{id_le_modele} (which will therefore be worth "1" in our example) ;

In thje second case #ENV{id} as #ENV{id_le_modele} will be worth "0" (zero) respectively.

Parameters of all kinds

The syntax of the shortcuts for models is in the form <model12>, <model|parameter1=thing|parametre2=whatsit> or <model12|alignment|parameter1=etc>. The parameters can contain both HTML and SPIP-language (on condition, of course, that the model which is called is written in such a way as to treat the parameters it receives).

Note that, in order to avoid any conflict with HTML tags, a model cannot be called by a shortcut such as <model>, containing neither number nor the | (pipe) symbol.

Parameters may be written on several lines to make shortcuts more legible:

<model 10
  |country=Germany
  |population=82000000
  |area=357027
  |ranking=63
  |anthem=<i>Das Lied der Deutschen</i>
  |url=http://en.wikipedia.org/wiki/Germany
>

The template receives all these parameters in the #ENV tag. Thus the value of #ENV{population} is 82000000. This tag is protected against the injection of any JavaScript. So if you want to use HTML in a parameter, you should write this: #ENV*{hymn}. If you wish to apply SPIP’s typographical correction as well, then you can use this: [(#ENV*{hymn}|typo)] or [(#ENV*{hymn}|propre)].

The main parameter (10), is passed in two ways: as #ENV{id}=10 and also as #ENV{id_model}=10. This makes it possible to access, in a model called by <article3|chapo>, the standfirst of article 3 using

<BOUCLE_a(ARTICLES){id_article}>
#CHAPO
</BOUCLE_a>

or else the news items linked to keyword 3, using

<BOUCLE_b(BREVES){id_mot=#ENV{id}}>
#TITRE
</BOUCLE_b>

As you see, each model needs its own documentation, because the shortcut in itself explains nothing at all about how the elements it passes will be made use of.

A possible use within templates

Models are not restricted to shortcuts within the text of articles. They can also be called from within a template by using the tag #MODELE{model}.
Example :

[(#MODELE{modele, p1=truc, p2=thing, p3=etc}|filtre...)]

Default models

SPIP comes with the following models:
-  img, doc, emb;

-  article_mots and article_traductions, which respectively display the list of keywords linked to an article and the list of the article’s translations (shortcuts: <article1|traductions> et <article1|mots>) — these models are also called by the template dist/article.html;

-  lesauteurs, which defines the output of the #LESAUTEURS tag, but which may not be called as a shortcut;

-  and a series of models used by the pagination system (see The Pagination System).

Forms

It is also possible to call up forms as templates inserted in editorial content.

Example :
<formulaire|login>

Some advice on how to write a model

First think about the syntax you wish to adopt: will the model be linked to a particular article? If so, then start with a shortcut like <article1|xxx>.

Once this is decided, create the file modeles/article_xxx.html and place in it just an #ENV tag.
Then in a test article type your shortcut: <article1|xxx|param=x...> and you should see appear in the article (in a somewhat cryptic form — it is a serialised table) the environment which has been passed to the model. You should be able to make out the article number with the identifiers #ENV{id} and #ENV{id_article}.

Then you can begin to code the template for the page fragment that you wish to make:

<BOUCLE_x(ARTICLES){id_article}>

or

<BOUCLE_x(ARTICLES){id_article=#ENV{id}}>

. And so on...

For the model to be complete, you should try the syntaxes:
<article1|xxx|left> et [<article1|xxx>->www.spip.net].

In the first case it is the parameter
align=left which is passed to the model (and it would be best for the model to align its output accordingly).

In the second case the link is passed in a parameter lien=http://www.spip.net and the class of the link in lien_classe=spip_out. It would be best to use the URL which is passed as a link in some way in the fragment rendered by the model (for example by placing the link on the title or logo). And in this case you must add into the first HTML tag of the model a class="spip_lien_ok". This signals to SPIP that the link has been made use of. If it does not receive this confirmation, SPIP will add an <a href=...>...</a> around the whole model.

The #ENV{x} tag has been conceived so as to avoid any undesired injection of HTML or JavaScript. You may sometimes wish to authorise HTML in the parameters of a model. In which case, you must use #ENV*{x} to receive the parameters and then if necessary filter the data with |propre or |typo, according to the kind of data involved (a text of several paragraphs: typo; a single line of text: propre).

As far as programming goes, it is recommended that you write your models using only SPIP loops, without any embedded PHP code or dynamic tags. Note: in a model which contains PHP it is the result of the calculation which is stored in the cache rather than the script itself (as is the case with main templates).

See also

• article 5156
• How to <INCLUDE> other templates
• #ENV tag