SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [vi] [zh] Espace de traduction

Télécharger
Accueil > Documentation en français > Webmestres > Guide des fonctions avancées > API de déclaration d’objets éditoriaux

API de déclaration d’objets éditoriaux

Mai 2012

Dans SPIP 3.0 la création de nouveaux objets éditoriaux est simplifiée par une interface de programmation (ou API) déclarative [1] qui permet à SPIP de construire de façon automatisée une grande partie de l’interface d’édition de ces objets.


La déclaration d’un nouvel objet éditorial se fait via le pipeline declarer_tables_objets_sql qui permet de peupler un tableau associatif :

  • Les clés du tableau sont les noms des tables SQL (exemple spip_articles)
  • à chaque clé sont associées un certain nombre de valeurs dans un tableau, selon la nomenclature ci-dessous, présentée par type d’information

Base de donnée

table_objet
Explication nom raccourci de la table
Exemple articles pour spip_articles
Valeur par défaut nom de la table sans spip_
dans SPIP 2.1 non déclaré
table_objet_surnom
Explication synonymes de table_objet pour les cas particuliers
Exemple pas de surnom pour articles (mais exemple : groupe_mots pour spip_groupes_mots)
Valeur par défaut pas de surnom
dans SPIP 2.1 via declarer_tables_objets_surnoms
type
Explication nom court de l’objet
Exemple article pour la table spip_articles
Valeur par défaut clé primaire sans id_ au début ni s a la fin, ou à défaut nom de la table sans spip_ au début ni s a la fin
dans SPIP 2.1
type_surnoms
Explication synonyme du type pour les cas particuliers
Exemple
Valeur par défaut pas de surnom
dans SPIP 2.1
field
Explication Déclaration SQL des champs de la table
Exemple array( "id_article" => "bigint(21) NOT NULL", "surtitre" => "text DEFAULT ’’ NOT NULL", "titre" => "text DEFAULT ’’ NOT NULL", "soustitre" => "text DEFAULT ’’ NOT NULL",...)
Valeur par défaut héritée de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe
key
Explication Déclaration SQL des clés de la table
Exemple array( "PRIMARY KEY" =>"id_article", "KEY id_rubrique" => "id_rubrique",...)
Valeur par défaut hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe
join
Explication les champs déclarés explicitement pour les jointures. sinon les jointures se feront exclusivement sur la clef primaire. attention : les champs ’idx’, ’maj’, ’date’ et ’statut’ ne peuvent PAS être déclarés comme champs de jointure possible.
Exemple array( "id_article"=>"id_article", "id_rubrique"=>"id_rubrique")
Valeur par défaut hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe
tables_jointures
Explication déclaration de la table de liens et de son champ de jointure. on joindra ainsi (par exemple) id_article, articles à id_auteur, auteurs en passant par la table auteurs_liens et ses lignes id_auteur, id_objet, objet (donc, ici : id_auteur, id_article, articles)
Exemple array(’id_auteur’ => ’auteurs_liens’)
Valeur par défaut hérité de la déclaration $tables_jointures si existante (compatibilité)
dans SPIP 2.1 $declarer_tables_objets_sql[’spip_articles’][’tables_jointures’] reprend l’ancien contenu de $tables_jointures[’spip_articles’]
principale
Explication Indique si la table est table principale ou auxiliaire ; prend les valeurs ’oui’ ou ’non’
Exemple ’oui’
Valeur par défaut hérité de la déclaration $tables_principales si existante (compatibilité)
dans SPIP 2.1 Remplace l’affectation des tableaux dans le pipeline declarer_tables_principales ou declarer_tables_auxiliaires
modeles
Explication permet de déclarer les modèles associés a cet objet
Exemple exemple pour spip_documents : array(’document’, ’doc’, ’img’, ’emb’, ’image’, ’video’, ’text’, ’audio’, ’application’)
Valeur par défaut la valeur de type
dans SPIP 2.1

Le titre, la date et la gestion du statut

titre
Explication Représentation SQL qui permet de récupérer le titre et la langue de l’objet
Exemple "titre, lang"
Valeur par défaut hérité de la déclaration $tables_titre (compatibilité) ou vide sinon
dans SPIP 2.1 Remplace la déclaration du titre de l’objet dans le pipeline declarer_tables_interfaces : $interface['table_titre']['articles'] = "titre, '' AS lang";
date
Explication déclare le champ date de l’objet utilisé pour le dater
Exemple date
Valeur par défaut hérité de la déclaration $tables_date ou vide
dans SPIP 2.1 Remplace la déclaration de la date de l’objet dans declarer_tables_interfaces : $interface['table_date']['articles'] = "date";
statut
Explication Déclaration du statut pour l’objet
Exemple array(array( ’champ’ => ’statut’, ’publie’ => ’publie’, ’previsu’ => ’publie,prop,prepa’, ’post_date’ => ’date’, ’exception’ => ’statut’))
Valeur par défaut vide
dans SPIP 2.1 Remplace la surcharge des boucles avec conditions where pour gerer le statut. Ici la déclaration est directement prise en compte dans les boucles génériques
statut_titres
Explication Chaines de langue du titre de chaque statut. Définit par la même la liste des statuts autorisés
Exemple array( ’prepa’=>’info_article_redaction’, ’prop’=>’info_article_propose’, ’publie’=>’info_article_publie’, ’refuse’=>’info_article_refuse’, ’poubelle’=>’info_article_supprime’)
Valeur par défaut null
dans SPIP 2.1
statut_images
Explication definit les puces associées à chaque statut
Exemple
Valeur par défaut null
dans SPIP 2.1 Pas d’équivalence
statut_textes_instituer
Explication Chaines de langue du libellé de chaque statut dans le bloc instituer de l’objet
Exemple array( ’prepa’ => ’texte_statut_en_cours_redaction’, ’prop’ => ’texte_statut_propose_evaluation’, ’publie’ => ’texte_statut_publie’, ’refuse’ => ’texte_statut_refuse’, ’poubelle’ => ’texte_statut_poubelle’)
Valeur par défaut null
dans SPIP 2.1 Pas d’équivalence

L’édition, l’affichage et la recherche

page
Explication Le nom de la page publique de l’objet
Exemple article
Valeur par défaut type si principale=’oui’, rien sinon
dans SPIP 2.1 Remplace la déclaration de l’url de l’objet dans le pipeline declarer_url_objets()
url_voir
Explication nom de l’exec privé pour voir l’objet
Exemple article
Valeur par défaut type
dans SPIP 2.1
url_edit
Explication nom de l’exec privé pour éditer l’objet
Exemple article_edit
Valeur par défaut type+_edit
dans SPIP 2.1
editable
Explication donner acces à une page d’édition dans l’espace privé
Exemple ’oui’ ou false
Valeur par défaut oui
dans SPIP 2.1
champs_editables
Explication Liste des champs de l’objet pouvant être modifiés dans le formulaire d’édition
Exemple array(’surtitre’, ’titre’, ’soustitre’, ’descriptif’,’nom_site’, ’url_site’, ’chapo’, ’texte’, ’ps’,’virtuel’)
Valeur par défaut vide
dans SPIP 2.1 listés explicitement dans la fonction articles_set de action/editer_article [2]
icone_objet
Explication nom du fichier d’icône fourni en 16/24/32px
Exemple article
Valeur par défaut type
dans SPIP 2.1
champs_versionnes
Explication Liste des champs de l’objet soumis au processus de révisions
Exemple array(’id_rubrique’, ’surtitre’, ’titre’, ’soustitre’, ’jointure_auteurs’, ’descriptif’, ’nom_site’, ’url_site’, ’chapo’, ’texte’, ’ps’)
Valeur par défaut array()
dans SPIP 2.1
rechercher_champs
Explication Déclaration des champs utilisés dans la recherche et de leur score respectif
Exemple array( ’surtitre’ => 5, ’titre’ => 8, ’soustitre’ => 5, ’chapo’ => 3,...)
Valeur par défaut array()
dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline rechercher_liste_des_champs : même syntaxe
rechercher_jointures
Explication Déclaration des champs et de leurs scores respectifs utilisés via une jointure lors de la recherche. Préciser la table de ces champs en premier élément de l’array.
Exemple array( ’auteur’ => array(’nom’ => 10) )
Valeur par défaut array()
dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline rechercher_liste_des_jointures : même syntaxe

Les chaines de langue

On déclare dans ces items là sous forme de chaine de langue les textes standards utilisés dans l’espace privé, dans les pages générées automatiquement par SPIP.

texte_ajouter
Explication Chaine "Ajouter un ..."
Exemple titre_ajouter_un_auteur
Valeur par défaut texte_ajouter_type
dans SPIP 2.1
texte_retour
Explication Chaine de langue du bouton retour dans la page d’édition de l’objet
Exemple icone_retour_article
Valeur par défaut icone_retour
dans SPIP 2.1
texte_modifier
Explication Chaine de langue du bouton modifier permettant d’ouvrir le formulaire d’édition de l’objet
Exemple icone_modifier_article
Valeur par défaut type:icone_modifier_type
dans SPIP 2.1
texte_creer
Explication Chaine de langue du bouton de création d’un nouvel objet
Exemple icone_ecrire_article
Valeur par défaut type:icone_creer_type
dans SPIP 2.1
texte_creer_associer
Explication  
Exemple creer_et_associer_un_auteur
Valeur par défaut type:texte_creer_associer_type
dans SPIP 2.1
texte_signale_edition
Explication Chaine de langue signalant que l’auteur x a travaillé récemment sur l’objet
Exemple texte_travail_article
Valeur par défaut info_qui_edite
dans SPIP 2.1
texte_objet
Explication Chaine de langue du singulier de l’objet. La valeur est censée être écrite avec une lettre capitale
Exemple public:article
Valeur par défaut type:titre_type
dans SPIP 2.1
texte_objets
Explication Chaine de langue du pluriel de l’objet La valeur est censée être écrite avec une lettre capitale
Exemple public:articles
Valeur par défaut type:titre_table_objet
dans SPIP 2.1
info_aucun_objet
Explication Chaine de langue désignant 0 article utilisée dans la fonction objet_afficher_nb()
Exemple info_aucun_article
Valeur par défaut type:info_aucun_type
dans SPIP 2.1
info_1_objet
Explication Chaine de langue désignant 1 article utilisée dans la fonction objet_afficher_nb()
Exemple info_1_article
Valeur par défaut type:info_1_type
dans SPIP 2.1
info_nb_objets
Explication Chaine de langue désignant nb article utilisée dans la fonction objet_afficher_nb()
Exemple info_nb_articles
Valeur par défaut type:info_nb_table_objets
dans SPIP 2.1
texte_logo_objet
Explication Chaine de langue du titre de la boite d’affichage du logo dans la page privée de l’objet
Exemple logo_article
Valeur par défaut type:titre_logo_type
dans SPIP 2.1 Remplace l’utilisation de la globale $GLOBALS['logo_libelles']['id_objet']

Exemple des brèves

Voici la déclaration telle que réalisée par le plugin qui ajoute les brèves comme objet éditorial dans SPIP :

  1. function breves_declarer_tables_objets_sql($tables){
  2.         $tables['spip_breves'] = array(
  3.                 'texte_retour' => 'icone_retour',
  4.                 'texte_objets' => 'breves:breves',
  5.                 'texte_objet' => 'breves:breve',
  6.                 'texte_modifier' => 'breves:icone_modifier_breve',
  7.                 'texte_creer' => 'breves:icone_nouvelle_breve',
  8.                 'info_aucun_objet'=> 'breves:info_aucun_breve',
  9.                 'info_1_objet' => 'breves:info_1_breve',
  10.                 'info_nb_objets' => 'breves:info_nb_breves',
  11.                 'texte_logo_objet' => 'breves:logo_breve',
  12.                 'texte_langue_objet' => 'breves:titre_langue_breve',
  13.                 'titre' => 'titre, lang',
  14.                 'date' => 'date_heure',
  15.                 'principale' => 'oui',
  16.                 'field'=> array(
  17.                         "id_breve"      => "bigint(21) NOT NULL",
  18.                         "date_heure"    => "datetime DEFAULT '0000-00-00 00:00:00' NOT NULL",
  19.                         "titre" => "text DEFAULT '' NOT NULL",
  20.                         "texte" => "longtext DEFAULT '' NOT NULL",
  21.                         "lien_titre"    => "text DEFAULT '' NOT NULL",
  22.                         "lien_url"      => "text DEFAULT '' NOT NULL",
  23.                         "statut"        => "varchar(6)  DEFAULT '0' NOT NULL",
  24.                         "id_rubrique"   => "bigint(21) DEFAULT '0' NOT NULL",
  25.                         "lang"  => "VARCHAR(10) DEFAULT '' NOT NULL",
  26.                         "langue_choisie"        => "VARCHAR(3) DEFAULT 'non'",
  27.                         "maj"   => "TIMESTAMP"
  28.                 ),
  29.                 'key' => array(
  30.                         "PRIMARY KEY"   => "id_breve",
  31.                         "KEY id_rubrique"       => "id_rubrique",
  32.                 ),
  33.                 'join' => array(
  34.                         "id_breve"=>"id_breve",
  35.                         "id_rubrique"=>"id_rubrique"
  36.                 ),
  37.                 'statut' =>  array(
  38.                         array(
  39.                                 'champ'=>'statut',
  40.                                 'publie'=>'publie',
  41.                                 'previsu'=>'publie,prop',
  42.                                 'exception'=>'statut'
  43.                         )
  44.                 ),
  45.                 'texte_changer_statut' => 'breves:entree_breve_publiee',
  46.                 'aide_changer_statut' => 'brevesstatut',
  47.                 'statut_titres' => array(
  48.                         'prop' => 'breves:titre_breve_proposee',
  49.                         'publie' => 'breves:titre_breve_publiee',
  50.                         'refuse' => 'breves:titre_breve_refusee',
  51.                 ),
  52.                 'statut_textes_instituer' =>    array(
  53.                         'prop' => 'breves:item_breve_proposee', //_T('texte_statut_propose_evaluation')
  54.                         'publie' => 'breves:item_breve_validee', //_T('texte_statut_publie')
  55.                         'refuse' => 'breves:item_breve_refusee', //_T('texte_statut_refuse')
  56.                 ),
  57.  
  58.                 'rechercher_champs' => array(
  59.                   'titre' => 8, 'texte' => 2, 'lien_titre' => 1, 'lien_url' => 1
  60.                 ),
  61.                 'rechercher_jointures' => array(
  62.                         'document' => array('titre' => 2, 'descriptif' => 1)
  63.                 ),
  64.                 'champs_versionnes' => array('id_rubrique', 'titre', 'lien_titre', 'lien_url', 'texte'),
  65.         );
  66.  
  67.         return $tables;
  68. }
Télécharger

Notes

[1] qui regroupe notamment en une seule, plusieurs déclarations existantes auparavant

[2] ce qui obligeait à dupliquer tout le code pour un nouvel objet, à ce détail près. Cette déclaration permet le support générique des objets dans action/editer_objet et ses fonctions objet_modifier/objet_inserer/objet_instituer


Voir le squelette de cette page Site réalisé avec SPIP | Espace de traduction | Espace privé