Rôles de documents

Principe

Les documents liés aux contenus n’ont pas forcément tous la même fonction, il est parfois utile de distinguer le rôle de chaque document : à quoi sert-il ? Quel est son sens ?

Prenons un exemple concret : pour une librairie nous avons un objet éditorial « livre », chaque livre doît être accompagné de sa couverture (le logo), du 4^e de couverture, et d’une série d’extraits.
Le squelette correspondant a besoin d´afficher ces images en des endroits particuliers, il faut donc un moyen de les identifier dans des boucles différentes : c’est possible au moyen des rôles.

Utilisation

La gestion des rôles s´effectue sur place, dans la liste des documents liés aux contenus.
Un même document peut avoir plusieurs rôles.
Le rôle attribué par défaut est le rôle générique « document ».

Gestion des logos

Le plugin fournit 2 rôles supplémentaires : « logo » et « logo de survol ».
Il est donc possible de s’affranchir de la gestion historique des logos et de profiter des avantages des documents : vous pouvez leur donner un titre, un descriptif, des crédits, les réutiliser, les faire pivoter, etc.

Les balises #LOGO_XXX voient leur fonctionnement étendu : si aucun logo « historique » n´est présent, elles vont chercher un document avec le rôle de logo .

Dans la médiathèque, un nouvel onglet permet de visualiser les documents avec le rôle de logo :

NB — Le plugin Logos par rôle va plus loin en remplaçant complètement la gestion des logos par celles des rôles de documents, le formulaire des logos est entièrement remplacé.

NB 2 — La roadmap de la prochaine version de SPIP (3.3) prévoit que les logos soient gérés via la table spip_documents.

Intégration dans les squelettes

Par défaut les boucles DOCUMENTS ressortent tous les rôles, même les logos : il faut les exclure explicitement si besoin.
Il est possible d’utiliser les critères {role} et {par role}.

Exemples :

Filtrer les documents par rôle :

<BOUCLE_docs(DOCUMENTS documents_liens) {id_article} {role = bandeau}>
#LOGO_DOCUMENT
</BOUCLE_docs>

Trier les documents par roles puis par titre :

<BOUCLE_docs(DOCUMENTS) {id_article} {par role,titre} >
#LOGO_DOCUMENT
</BOUCLE_docs>

Afficher les rôles d´un document :

<BOUCLE_docs(DOCUMENTS) {id_article}>
#TITRE
Rôle(s) :
<BOUCLE_roles(documents_liens){id_document}{objet}{id_objet}{par role}{role!=''}{", "}>[(#ROLE|role{documents})]</BOUCLE_roles>
</BOUCLE_docs>

Déclarer de nouveaux rôles

Tout est expliqué dans la documentation de l’API des rôles, mais reprenons les grandes lignes avec quelques exemples.

Les rôles se manipulent au moyen du pipeline declarer_tables_objets_sql.
Les 2 clés roles_titres et roles_objets permettent d’indiquer les chaînes de langues des nouveaux rôles, ainsi que les rôles possibles pour chaque type d’objet éditorial.

Attention, pour être sûr de vous appuyer sur les déclarations par défaut, pensez bien à nécessiter ou utiliser le plugin « roles_documents » dans le XML de votre plugin, afin de passer après dans le pipeline.

La clé roles_objets est un tableau associatif, vous avez donc la possibilité d’ajouter des valeurs à celles existantes, ou bien de remplacer complètement certaines entrées.

Gardez également bien en tête les priorités de l’API des rôles : il y a des rôles déclarés par défaut pour tous les objets, et optionnellement des rôles pour chaque type d’objet, ces derniers sont pris en priorité.
Le plugin ne déclare que les rôles par défaut pour tous les objets, dès que vous ajoutez des rôles pour un type d’objet en particulier, ils prendront le dessus, dans ce cas pensez à inclure le rôle « logo ».

Voici quelques exemples :

1) Compléter les rôles par défaut

On veut ajouter des rôles à tous les objets, tout en conservant ceux déclarés par le plugin : on fait un merge.

function monplugin_declarer_tables_objets_sql($tables){

  $tables['spip_documents'] = array_merge_recursive(
    $tables['spip_documents'],
    array(
      'roles_titres' => array(
        'alpha' => 'monplugin:role_alpha',
        'beta'  => 'monplugin:role_beta'
      ),
      'roles_objets' => array(
        '*' => array(
          'choix' => array('alpha', 'beta'),
        ),
      ),
    )
  );

  return $tables;
}

2) Remplacer complètement les rôles par défaut

On veut avoir complètement la main sur les rôles, pas de merge.
Dans ce cas, il faut penser à mettre le rôle « logo », et indiquer le choix par défaut.

function monplugin_declarer_tables_objets_sql($tables){

  $tables['spip_documents']['roles_titres'] = array(
    'alpha' => 'monplugin:role_alpha',
    'beta'    => 'monplugin:role_beta'
  );
  $tables['spip_documents']['roles_objets'] = array(
    '*' => array(
      'choix'  => array('logo','alpha', 'beta'),
      'defaut' => 'alpha',
    ),
  );

  return $tables;
}

3) Avec des rôles par types d’objets

Un dernier exemple pour ajouter des rôles aux articles et aux brèves, tout en conservant les rôles par défaut pour les autres types d’objets.
Là on fait un merge pour garder la clé '*', et ajouter 2 clés 'articles' et 'breves'.
Comme dans l’exemple précédent, pour ces 2 objets il faut remettre le rôle « logo » et le choix par défaut.

$tables['spip_documents'] = array_merge_recursive(
  $tables['spip_documents'],
  array(
    'roles_titres' => array(
      'alpha'  => 'monplugin:role_alpha',
      'beta'   => 'monplugin:role_beta',
    ),
    'roles_objets' => array(
      'articles' => array(
        'choix' => array('document', 'logo', 'alpha'),
        'defaut' => 'document',
      ),
      'breves' => array(
        'choix' => array('document', 'logo', 'beta'),
        'defaut' => 'document',
      ),
    ),
  )
);

Limitations

l´API des rôles ne permet pour l´instant pas de limiter le nombre de rôles utilisés pour un objet.
Il est impossible de dire qu´un rôle « logo » ne peut être utilisé qu´une seule fois pour un contenu, par conséquent c´est aux rédacteurs à veiller à ne l´attribuer qu´une fois.