Archivage de Contenus, fonctionnement avancé

Le mécanisme d’archivage

Le mécanisme d’archivage est basé sur deux assertions:

• par défaut, les objets archivés sont exclus des boucles (sauf condition particulière) ;
• l’archivage d’un objet conteneur est propagé automatiquement à ses objets enfants.

Le pipeline post_boucle

Le principe du plugin est, par défaut, d’exclure des boucles les objets archivés. Ce mécanisme est orchestré par le pipeline post_boucle qui est appelé systématiquement à la fin de la compilation d’une boucle SPIP. Si aucune condition impliquant le débrayage du mécanisme est identifiée, la boucle SPIP est mise à jour avec la condition supplémentaire, est_archive=0.

Les conditions qui débrayent le mécanisme d’exclusion automatique sont les suivantes :

• La table n’est pas autorisée à l’archivage ;
• La requête concerne le calcul de la hiérarchie ;
• Le critère {ignorer_archivage} est présent ;
• Un critère sur le champ est_archive est utilisé ;
• Le critère {archive} ou {!archive} est utilisé ;
• Un critère d’égalité ou d’appartenance à une liste sur l’id de la table est présent.

En outre, si le critère conditionnel {est_archive ?} est utilisé dans une boucle sans que le contexte ne fournisse la valeur, la condition obtenue est est_archive=0, c’est-à-dire que les objets archivés restent toujours exclus.

La propagation des actions

Toute action à l’exception de l’explication (modification du motif) est propagée sur les enfants si l’objet concernée est un conteneur et que sa configuration identifie bien les informations nécessaires sur ces enfants. Les enfants ne sont modifiables que s’ils respectent des conditions d’archivage liées à l’action déclenchée:

• demande d’archivage : on propage à tous les objets enfants non archivés, y compris ceux pouvant être repérés comme désarchivés;
• demande de désarchivage ou d’effacement:
  1. si l’objet propageant le désarchivage est la racine d’un archivage, on propage aux descendants de cet objet ;
  2. si l’objet propageant le désarchivage est déjà un descendant d’une autre racine d’archivage R, on propage aux descendants de cet objet ayant pour consignation de racine, la racine R.
     Les traitements du désarchivage et de l’effacement diffèrent par le fait que le premier s’applique aux enfants archivés alors que le deuxième s’applique aux enfants non archivés.

Si le motif est utilisé et que l’action n’est pas un effacement, les enfants se voient attribués un motif standard qui rappelle la propagation par l’objet racine à l’initiative de l’action.

Le pipeline post_archivage_objet

Le pipeline post_archivage_objet est appelé à la suite du traitement complet d’une action sur un objet autorisé à l’archivage. Dans le cas où l’objet est un conteneur, la propagation sur les enfants est effectuée avant l’appel du pipeline qui ne concerne donc que l’objet racine initiateur. Le pipeline reçoit le type et l’id de l’objet initiateur, l’identifiant de l’action, la date et l’identifiant du motif si utilisé.

Les boucles et les critères

Le plugin fournit des critères spécifiques qui peuvent être utilisés dans les boucles des objets autorisés à l’archivage. Si un critère d’archivage est utilisé dans une boucle d’un objet non autorisé à l’archivage, celui-ci est inpérant.

Le critère {archive}

Le critère archive est une expression plus lisible du critère {est_archive=1}. Sa négation, {!archive} est donc un alias du critère {est_archive=0}.

Le critère {ignorer_archivage}

Le critère {ignorer_archivage} permet, pour la boucle concernée, de lever la restriction sur les objets archivés. Toute restriction explicite ou implicite concernant l’archivage ne sera pas prise en compte.

Le critère {desarchive}

Le critère {desarchive} permet, pour la boucle concernée et si la consignation du désarchivage est activée, de sélectionner les objets désarchivés. Si la consignation du désarchivage est désactivée, le critère ne retourne aucun objet. Sinon, il correspond à la conjonction des critères {est_archive=0} et {date_archive>0}.

L’installation et la configuration

A l’installation du plugin Archivage de Contenus, les champs du contexte d’archivage sont ajoutés à chacune des tables d’objets (pipeline declarer_tables_objets_sql). Si, par la suite, un autre plugin crée un nouveau type d’objet celui-ci ne bénéficiera pas d’emblée du contexte d’archivage. Néanmoins, le nouveau type étant proposé à l’archivage dans le formulaire de paramétrage du plugin, le choisir provoquera la création des champs du contexte.

En outre, chaque changement de configuration est suivi par une réinitialisation du contexte d’archivage des objets concernés de façon à conserver une cohérence nécessaire à l’application des mécanismes d’archivage.

Personnaliser l’utilisation du plugin

Personnaliser la liste des tables archivables

Par défaut, Archivage de Contenus considère que toutes les tables déclarées au travers du pipeline declarer_tables_objets_sql sont éligibles à l’archivage. Néanmoins, certains objets n’ont aucun intérêt de faire partie de cette liste car ils ne seront jamais concernés par l’archivage. C’est le cas, par exemple, des objets plugins, paquets et dépôts de SVP. De fait, il est possible d’exclure des tables de la liste, tables qui ne seront jamais présentées dans le formulaire de configuration du plugin:

• soit en utilisant la constante _ARCHIVAGE_TABLES_EXCLUES,
• soit en utilisant le pipeline archivage_exclusion_tables.

L’exemple ci-dessous illustre l’utilisation de la constante.

// Exclusions de l'archivage
define('_ARCHIVAGE_TABLES_EXCLUES', ['spip_depots', 'spip_plugins', 'spip_paquets']);

Personnaliser la liste des motifs

Par défaut, le plugin Archivage de Contenus propose deux motifs, l’un pour l’état archive, l’autre pour l’état calculé desarchive, si utilisé. Ces motifs sont communs à tous les types d’objet.

Un plugin utilisateur peut déclarer de multiples motifs pour chaque état mais aussi pour chaque type s’il souhaite différencier les motifs par type d’objet. Pour cela, il doit utiliser le pipeline archivage_liste_motifs dont les arguments sont le type d’objet et l’état calculé.

L’exemple suivant illustre l’utilisation du pipeline : on définit une identifiant de motif pour chaque état et chaque type d’objet.

function galactic_contrib_archivage_liste_motifs(array $flux) : array {
    // On rajoute des motifs pour Contrib
    $etat = $flux['args']['etat'];
    $objet = $flux['args']['objet'];
    $motifs_contrib = [
       "{$etat}_{$objet}_obsolescence"
    ];
    $flux['data'] = array_merge($flux['data'], $motifs_contrib);

    return $flux;
}

Pour traduire chaque motif, il est ensuite nécessaire de définir chaque item de langue dans un module archivage, un item de langue étant toujours de la forme motif_{$identifiant_motif}.

'motif_archive_article_obsolescence_label'     => 'article archivé car obsolescent',
'motif_archive_rubrique_obsolescence_label'    => 'rubrique archivée car obsolescente',
'motif_desarchive_article_obsolescence_label'  => 'article désarchivé suite à une erreur d\'archivage',
'motif_desarchive_rubrique_obsolescence_label' => 'rubrique désarchivée suite à une erreur d\'archivage',

Personnaliser les motifs par défaut

Le plugin Archivage de Contenus utilise les deux motifs qu’il a défini comme motif par défaut pour chaque état quel que soit le type d’objet.

Un plugin utilisateur peut déclarer, parmi ses listes de motifs, ceux qui doivent être utilisés par défaut. Pour cela il doit utiliser le pipeline archivage_motif_defaut dont les arguments sont le type d’objet et l’état calculé.

L’exemple suivant illustre l’utilisation du pipeline.

function galactic_contrib_archivage_defaut_motif(array $flux) : array {
    // On rajoute des motifs pour Contrib
    $etat = $flux['args']['etat'];
    $objet = $flux['args']['objet'];
    $flux['data'] = "{$etat}_{$objet}_obsolescence";

    return $flux;
}

Personnaliser les listes d’archives

Pour éviter de multiplier les squelettes de liste en fonction du type d’objet, le plugin Archivage de Contenus propose une liste générique prive/objets/liste/archives.html. Celle-ci est motorisée par une boucle DATA sur le tableau retourné par la balise #ARCHIVAGE_LISTE et permet d’afficher les objets archivés mais aussi les objets désarchivés quand la consignation du désarchivage est activée.

Néanmoins, il est possible de surcharger cette liste pour un type d’objet donné en créant un squelette prive/objets/liste/{$objets}_archives.html. Par exemple, pour les articles, il faudrait créer une liste nommée articles_archives.html.

Cette liste possède en entrée un contexte avec a minima les éléments suivants :

• l’état d’archivage sous la forme canonique (est_archive) et calculé (archive, desarchive);
• un critère where dans le cas des objets désarchivés;
• le type d’objet;
• le titre éventuel si aucun objet n’est répertorié;
• le tri, par défaut, par date d’archive.

La boucle doit posséder des critères conditionnels indispensables, à savoir, {est_archive ?} et {where ?} comme illustré dans l’exemple suivant pour les articles :

<BOUCLE_liste_art(ARTICLES)
    {est_archive?}
    {where?}
    {id_?}
    {statut?}
    {recherche?} 
    {par titre}{pagination #ENV{nb,20}}
    {!lang_select}>