SPIP

SPIP 3.0

George Kandalaft, Paolo — 2012-05-27T10:18:07Z

SPIP 3 is a major upgrade. The following features are of special note: the private area has been completely revamped using customisable templates, a high degree of modularity (all non-core functionalities are now in plugins), and a revolutionary DATA loop which allows SPIP to connect to many new kinds of data.

SPIP 2.0 could already be used as a “framework” for developing Web applications, well beyond SPIP's original purpose as a simple CMS. SPIP 3 pushes the logic of the “framework” further so that it can now be applied to SPIP itself: The whole private area of SPIP has been revamped into templates, themselves based on the tools and features offered by SPIP's template language.

This rewrite of the private area was an opportunity to rethink all the editorial objects and standardise their use to make them as generic as possible: most of the historical particularities of each object (and associated processing exceptions in SPIP code) have been reduced to a simple declaration.

In this way the creation of new editorial objects and the customisation of existing objects have become much easier and quicker.

SPIP 3 also concludes the modularisation of the software into plugins which SPIP 2 had begun: all the features offered by SPIP 2 are now based on a core SPIP 3 accompanied by 23 plugins.

This segmentation of the core has made it possible to complete the system of APIs and entry points for plugin developers.

SPIP 3 has drawn heavily on developments made by the SPIP-Zone community, and this marks a reversal: it is no longer the core programme which is encouraging the development of plugins, but instead development of plugins which, by their experimentation, is now fuelling the advance of SPIP. [1].

Among its new functions, SPIP 3 introduces a new loop, DATA which now makes it possible to loop over any kind of data, not only SQL tables. You can now browse an enum or a CSV, XML, YAML file. And furthermore, the DATA loop can even be used directly on a URL: thus it becomes possible to directly integrate data from a Google spreadsheet, an online calendar, a list of Youtube videos, photos on Flickr ... the Web becomes your database if not your oyster!

System requirement:
In order to function correctly, SPIP 3.0 needs PHP version 5.1.0 or newer.

A new private area [2]

Visually, the private area remains in continuity with previous versions, while using new icons:
- * the main icons for navigation are a set made for SPIP by Sebastian Desbenoit
- * the other icons are from a set which was derived from FatCow.

The revamping of the interface is essentially technical, though it has also solved a number of ergonomic flaws.

The navigation system has been redesigned. The drop-down menu, now fully navigable with the keyboard, also integrates delays for ease of use with the mouse and to be more robust against poorly controlled movements.

All of the private area is now in the form of templates stored in the prive/squelettes directory, organised by subdirectories corresponding to a division of the page into blocks. This division is mainly used for reloading pieces of a page with Ajax, avoiding the full reload of pages and making actions more fluid [3].

Many entry points (primarily used by the core plugins) are available as pipelines to allow plugins to extend the functionality of the private area.

Pages of the private area have been reorganised and renamed. In particular all pages of editorial objects use a consistent naming scheme based on the object name.

The rewrite also allowed for an upgrade of the HTML structure and its accessibility. A programming guide has been set up so that plugin developers can use the same structures, and that the interfaces they add remain consistent with the core.

All objects lists are templates, and therefore easy to customize. They all have built-in sorting by column and ajax pagination.

A scaffolding system of object pages can automatically build a minimal interface for new objects declared by plugins. Each element of the default interface can then be customized according to the particularities of each object: [4].

All interactive forms are written as CVT forms, which ensures good management of error messages, input checking, ajax robust control, and multi-page forms are available if necessary. They can all be easily extended by plugins.

In edit mode SPIP 3 takes carriage returns into account (it is no longer necessary to use “_”).

Lastly, the private area includes a mechanism for themes, allowing them to customize the style sheets, or some or all of the icons. This mechanism can be used by a plugin offering the user to choose a preferred presentation.

Modularity with plugins

SPIP 3 has concluded the process of fragmenting the system into plugins. The core retains the management of articles, sections and authors, the template language and the structure of the private area. All other functions are now outsourced in plugins which are automatically installed with the default distribution of SPIP 3. These default plugins are storedin the directory plugins-dist/ [5]

This separation of functions has made it possible to define a number of implicit APIs, which are now available to plugin developers who can add functionalities without limit, modelled on SPIP's native plugins.

In the field of plugins, SPIP 3 also brings a major overhaul of the formalism of the XML declaration. Besides improved readability, the question of translations of plugins is treated and there are automatic tools for listing plugins and for loading them.

Plugins can also make use of the upgrading functions of the core database (with recovery after timeout) by a simple declaration of the procedure.

Plugins distributed with SPIP default are:

Brèves deals with the editorial object News Items.
Companion displays information and support during the initial access to the private area.
Compressor) (already in SPIP 2.1) optimizes performance by compressing and concatenating CSS and JavaScript files used. This version of the plugin improves sheets by media. Using @media to concatenate all media into one file without changing the load order. Absolute urls are managed without protocol so that compressed style sheets work with both http and https.
Dump manages backup and recovery. The feature has been completely rewritten to provide a full and reliable backup. The backup format is now SQLite and all tables are systematically preserved.
Forum manages the editorial object forum, both for the public site and the private area. In addition to a redesigned moderation interface, forums can now be used on all SPIP objects (whether native or added through plugins).
Images (already in SPIP 2.1) manages all the image and colour filters which can be used in templates.
jQueryUI implements this library in SPIP. It facilitates the creation of dynamic graphical components: tabs, drag & drop, progress bars, widgets, effects ...
Mediabox integrates a default pop-in box to view media or offer interactions [6].
Medias [7] manages documents and images. It redesigns the interface and allows documents to be attached to any editorial object.
Mots manages keywords and keyword groups. The keywords can now be used on all editorial objects.
Organiseur provides the messaging functions and internal calendar of the editing area. The interface is completely redesigned. Internal messaging has email notification, and the calendar is based on the library FullCalendar allowing smooth navigation.
Pétitions handles petition items and offers a redesigned moderation interface.
Quill (Porte-plume) (already in SPIP 2.1) provides input assistance.
Revisions provides versioning which can be used on all SPIP editorial objects. The management interface has been updated.
SafeHTML (already in SPIP 2.1) takes care of potentially threatening external content.
Sites makes the “Syndicated sites” object work as well as syndicated articles. An interface to moderate syndicated articles is available.
Squelettes par rubriques (Templates per section) makes templates with suffixes work (article-2.html for articles of section 2 and its sub-sections, etc.).
Statistics provides the calculation of statistics for the sites and articles, with a completely redesigned interface.
Support of older browsers (already in SPIP 2.1) offers JavaScript functions which can be activated to allow older browsers to display your site correctly.
SVP manages plugins: search, installation, activation, update, ...
TextWheel is an engine that supports SPIP's typographical shortcuts. They are now defined in a rule file in YAML format. This results in a significantly quicker calculation of shortcuts (up to twice as fast with some content), and facilitates the development and customization of shortcuts.
Urls Etendues supports contextual URLs or hierarchical URLSs, and provides a configuration interface and an optional advanced management interface to give fine control over the URLs of each page.
Vertebrae (already in SPIP 2.1) allows the webmaster to display the content of a SPIP SQL table using an automatically generated template based on the structure of the SQL table. This display is now in the private area.

A new set of default templates

To mark the occasion the default templates have been revised. With the division of styles into various independently reusable stylesheets (see Daisy method and One, two, three ... CSS), there is now a modular HTML/CSS basis on which a site can be built straight away. A full, harmonious typographical treatment, based on the Blueprint framework, forms one part of the CSS. The old stylesheet spip_style.css gives way to spip.css, which can be used as a complement to your usual framework.

The templates adopt a new HTML base structure which already put in place some HTML5 elements; they are responsive by default, and load conditional selectors for greater CSS flexibility.

New features

SQLite support has been greatly improved, and this, because of its simplicity of installation, is now the default database format (if supported by the server) when a new site is installed. [8]

The management of editorial objects has been made generic. Therefore authors, documents, keywords, forums, versioning, and logos can be used on any object (all SPIP objects and also any editorial object added by a plugin following the new declaration API).
The status, date of publication, language and translation is also generalised and can be used on any object by simple declaration.
When the signalling of concurrent editing is enabled, any editable object is now included in the signalling.

The identity of the site is complemented by a site slogan, something between the title and the description. It is displayed with the tag #SLOGAN_SITE_SPIP.

The safety screen is included as standard.

The level of tracking recorded in log files can be managed. By default, the logs are much less verbose in production and only report anomalies or important information. The log level can be adjusted for debug or development.

The occasional cron job which was file-based has been deleted in favour of a queue of pending tasks (which also manages periodic tasks). This job queue makes it possible to program asynchronous actions [9] and offers an easy to use API for plugin developers.

The Ajax in templates ({ajax} on INCLURE) supports ARIA attributes, improving its accessibility. In addition, the browsing history is also handled automatically through the API “History” of HTML5 [10]. The browser URL is updated automatically on ajax links allowing for problem-free backtracking.

Models used in text now automatically receive the environment of the template which display them.

The forms of the private area use HTML5 features, for example the required and placeholder attributes.

The characters # [] () {} <> can now be escaped in templates by using a slash: \. This makes it possible, for example, to write conditions on a check-box in a much more elegant way, without the square brackets of the name attribute interfering with those of the SPIP tag:

[(#ENV{param}|yes)
With kindness?
]

Shortcuts

There is now a shortcut for abbreviations: [NHS|National Health Service] (or [SNCF|Société Nationale des Chemins de fer Français{fr}] to indicate a different language from the main text) generates an abbr tag [11].

Document models accept width or height arguments to limit their size: .

Double-entry tables (whether horizontally or vertically) are now handled correctly.

It is no longer necessary to use the shortcut " _ " to produce a simple carriage return or line break. A carriage return in the text does the job. To maintain the previous behaviour, this feature can be disabled by placing define ('_AUTOBR', '') in mes_options.php.

Loops

SPIP's system of loops has been generalised so that it applies no longer directly to a SQL table but to an iterator. An SQL iterator maintains the traditional operation of loops on SQL tables, but it is now possible to iterate over any given set of data: Les itérateurs de SPIP

A first example of an application for this: the loop DATA extends the operation of loops to structured information in tabular form. It becomes possible to loop over a CSV file, or on a remote url that returns JSON information ... :

To ensure the easy migration of templates containing POUR and CONDITION loops, these loops are also supported as special cases of the DATA loop, with the previous syntax.

Criteria

{si ...}: lets you place a condition on the execution of a loop which depends on the context of the template rather than on values in the database.

{tri ...}: used with the #TRI tag for easy sorting.

{feuille}: makes it possible to select sections without children (those at the bottom of the hierarchy).

{noeud}: makes it possible to select sections which have child sections.

{!racine}: excludes the first level sections (sectors).

{profondeur=3}: selects the only third-level sections (the root is level 0, sectors are level 1, then underneath, level 2 etc.).

Filters

|lien_ou_expose can be used, for example, to build a menu with several links and marking the currently selected item with while maintaining a link for other items. Example: [(#URL_PAGE{mypage}|{lien_ou_expose{label, #ENV{page}|}=={mypage, class, title, rel})].

|singulier_ou_pluriel displays one string or another depending on the number to which it is applied: [(#TOTAL_BOUCLE|singulier_ou_pluriel{1_article,nb_articles})]. 1_article and nb_articles are language strings that receive the number as an argument @nb@. If the number is zero, the filter is ignored.

|balise_img can quickly build an HTML tag from a file name which includes the width and height for faster page rendering: [(#CHEMIN{myimage.png}|balise_img{alt, class})]

|affdate_debut_fin displays an interval of time in a reader-friendly way, taking into account whether the start date and end date are or are not the same day, month or year, and displaying the time or not according to the second argument (oui or non. Example: [(#DATE_DEBUT|date_debut_fin{#DATE_FIN, oui})].

|timestamp adds a timestamp in the form ?1234567890 to a filename, where the number represents the file date in seconds since 1 January 1970. This filter is useful, for example, when referencing a style sheet, in order to make sure that the browser will reload the file when it is changed:
[]

|objet_icone returns the standard icon of a SPIP object. By default, the 24px version is returned, unless the size 16 or 32 is requested as an argument: [(#OBJECT|objet_icone{16})].

|objet_info returns a property of a SPIP object as declared (or automatically supplied by SPIP) via the API declarer_tables_objets_sql.

|objet_afficher_nb displays the number of objects by taking into account the number to which the filter is applied and language strings declared for the object: [(#TOTAL_BOUCLE|objet_afficher_nb{auteur})], for example, will display1 author or 23 authors.

|wrap wraps an html tag around the text returned by the SPIP tag: [(#TITLE|wrap{
})] will produce the same result as [(#TITLE) ].

|generer_info_entite displays a field of a SPIP object: [(#ID_ARTICLE|generer_info_entite{article,titre})] returns the title of the article #ID_ARTICLE. This is equivalent to [(#INFO_TITRE{article,#ID_ARTICLE})].

In the private area:

|icone_horizontale displays an icon of the private area in horizontal format. The syntax is: [(#URL|{icone_horizontale{label,icon,function})]. icon can be designated by an abbreviation (e.g.article) for a format of 24px, or else explicitly (article-24.png). The third argument, function, specifies the kind of action associated with the icon and can be one of the following: add, del edit, new, or else omitted. Example: [(#URL_ECRIRE{auteur_edit,new=oui}|icone_horizontale{<:icone_creer_nouvel_auteur:>,auteur,new})]

|icone_verticale displays an icon of the private area in a vertical format. The syntax is the same as for |icone_horizontale.

|bouton_action_horizontal uses the same syntax as|icone_horizontale and displays a visually similar result. However the HTML markup will be of the same type as #BOUTON_ACTION to trigger a POST to the url and is therefore useful when the url makes a change to the database.

|sinon_interdire_acces placed anywhere in the page allows you to block access to it when the expression to which it applies is false. In this case an error page is displayed, unless a redirection URL is provided as an argument (you can then also provide an http redirect status as the second argument). It is generally used with an authorization check: [(#AUTORISER{modifier,article,#ID_ARTICLE}|sinon_interdire_acces)].

JavaScript

SPIP 3 uses the version 1.7.2 of jQuery and also includes jQuery UI (v. 1.8.20). It is possible to use a different version of jQuery in the public site simply by overloading javascript /jquery.js in the squelettes/ directory without any risk of breaking the private area.

Ajax links:
.ajax links no longer break the browsing history on browsers that support the HTML5 History API (Firefox, Safari, Chrome at the time of writing). That is to say that when you click on a link that reloads the SPIP ajax part of the page, the URL is updated in the browser and the visitor can click on the back button to return to the previous view.

Special classes on ajax links:

.nohistory indicates that the link should not affect the browser history when clicked.
.preload tells SPIP that the content of the ajax link should be preloaded when the page loads. Thus a click on the link will produce immediate update.
.nocache tells SPIP that the contents loaded by the ajax link should not be cached. So several clicks on the same link will cause as many loads from the server (by default, only the first load is made for a given url and the content is then cached by the browser).

Reloading remote ajax blocks
An .ajax link, by default, reloads the block that contains it, but sometimes it is necessary to reload an ajax block elsewhere on the page.

To achieve this, ajax blocks can be named when they are included:
. The named block can then be reloaded by a call from ajaxReload('blockname'). A list of options can be passed as a second argument:

callback: callback function to be called after loading the ajax block.
args: list of arguments to be passed to the url when loading the block (makes it possible to change #ENV of an updated block).
history: whether or not the loading should affect the browsing history (default: false). Example:
ajaxReload('blockname', {

callback:function(){alert('done');},

args:{id_article:3},

history:false

});

ajaxReload can also be used on a jQuery selector in which case it will cause a reload of the smallest ajax block containing the target element. It then accepts only the one possible argument (the array of options): $('#content').ajaxReload({args:{id_article:3}})

Javascript animations
During interactions triggered by the user, it is possible to trigger several generic animations which are all applied to a jQuery selector:

jQuery('#myid').animateLoading() triggers the loading animation on #myid (automatically triggered by ajax reloading).
jQuery('#myid').endLoading() stops the loading animation on #myid (automatically triggered by ajax reloading).
jQuery('#myid').animateAppend() animates the block#myid to show it was just added by the interaction.
jQuery('#myid').animateRemove() animates the block#myid to show it was deleted by the interaction.

Utility functions:
parametre_url() is used as a PHP version of the filter of the same name (|parametre_url) to add, delete, or retrieve parameters of a URL:

parametre_url(url,arg,value) adds arg=value to url and returns the modified URL.
parametre_url(url,arg,'') removes the value of arg from url and returns the modified URL.
parametre_url(url,arg) returns the value of arg in url.

$('a').followLink() follows a link by simulating a click on it (takes into account whether the link is an ajax link or not).

Popins in the private area:
A link to a page in the private area with the class .popin opens a popin containing the centre of the target page (the content/ block). The link retains its ability to be opened in new tab by a right click and in this case the full page is displayed.

API

SPIP 3 brings several generic APIs to the management of editorial objects:

The API editer_liens manages tables of links between any two objects.
The creation of new editorial objects is simplified by a declarative API.
Management of the functions controlling the insertion, modification or publication of editorial objects: API editer_objet.
objet_test_si_publie($object, $id_object) tests if an object is published or not according to its status as declared (and according to a possible post-publication).
generer_url_ecrire_objet($object,$id_object,$args,$anchor) returns the url to the page of the object in the editing area. $args and $anchor are optional.
The pipeline optimiser_base_disparus is called when cleaning the database of objects which have been binned and the resulting dead links.

SPIP 3 also has management of a task queue which makes it possible to program tasks for future execution or simply set them as asynchronous (ASAP but without making the user wait).

The implementation of plugin configuration is simplified by the automated support for forms: #FORMULAIRE_CONFIGURER_XXX, and by the functions lire_config, ecrire_config and effacer_config (see Configurer une fonctionnalité de votre site, ou un plugin).

CVT forms Make it easy to construct multi-page forms, and also support automatic backup of text entry upon simple declaration.
The pipeline formulaire_fond provides a way to customize the background of forms (i.e. to edit the HTML of the form) [12]

In the SQL API:

The sql_skip function is added: it allows you to skip a set number of results.
The values null in sql_updateq and sql_insertq are translated into NULL for SQL and are no longer treated as an empty string.
The functions sql_demarrer_transaction and sql_terminer_transaction as the names suggest, are used respectively to start or close an SQL transaction [13].

A sandbox entry point, (public/sandbox.php) for template compilation, allows a plugin to manage the compilation of templates in a set of filters, to whitelist or blacklist functions, and to forbid PHP in templates.

Specialisation of criteria:
It is possible to prefix the name of the criterion function with the server name and/or the name of the table. The search is carried out in this order:

critere_serveur_TABLE_mycriterion_dist,
critere_serveur_TABLE_mycriterion,
critere_serveur_mycriterion_dist,
critere_serveur_mycriterion,
critere_TABLE_mycriterion_dist,
critere_TABLE_mycriterion,
critere_mycriterion_dist,
critere_mycriterion

In the file options.php of a plugin, or in the mes_options.php file, $GLOBALS['marqueur_skel'] .= ":prefix" can be used to differentiate the cache of compiled templates just as $GLOBALS['marker'] .= ":prefix" used to differentiate the cache of templates.

[1] Besides The Quill which was already integrated to SPIP 2, this movement includes Afficher Objets, Base CSS, multi-page CVT forms, Forum, Job queue, Mediabox, Media Library, TextWheel, Editable URLs, Comments, and others. Some of these have inspired the development of SPIP's core code, while others have been integrated after some alterations as new plugins.

[2] This project has begun some time ago on SPIP-Zone, and those who have already used the plugins Navigation du privé or Média Library will recognise the changes.

[3] For example, opening an article for editing becomes instantaneous thanks to Ajax pre-loading.

[4] http://core.spip.org/projects/spip/repository/revisions/17650

[5] In SPIP 2.1 they were placed in the extensions/ which now disappears.

[6] This is an alternative, based on the library Colorbox, to plugins such as ThickBox, LightBox ...

[7] Known in SPIP 2 under the name “Media Library”

[8] Support for PostGreSQL, however, should be considered experimental and incomplete for production use.

[9] for example, to send an email “when it becomes possible,” allowing the user to continue working without waiting for that email to actually be sent

[10] in all modern browsers, except Internet Explorer, which does not yet support it

[11] The tag is no longer used in HTML5.

[12] http://core.spip.org/projects/spip/repository/revisions/18754

[13] Another function added, experimentally, is sql_preferer_transaction to bypass a problem of slowness on multiple insertions on SQLite which are executed faster in transactional mode. This function returnstrue in SQLite only.

SPIP 3.0

cerdic, tetue — 2012-05-19T11:00:00Z

SPIP 3 : une nouvelle version marquée par la réécriture complète de l'espace privé en squelettes, une forte modularisation et une boucle DATA révolutionnaire.

SPIP 2.0 avait apporté les fonctionnalités permettant de l'utiliser comme un « framework » pour le développement d'applications Web, au-delà de sa vocation initiale de simple outil de publication.

SPIP 3 pousse la logique du « framework » jusqu'à se l'appliquer à lui-même : l'ensemble de l'espace privé de SPIP a été recodé en squelettes, sur la base des outils et fonctions proposés par le langage de squelettes de SPIP.

Cette remise à plat de l'espace privé a été l'occasion de repenser le fonctionnement des objets éditoriaux et de normaliser leur usage pour le rendre le plus générique possible : la plupart des particularités historiques de chaque objet (et les exceptions de traitement associées dans le code de SPIP) ont été gommées pour être ramenées à une simple déclaration.

La création de nouveaux objets éditoriaux et la personnalisation des objets existants deviennent ainsi beaucoup plus faciles et plus rapides.

SPIP 3 achève également la découpe du logiciel en plugins comme SPIP 2 l'avait amorcé : l'ensemble des fonctionnalités proposées par SPIP 2 repose dorénavant sur un noyau SPIP 3 accompagné de 23 plugins.

La découpe complète du noyau a permis de compléter ses API et points d'entrée pour les développeurs de plugins.

SPIP 3 se nourrit fortement des développements de la communauté SPIP-Zone, et marque une forte inversion : ce n'est plus le noyau qui tire les développements des plugins, mais les développements de plugins qui nourrissent l'avancée de SPIP par leurs expérimentations [1].

Parmi de nombreuses autres nouveautés fonctionnelles, SPIP 3 introduit une nouvelle boucle DATA qui permet enfin de boucler sur tout type de données et plus seulement sur les tables SQL. Il devient ainsi possible de parcourir soit une énumération, soit un fichier CSV, XML, YAML... Plus fort encore, la boucle DATA permet directement de boucler sur une URL : il devient possible de parcourir directement une feuille de calcul Google Spreadsheet, un calendrier en ligne, une liste de vidéos sur Youtube, des photos sur Flickr… le Web devient votre base de données !

Prérequis :
SPIP 3.0 requiert désormais au minimum une version 5.1.0 de PHP pour pouvoir fonctionner correctement.

Un nouvel espace privé [2]

Visuellement, l'espace privé demeure dans la continuité des versions précédentes, complétée de nouvelles icônes, avec :

pour les icônes principales de navigation, un jeu spécifique réalisé pour SPIP par Sébastien Desbenoît,
pour le reste de la page, l'adoption d'un jeu dérivé de FatCow.

La refonte de l'interface est essentiellement technique, même si elle a également permis de résoudre un certain nombre de défauts ergonomiques historiques.

La navigation principale est repensée et réorganisée. Le menu déroulant, désormais entièrement navigable au clavier, intègre aussi des temporisations pour faciliter son utilisation à la souris et être plus robuste aux mouvements mal contrôlés.

L'ensemble de l'espace privé est donc réécrit sous forme de squelettes rangés dans le répertoire prive/squelettes organisés par sous-dossiers correspondants à un découpage de la page en blocs. Ce découpage est utilisé notamment pour le rafraîchissement des morceaux de page en Ajax, évitant le rechargement complet des pages et fluidifiant les interactions [3].

De nombreux points d'entrée (utilisés en premier lieu par les plugins du noyau) sont disponibles sous forme de pipeline pour permettre aux plugins d'étendre les fonctionnalités de l'espace privé.

Les pages de l'espace privé sont réorganisées et renommées. En particulier toutes les pages d'objets éditoriaux utilisent un nommage cohérent fondé sur le nom de l'objet.

La réécriture a également permis de remettre à niveau la structure complète du HTML et son accessibilité. Un référentiel a été mis en place pour que les développeurs de plugins puissent réutiliser les mêmes structures, et que les ajouts d'interface restent homogènes avec le noyau.

Toutes les listes d'objet sont des squelettes qu'il devient facile de personnaliser. Elles bénéficient toutes du tri par colonne et de pagination ajax.

Un système d'échafaudage des pages d'objet permet de construire automatiquement une interface minimale pour les nouveaux objets déclarés par les plugins. Chaque élément de cette interface par défaut peut ensuite être personnalisé en fonction des particularités de chaque objet : [4].

Tous les formulaires interactifs sont écrits sous forme de formulaires CVT, ce qui permet d'assurer des interactions de qualité avec gestion systématique des messages d'erreur, vérification de saisie, ajax robuste à volonté, saisie multipage si nécessaire… Ils sont ainsi tous facilement extensibles par les plugins.

Autre nouveauté, en mode édition, SPIP 3 prend en compte le retour à la ligne simple (il n'est désormais plus nécessaire d'utiliser « _ »).

Enfin, l'espace privé intègre un mécanisme technique de thèmes qui permet de personnaliser les feuilles de style ou tout ou partie des icônes. Ce mécanisme pourra être utilisé par un plugin proposant des variantes activables par chaque utilisateur en fonction de ses préférences.

Modularisation en plugins

SPIP 3 achève donc la découpe du logiciel en plugins. Son noyau conserve la gestion des articles, rubriques et auteurs ; le langage de squelettes et l'ossature de l'espace privé. Toutes les autres fonctionnalités sont externalisées dans des plugins, automatiquement installés dans la distribution par défaut de SPIP 3. Ces plugins fournis par défaut sont désormais placés dans un dossier plugins-dist/ [5]

Cette découpe du noyau a permis de compléter un certain nombre d'API implicites, maintenant à disposition des développeurs de plugins qui peuvent ainsi ajouter des fonctionnalités sans limite, en prenant modèle sur les plugins natifs de SPIP.

Dans le domaine des plugins, SPIP 3 amène également une refonte importante du formalisme de déclaration XML. Outre une lisibilité améliorée, cette évolution intègre la question des traductions de plugins, ainsi que les outils d'alimentation automatique d'un annuaire des plugins de SPIP et un outil de chargement.

Par ailleurs, les plugins peuvent bénéficier des fonctions de mise à jour de base de données du core (avec reprise sur timeout) par simple déclaration de la procédure.

Les plugins distribués par défaut avec SPIP sont :

Brèves s'occupe de l'objet éditorial Brèves.
Compagnon propose l'affichage de textes pédagogiques d'information et d'accompagnement lors des premiers accès à l'espace privé.
Compresseur déjà présent dans SPIP 2.1, prend en charge l'optimisation des performances du site en compressant et concaténant les feuilles de style CSS et les fichiers JavaScript embarqués dans la page. Cette version du plugin améliore des feuilles par média. Utilisation de @media pour concaténer tous les médias en un seul fichier sans en modifier l'ordre de chargement. Gestion des urls absolues sans protocole pour que les feuilles de style compressées fonctionnent sur http et https.
Dump assure la gestion des sauvegardes et restaurations. La fonctionnalité a été complètement ré-écrite pour assurer une sauvegarde complète et fiable. Le format de sauvegarde est maintenant SQLite et toutes les tables sont systématiquement conservées.
Forum gère l'objet éditorial forum, tant pour le site public que pour les interactions éditoriales dans l'espace privé. Outre une interface de modération repensée, les forums sont maintenant utilisables sur tous les objets éditoriaux de SPIP (natifs ou ajoutés par des plugins).
Images, déjà dans SPIP 2.1, prend en charge tous les filtres d'images et de couleurs dans les squelettes.
jQuery UI implémente dans SPIP la librairie complémentaire. jQuery UI facilite la création de composants graphiques dynamiques : onglets, drag & drop, barres de progression, widgets, effets…
Mediabox intègre dans SPIP par défaut une boîte pop-in pour visualiser les médias ou proposer des interactions [6].
Medias [7] prend en charge la gestion des documents et images. Il propose une refonte de l'interface et rend les documents utilisables sur n'importe quel objet éditorial.
Mots apporte la gestion des mots-clés et groupes de mots. Les mots-clés sont maintenant utilisables sur tous les objets éditoriaux.
Organiseur assure les fonctions de messagerie et calendrier interne de l'espace privé. L'interface est complètement refondue. La messagerie interne bénéficie de notification par email, et le calendrier repose sur la librairie FullCalendar qui permet une navigation fluide.
Pétitions gère les pétitions sur les articles et propose une interface de modération repensée.
Porte plume, déjà dans SPIP 2.1, assure l'aide à la saisie.
Révisions assure le versionage utilisable sur tous les objets éditoriaux de SPIP. L'interface de gestion des révisions est modernisée.
SafeHTML, déjà dans SPIP 2.1, prend en charge la sécurisation des contenus externes potentiellement dangereux.
Sites assure le fonctionnement de l'objet éditorial « Site syndiqué » ainsi que des articles syndiqués. Une interface de modération des articles syndiqués est proposée.
Squelettes par rubriques assure le fonctionnement des squelettes suffixés (article-2.html pour les articles de la rubrique 2 et de ses sous-rubriques).
Statistiques assure le calcul des statistiques du site et des articles, et propose un affichage complètement refondu.
Support vieux navigateur, déjà dans SPIP 2.1, propose des fonctions JavaScript activables pour permettre aux vieilles versions de navigateurs d'afficher correctement votre site.
Svp permet la gestion complète des plugins : installation, activation, mise à jour, recherche…
Textwheel est un moteur typographique qui supporte intégralement les raccourcis de SPIP, décrits désormais dans un fichier de règles au format YAML. Ce moteur permet une nette accélération du traitement des raccourcis (jusqu'à 2 fois plus rapide sur certains contenus), et facilite l'évolution et la personnalisation des raccourcis.
Urls Étendues supporte les URLs propres ou arborescentes, et propose une interface de configuration ainsi qu'une interface de gestion avancée optionnelle pour gérer finement les URLs de chaque page.
Vertèbres, déjà dans SPIP 2.1, permet au webmestre d'afficher le contenu d'une table SQL de SPIP au moyen d'un squelette généré automatiquement d'après la structure SQL de la table. Cet affichage se fait maintenant dans l'espace privé.
Un nouveau jeu de squelettes par défaut

Pour marquer le coup, les squelettes par défaut ont été révisés. Par la répartition en plusieurs feuilles de styles ré-utilisables indépendamment (méthode Daisy, cf. Un, deux, trois… feuilles CSS !), ils constituent désormais un cadre de travail HTML/CSS modulaire, immédiatement utilisable pour démarrer un site. Ils proposent notamment un traitement typographique complet et harmonieux, inspiré du framework Blueprint. L'historique spip_style.css disparaît au profit de spip.css, qui peut être utilisée en complément de votre framework habituel.

Les squelettes adoptent une nouvelle structure HTML de base qui anticipe le HTML5, "responsive" par défaut, et embarque des sélecteurs conditionnels pour plus de souplesse CSS.

De nouvelles fonctionnalités

Le support de SQLite a été nettement amélioré, et c'est le format de base de données proposé par défaut lors d'une nouvelle installation (quand il est supporté par le serveur), compte tenu de sa simplicité de mise en œuvre [8].

La gestion des objets éditoriaux est généralisée. Par suite, les auteurs, documents, mots-clés, forums, révisions et logos sont utilisables sur n'importe quel objet (tous ceux de SPIP mais aussi tout objet éditorial ajouté par un plugin avec la nouvelle API de déclaration).
La gestion du statut, de la date de publication, de la langue et de la traduction est également généralisée et utilisable sur tout objet par simple déclaration.
Lorsque le signalement de l'édition concourante est activé, tout objet édité est désormais pris en compte dans le signalement.

L'identité du site est complétée d'un slogan du site, entre titre et descriptif long, utilisable avec la balise #SLOGAN_SITE_SPIP.

L'écran de sécurité est intégré en standard.

Les logs (fichiers de trace) bénéficient d'une gestion par niveau d'importance. Par défaut, les logs sont beaucoup moins verbeux en production et ne signalent que les anomalies ou informations importantes. Le niveau de log peut être ajusté pour le debug ou le développement, permettant ainsi d'avoir toutes les informations nécessaires.

Le cron périodique qui reposait sur des fichiers a été supprimé au profit d'une file de tâches en attente (qui gère aussi les tâches périodiques). Cette file de tâches permet de programmer des actions asynchrones [9] et propose une API simple d'utilisation pour les développeurs de plugin.

L'ajax des squelettes ({ajax} sur les INCLURE) bénéficie d'une prise en charge des attributs ARIA pour améliorer son accessibilité. De plus, l'historique de navigation est aussi automatiquement pris en charge grâce à l'API « History » de HTML5 [10]. L'URL du navigateur est donc mise à jour automatiquement sur les liens ajax, et permet les retours en arrière sans soucis.

Les modèles utilisés dans du texte éditorial reçoivent automatiquement l'environnement du squelette dans lequel est affiché le texte [11].

Les formulaires des l'espace privé utilisent les possibilités de HTML5 avec par exemple les attributs required ou placeholder.

Les squelettes peuvent maintenant échapper les caractères # [ ] ( ) { } < > en utilisant une barre oblique \. Il devient possible d'écrire des conditions par exemple sur une case à cocher de formulaire de manière bien plus élégante, sans que les crochets de l'attribut name n'interfèrent avec les crochets de la balise englobante :

[(#ENV{param}|oui)

Avec tendresse ?

]

Raccourcis

Un raccourci pour les abréviations a été introduit nativement : [SNCF|Société Nationale des Chemins de fer Français] (ou [CMS|Content Management System{en}]) pour indiquer une langue différente du texte principal) génère une balise abbr [12].

Les modèles de document peuvent prendre en argument la largeur ou la hauteur pour réduire leur dimension : .

Les tableaux à 2 entrées (horizontale et verticale) sont désormais gérés correctement.

Il n'est désormais plus nécessaire d'utiliser le raccourci « _ » pour produire un retour ligne simple.
Pour retrouver le fonctionnement antérieur, ce nouveau comportement est débrayable en utilisant un define('_AUTOBR', ''); dans son fichier mes_options.php.

Boucles

Le système de boucles de SPIP a été généralisé pour s'appliquer non plus directement sur une table SQL mais sur un itérateur. Un itérateur SQL assure le fonctionnement historique des boucles sur les tables SQL, mais il devient possible de boucler sur toute donnée itérable : Les itérateurs de SPIP

Premier exemple de nouvelle application : la boucle DATA étend le fonctionnement des boucles à toute information structurée sous forme de tableau. Il devient possible de boucler sur un fichier CSV, sur une url distante qui renvoie une information en JSON... :

Exemples de BOUCLE(DATA)
http://zzz.rezo.net/La-boucle-iCalendar.html
http://zzz.rezo.net/Exemples-de-boucles-YQL.html

Pour assurer la migration facile des squelettes qui utilisaient des boucles POUR et CONDITION, celles-ci sont également supportées comme cas particuliers de la boucle DATA, dans la même syntaxe que celle qui existait.

Critères

{si ...} : permet de conditionner l'exécution d'une boucle à la condition exprimée dans le critère, qui ne dépend pas des données en base mais du contexte du squelette.

{tri ...} : associé à la balise #TRI pour des tris faciles.

{feuille} : permet de sélectionner les rubriques sans enfants (celles tout en bas de la hiérarchie).

{noeud} : permet de sélectionner les rubriques qui ont des enfants.

{!racine} : exclut les rubriques de la racine.

{profondeur=3} : permet de sélectionner les rubriques du 3e niveau (la racine est le niveau 0, les rubriques secteurs sont le niveau 1, puis les rubriques du dessous le niveau 2 etc ...).

Balises

Les modèles peuvent avoir un cache s'ils contiennent une balise #CACHE (mais par défaut ils n'en ont pas, comme auparavant).

Dans l'espace privé, les squelettes n'ont pas de cache non plus, sauf si une balise #CACHE est présente.

#LOGO_DOCUMENT peut prendre en argument le mode d'affichage du logo :

auto (par défaut, et c'est le fonctionnement historique) affiche automatiquement la vignette du document si existante, sinon un aperçu ; et sinon l'icône correspondant au type de document.
icone indique que c'est l'icône correspondant au type du fichier qui doit être affichée
apercu affiche un aperçu de l'image exclusivement, même si une vignette existe.
vignette affiche la vignette du document si elle existe, ou sinon rien.

La balise #SPIP_CRON disparaît et n'a plus d'effet dans les squelettes où elle serait encore utilisée.

#BOUTON_ACTION{libellé, url, classe, confirm, title, callback} génère un mini formulaire HTML avec un seul bouton qui affiche « libellé » et déclenche au clic un POST vers « url ». Cette balise est à utiliser de préférence à un lien quand la page « url » modifie la base de données. Si la « classe » contient la valeur « ajax » le bouton déclenchera un rechargement du bloc ajax qui l'inclue. « confirm » permet d'indiquer un message pour faire confirmer l'action par l'utilisateur, « title » le contenu de l'attribut homonyme sur le bouton, et « callback » une fonction javascript à appeler lors du clic sur le bouton.

#INFO_XXX{article, 13} : permet de retrouver le #XXX sans faire une boucle ARTICLES sur l'article 13 (utilisable pour toute boucle et tout champ de la boucle : #INFO_TITRE{article,13}, #INFO_NOM{auteur,2}...)

#CONFIG{nom} permet d'afficher la valeur de la meta de configuration nom.
Si la meta est un tableau, il est possible d'accéder directement à des sous valeurs avec la syntaxe #CONFIG{nom/sousvaleur} qui renverra la sousvaleur de la meta nom.
Pour accéder à la meta d'une table spécifique à un plugin, il faut utiliser la syntaxe #CONFIG{/metamonplugin/nom} : en commençant par un /, on indique que l'on veut la meta nom de la table spip_metamonplugin au lieu de la table spip_meta de SPIP.
Dans tous les cas, il est possible d'indiquer en second argument la valeur par défaut qui doit être utilisée si la meta n'existe pas encore : #CONFIG{nom,valeurpardefaut}

À l'instar de #CONFIG{nom/sousvaleur} les balises #ENV, #GET, #SESSION permettent d'utiliser des barres obliques pour obtenir des sous valeurs de tableau tel que :#ENV{nom/sousvaleur}, #GET{tableau/cle/souscle}, #SESSION{prefs/couleur}.

#PUBLIE : pour tester l'état (publié ou non) d'un objet. S'utilise dans une boucle, porte implicitement sur l'objet en cours ou avec des arguments explicites : [(#PUBLIE{article, 3}|oui) ... ], sur tout autre objet.

#CLE et #VALEUR sont les deux balises qui permettent d'afficher la clé et la valeur dans une boucle DATA
#VALEUR{x} permet d'afficher la sous valeur de x si #VALEUR est un tableau (équivalent à [(#VALEUR|table_valeur{x})]). On peut enchaîner plusieurs sous index #VALEUR{x/y/z} pour afficher une valeur dans un sous-niveau du tableau.

#PRODUIRE : renvoie le nom d'un fichier statique produit à partir d'un squelette. Utile pour une feuille de style calculée ou un fichier javascript calculé. La syntaxe est la même que pour la balise #INCLURE : #PRODUIRE{fond=mafeuille.css,couleur=ffffff} pour utiliser le squelette mafeuille.css.html

#LISTE{a,b,c} renvoie simplement un tableau contenant les valeurs a,b et c. C'est une écriture simplifiée de #ARRAY{0,a,1,b,2,c}.

#TOTAL_UNIQUE renvoie le nombre d'éléments affichés par l'intermédiaire du filtre |unique. Si on utilise |unique{nom}, il faut faire référence au même nom dans la balise : #TOTAL_UNIQUE{nom}

Dans l'espace privé :

#AIDER{surtitre} permet d'afficher un lien vers la section surtitre de l'aide de SPIP.

#BOITE_OUVRIR, #BOITE_PIED et #BOITE_FERMER permettent d'utiliser les boites stylées de l'espace privé :

#BOITE_OUVRIR{titre,classe} ouvre une boîte. le titre peut être omis. Les classes stylées dans l'espace privé sont : simple, info, note, raccourcis et important ;
le HTML qui suit est inclus dans la boîte ;
#BOITE_PIED permet de passer au pied de la boîte quand un pied est nécessaire.
#BOITE_FERMER ferme la boîte.

Pour de nombreux exemples, voir la page de l'espace privé ecrire/?exec=charte_boites proposée par le plugin http://plugins.spip.net/dev

#FORMULAIRE_RECHERCHE_ECRIRE affiche le formulaire de recherche de l'espace privé. On peut lui indiquer en premier argument l'url vers laquelle il doit pointer, et une classe en second argument. En présence de javascript le formulaire se comporte comme un lien vers url avec le paramètre recherche fourni par la saisie. Si on indique la classe ajax en second argument, le formulaire provoque le rechargement du bloc ajax incluant, comme un lien ajax donc : #FORMULAIRE_RECHERCHE_ECRIRE{#SELF, ajax}

#CHEMIN_IMAGE{article-24.png} renvoie le chemin vers l'icône article-24.png du thème de l'espace privé en cours d'utilisation par l'auteur connecté.

Filtres

|lien_ou_expose permet de construire simplement un menu de plusieurs liens en exposant celui qui est sélectionné par un et en gardant un lien sinon. Exemple : [(#URL_PAGE{mapage}|lien_ou_expose{libelle, #ENV{page}|=={mapage}, classe, title, rel})]

|singulier_ou_pluriel affiche une chaîne ou une autre en fonction du nombre sur lequel il est appliqué : [(#TOTAL_BOUCLE|singulier_ou_pluriel{1_article,nb_articles})]. 1_article et nb_articles sont des chaînes de langue qui reçoivent le nombre en argument @nb@. Si le nombre est zéro, le filtre n'affiche rien.

|balise_img permet de construire rapidement une balise HTML à partir d'un nom de fichier en renseignant systématiquement le width et le height pour accélérer le rendu de la page : [(#CHEMIN{monimage.png}|balise_img{alt,class})]

|affdate_debut_fin affiche sous forme sympathique un intervalle de temps entre une date de début et une date de fin, en prenant en compte le fait que la date de début et la date de fin sont ou non le même jour, le même mois, la même année, et en prenant en compte l'affichage de l'heure ou non (second argument, oui ou non. Exemple :
[(#DATE_DEBUT|affdate_debut_fin{#DATE_FIN,horaireouinon})]

|timestamp ajoute au nom d'un fichier un horodatage sous la forme ?1234567890 où le nombre représente la date du fichier compté en secondes depuis le 1er janvier 1970. Ce filtre est utile pour référencer par exemple des feuilles de styles en s'assurant que le navigateur les rechargera quand leur url change :
[]

|objet_icone renvoie l'icône standard d'un objet de SPIP. Par défaut, la taille 24px est renvoyée sauf si la taille 16 ou 32 est demandée en argument : [(#OBJET|objet_icone{16})]

|objet_info renvoie une propriété d'un objet de SPIP telle que déclarée (ou automatiquement renseignée par SPIP) via l'API declarer_tables_objets_sql

|objet_afficher_nb affiche le nombre d'objets en prenant en compte le nombre auquel le filtre s'applique et les chaînes de langue déclarées pour l'objet : [(#TOTAL_BOUCLE|objet_afficher_nb{auteur})] affichera par exemple 1 auteur ou 23 auteurs.

|wrap encadre un texte d'une balise html : [(#TITRE|wrap{
})] produit le même résultat que [(#TITRE) ]

|generer_info_entite affiche le champ d'un objet SPIP : [(#ID_ARTICLE|generer_info_entite{article,titre})] renvoie le titre mis en forme de l'article #ID_ARTICLE. C'est équivalent ici à [(#INFO_TITRE{article,#ID_ARTICLE})].

Dans l'espace privé :

|icone_horizontale affiche une icône de l'espace privé au format horizontal. La syntaxe est : [(#URL|icone_horizontale{libelle,icone,fonction})]. icone peut être désigné en abrégé (article) et sera alors au format 24px ou explicitement (article-24.png). Le 3ème argument fonction précise une famille d'action associée à l'icône et peut être au choix add, del, edit, new, ou omis. Exemple [(#URL_ECRIRE{auteur_edit,new=oui}|icone_horizontale{<:icone_creer_nouvel_auteur:>,auteur,new})]

|icone_verticale affiche une icône de l'espace privé au format vertical. La syntaxe est la même que pour |icone_horizontale

|bouton_action_horizontal utilise la même syntaxe que |icone_horizontale et affichera un résultat visuellement semblable. Cependant le markup HTML sera du même type que celui de #BOUTON_ACTION pour déclencher un POST vers l'url et est donc utile quand l'url modifie la base de données.

|sinon_interdire_acces placé à n'importe quel endroit de la page permet de bloquer l'accès à celle-ci quand l'expression à laquelle il s'applique est fausse. Dans ce cas une page d'erreur est affichée, sauf si une url de redirection est fournie en argument (on peut aussi alors fournir un status http de redirection en second argument). On l'utilise généralement sur une vérification d'autorisation [(#AUTORISER{modifier,article,#ID_ARTICLE}|sinon_interdire_acces)]

JavaScript

SPIP 3 utilise la version 1.7.2 de jQuery et intègre désormais jQuery UI en version 1.8.20. Il devient possible d'utiliser une version différente de jQuery dans le site public en surchargeant simplement javascript/jquery.js dans le dossier squelettes/ sans risquer de casser l'espace privé.

Liens ajax :
Les liens .ajax ne cassent plus l'historique de navigation sur les navigateurs qui supportent l'API HTML5 History (Firefox, Safari, Chrome à la date de cet article). C'est-à-dire que lorsqu'on clique sur un lien ajax de SPIP qui recharge une partie de la page, l'URL est mise à jour dans le navigateur et le visiteur peut cliquer sur Précédent pour revenir en arrière.

Classes spéciales sur les liens ajax :

.nohistory indique que le lien n'affecte pas l'historique de navigation lorsqu'il est cliqué ;
.preload indique à SPIP que le contenu du lien ajax doit être préchargé au moment où la page est chargée. Ainsi le clic sur le lien produira une mise à jour immédiate ;
.nocache indique à SPIP que le contenu du lien ajax ne doit pas être mis en cache. Ainsi plusieurs clics sur le même lien provoqueront autant de chargements depuis le serveur (par défaut, seul le premier chargement à lieu pour une url donnée et le contenu est ensuite mémorisé par le navigateur).

Rechargement télécommandé de blocs ajax :
Les liens .ajax permettent par défaut le rechargement du bloc ajax qui les contient, mais il est parfois nécessaire de provoquer le rechargement d'un autre bloc ajax de la page.

Pour cela, il devient possible de nommer les blocs ajax au moment de leur inclusion :
. Le bloc ajax ainsi nommé peut ensuite être rechargé via l'appel de ajaxReload('nomdubloc');. Il est possible de passer en second argument une liste d'options contenant :

callback : fonction callback qui doit être appelée après le chargement ajax du bloc
args : liste d'argument qui seront passés à l'url lors du chargement du bloc (permet de modifier le #ENV du bloc mis à jour) ;
history : indique si le rechargement affecte ou non l'historique de navigation (faux par défaut). Exemple :
ajaxReload('nomdubloc', {

callback:function(){alert('fini');},

args:{id_article:3},

history:false

});

ajaxReload peut être utilisé également sur un sélecteur jQuery auquel cas il provoquera le rechargement du plus petit bloc ajax qui contient l'élément ciblé. Il ne prend alors qu'un argument possible (le tableau d'options) : $('#contenu').ajaxReload({args:{id_article:3}})

Animations javascript :
Lors des interactions déclenchées par l'utilisateur, il est possible de déclencher plusieurs animations type qui s'appliquent toutes sur un sélecteur jQuery :

jQuery('#monid').animateLoading() déclenche l'animation de chargement sur #monid (automatiquement déclenchée lors des rechargements ajax)
jQuery('#monid').endLoading() arrête l'animation de chargement sur #monid (automatiquement déclenchée lors des rechargements ajax)
jQuery('#monid').animateAppend() anime le bloc #monid pour montrer qu'il vient d'être ajouté par l'interaction
jQuery('#monid').animateRemove() anime le bloc #monid pour montrer qu'il est supprimé par l'interaction

Fonctions utilitaires :
parametre_url() s'utilise comme sa version PHP de parametre_url pour ajouter, supprimer, récupérer des arguments d'une URL :

parametre_url(url,arg,value) ajoute arg=value à url et retourne l'url modifiée ;
parametre_url(url,arg,'') supprime la valeur de arg dans url et retourne l'url modifiée ;
parametre_url(url,arg) retourne la valeur de arg dans url

$('a').followLink() suit le lien en simulant un clic dessus (prend en compte le fait que le lien est ou non un lien ajax).

Popin dans l'espace privé :
Un lien vers une page de l'espace privé avec une classe .popin provoque l'ouverture d'une popin qui contient le coeur de la page pointée (bloc contenu/). Le lien conserve sa capacité à être ouvert dans un autre onglet via clic droit et la page complète est affichée dans ce cas.

API

SPIP 3 introduit plusieurs API génériques dans la gestion des objets éditoriaux :

une gestion générique des tables de liens d'un objet avec n'importe quel autre objet : c'est l'API editer_liens
La création de nouveaux objets éditoriaux est simplifiée par une API déclarative
une gestion générique des fonctions d'insertion, modification ou publication des objets éditoriaux : l'API editer_objet
objet_test_si_publie($objet, $id_objet) permet de tester facilement si un objet est publié ou non en fonction de son statut tel que déclaré (et en fonction d'une éventuelle post-publication)
generer_url_ecrire_objet($objet,$id_objet,$args, $ancre) renvoie l'url vers la page de l'objet dans l'espace privé. $args et $ancre sont optionnels.
le pipeline optimiser_base_disparus est appelé lors du nettoyage en base des objets à la poubelles et des liens morts qui en résultent

SPIP 3 dispose également d'une gestion de file de tâches qui permet de programmer l'exécution future ou simplement asynchone (ASAP mais sans faire attendre l'utilisateur) de fonctions.

La mise en place de configuration des plugins est simplifiée par la prise en charge automatisée des formulaires #FORMULAIRE_CONFIGURER_XXX et par l'utilisation des fonctions lire_config, ecrire_config, effacer_config (voir Configurer une fonctionnalité de votre site, ou un plugin).

Les formulaires CVT permettent facilement de faire des formulaires en plusieurs pages, et supportent également la sauvegarde automatique de la saisie par simple déclaration.
Un pipeline formulaire_fond permet de personnaliser le fond des formulaires (pour modifier le HTML du formulaire) [13]

Dans l'API SQL :

la fonction sql_skip est ajoutée et permet de sauter un certain nombre de résultats.
Les valeurs null dans sql_updateq et sql_insertq sont traduites en NULL SQL et ne sont plus assimilées à une chaîne vide.
les fonctions sql_demarrer_transaction et sql_terminer_transaction permettent respectivement comme leur nom le suggère de démarrer ou de clôturer une transaction SQL [14].

Introduction d'un point d'entrée bac-à-sable, (public/sandbox.php) pour la compilation des squelettes, permet à un plugin de gérer la compilation des squelettes dans un ensemble de filtres et fonctions en liste blanche ou liste noire, et d'interdire le PHP dans les squelettes.

Spécialisation des critères :
Il est possible de préfixer par le nom du serveur et/ou le nom de la table le nom de la fonction critère. La recherche se fait dans l'ordre :

critere_serveur_TABLE_moncritere_dist,
critere_serveur_TABLE_moncritere,
critere_serveur_moncritere_dist,
critere_serveur_moncritere,
critere_TABLE_moncritere_dist,
critere_TABLE_moncritere,
critere_moncritere_dist,
critere_moncritere

Dans le fichier options.php d'un plugin ou dans le fichier mes_options.php, $GLOBALS['marqueur_skel'] .= ":prefixe" permet de différencier le cache des squelettes compilés comme $GLOBALS['marqueur'] .= ":prefixe" permettait déjà de différencier le cache des squelettes.

[1] Outre le Porte-plume déjà intégré dans SPIP 2 et qui initiait ce mouvement, on peut citer notamment les plugins Afficher_objets, Base CSS, Navigation du privé, CVT multi-étapes, Forum, Job-queue, Mediabox, Médiathèque, TextWheel, URLs éditables, Comments, qui ont, pour certains, inspiré fortement le développement de SPIP lui-même ; pour d'autres été intégrés, avec quelquefois certaines évolutions.

[2] Ce chantier avait été amorcé depuis quelque temps sur la Zone, et ceux qui d'entre vous utilisaient déjà le plugin Navigation du privé ou la médiathèque retrouveront vite leurs marques.

[3] Par exemple, le passage en édition sur un article devient instantané grâce au pré-chargement Ajax.

[4] http://core.spip.org/projects/spip/repository/revisions/17650

[5] en SPIP 2.1 ils étaient placés dans le dossier extensions/ désormais inutile.

[6] C'est une alternative aux plugin Thickbox, LightBox... qui repose sur la librairie Colorbox

[7] Connu pour SPIP 2 sous le nom "Médiathèque"

[8] en revanche le support de PostGreSQL doit être considéré comme expérimental et incomplet pour un usage en production

[9] Par exemple, pour l'envoi d'un mail "dès que possible" qui permet de rendre la main à l'utilisateur immédiatement sans devoir attendre que le mail soit effectivement envoyé

[10] dans tous les navigateurs modernes à l'exception de Internet Explorer qui ne la supporte pas encore

[11] Voir Utiliser les modèles

[12] La balise n'est plus utilisée en HTML5.

[13] http://core.spip.org/projects/spip/repository/revisions/18754

[14] Est ajouté de manière expérimentale également sql_preferer_transaction présent plutôt pour contourner un problème de lenteur sur des insertions multiples avec SQLite, qui sont exécutées plus rapidement en mode transactionnel. Cette fonction renvoie true uniquement en SQLite

API de gestion de la file des travaux

cerdic — 2012-05-19T09:50:41Z

SPIP 3.0 intègre nativement une interface de programmation (ou API) de gestion de file de travaux. Elle permet de programmer des tâches à exécuter dans le futur, ou simplement le plus tôt possible mais sans faire attendre l'utilisateur [1].

Les travaux programmés sont à tout moment visualisables dans l'espace d'administration via le menu Maintenance > Liste des travaux. La page de suivi permet de forcer l'exécution immédiate d'une tâche, ou de supprimer certaines tâches.

Ajouter un travail dans la file
$id_job = job_queue_add($function, $description, $arguments = array(), $file = '', $no_duplicate = FALSE, $time=0, $priority=0)
Avec les arguments :

$function : le nom de la fonction PHP qui doit être appelée
$description : une description humainement compréhensible de ce que fait la tache (essentiellement pour l'affichage dans la page de suivi de l'espace privé)
$arguments (facultatif, vide par défaut) : les arguments qui seront passés à la fonction, sous forme de tableau PHP
$file (facultatif, vide par défaut) : nom du fichier à inclure. Si le nom finit par un / alors on considère que c'est un répertoire et SPIP fera un charger_fonction($function,$file)
$no_duplicate (facultatif, false par défaut)
si vaut true la tâche ne sera pas ajoutée si elle existe déjà en file d'attente avec la même fonction et les mêmes arguments.
si vaut 'function_only' la tâche ne sera pas ajoutée si elle existe déjà en file d'attente avec la même fonction indépendamment de ses arguments
$time (facultatif, 0 par défaut) indique la date sous forme de timestamp à laquelle la tâche doit être programmée. Si 0 ou une date passée, la tâche sera exécutée aussitôt que possible (en général en fin hit, en asynchrone).
$priority (facultatif, 0 par défaut) indique un niveau de priorité entre -10 et +10. Les tâches sont exécutées par ordre de priorité décroissante, une fois leur date d'exécution passée. La priorité est surtout utilisée quand une tâche cron indique qu'elle n'a pas fini et doit être relancée : dans ce cas SPIP réduit sa priorité pour être sûr que celle tâche ne monopolise pas la file d'attente.

La fonction renvoie le numéro de travail ajouté ou 0 si aucun travail n'a été ajouté.

Supprimer un travail de la file
job_queue_remove($id_job)
$id_job est le numéro du travail en attente, tel que retourné par la fonction job_queue_add

La fonction retourne true si le travail a bien été trouvé et supprimé, false sinon.

Associer un travail à un objet éditorial
job_queue_link($id_job,$objets)
Avec les arguments :

$id_job : le numéro de travail en attente, tel que retourné par la fonction job_queue_add
$objets une liste d'objets sous la forme d'un tableau d'objets array(array('objet'=>'article','id_objet'=>23),...)

Lorsque des travaux sont associés à un objet, ils apparaissent sur la page de l'espace privé de cet objet, et les auteurs qui ont le droit de modifier l'objet peuvent aussi supprimer le travail avant son exécution.

[1] Ces fonctionnalités étaient disponibles pour SPIP 2.1 dans le plugin job_queue

API « editer_objet »

cerdic — 2012-05-19T09:49:54Z

L'ajout, la modification et la publication des instances d'objets éditoriaux sont simplifiés par une interface de programmation (ou API) constituée de 3 fonctions génériques qui peuvent servir pour manipuler tous les objets de SPIP.

Insérer

Une nouvelle instance d'un objet éditorial est créée en base par

include_spip('action/editer_objet');

$id_objet = objet_inserer($objet, $id_parent);

Télécharger

objet_inserer prend 2 arguments :

$objet est le nom de l'objet inséré (article, breve,...)
$id_parent (facultatif) est l'id du parent de l'objet (id_rubrique pour un article ou une breve, id_groupe pour un mot...)

Les pipelines pre_insertion et post_insertion sont appelés automatiquement par la fonction.

Si, pour l'objet demandé, une fonction spécifique xxx_inserer existe dans action/editer_xxx, elle sera automatiquement appelée par objet_inserer à la place du traitement générique.

La fonction retourne l'id de l'enregistrement ajouté en base, ou 0 en cas d'échec.

Modifier

Pour modifier une instance d'un objet en base, on utilise la fonction : objet_modifier

include_spip('action/editer_objet');

objet_modifier($objet, $id_objet, $set);

Télécharger

Les 3 arguments :

$objet indique le nom de l'objet modifié
$id_objet donne l'id de l'objet modifié
$set est un tableau associatif champ=>valeur des champs modifiés

La fonction appelle automatiquement les pipelines pre_edition et post_edition.

Si pour l'objet demandé, une fonction spécifique xxx_modifier existe dans action/editer_xxx, elle sera automatiquement appelée par objet_modifier à la place du traitement générique.

La fonction retourne une chaîne vide si tout s'est bien passé ou l'erreur en cas d'échec.

La fonction objet_modifier vérifie les droits de l'auteur de la session en cours à faire l'action, via un appel à autoriser('modifier', $objet, $id_objet). Si elle est appelée par une tâche anonyme, il sera nécessaire d'accorder une autorisation exceptionnelle comme indiquée dans API « autoriser ».

Publier

Pour la publication d'un objet (modification du statut ou de la date), il convient d'appeler la même fonction objet_modifier de la même façon que pour la modification.

Cette fonction délègue à objet_instituer la mise à jour des champs qui concernent le statut de l'objet. Il est ainsi possible de modifier le contenu d'un objet et de le publier en un seul appel.

Si une fonction xxx_instituer existe dans action/editer_xxx elle sera automatiquement appelée par objet_instituer à la place du traitement générique.

La fonction objet_instituer vérifie les droits de l'auteur de la session en cours à faire l'action, via un appel à autoriser('instituer', $objet, $id_objet). Si elle est appelée par une tâche anonyme, il sera nécessaire d'accorder une autorisation exceptionnelle comme indiquée dans API « autoriser ».

API « autoriser »

cerdic — 2012-05-19T09:49:00Z

L'interface de programmation (API) « autoriser » introduite dans SPIP 2.0 permet de gérer finement les autorisations données à un auteur d'effectuer une action sur un objet.

Vérifier une autorisation

La vérification d'une autorisation se fait par un appel de la forme :

include_spip('inc/autoriser');

if (autoriser('modifier', 'article', $id_article)) {

...

}

Télécharger

La fonction autoriser($faire, $type, $id, $qui, $opt) accepte 5 arguments dont seul le premier est obligatoire :

$faire est une chaîne qui désigne l'action soumise à autorisation. C'est en règle générale un verbe simple (modifier, creer, supprimer, voir, configurer...), parfois associé à un contexte (les mots sont alors collés : changerlangue, publierdans...).
Il y a quelques exceptions où le $faire n'est pas un verbe et s'utilise sans aucun autre argument (autoriser('webmestre') par exemple, ou autoriser('ecrire') —qui désigne ici l'espace d'administration et non l'action—).
$type est une chaîne qui désigne sur quoi porte l'action. C'est en général le type d'un objet éditorial (article, rubrique, mot, groupe-mots, ...).
$id désigne l'id (la clé primaire) de l'objet sur lequel porte l'action. $id est en général un nombre entier, mais peut être une chaîne si cela correspond à la clé primaire de la table SQL concernée.
$qui désigne l'auteur (au sens SPIP) qui va faire l'action. Si il n'est pas fourni (ou null dans l'appel de la fonction autoriser, c'est implicitement l'auteur connecté qui est pris en compte. Sinon $qui peut être l'id_auteur d'un auteur dont on veut vérifier les droits, ou un tableau associatif qui décrit l'auteur (tableau qui contient alors les champs de la table spip_auteurs pour l'auteur concerné)
$opt est un tableau associatif de données supplémentaires contextuelles concernant l'action qui sont parfois utilisées par l'autorisation. Par exemple lorsqu'on veut modifier/publier un article, on appellera autoriser('instituer', 'article', $id_article, null, array('statut' => 'publie'))

La fonction autoriser retourne « true » ou « false » en fonction des droits de l'auteur à faire l'action demandée.

Dans un squelette, la vérification d'une autorisation se fait par la balise #AUTORISER.

Donner une autorisation exceptionnelle

Il arrive qu'on ait besoin de faire une action qui sera soumise à autorisation pour un auteur qui normalement n'en a pas le droit. Cela peut se produire, par exemple, dans le cas d'une action programmée qui sera alors exécutée anonymement.

Dans ce cas, il existe un mécanisme via la fonction autoriser_exception qui donne une autorisation exceptionnelle, le temps de réaliser l'action concernée.

include_spip('inc/autoriser');

// donner une autorisation exceptionnelle temporaire

autoriser_exception('modifier', 'article', $id_article);

// réaliser l'action désirée

include_spip('action/editer_objet');

objet_modifier('article', $id_article, array('titre' => 'Nouveau titre'));

// retirer l'autorisation exceptionnelle

autoriser_exception('modifier', 'article', $id_article, false);

Télécharger

La fonction autoriser_exception($faire, $type, $id, $autoriser) prend 4 arguments :

$faire avec la même signification que pour autoriser()
$type avec la même signification que pour autoriser()
$id avec la même signification que pour autoriser()
$autoriser qui est un booléen et indique si l'autorisation exceptionnelle est accordée ou non :
Lorsque $autoriser vaut « true » ou n'est pas fourni, on accorde une autorisation exceptionnelle : tous les appels suivant à autoriser() avec les mêmes arguments $faire, $type et $id renverront true
Lorsque $autoriser vaut « false » cela signifie que l'autorisation revient sous le régime normal et sera vérifiée selon la règle en vigueur (elle peut donc être encore autorisée ou effectivement interdite). Le false n'indique donc pas ici qu'on interdit l'action, mais simplement qu'il n'y a plus d'exception.
Déclarer une nouvelle autorisation

Lorsque la fonction générique autoriser() est appelée, elle cherche une fonction nommée à laquelle déléguer la vérification.

Si aucun $type n'est fourni dans l'appel à autoriser(), la recherche de la fonction se fait dans l'ordre suivant :

autoriser_$faire
autoriser_$faire_dist
autoriser_defaut
autoriser_defaut_dist

Si un $type est fourni dans l'appel à autoriser(), la recherche se fait dans l'ordre suivant :

autoriser_$type_$faire
autoriser_$type_$faire_dist
autoriser_$type
autoriser_$type_dist
autoriser_$faire
autoriser_$faire_dist
autoriser_defaut
autoriser_defaut_dist

Dans les deux cas, la recherche va du plus précis vers le plus général. Cela permet de définir des familles d'autorisation avec une règle générale (pour une action par exemple), que l'on précise ensuite pour certains objets qui suivent une règle différente.

Pour définir une autorisation, il suffit donc de créer une fonction avec l'un des noms de la liste ci-dessus. La fonction recevra en arguments ceux envoyés à la fonction autoriser() et doit renvoyer « true » ou « false ».

On peut définir une autorisation générique. Lorsque c'est une autorisation qui n'est pas encore définie, on la suffixe en général par un _dist qui permet toujours à un webmestre de la surcharger dans son fichier mes_options.php (en déclarant la fonction de même nom, mais sans son suffixe _dist).

Attention : on voit que dans le nom de la fonction, l'ordre de $faire et $type est inversé par rapport à celui de l'appel à autoriser().

À noter également qu'à partir de SPIP 3.0 le $type est présumé correspondre à un objet, et est normalisé lors de l'appel : vérification qu'il correspond bien à un type d'objet et sinon suppression du « s » final. Cela permet d'assurer qu'on appellera bien la bonne fonction d'autorisation même si on utilise un synonyme du $type (syndic au lieu de site par exemple, ou groupes_mot au lieu de groupe_mots qui est une exception de nommage).
Il est cependant possible d'échapper à cette normalisation en préfixant le $type par un '_' (underscore) dans l'appel à autoriser().

Dans tous les cas, tous les autres caractères '_' sont retirés du $type

Ainsi un appel à autoriser('modifier', 'groupes_mots', $id_groupe) délèguera à la fonction autoriser_groupemots_modifier() (ou l'une des variantes selon la règle ci-dessus si cette fonction précise n'existe pas).
Dans les versions antérieures à SPIP 3.0 il convient de toujours faire très attention à bien utiliser le nom de l'objet sans erreur, car sinon l'autorisation par défaut sera appelée ce qui peut conduire à une erreur d'autorisation plus ou moins grave selon le cas.

Exemple de fonction d'autorisation :

/**

* Autoriser a creer un article :

* Il faut qu'une rubrique existe et qu'on ait le statut necessaire pour creer

*

* @return bool

*/

function autoriser_article_creer_dist($faire, $type, $id, $qui, $opt) {

return (sql_countsel('spip_rubriques')>0 AND in_array($qui['statut'], array('0minirezo', '1comite')));

}

Télécharger
Aide au développement

Lors du développement d'un plugin, il peut être utile de comprendre comment sont appelées les autorisations et dans quel ordre d'enchaînement.

Pour cela il suffit d'ajouter la ligne suivante dans le fichier mes_options.php :

define('_DEBUG_AUTORISER', true);

Chaque appel à autoriser() sera alors tracé dans le fichier spip.log avec le nom de la fonction appelée et le résultat qu'elle a retourné.

#HTML5

davux — 2012-05-19T09:31:16Z

Permet de tester si le site est en HTML5.

Il arrive souvent que SPIP, ainsi que les plugins, génèrent des bouts de code HTML sur le site public. Avec l'arrivée du HTML5, on a désormais la possibilité de produire du HTML plus sémantique, que ce soit par les nouvelles balises, les nouveaux éléments de formulaire, etc.

Cependant, sil l'on souhaite continuer à avoir un site valide au sens du W3C (organisme de standardisation du langage HTML entre autres), il est nécessaire que l'utilisation de code HTML5 soit accompagnée de la déclaration du doctype suivant :

Cela signifie donc que SPIP et les plugins ne peuvent pas utiliser aveuglément des éléments de HTML5 : il leur faut une indication de la part de la (ou du) webmestre pour savoir quel est le niveau de compatibilité HTML souhaité. Cela est possible depuis SPIP 3.0 par l'apparition d'une nouvelle option de configuration.

Configuration HTML5

Zone de configuration dans SPIP pour autoriser ou non l'utilisation de HTML5.

La balise #HTML5 permet de tenir compte de ce choix :

Si le HTML5 est autorisé, la balise renvoie un résultat non-vide (espace)
Si la configuration reste sur HTML4 (valeur par défaut), la balise renvoie un résultat vide. Sur les versions de SPIP inférieures à SPIP 3.0, la balise est inconnue, et renverra donc également un résultat vide. Il est donc possible de l'utiliser n'importe où, quelle que soit la version de SPIP visée : les sites sous SPIP avant 2.2 seront juste considérés comme étant en HTML4.
Exemples d'utilisation

Par exemple, un plugin ou un squelette qui génère une zone de recherche dans un formulaire pourra utiliser la balise de la manière suivante :

type="[(#HTML5|?{search,text})] ... />

Ce code génèrera, si le HTML5 est activé dans la configuration :

type="search" ... />

et dans le cas contraire :

type="text" ... />

Autre exemple : définition d'une zone de saisie de formulaire comme obligatoire :

type="text" [(#HTML5)required="required"] ... />

Le résultat sera donc l'un ou l'autre de ceux-ci suivant la configuration :

type="text" required="required" ... />

type="text" ... />

Support par les navigateurs

Bien sûr, comme toujours en développement web, n'oubliez pas de vérifier quel est le comportement des navigateurs qui ne connaissent pas les balises HTML et attributs que vous souhaitez utiliser.

Formulaires CVT en plusieurs pages

JLuc — 2012-05-19T09:31:09Z

Les formulaires multi-étapes (ou multi-pages) sont une variation des formulaires CVT qui permet d'enchainer plusieurs pages de saisies, avec une validation (vérification) intermédiaire de chacune de ces pages et un traitement final qui permet de prendre en compte toutes les valeurs saisies en une seule fois.

Il est nécessaire d'être déjà familier avec les formulaires CVT pour créer un formulaire CVT en plusieurs pages.

Nous allons voir comment construire facilement un formulaire d'inscription en 3 pages distinctes, SPIP prenant en charge la partie compliquée qui consiste à mémoriser les données déja saisies pour le traitement final, et à permettre la navigation entre les pages.

Les squelettes de chaque page

Chaque page du formulaire se présente comme un formulaire complet (avec un bouton de validation qui sert à passer à l'étape suivante).

Chacune des étape est numérotée, à partir de 1, et décrite par un fichier squelette indépendant qui implémente un formulaire autonome pour les saisies de cette page.

Pour l'étape 1, le squelette est formulaires/inscription.html.
Pour l'étape 2, le squelette est formulaires/inscription_2.html.
Pour l'étape 3, le squelette est formulaires/inscription_3.html.

Voici par exemple à quoi ressemble la première page de notre formulaire :

[
(#ENV*{message_ok})
]

[
(#ENV*{message_erreur})
]

[(#ENV{editable})

[(#REM) les hidden qui declencheront le service du formulaire parametre : url d'action ]

#ACTION_FORMULAIRE{#ENV{action},#FORM}

Votre email

<:pass_ok:>" />

]

Télécharger

À l'intérieur de chaque squelette, #ENV{_etape} renvoie le n° de l'étape, et #ENV{_etapes} renvoie le nombre total d'étapes de saisie. Cela permet par exemple d'afficher un état de l'avancement de la saisie par rapport au nombre total de pages de saisies :

#FORM formulaire_#FORM_#ENV{_etape}">

Inscription #ENV{_etape} / #ENV{_etapes} : indiquez votre email

...

Télécharger

A chaque page, #ENV contient toutes les valeurs déjà saisies lors des étapes précédentes. Ainsi, si vous voulez proposer une valeur par défaut qui dépend d'une saisie précédente, il suffit d'utiliser celle-ci pour pré-remplir votre saisie.

Sur chaque page, il est aussi possible de proposer un bouton qui renvoie vers une autre étape (par exemple pour faire un bouton de retour à l'étape précédente). Il suffit pour cela de donner au bouton l'attribut name avec la valeur _retour_etape_n, n désignant le numéro de l'étape visée :
<p class="boutons"> <input type="submit" class="submit" name="_retour_etape_2" value="<:retour:>" /> </p>
Il est possible que cette étape soit une étape en avant, mais attention : dans tous les cas l'utilisateur ne pourra passer à une étape n que si la saisie des étapes précédentes est correcte et sans erreur ! Dans le cas contraire, c'est la première page avec des erreurs qui lui sera présentée.

Charger et déclarer les étapes de saisie

La déclaration des étapes ou pages de saisies se fait dans la fonction charger() de votre formulaire CVT.

La fonction charger() est identique à celle d'un formulaire CVT conventionnel : elle doit retourner un tableau de tous les champs qui seront saisis dans l'ensemble du formulaire (donc toutes étapes confondues, comme si il n'y avait qu'une seule page de saisie).

Mais en plus, elle doit déclarer que le formulaire comporte plusieurs pages. Cela se fait en renvoyant en plus une valeur '_etapes' qui désigne le nombre d'étapes de saisies.

Dans notre exemple :

function formulaires_inscription_charger_dist() {
return array (
'email' => '', // etape 1
'nom' => '', // etape 2
'prenom' => '',
'semaine' => 0, // étape 3
'_etapes' => 3);
}
Télécharger

C'est cette valeur _etapes qui va déclencher la prise en charge par SPIP des différentes pages préparées ci-dessus.

Vérifier la saisie à chaque étape

La vérification de la saisie présente ici une particularité. Au lieu d'avoir une seule fonction verifier() comme dans un formulaire CVT conventionnel, il va falloir fournir ici une fonction verifier() par page de saisie. Celles-ci sont numérotées à partir de 1 comme pour les squelettes des différentes pages.

formulaires_inscription_verifier_1_dist vérifie les saisies de l'étape 1 uniquement.
formulaires_inscription_verifier_2_dist vérifie les saisies de l'étape 2.
formulaires_inscription_verifier_3_dist vérifie les saisies de l'étape 3.
etc.

A l'intérieur de ces fonctions, l'appel à _request permet d'accéder aux valeurs saisies depuis l'étape 1 jusqu'à l'étape courante.

Le numéro d'étape courante et le nombre totale d'étapes sont également accessible par request('_etape') et par request('_etapes'), si nécessaire, pour mutualiser du code par exemple.

Après chaque page n, SPIP appelle les fonctions de vérification des étapes 1 à n pour vérifier l'absence de régression dans la validation (qui pourrait être due à une erreur ou à une tentative de fraude par l'utilisateur). En cas d'erreur, l'utilisateur est automatiquement renvoyé sur la première page dont la saisie n'est pas correcte.

En cas de succès, SPIP passe à l'étape suivante, sauf si l'utilisateur est arrivé à la dernière page, auquel cas SPIP appelle la fonction traiter().

Traiter la saisie

La fonction de traitement des saisies du formulaire n'est appelée que lorsque toutes les pages ont été saisies sans erreur.

Elle peut accéder à l'ensemble des saisies avec la fonction _request comme si le formulaire avait été saisi en une seule fois.

La fonction de traitement est donc tout à fait identique à celle d'un formulaire en une page et se nomme classiquement (ici formulaires_inscription_traiter_dist()).

Sans oublier...

- Ce formulaire ainsi construit bénéficie de tous les avantages des formulaires CVT. Il suffit donc de l'encapsuler dans une
pour qu'il soit automatiqent pris en charge et permette la saisie multi-page en ajax.

- Il est possible d'appeler le formulaire en commençant directement à l'étape 5, par exemple. Pour cela, il suffit de passer le paramètre "_etape=5" dans l'environnement (dans l'url par exemple).
Dans ce cas, les vérifications des 4 pages précédentes sont effectuées et en cas de validation, l'étape 5 est affichée. Sinon c'est la première étape qui présente une erreur qui est affichée.

[1] Cette fonctionnalité est également accessible pour SPIP 2 mais nécessite l'activation du plugin cvt-multi-etapes

Formulaire CVT avec sauvegarde automatique

cerdic — 2012-05-19T09:31:05Z

Pour éviter que les utilisateurs ne perdent le bénéfice de leur saisie en cas de perte de connexion ou de fausse manipulation, il est possible d'activer une fonction de sauvegarde automatisée dans les formulaires CVT.

Activer la fonction

Pour activer la prise en charge, il suffit que la fonction charger() du formulaire renvoie un identifiant unique qui désigne le formulaire.

Il y aura une sauvegarde différente par identifiant unique (et par formulaire), celui-ci doit donc dépendre du contexte de la saisie. Par exemple sur un formulaire de forum en réponse à un article on choisira de passer comme identifiant l'id_article de l'article auquel on répond.

Cet identifiant peut être un entier, une chaine ou un tableau, et doit être envoyé dans le champ '_autosave_id' :

function formulaires_repondre_article_charger_dist($id_article){

...

return array(

...,

'_autosave_id' => $id_article

);

}

Télécharger
Ou sont sauvegardées les données ?

Lorsqu'on active cette fonction, le formulaire va envoyer à chaque modification de saisie une requête à SPIP avec la liste de tous les champs saisis. SPIP va alors stocker cette information dans la session de l'utilisateur, sur le serveur.

Lorsque la saisie est complète et que l'utilisateur valide le formulaire, SPIP va alors vider cette sauvegarde (lors du traitement du formulaire).

Mais si l'utilisateur rencontre une erreur ou un problème et oublie de valider le formulaire, la sauvegarde est conservée 72H. Si l'utilisateur revient sur le même formulaire, il va retrouver le formulaire pré-rempli avec toutes les informations qu'il avait saisi auparavant.

De la vie privée ...

Attention cependant à ne pas utiliser cette sauvegarde automatique dans un formulaire qui collecte des données personnelles dans une session anonyme.

Si l'utilisateur est sur un poste de consultation public et ne valide pas, ses données seront alors disponibles pour quiconque revient sur la même page avec son poste de consultation.

Par ailleurs, il est possible de personnaliser la durée de 72H de conservation des données saisies en précisant dans le fichier mes_options.php par exemple (pour une durée de 24h) :

define('_AUTOSAVE_GB_DELAY',24*3600)

{tri} et #TRI dans les boucles

cerdic — 2012-05-19T09:31:01Z

SPIP 3.0 introduit un critère et une balise qui permettent de faire facilement des listes triables.

Le critère {tri} simplifie la réalisation de listes triables de la même façon que le critère {pagination} simplifie la réalisation de listes paginées.

Dans une boucle simple, il permet de définir le critère de tri en lui indiquant en argument le champ à utiliser par défaut :

(ARTICLES){tri titre}>

Télécharger

Jusque là rien de nouveau par rapport au critère {par}. Mais {tri} peut être associé à la balise #TRI qui permet de générer un lien pour changer le critère de tri. La balise #TRI prend en premier argument le champ de tri, et en second argument le libellé du lien clicable pour utiliser ce champ pour le tri :

#TRI{titre,'Trier par titre'} | #TRI{date,'Trier par date'} |

#TRI{date_redac,'Trier par date de rédaction'}

(ARTICLES){tri titre}>

Télécharger

Ce faisant l'utilisateur se voit proposer un menu pour modifier le tri de la boucle. Le tri actuellement utilisé est exposé en gras et non clicable, et les tris non utilisés sont des liens clicables.

Si la boucle est dans une inclusion ajax, il suffit de renseigner la classe ajax en troisième argument de la balise #TRI pour que les liens se comportent avec un rechargement partiel de la page :

#TRI{titre,'Trier par titre',ajax} | #TRI{date,'Trier par date',ajax} |

#TRI{date_redac,'Trier par date de rédaction',ajax}

(ARTICLES){tri titre}>

Télécharger

Le critère {tri} permet également d'indiquer le sens du tri par défaut en second argument. Il faut indiquer la valeur direct ou 1 pour indiquer un tri croissant par défaut, et inverse ou -1 pour un tri décroissant par défaut :

#TRI{titre,'Trier par titre'} | #TRI{date,'Trier par date'} |

#TRI{date_redac,'Trier par date de rédaction'}

(ARTICLES){tri date,-1}>

Télécharger

Par ailleurs il est aussi possible de proposer le choix du sens de tri. Cela se fait en passant > pour un tri croissant et < pour un tri décroissant en premier argument de la balise #TRI :

#TRI{>,'Tri croissant',ajax} | #TRI{>,'Tri décroissant',ajax} | #TRI{titre,'Trier par titre',ajax} | #TRI{date,'Trier par date',ajax} |

#TRI{date_redac,'Trier par date de rédaction',ajax}

(ARTICLES){tri titre}>

Télécharger

Cela dit, plutôt que de proposer des boutons de tri systématique, une alternative est possible : adapter automatiquement le sens du tri à la colonne utilisée pour le tri. Cela se fait en passant en second argument de la balise tri un tableau avec le sens par défaut pour chaque colonne :

#SET{defaut_tri,#ARRAY{

tri,1,

date,-1,

date_redac,-1

}}

#TRI{titre,'Trier par titre',ajax} | #TRI{date,'Trier par date',ajax} |

#TRI{date_redac,'Trier par date de rédaction',ajax}

(ARTICLES){tri titre,#GET{defaut_tri}}>

Télécharger

Ainsi quand l'utilisateur choisira le tri par titre, celui-ci sera dans un ordre croissant. Mais quand il choisira la date ou la date de rédaction, le tri se fera dans un ordre décroissant.

Les itérateurs de SPIP

Fil, Matthieu Marcillaud — 2012-05-19T09:30:50Z

Nous sommes en train de développer dans SPIP une notion générale de boucle, basée sur les itérateurs de PHP.

Ces boucles ne portent plus exclusivement sur des requêtes SQL, mais peuvent tourner sur toutes sortes de listes de données. Par exemple :
— un tableau de données produit par une fonction quelconque
— le contenu d'un fichier local au format XML, CSV, JSON, YAML, etc.
— une liste de fichiers dans un répertoire du serveur
— une requête sur un webservice
— etc (LDAP...).

Les boucles SQL

Sans surprise, l'itérateur classique de SPIP s'appelle SQL. Il exécute la requête telle que SPIP l'a calculée, et sait parcourir la liste de résultats pour les envoyer à la boucle.

La boucle (DATA)

C'est une boucle capable d'itérer n'importe quel tableau de données. Sa syntaxe de base est la suivante :

#BALISES

Le critère {source format, données} définit les données sur lesquelles la boucle va itérer.

La définition d'une source de données nécessite deux éléments :

— La partie données : cet élément peut être de plusieurs natures :
- un tableau de données, par exemple #ENV*
- le chemin d'un fichier sur le disque dur, ex : sources/definitions.csv
- l'URL d'un fichier ou d'un webservice, ex : http://per.sonn.es/bases/phobia.fr.yaml
- ou encore, une chaîne quelconque que le format saura transformer en tableau de données, ex : "select * from flickr.photos.search where text='spip'"

— La partie format est à prendre dans la liste ci-dessous :
- table (alias array ou tableau), pour un tableau déjà créé
- csv, json, yaml pour un fichier composé dans l'un de ces formats
- file pour boucler sur les lignes d'un fichier
- glob ou pregfiles pour boucler sur les fichiers d'un répertoire (et plus...)
- rss (alias atom) pour lire un flux de nouvelles
- plugins pour lister les plugins actifs sur le site
- yql pour envoyer une requête sur le webservice de Yahoo Query Language
- sql pour envoyer une requête brute au serveur SQL (utiliser {source sql, connecteur:requete} pour envoyer la requête sur une base externe)
- ics pour boucler sur des calendriers (nécessite le plugin icalendar : lire La boucle iCalendar)
- etc.

Tous ces formats sont déjà disponibles, et il est très aisé d'en ajouter un nouveau, en créant une simple fonction inc_FORMAT_to_array($u). A titre d'exemple voici la fonction qui transforme un fichier JSON en tableau de données :

function inc_json_to_array_dist($u) { if (is_array($json = json_decode($u)) OR is_object($json)) return (array) $json; }

A lire : Exemples de BOUCLE(DATA) .

YQL — Yahoo Query Language

YQL est un webservice permettant d'interroger de façon simple de nombreux sites comme google, twitter, flickr, etc. Avec la boucle (DATA), SPIP facilite grandement son intégration sous forme de boucles : Cf. http://zzz.rezo.net/Exemples-de-bou....

Itérateurs PHP

SPIP est capable d'utiliser les itérateurs PHP standards. Il convient de se reporter à leur documentation, qui est souvent très succincte, et de vérifier que les itérateurs en questions sont disponibles sur votre système.

Notons, par exemple, DirectoryIterator, qui permet de lister les fichiers d'un répertoire :

Boucle :

{pagination 10} {valeur!==^\.}{valeur==\.jpg$} >[(#VAL{Y-m-d H:i:s}|date{#GETMTIME})] / #VALEUR #PAGINATION

Résultat :

2008-02-01 23:27:23 / arton2135.jpg 2008-08-21 11:12:58 / DSC03420.jpg 2008-08-21 11:13:11 / DSC03421.jpg 2009-08-27 11:20:11 / hash-1.jpg 2009-08-27 11:20:04 / hash.jpg

Il convient d'indiquer à SPIP qu'il s'agit d'un itérateur PHP, en indiquant (php:...) avant le nom de l'itérateur.

Le critère {args xx,yy} définit les arguments que l'on va passer à l'itérateur lors de son initialisation. Pour DirectoryIterator, il s'agit du chemin du répertoire à lister.

Les méthodes de cet itérateur (cf. http://php.net/manual/fr/class.directoryiterator.php) sont disponibles sous forme de balises (ici, #GETMTIME).

Remarque : pour lister le contenu d'un répertoire, le format glob de la boucle (DATA) est sans doute plus facile à utiliser que cet itérateur PHP.

{!par mtime}> ...
Filtrage, tri, pagination, fusion

Filtres. Comme les boucles SQL, les boucles (DATA) peuvent être filtrées par des critères du type {valeur=x} ; les opérateurs disponibles sont =, >, <, >=, <=, == (expression rationnelle) et LIKE.

Cependant ce filtrage s'effectue non pas en amont lors de la requête, comme en SQL, mais en aval, sur le tableau de données initialement récupéré.

Tris. Les tris {par xx} sont également possibles, avec leur variante {!par xx} pour trier en ordre inverse.

Pagination. La pagination fonctionne normalement, ainsi que le critère offset/limit {a,b}.

Fusion. Le critère {fusion /x/y} fonctionne aussi. Par exemple, pour un fichier d'adresses au format CSV, si l'email est le champ n° 3, on pourra ne retenir qu'un seul enregistrement par email avec la boucle suivante :

{fusion /3} {par /0}{' '}> #VALEUR{0} : #VALEUR{3}

La fusion se fait après le tri, et retient le premier élément
rencontré. De cette manière, si un tableau est trie {!par date} puis fusionné sur l'email, l'enregistrement retenu pour chaque email sera le plus récent.

Dans le prochain article, nous verrons des exemples de boucles (DATA).

SPIP

SPIP 3.0

A new private area [2]

Modularity with plugins

A new set of default templates

New features

Shortcuts

Loops

Criteria

Tags

Filters

(#TITLE)

JavaScript

API

SPIP 3.0

Un nouvel espace privé [2]

Modularisation en plugins

Un nouveau jeu de squelettes par défaut

De nouvelles fonctionnalités

Raccourcis

Boucles

Critères

Balises

Filtres

(#TITRE)

JavaScript

API

API de gestion de la file des travaux

Ajouter un travail dans la file

Supprimer un travail de la file

Associer un travail à un objet éditorial

API « editer_objet »

Insérer

Modifier

Publier

API « autoriser »

Vérifier une autorisation

Donner une autorisation exceptionnelle

Déclarer une nouvelle autorisation

Aide au développement

#HTML5

Exemples d'utilisation

Support par les navigateurs

Formulaires CVT en plusieurs pages

Les squelettes de chaque page

Inscription #ENV{_etape} / #ENV{_etapes} : indiquez votre email

Charger et déclarer les étapes de saisie

Vérifier la saisie à chaque étape

Traiter la saisie

Sans oublier...

Formulaire CVT avec sauvegarde automatique

Activer la fonction

Ou sont sauvegardées les données ?

De la vie privée ...

{tri} et #TRI dans les boucles

Les itérateurs de SPIP

Les boucles SQL

La boucle (DATA)

YQL — Yahoo Query Language

Itérateurs PHP

Filtrage, tri, pagination, fusion

La boucle `(DATA)`