Formats de métadonnées

Les étapes pour créer une nouvelle classe de format de métadonnées sont les suivantes :

1. Créez un nouveau fichier dans le répertoire de format local (ou client pour les formats de métadonnées fournis par Axiell). Nommez le fichier après le metadataPrefix du format de métadonnées qu’il implémente et utilisez une extension de fichier php. Par exemple : oai_dc.php
2. Ouvrez le fichier avec votre éditeur préféré. Comme le format des métadonnées est écrit dans le langage de programmation PHP, nous devons inclure les balises d’ouverture et de fermeture PHP au début et à la fin du fichier :

   < ?php ... ?> 

3. Chaque classe doit étendre la classe BaseMetadataFormat, nous devons donc spécifier l’emplacement du fichier qui contient cette classe :

   require_once WS ::$shared . '/BaseMetadataFormat.php' ; 

4. Commencez la définition de la classe. Nous devons spécifier le nom de la classe dans une variable $class, puis spécifier la classe elle-même. Le nom de la classe doit être le nom du metadataPrefix suivi d’un trait de soulignement suivi du nom du répertoire de format, c’est-à-dire local ou client. Nous devons étendre la classe BaseMetadataFormat :

   $class = 'oai_dc_local' ;  class oai_dc_local extends BaseMetadataFormat { ... } 

   Note: Vous devez ajouter le nom du répertoire de format au nom de la classe, par exemple oai_dc_local (ou oai_dc_client pour les formats de métadonnées fournis par Axiell).

5. Définissez le constructeur de la classe. Dans le constructeur, vous devez appeler le constructeur parent (BaseMetadataFormat) avec quatre paramètres, les metadataPrefix, schema et metadataNamespace qui identifient le format et le version du format que vous implémentez :

   fonction publique __construct() { parent ::__construct('oai_dc', 'http://www.openarchives.org/OAI/2.0/oai_dc.xsd', 'http://www.openarchives.org/OAI/2.0/oai_dc/', '2.0') ; } 

6. Définissez la fonction getColumnsByModule. Il spécifie les modules et les colonnes à récupérer à partir du SGC EMu. La fonction doit retourner un tableau associatif qui a des noms de modules comme clés et un tableau de noms de colonnes comme valeurs :

   fonction publique getColumnsByModule() { $columnsByModule = array  ( 'emultimedia' => array  ( 'DetSubject_tab', ' DetPublisher', 'MulDescription', 'MulMimeFormat', 'MulMimeType', 'MulTitle', ), ) ; return($columnsByModule) ; } 

   Note: Les colonnes irn, AdmDateInserted, AdmTimeInserted, AdmDateModified et AdmTimeModified sont automatiquement ajoutées pour chaque module afin que vous n’ayez pas à les spécifier.

   Voir Spécification des colonnes pour plus de détails.

7. Définissez la fonction writeMetadata. La fonction génère en fait la section d’enregistrement XML metadata. La fonction doit accepter deux paramètres, un nom de module EMu $name et un tableau $row. Le paramètre $name est le nom d’un module spécifié dans la fonction getColumnsByModule. Le paramètre $row est un tableau associatif de noms de colonnes et de valeurs de colonnes pour un seul enregistrement EMu :

   public function writeMetadata($name, array $row) { $this->writer->startElement('oai_dc:dc'); $this->writer->writeAttribute('xmlns:oai_dc', 'http://www.openarchives.org/OAI/2.0/oai_dc/'); $this->writer->writeAttribute('xmlns:dc', 'http://purl.org/dc/elements/1.1/'); $this->writer->writeAttribute('xmlns:xsi', 'http://www.w3.org/2001/XMLSchema-instance'); $this->writer->writeAttribute('xsi:schemaLocation', 'http://www.openarchives.org/OAI/2.0/oai_dc/' . 'http://www.openarchives.org/OAI/2.0/oai_dc.xsd'); $date = $this->getDateInserted($row); $this->writer->writeElement('dc:date', $date); if ($this->hasValue($row, 'MulDescription')) $this->writer->writeElement('dc:description', $row['MulDescription']); if ($this->hasValue($row, 'MulMimeFormat')) $this->writer->writeElement('dc:format', $row['MulMimeFormat']); if ($this->hasValue($row, 'DetSubject_tab')) { foreach ($row['DetSubject_tab'] as $subject) $this->writer->writeElement('dc:subject', $subject); } if ($this->hasValue($row, 'MulTitle')) $this->writer->writeElement('dc:title', $row['MulTitle']); if ($this->hasValue($row, 'MulMimeType')) $this->writer->writeElement('dc:type', $row['MulMimeType']); $this->writer->endElement(); } 

   Voir Écriture des métadonnées fpour plus de détails.

   Note: Vous devez toujours vérifier qu’une valeur pour une colonne de la variable $row existe avant d’essayer de l’écrire en XML, sinon votre sortie pourrait être invalide. La classe BaseMetadataFormat fournit la méthode hasValue à cette fin.

8. Ajoutez le metadataPrefix du nouveau format de métadonnées à l’option ws.ini du fichier de configuration supportedFormats.

Note: Des exemples complets de format de métadonnées peuvent être trouvés dans les Annexes.

Les étapes pour modifier une classe de format de métadonnées existante sont les suivantes :

1. Créez un nouveau fichier. Comme pour Création d’un nouveau format de métadonnées.
2. Ouvrez le fichier. Comme pour Création d’un nouveau format de métadonnées.
3. Comme nous étendons un format de métadonnées existant, nous devons spécifier l’emplacement de cette classe :

   require_once WS ::$base . '/common/formats/oai_dc.php' ; 

4. Commencez la définition de la classe. Nous étendons le format de métadonnées existant :

   $class = 'oai_dc_local' ;  class oai_dc_local extends oai_dc { ... } 

5. À moins que nous ayons besoin de redéfinir les schema et metadataNamespace qui identifient le format ou le version du format de métadonnées que nous étendons, il n’est pas nécessaire de définir un constructeur de classe. Si vous souhaitez redéfinir le metadataPrefix, vous devez consulter Création d'un nouveau format de métadonnées.
6. Définissez la fonction getColumnsByModule. Comme pour Création d’un nouveau format de métadonnées.
7. Définissez la fonction writeMetadata. Comme pour Création d’un nouveau format de métadonnées.

Les colonnes spécifiées dans la fonction getColumnsByModule peuvent être plus que de simples noms de colonnes. Il est également possible de :

• Récupérer les colonnes des modules auxquels l’enregistrement en cours est joint.

  Par exemple, supposons que le module Catalogue documente le créateur d’un objet en tant que pièce jointe (à un enregistrement dans le module Personnes / Organisations) dans une colonne appelée CatCreatorRef. Si l’on recherche le module Catalogue, il est possible d’obtenir le nom de famille du créateur pour chaque enregistrement du Catalogue dans l’ensemble des résultats comme suit :

   'CatCreatorRef.NamLast' 

  Cette technique peut être étendue pour récupérer les données de plus d’une colonne :

   'CatCreatorRef. (NamTitle,NamLast,NamFirst)' 

• Récupérer les colonnes des enregistrements joints à l’enregistrement en cours.

  Par exemple, pour récupérer des informations à partir d’un ensemble d’enregistrements du Catalogue qui sont joints à l’enregistrement Personnes / Organisations en cours via la colonne CatCreatorRef du Catalogue, spécifiez :

   '<ecatalogue :CatCreatorRef>.( irn,TitMainTitle)' 

• Renommer les colonnes.

  Il est possible de renommer n’importe quelle colonne lorsqu’elle est renvoyée en ajoutant le nouveau nom devant la colonne réelle demandée, suivi d’un signe égal. Par exemple, pour demander des données à partir de la colonne NamLast mais la renommer en last_name, spécifiez :

   'last_name=NamLast' 
  

  La variable $row contiendra un élément appelé last_name plutôt que NamLast.

• Regrouper les colonnes de tables imbriquées.

  Le regroupement permet de refléter une association entre colonnes dans la structure des données renvoyées. Pour regrouper les colonnes, entourez-les de crochets :

   '[DocIdentifier_tab,DocMimeType_tab,DocMimeFormat_tab]' 

  La variable $row contiendra un élément, appelé group1, où chaque ligne correspondante des tables spécifiées dans le groupe est répertoriée ensemble, par exemple :

   [group1] => Array ( [0] => Array ( [DocMimeFormat_tab] => tiff [DocMimeType_tab] => image [DocIdentifier_tab] => image.tif ) [1] => Array ( [DocMimeFormat_tab] => jpeg [DocMimeType_tab] => image [DocIdentifier_tab] => image.thumb.jpg ) ) 

  par opposition à l’exemple non groupé :

   [DocMimeType_tab] => Array ( [0] => image [1] => image ) [DocIdentifier_tab] => Array ( [0] => image.tif [1] => image.thumb.jpg ) [DocMimeFormat_tab] => Array ( [0] => tiff [1] => jpeg ) 

  Par défaut, les groupes reçoivent un nom de group1, group2 et ainsi de suite, qui peut être changé assez facilement, par exemple, nous pouvons changer le nom du groupe en multimedia :

   'multimedia=[DocIdentifier_tab,DocMimeType_tab,DocMimeFormat_tab]' 

  N’importe laquelle des méthodes de spécification des colonnes listées dans la documentation PHP d’IMu ici peut être utilisée.

La propriété de la classe BaseMetadataFormat writer est une instance de la classe PHP XMLWriter et est accessible par toute classe qui étend la classe BaseMetadataFormat. Lors de la définition de la fonction writeMetadata d’un format de métadonnées, la propriété writer peut être utilisée pour produire n’importe quel XML arbitraire. La classe XMLWriter définit un certain nombre de méthodes pour écrire du XML :

• startElement : commencer une balise d’élément XML.
• writeAttribute : écrire un nom et une valeur d’attribut XML.
• text : écrire un nœud de texte XML.
• endElement : termine une balise d’élément XML.
• writeElement : commence une balise d’élément XML, écrit un nœud de texte et termine la balise d’élément XML.

Par exemple, les méthodes suivantes :

$this->writer->startElement('start'); $this->writer->writeAttribute('name', 'value'); $this->writer->text('voici un texte'); $this->writer->endElement(); 

généreront le XML suivant :

<start name="value">Ceci est un peu plus de texte</start>

et la méthode suivante :

$this->writer->writeElement('start', 'voici un texte supplémentaire');

généreront le XML suivant :

<start>Ceci est un peu plus de texte</start>

Il est de votre responsabilité de produire une sortie XML valide, bien que XMLWriter échappera automatiquement les entités prédéfinies dans toute sortie texte. Voir la documentation PHP XMLWriter pour plus de détails.

Comme il est possible d’utiliser toutes les fonctionnalités du langage de programmation PHP, les options d’écriture XML sont très flexibles.

Il est possible de produire du texte statique (codé en dur) ou de mélanger du texte statique et dynamique :

$this->writer->writeElement('dc:publisher', 'The National Museum'); $this->writer->writeElement('dc:identifier', 'http://nationalmusuem.com/collection?object=' . $row['irn']); 

Nous pouvons produire du texte de manière conditionnelle :

if ($this->hasValue($row, 'DetPublisher') && $row['DetPublisher'] == 'NM') $this->writer->writeElement('dc:publisher', 'The National Museum'); 

Nous pouvons également produire un contenu entièrement dynamique :

if ($this->hasValue($row, 'DetPublisher')) $this->writer->writeElement('dc:publisher', $row['DetPublisher']);