Albums 3

Avant d’effectuer une mise à jour depuis la version 1 ou 2, consultez les notes sur la rétro-compatibilité. Les modèles, notamment, on reçut quelques changements pour la bonne cause.

En préambule, une courte vidéo de présentation.
Si vous rencontrez des difficultés pour la lecture, rendez vous sur medias.spip.net où le fichier source est téléchargeable.

Évolutions

• v3.6.0 : permet de réordonner les documents des albums par glisser-déposer

Des albums, pour quoi faire ?

Dans sa première version, le plugin permettait d’insérer des galeries d’images au fil du texte, dans les articles.

Depuis la version 2, les albums sont des objets éditoriaux à part entière, aussi la portée du plugin est plus générale : il sert à la gestion de groupes de documents.

⇒ Des groupes de documents

Un album, c’est donc un conteneur pour une série de documents.
Précisons le bien, si le terme «album» évoque des albums d’images, il peut contenir tout type de document : images, bandes-son, vidéos et autres.
Un même document peut appartenir à plusieurs albums : toutes sortes de combinaisons sont envisageables.

⇒ Albums et documents liés à un objet

En SPIP 3, les documents liés à un objet sont présentés sous forme de 3 groupes : «illustrations», «portfolio» et «documents». Leur finalité est expliquée dans cet article, mais retenons qu’il s’agit d’une séparation arbitraire pensée pour les articles.
Dans cette documentation, on va se référer à ces documents comme des documents «individuels», par opposition au documents regroupés au sein d’albums.

Les documents individuels et les albums sont indépendants et n’ont pas d’incidence l’un sur l’autre : on peut continuer à gérer les documents individuels comme avant.
En pratique, vous avez le choix au moment d’ajouter des documents à un objet : ils peuvent être ajoutés individuellement, ou regroupés au sein d’albums.

Installation & configuration

L’installation se fait comme n’importe que plugin.
2 tables vont être ajoutées : spip_albums et spip_albums_liens.

Des plugins supplémentaires doivent être installés si vous souhaitez bénéficier du formulaire qui permet de personnaliser les balises <album> à insérer dans le texte. Il s’agit de dépendances optionnelles.

• YAML : télécharger
• Saisies : télécharger
• Vérifier : télécharger

Une fois l’installation effectuée, un passage sur la page de configuration est ensuite nécessaire. Elle est constituée de 2 onglets.

⇒ Onglet «options»
L’option principale permet de définir sur quels objets les albums pourront être ajoutés.
2 autres options permettent de proposer un titre par défaut lorsqu’on ajoute un nouvel album à un objet, et d’activer le déplacement de documents par cliquer-glisser.

⇒ Onglet «outils»
Un formulaire permet de migrer des articles en albums.
Il est prévu dans le cas où l’on se servait d’articles comme de pseudo albums, et se charge de créer des vrais albums à l’identique à partir de ceux-ci.

Utilisation

Les albums peuvent être autonomes ou liés à d’autres objets éditoriaux.

⇒ Dans le cas d’albums autonomes, on les créera depuis la barre d’outil rapide ou depuis la page des albums, comme n’importe quel objet éditorial.

⇒ Dans le cas d’albums liés à des objet éditoriaux, leur gestion est assez similaire à celle des documents : on peut gérer les albums depuis la fiche d’un objet ou lorsque celui-ci est en cours d’édition.

Gestion des albums sur la fiche d’un objet

Sur la fiche d’un objet éditorial, les albums font suite aux documents. L’interface permet d’ajouter de nouveaux albums ou des albums existants, d’éditer leur texte et de manipuler leurs documents.

⇒ Ajouter des albums

Le bouton «Ajouter un album» fait apparaître un formulaire proposant deux méthodes [1] :

Créer et remplir un nouvel album. Titre et descriptif sont optionnels : laissé vide, le titre sera rempli à posteriori avec «Nouvel album N° X».

Choisir un ou plusieurs albums existants : on peut parcourir la liste, ou rentrer directement les numéros des albums.

⇒ Editer un album sur place

Les albums peuvent être édités sur place. Pour l’édition complète (gestion des auteurs, des mots-clés etc.), on se rendra sur leur fiche.

Editer le texte : une icône apparaît au survol du header, elle permet d’afficher le formulaire d’édition du titre et du descriptif.

Ajouter des documents : un lien situé en bas fait apparaître le formulaire d’ajout de documents.

Manipuler les documents : les boutons d’édition apparaissent au survol de chaque document.

Il est également possible, sous certaines conditions, de déplacer des documents entre albums par cliquer-glisser.

⇒ Retirer des albums

Pour retirer un album, cliquer sur le bouton qui apparaît au survol, en bas de chaque album.
Lorsqu’il y a plusieurs albums, un bouton présent à la fin de la liste permet de tous les retirer d’un coup.

Gestion des albums lors de l’édition d’un objet

Pendant l’édition d’un objet, la gestion des albums s’opère au même endroit que celle des documents, dans la colonne de gauche.
Quand l’objet peut recevoir à la fois des documents et des albums, un menu permet de basculer entre les deux.

⇒ Ajouter, éditer et retirer les albums

On gère les albums de la même façon que lorsqu’on se trouve sur la fiche de l’objet : même formulaire pour ajouter des documents, mêmes possibilités pour éditer les albums et manipuler leur documents.

⇒ Insertion des balises <album> dans le texte

Les albums insérés dans le texte au moyen de la balise <albumX> seront automatiquement associés à l’objet : ce comportement est similaire à celui des balises <doc>, <img> et <emb> des documents.

Un formulaire permet de personnaliser les balises de chaque album : choix de la variante, alignement, paramètres des modèles, etc.

Important : pour bénéficier de cette fonctionnalité, des plugins supplémentaires doivent être installés. Consultez la section sur l’installation.

Les modèles

L’apparence, la structure et certains paramètres évoluent par rapport aux versions 1 et 2. Consultez les notes sur la rétro-compatibilité.

2 modèles «album» sont proposés : le modèle de base est une vue en vignettes, complété d’une variante avec une vue en liste.
Par défaut, ces 2 modèles produisent un affichage minimaliste : titre, descriptif, et autres éléments “superflus” ne sont pas affichés à moins d’utiliser les paramètres adéquats (détaillés plus bas).
De même, la feuille de style chargée sur le site public ne contient que le strict minimum.

Ces 2 modèles ne prétendent pas répondre à tous les cas de figure. Les usages possibles sont trop vastes pour être tous pris en compte par un modèle générique : listes de lecture audio ou vidéo, diaporamas, etc.
Pour vos besoins spécifiques, ajoutez des variantes du modèle.

⇒ Modèle <album> : vue en vignettes

Ce modèle est prévu pour afficher des séries d’images : les documents sont affichés sous forme de vignettes cliquables.
Il est basé sur Tiny Typo, la base CSS de Romy Têtue.
Les images peuvent être retaillées et recadrées pour obtenir un affichage uniforme, par défaut elles sont retaillées selon une hauteur de 100 pixels.

La structure HTML de base est la suivante (avec #HTML5 activé) :

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

⇒ Modèle <album|liste> : vue en liste

Cette variante affiche les documents sous forme d’une simple liste. Elle est donc adaptée à tout type de documents.

La structure HTML de base est la suivante :

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

⇒ Paramètres des modèles

⇒ Ajouter des modèles

Pour que vos propres variantes du modèle soient prises en compte par le formulaire de personnalisation des balises, il faut créer un fichier YAML en plus du squelette HTML.

Ce fonctionnement est inspiré par celui du plugin Insérer Modèles : chaque fichier YAML décrit le modèle et ses paramètres, sous forme de saisies. La syntaxe est identique, avec toutefois 2 éléments supplémentaires :

• alias : nom de la variante
• description : description de la variante (optionnelle)

Pour assurer la compatibilité avec le plugin cité plus haut, 4 paramètres sont obligatoires : modele, id_modele, id_album et variante.
Les 3 premiers étant identiques pour toutes les variantes, ils sont regroupés dans un fichier inc-yaml/album-compat.yaml qu’il suffit d’inclure.

Pour les saisies, une option supplémentaire config permet d’avoir comme valeur par défaut un réglage stocké dans la table spip_meta.
Dans l’idée, config:'truc' revient à faire 'defaut'=>lire_config('truc') en php.

Exemple : Imaginons un plugin fournissant une variante «diaporama».
Ce modèle accepterait entre autre un paramètre vitesse dont la valeur par défaut serait enregistrée dans une méta du plugin. Le squelette HTML serait nommé album_diaporama.html et le fichier YAML album_diaporama.yaml.
Ce dernier ressemblerait à ça :

nom: 'un 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: 'input'
    options:
      nom: 'vitesse'
      config: 'plugin/vitesse'
  - le reste des saisies...

En cas de doute, vous pouvez prendre la variante «liste» comme référence.

Albumothèque

L’albumothèque est l’équivalent de la médiathèque, pour les albums.

Les filtres situés dans la colonne de gauche sont prévus pour sélectionner les albums en fonction de leurs documents et de leurs liaisons avec les objets : articles, auteurs, mots-clés etc. Attention, il ne s’agit pas de menus, mais bien de filtres : un clic pour activer, un autre pour désactiver.

Des champs avec autocomplétion permettent de trouver un objet précis.
Par exemple, pour afficher les albums liés à un article en particulier, il faut cliquer sur l’icône à droite du filtre «articles», puis rentrer les premières lettres du titre ou son numéro : les articles correspondants vont apparaître dans une liste déroulante, cliquer sur un résultat va mettre à jour la liste des albums.
La fontion d’autocomplétion ne va chercher que les objets ayant un lien avec les albums.

Déplacer des documents entre albums par cliquer-glisser

Il est possible de déplacer les documents entre albums par cliquer-glisser. L’option doit être activée dans la page de configuration, et vous devez y avoir l’autorisation.

Gardez en tête qu’il s’agit d’une fonctionnalité un peu expérimentale !

Lorsqu’on entame le déplacement d’un document, les albums pouvant recevoir celui-ci sont surlignés d’une bordure verte, il suffit d’y relacher le document. Dès qu’un document à été déplacé, un formulaire apparaît en bas de la liste pour enregistrer les modifications. On peut cependant effectuer plusieurs déplacement d’affilée avant de les enregistrer.

Notez qu’il est possible de manipuler également les documents «individuels» liés aux objets.

Boucles & critères

⇒ Critère {orphelins}

Le critère {orphelins} permet de sélectionner les albums sans lien avec un objet éditorial (on qualifiait ces albums «d’autonomes» plus haut).

⇒ Jointures

Les albums ont une jointure automatique pour tous les objets (cf. déclaration de la base).

Dès qu’un qu’un id_xxx est présent dans l’environnement, on peut donc sélectionner les albums liés à l’objet sans avoir à faire de jointure explicite avec la table de liens :
<BOUCLE_albums(ALBUMS){id_xxx}>

Attention, pour {id_auteur}, le comportement est différent :

• <BOUCLE_albums(ALBUMS){id_auteur}> sélectionne les albums de l’auteur (d’après la table spip_auteurs_liens).
• <BOUCLE_albums(ALBUMS){objet=auteur}{id_objet=#ID_AUTEUR}> sélectionne les albums liés à l’auteur (d’après la table spip_albums_liens).

⇒ Sélectionner les albums en fonction de leurs documents

En faisant une jointure avec la table spip_documents, on peut utiliser certains critères des documents :
<BOUCLE_albums(ALBUMS documents){documents.critere=xxx}>
Quelques exemples avec les critères les plus utiles :

• {documents.media IN image,audio} : albums contenant des images ou des bandes-sons.
• {documents.id_document=x} : albums contenant le document n°x.
• {documents.titre LIKE %truc%} : albums contenant des documents dont le titre ou le nom de fichier comprend le terme «truc».
• {documents.extension == mp3|ogg|oga} : albums contenant des fichiers mp3 ou ogg audio.
• {documents.taille > 1000000} : albums contenant des documents d’une taille supérieure à 1Mo [2].

Autorisations

Voici comment sont définies certaines autorisations particulières (les administrateurs complets peuvent tout faire).

• Modifier un album : il faut être auteur de l’album et avoir le droit de modifier tous les objets auquel l’album est lié.
• Ajouter un album à un objet : il faut que l’objet soit activé dans les options, et avoir le droit de le modifier.
• Déplacer des documents entre albums : il faut que l’option soit activée, et dans le contexte d’un objet, avoir le droit de modifier tous les albums liés.
• Supprimer un album : il faut qu’il soit vide, inutilisé et non publié.

Rétro-compatibilité

Modèles

La syntaxe de la version 1, qui avait disparu de la version 2, est à nouveau supportée dans cette version : <album|id_article=x> et <album|id=x,y,z>

La structure du modèle de base a changé, afin notamment de respecter l’usage des balises <figure> et <figcaption> en HTML5.

Visuellement, quelques altérations ont eu lieu :
-  par défaut, les titres sont cachés.
-  le titre et le descriptif du modèle de base passent en bas.

Changement de quelques paramètres :
-  vignettes & liste : titraille est supprimé
-  vignettes & liste : balise_titraille est déprécié au profit de balise_titre
-  liste : infos est déprécié au profit de metas

Divers

-  Le critère {contenu} apparu dans la version 2 est supprimé : on peut utiliser à la place le critère {documents.media == x} avec une jointure (ALBUMS documents) pour un résultat similaire.
Voir la section sur les jointures.

Paramétrage fin par les constantes

-  Constante _ALBUMS_TITRE_COURT : si vous insérez define('_ALBUMS_TITRE_COURT','oui'); dans votre mes_options.php, le titre des images sous les images sera réduit à leur titre et n’incluera pas les indications techniques.