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.

Utilisation

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.

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.

Les modèles

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.

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 :

Albums page

Albumothèque

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.

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.