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, 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.
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.
⇒ 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.

⇒ 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.

⇒ 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.
⇒ 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
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»
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">
<ul>
<li>
<a href="#"><img src="..."></a>
</li>
</ul>
</figure>
⇒ Model «list»
This variation displays documents as a simple list.
The basic HTML structure is as follow :
<div class="album liste">
<ul class="spip">
<li>
<a href="#">...</a>
</li>
</ul>
</div>
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 |
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 |
Parameter | Description |
---|---|
metas |
«oui» in order to display additional information, or a list of elements comma-separated : → extension, taille, dimensions |
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'
parametres:
- 'inclure:inc-yaml/album-compat.yaml'
-
saisie: 'hidden'
options:
nom: 'variante'
defaut: 'diaporama'
-
saisie: 'selection_album'
options:
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.
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.
Boucles & critères
⇒ Critère {orphelins}
The criteria {orphelins}
will select albums not associated with any other object.
⇒ Joins
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 :
<BOUCLE_albums(ALBUMS){id_xxx}>
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 :
-
{documents.media 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].
Autorisations
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.
Retro-compatibility
Models
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
Divers
The {contenu}
criteria of the version 2 has been removed.
See the section about joins.
Discussions by date of activity
One discussion
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 :
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.
Follow the comments:
|
