Albums 3 (en)

The plugin «Albums» evolves with a version 3 made for SPIP 3.

Before upgrading from previous versions, read the notes regarding the retro-compatibility.

This quick presentation video is in french, but it might be helpfull nonetheless.

Albums purpose

In the first version, the plugin’s purpose was to insert galleries of images inside the text of articles.

Since the version 2, albums are editorial objects, and so the plugin’s scope is broader : its purpose is now to manage groups of documents.

Groups of documents

An album is a container for a serie of documents.
Despite its name, it may contain any types of documents, not just images.
One document may belong to several different albums : all kind of combinations are possible.

Albums are groups of documents

Albums, documents and objects

In SPIP 3, documents associated with an object are dispatched into 3 sections : «illustrations», «portfolio» and «documents».
In this documentation, we will refer to these documents as «individual» documents, as opposed to documents grouped into albums.

Individual documents and albums are independents and do not interfere with each other : you can continue to manage individual documents the same way as before.
Except now, you have the choice when adding documents to an object : they can be added individually, or grouped into albums.

Albums et documents liés
Documents individuels et regroupés aux seins d’albums

Installation & configuration

You can install the plugin the standard way.
2 tables will be added : spip_albums and spip_albums_liens.

Additional plugins are neccesary in order to enable the customization of <album> tags. These are optional dependencies, install them if you whish to benefit from this functionnality.

Once the installation is done, visit the plugin’s configuration page. It is divided in 2 tabs.

«options» tab
First, choose which objects may receive albums.
There are 2 more options : you can enable the suggestion of a default title when adding an album to an object, and enable moving documents between album with drag and drop.

«tools» tab
A form will convert articles into albums.
Use it in case you were using articles as pseudo-albums : real ones will be created identically.


Albums may be independents or associated with editorial objects.

⇒ Independent albums can be created from the toolbar or from the «Albums» page.

⇒ The management of albums associated with objects is quite similar to that of individual documents : albums can be managed from the object’s page or when the object is being edited.

Managing albums from an object’s page

On the page of an object, albums are located after the documents. You can add new albums or existing ones, edit their text and manage their documents.

Albums et documents liés
1) documents «individuels» 2) documents regroupés au sein d’albums

Adding albums

The «Add an album» button displays a form which has two methods :

Create and «fill» a new album. The title and the description are both optionals : if the title is leaved empty, it will be populated afterward with «New album No X».

Choose existing albums : you can browse a list, or enter directly the album’s numbers.

Ajouter un album à un objet éditorial
1) Créer et remplir un nouvel album 2) Choisir un ou plusieurs albums existants

Editing an album

Albums can be quickly edited «on site». For the full-blown edition (managing authors, keywords...), go to the album’s page.

Editing text : an icon will appear when hovering the header, clicking it will display the form to edit the text and the description.

Adding documents : a link located in the footer will display the form to add documents.

Managing documents : the buttons will appear when hovering each document.

It is also possible, under some conditions, to move documents between albums with drag and drop.

Édition rapide d’un album
1) Editer titre et descriptif 2) Ajouter des documents 3) Modifier les documents

Removing albums

To remove an album, hover the footer to reveal the corresponding button.
When there are several albums, a button located at the end of the list can remove all of them at once.

Managing albums when editing an object

When editing an object, the albums can be managed in the same place as documents, in the left column.
When the object can receive both individual documents and albums, a menu allows you to switch between them.

Albums et documents lors de l’édition d’un objet
1) Gestion des documents 2) Gestion des albums

Adding, removing and editing albums

The management is the same as when you’re on the object’s page : same form to add albums, same way to edit them and manage their documents.

Inserting <album> inside texts

Albums inserted inside texts with the tag <albumX> will be automatically associated with the object.

A form will help you to customize the tag of each album, providing both YAML and Saisies plugins are installed.
Important : for this functionality to be available, additional plugins must be installed. Consult the section regarding dependencies.

Personnaliser la balise d’un album
En mode édition, un formulaire permet de personnaliser la balise de chaque album en vue de l’insérer dans le texte.

Les modèles

Models have slightly changed since versions 1 et 2. Read the notes about retro-compatibility.

2 models are available : the basic one is a thumbnail view, and there is a variation as a list view.
By default, both of them are minimalist : the title and description are not displayed unless you use the proper parameters.

The stylesheet loaded on the public site is also reduced to a minimum.

These models will not fulfill all the use-cases, as the albums may contain all kind of documents and thus may be used for all kind of purposes : audio and video playlists, diaporamas...
Do not hesitate to create your own variations of the model.

Model «thumbnails»

Modèle album par défaut : vue en vignettes

This model is intended for series of images. It is based on Tiny Typo.
Images may be resized and cropped in order to obtain an even display, by default they are resized with a 100px height.

The basic HTML structure is as follow (with #HTML5 activated) :

<figure class="album vignettes figure">
            <a href="#"><img src="..."></a>

Model «list»

Modèle album, variante sous forme de liste

This variation displays documents as a simple list.

The basic HTML structure is as follow :

<div class="album liste">
    <ul class="spip">
            <a href="#">...</a>

Models parameters

Common parameters
Parameter Description
titre «oui» to display the title
Any string in order to use it as a custom title
balise_titre In order to wrap the title in a tag.
→ strong, h4, etc.
descriptif «oui» in order to display the description
par Documents ordering, default : «titre»
→ date, titre, media, fichier, extension, taille
media In order to restrain documents to one type
→ image, file, audio, video
«thumbnails» specific parameters
Parameter Description
largeur Max width
hauteur Max height, default: 100 (pixels)
recadrer «oui» in order to crop images
label «oui» in order to display each document’s title
«list» specific parameters
Parameter Description
metas «oui» in order to display additional information, or a list of elements comma-separated :
→ extension, taille, dimensions

Adding models

When you create a new HTML template as a variation of the model, a YAML file must be created as well, in order for the model to be detected by the form.

This method is inspired by the plugin Insérer Modèles : each YAML file describes the model and its parameters.
The syntax remains the same, though there are 2 more elements :

  • alias : name of the variation
  • description : description of the variation

4 parameters are mandatory : modele, id_modele, id_album et variante.
As the first 3 are identical for all variations, they are found in the file inc-yaml/album-compat.yaml which you can include.

An additional config option allows you to use a default value stored in the table spip_meta.
In a way, config:'truc' is the equivalent of 'defaut'=>lire_config('truc') with php.

Confusing? Take a look at the example.

Example : let’s imagine a plugin with a «diaporama» model. It would have, among others, a speed parameter whose default value would be stored in the plugin’s meta. The HTML template would be named album_diaporama.html and the YAML file would be named album_diaporama.yaml.
The later would be like that :

nom: 'an album (diaporama)'
logo: 'prive/themes/spip/images/album-24.png'
icone_barre: 'album-diaporama.png'
alias: 'Diaporama'
 - 'inclure:inc-yaml/album-compat.yaml'
    saisie: 'hidden'
      nom: 'variante'
      defaut: 'diaporama'
    saisie: 'selection_album'
      nom: speed'
      config: 'plugin/speed'
    the remaining inputs...

Use the «list» variation as a reference.

Albums page


The filters located in the side column allow you to select albums according to their documents or their associations with objects : articles, authors, keywords...

Some inputs with an autocomplete function will help you find specific objects.
For instance, in order to display the albums associated with a given article, click on the icon on the right side, then enter the first letters of the article’s title or its number : the corresponding articles will appear, and clicking on one entry will update the albums list.
The autocomplete function only retrieves objects associated with albums.

Albumothèque : filtres
Des champs avec autocomplétion permettent de trouver les objets liés aux albums.

Moving documents between albums with drag and drop

If the option is activated, and provided you are authorized, it is possible to move documents between albums with drag and drop.
Be aware that this is experimental-ish !

When you start draging a document, the albums which may receive it are highlighted with a dotted border. Once a document has been released in a different album, a form will appear at the bottom of the list in order to save the modifications. You may however proceed with more modifications before saving them.

Note that it is possible to include individual documents in the manipulations.

Déplacer des documents entre albums par cliquer-glisser
1) Effectuer un ou plusieurs déplacements 2) Valider avec le formulaire qui apparaît en bas

Boucles & critères

Critère {orphelins}

The criteria {orphelins} will select albums not associated with any other object.


Albums have automatic joins with all objects.

Provided that id_xxx is present in the environnement, you may select albums associated with the object without using an explicit join :

Beware though, {id_auteur} behaves differently :

  • <BOUCLE_albums(ALBUMS){id_auteur}> select the author’s albums (on spip_auteurs_liens).
  • <BOUCLE_albums(ALBUMS){objet=auteur}{id_objet=#ID_AUTEUR}> selects albums associated with the author (on spip_albums_liens).

Select albums according to their documents

When using a join with the table spip_documents, it is use some criterias of documents :
<BOUCLE_albums(ALBUMS documents){documents.criteria=xxx}>
For instance :

  • { IN image,audio} : albums containing images or audio files.
  • {documents.id_document=x} : albums containing the document no x.
  • {documents.titre LIKE %something%} : albums containing documents whose title or filename corresponds to the term «something».
  • {documents.extension == mp3|ogg|oga} : albums containing mp3 or ogg audio files.
  • {documents.taille > 1000000} : albums containing documents whose weight exceeds 1Mo [1].


Here are how some particular authorizations are defined (administrators can do everything).

  • Modify an album : one must be the album’s auhtor and be authorized to modify all the objects associated with the album.
  • Add an album to an object : the object must be activated in the options, and one must be authorized to modify the object.
  • Move documents between albums : the option must be activated, and in the context of an object, one must be authorized to modify all the associated albums.
  • Delete an album : the album must be empty, not used, and not published.



The version 1 syntax, disabled in version 2, is supported anew : <album|id_article=x> and <album|id=x,y,z>

The structure of the basic model has changed, in order to respect the standards for the tags <figure> and <figcaption>.

Visually, a few changes occured :
-  titles are hidden by default.
-  the title and the description of the basic model are now located on the bottom.

Parameters :
-  thumbnails & list : titraille has been remove
-  thumbnails & list : balise_titraille is deprecated in favor of balise_titre
-  liste : infos is deprecated in favor of metas


The {contenu} criteria of the version 2 has been removed.
See the section about joins.


[11000000 octets = 975ko, but let’s not chipote

The version 2 of the plugin has served as a transition, so to speak, between the version 1 and this version, which is the «correct» version for SPIP 3.
It will only receive bug corrections.


One discussion

  • Sébastien

    Malgré le fait que je trouve le plugin excellent, je ne trouve pas comment modifier une couleur.
    Quand le clique sur une image de l’album, l’image s’affiche en grand, avec un fond coloré (très sombre, voire noir, j’ai une vue un peu déformée).
    Est-il possible de modifier cette couleur ?
    Je suppose que oui (car spip et très fort. Mais comment ?

    Reply to this message

Add a comment

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite / PostgreSQL
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparait.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Who are you?
[Log in]

To show your avatar with your message, register it first on (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom