Table of contents
Remember (Using models) that a "modèle" template is simply an ordinary SPIP template file that is directly callable from within the text stored in the database, as a way of delivering a precise insertion point of the HTML fragment described by the "parent" template file. For positioning any attached documents, there are essentially two such "model" templates available: doc (to reference the document) and emb (for embedding it). Embedding offers more possibilities.
The emb template currently delegates the work to five other templates named with the document MIME group name in question:
text, image, audio, video, application.
These templates can be used directly (e.g. <audio44|center> is equivalent to using <emb44|center> if the document belongs to the audio group) and is additionally a more efficient way of doing it, with the emb template being more there in the event of any doubts about the document’s group. The direct usage also has the advantage of forcing the embedding according to the selected template, even if the document is officially a member of another group. This makes it possible to get around various incongruities in the MIME classification: lots of documents strictly textual in nature are officially classed as an application, including XHTML which is nonetheless only a subset of HTML, which itself officially belongs in the text group.
The text template
The text template embeds the contents of a text document into an article, by preliminarily applying to a filtre_T function (if it has one) where T is a name determined from the document’s MIME type. This determination consists of replacing in the name of the type any non-alphanumeric characters with an underscore character. As such, for the type text/txt, the template will go to look to see if there is a function called filtre_text_txt.
This function filtre_text_txt is actually provided in advance by SPIP, and it is used by default for documents in the text group. It replaces any left and right angle characters in the body of the document by their matching HTML entities, and surrounds them with a pre tag, which makes it possible to present the contents of the document directly.
SPIP similarly provides the filtre_text_csv function, intended for processing text/csv documents. Since RFC4180 is rather only loosely adhered to by spreadsheet programmes, this function counts the number of tabs, commas and semi-colons in the document and assumes that the most frequently used of these three is the field separator employed within that document. It replaces that separator with the appropriate SPIP short-cuts, which will supply an HTML table that matches the one generated by the spreadsheet programme. The use of quotation marks to introduce the separator itself, or a manual line feed, is treated correctly (by an HTML entity and a br tag respectively). The optional final line feed is also properly handled.
If the first row only has its first column filled, this will be used to provision the caption tag for the table. The second row (or the first if it was not a caption) will be considered as the column names, and will therefore be typeset with th tags. The CSV format not having a method to indicate the character encoding, it is essential that the document encoding is the same as the site before using this filter, since SPIP can’t possibly know by itself if a re-encoding is necessary or not.
Finally, there is also a filtre_text_html filter, intended for processing text/html documents. It embeds the body of the document (that being whatever is enclosed by the body) tags. This body will however by purged of its scripts as a security measure. The style tags that might be present in the header will be regrouped into a single styling at the start of the embedding. Any stylesheets referenced in the HTML document’s header with link tags of the type
text/css will be retrieved from the WEB and their contents will be added to the style tag just mentioned above.
However, this will only be possible for stylesheets with absolute URLs (aka full URLs).
Only such conditions can SPIP present the document in an equivalent manner to the original, and subject to the additional condition that any img tags within the document also use absolute URLs.
The audio template
The audio template is used to embed the contents of an audio document into an article in the form of an object tag. As with the previous template, this template looks to see if there is a filtre_T function where T is the name of the type after substituting non alpha-numeric characters by underscore characters.
But it also applies to the ID of the document. The result of this function is inserted into the object tag, which notably makes it possible to specify the param tags that are often specific to the audio type in question.
In addition, any assignment pairs passed as arguments to the template (written as name=value) are also converted into param tags.
The image template
The image template is a small extension on the
img short-cut, already existing for a long time within SPIP. It only differs in that it generates an object tag rather than an img tag whenever that tag does not handle the MIME type of the document in question. For such types, it behaves just like the audio template, with a difference being that assignment pairs passed as arguments will be treated as attributes to the object tag. This therefore makes it the better choice specifically for embedding any SVG type documents, which officially belong to the application group.
The video template
The video template embeds the document by surrounding it in a control panel that can be used to make it run.
The application template
This template corresponds to the catch-all group in the MIME specification, which does not actually have a terribly clear summarising description. It will certainly be changing a lot over time, most notably with the (at the time of writing) rather nebulous definitions in the HTML5 schemas.
Usage
As with any other templates, we would code, for example
<text67> to apply the text template to document number 67, and we would therefore see that document’s content included directly on the relevant page.
These templates are similarly used implicitly by the article template that comes in the standard installation of SPIP whenever the article has an empty body and also has only a single attached document.
That template therefore behaves as if the article’s text had been reduced to a single occurrence of <embN>, where N is the document number, which has the overall effect of presenting the document body as the contents of the article.
To display on a web site the formatting provided by a spreadsheet programme, all you need to do is to create an article and attach the csv version of this type of document without requiring any additional manipulation.
The same applies if you wish to simply publish a video or audio file without any additional body text.
It is also easily possible to provision a static HTML site using SPIP by associating each of its pages with an empty article: if the URLs of their stylesheets and their images are fully descriptive URLs, SPIP will allow them to take full control over the relevant page formatting.