le code source de SpirHAL est disponible ici.

Plan de la documentation :

Installation sur une page¶

Pré-requis¶

Pour installer l’affiche des notices de HAL pour un membre il est nécessaire d’avoir un site hébergé. Ce module vient s’intégrer dans la page pour afficher les notices d’un membre donné. Aucune autre pré requis n’est nécessaire.

Installation¶

Récupération du script¶

Pour récupérer SpirHAL vous avez trois possibilités :

CDN¶

La première possibilité est d’utiliser directement la dernière version de SpirHAL sur un serveur qui l’héberge :

https://spirhal.murloc.fr/Spirhal-latest.js

Téléchargement¶

Une autre possibilité est de récupérer une version déjà compilée de SpirHAL sur ce lien.

Compilation¶

La dernière possibilité est de compiler vous même SpirHAL. Pour compiler vous même le script il est nécessaire d’avoir installé Node.JS et Angular-CLI. Il est aussi nécessaire d’avoir GIT d’installé sur votre machine.

Tout d’abord il vous faut cloner le git du projet SpirHAL :

git clone git@framagit.org:Murloc6/Spirhal.git

Une fois le contenu du projet récupérer, il faut se rendre dans le dossier et lancer la commande de compilation :

cd Spirhal
npm install
ng build

Lorsque le processus est terminé, les fichiers compilés de SpirHAL sont disponibles dans le dossier dist.

Importer les fichiers sur votre page web¶

Maintenant que vous avez les fichiers compilés de SpirHAL (soit par CDN, soit en les téléchargant soit en les compilant vous même) il vous faut les importer dans le code de votre page web. Pour cela il faut rajouter les balises d’import dans le head de votre page web. Par exemple si nous avons utilisé la version hébergée sur le serveur CDN, le script à importer sont :

<script src="https://spirhal.murloc.fr/Spirhal-latest.js"></script>

Ce scripts importé contien toutes les dépendances nécessaires à SpirHAL pour fonctionner.

Initialisation de SpirHAL¶

Une fois le fichier importé il faut maitnenant initialiser SpirHAL. Pour cela, SpirHAL utilise le principe de “Component” d’Angular (plus d’informations ici). Ce qui signifie que l’on utilise une balise spéficique pour SpirHAL avec les paramètres correspondants. Ici la balise s’appelle “spirhal”. Nous pouvons alors insérer dans notre page cette balise et la paramétrer pour qu’elle affiche les notices de la personne concernée. Par exemple si nous souhaitons afficher les notices de “Hélène Débax” du laboratoire Framespa (structID HAL 620) avec la norme “EHESS” alors nous pouvons insérer la balise suivante :

<spirhal researcherName="Hélène Débax" norm="EHESS" structId="620"></spirhal>

On peut remarquer le nom de la balise est bien “spirhal” et ensuite les paramètres sont des attributs de la balise :

“researcherName” est la personne dont on souhaite afficher les notices venant de HAL (attention de bien réspecter “Prénom Nom” dans cet ordre avec ces majuscules pour que la requête sur HAL fonctionne correctement)
“norm” est le nom de la norme bibliographique à utiliser (seul les normes implémentées peuvent être utilisées). S’il n’y a pas de norme spécifiée alors SpirHAL utilisera la représentation utilisée sur HAL
“structId” est le structId sur HAL du laboratoire auquel appartient la personne (ce paramètre est optionnel)
- il est possible de connaitre le structId d’un laboratoire sur AuréHAL

Une fois cette balise ajoutée, les notices provenant de la personne spécifiée dans “researcherName” seront affichées à l’endroit où est la balise.

Page complète¶

Un exemple de page complète pour “Hélène Débax” et ne contenant que la liste des notices est la suivante :

<html>
    <head>
        <script src="https://spirhal.murloc.fr/Spirhal-latest.js"></script>
    </head>
    <body>
        <spirhal researcherName="Hélène Débax" norm="EHESS" structId="620"></spirhal>
    </body>
</html>

Style CSS¶

La balise « <spirhal> » va générer du contenu HTML qu’il est possible de stylisé avec du CSS comme tout élément d’une page HTML.

Voici un exemple du HTML généré pour une notice ayant le texte intégral disponible :

<spirhal researcherName="Hélène Débax" norm="EHESS" structId="620">
    <div class="publiList">
        <div class="groupCitation">
            <div>
                <h3>
                  Article(s)
                </h3>
            </div>
            <div class="card-body list-group">
              <div class="row-citation specificResearcher">
                <div class="citation row">
                    <ehess class="col-md-10">
                      <div class="citation EHESS">
                        <a href="https://halshs.archives-ouvertes.fr/halshs-00498858">
                            <span class="author">Hélène Débax,</span>
                            <span class="title">«Le serrement des mains. Éléments pour une analyse du rituel des serments féodaux en Languedoc et en Provence (XIe-XIIe siècles)»,</span>
                            <span class="journalTitle"><i>Le Moyen Age. Revue d'histoire et de philologie</i>,</span>
                            <span class="volume">tome CXIII,</span>
                            <span class="issue">n°1,</span>
                            <span class="year">2007,</span>
                            <span class="pages">p. 9-23</span>
                        </a>
                      </div>
                    </ehess>
                  <a class="picto-fulltext col-md-2" target="__blank" href="https://halshs.archives-ouvertes.fr/halshs-00498858/file/Debax_serrement.pdf">
                    <img _ngcontent-c1="" src="assets/picto-article.png" width="30">
                  </a>
                </div>
              </div>
            </div>
        </div>
    </div>
</spirhal>

On peut remarquer ici les classes utilisées pour encapsuler chaque éléments de la notice. Bootstrap est utilisé pour aligner les éléments sur la page.

Modifier SpirHAL¶

Le projet SpirHAL étant du logiciel libre il est tout à fait possible de modifier tous les éléments de ce projet. Nous allons ici présenter comment modifier ou ajoute une nouvelle norme dans SpirHAL.

Le code source de SpirHAL est développé en utilisant la technologie React il est donc fortement recommandé de maîtriser cette technologie avant de proposer des modifications à SpirHAL.

Modifier une norme bibliographique¶

Chaque norme bibliographique est proposée comme un “Component” React. Toutes les normes sont présentes dans le dossier “/src/components/spirhal/norms”. Trois sont implémentées pour l’instant: EHESS, APA, MLA.

La logique de formatage d’une notice suivant une norme est contenue dans un sous-dossier de “/src/components/spirhal/norms” ayant le nom de la norme. Chaque norme doit fournir un composant React pour affichage d’une notice selon la norme bibliographique dont les propriétés implémentent l’interface Notice (« src/components/spirhal/Notice.tsx »).

Une norme exporte aussi une liste renderedGroups de types de notices qui nécessitent un traitement particulier par la norme pour leur affichage. Les autres types de notices sont traités « par défaut » par la norme.

export const renderedGroups = ["OUV", "COUV", "ART", "COMM", "DOUV", "POSTER", "THESE", "HDR"];

export const APANotice: React.FC<Notice> = (notice) => {
   ....

}

Ajouter une norme bibliographique¶

Pour ajouter une nouvelle norme nommée « EXEMPLE » dans SpirHAL, il faut créer un dossier “/src/components/spirhal/norms/EXEMPLE”. Dans celui-ci créer un fichier « EXEMPLE.tsx » qui exportera un composant React comme suit et la liste des types de notices suivant un traitement particulier par la norme.

...
export const renderedGroups = ["OUV", "COUV", "ART", "COMM", "DOUV", "POSTER", "THESE", "HDR"];

...

export const EXEMPLENotice: React.FC<Notice> = (notice) => {
   ....

}

D’autres fichiers peuvent être créés dans le dossier « EXEMPLE » pour contenir la logique propre à la norme.

Ensuite, dans « src/components/spirhal/Notice.tsx », il faut:

importer le composant EXEMPLENotice
ajouter la valeur à l’énumération Norm
ajouter un cas dans le switch de GenericNoticeComponent

...
import { EXEMPLENotice } from "./norms/EXEMPLE/EXEMPLE";

...

enum Norm {
  EHESS = "EHESS",
  APA = "APA",
  MLA = "MLA",
  DEFAULT = "default",
  EXEMPLE = "EXEMPLE",
}


...

const GenericNoticeComponent: React.FC<Notice> = (notice) => {
  ...
  switch (norm) {
    case Norm.EXEMPLE:
      noticeComponent = <EXEMPLENotice {...notice} />;
      break;
  ...
  }
  ...
}

Dans le fichier « src/components/spirhal/Groups.tsx », il faut:

importer le contenu de la norme (ou au moins la liste des renderedGroups)
ajouter la liste des renderedGroups au dictionnaire normRenderedGroups

import * as EXEMPLE from "./norms/EXEMPLE/EXEMPLE";

...

const normRenderedGroups: { [key: string]: string[] } = {
  EHESS: EHESS.renderedGroups,
  APA: APA.renderedGroups,
  MLA: MLA.renderedGroups,
  EXEMPLE: EXEMPLE.renderedGroups,
};

Il faudra enfin utiliser le nom de la norme lors de l’implémentation de SpirHAL pour utiliser cette nouvelle norme dans votre page de votre site web avec :

<spirhal researcherName="Hélène Débax" norm="EXEMPLE" structId="620"></spirhal>

Le projet SpirHAL est l’initiative du groupe de travail Open Access de l’université Toulouse Jean Jaurès. L’objectif de ce projet a été de développer un outil facile d’utilisation et d’installation pour permettre l’affichage du contenu de HAL sur la page annuaire de chaque chercheur. De cette manière la bibliographie des membres de laboratoire est plus simple à maintenir et l’affichage est homogène sur toutes les pages annuaires d’un même laboratoire.

Ce projet a ensuite évolué pour permettre la détection de champs manquants (champs nécessaire à l’affichage de la citation en suivant la norme déterminée par le laboratoire) et des doublons (entre une citation présente dans HAL et sur la fiche annuaire).

l’entreprise Murloc WebDev (Fabien Amarger) a développé ce projet en collaboration avec le groupe de travail Open Access.

Présentation du projet¶

SpirHAL est un projet open-source permettant le déploiement d’un module d’affichage sur un site web des notices de publications scientifiques figurant sur la plateforme HAL.

Affichage pour une personne¶

Ce mode permet l’affichage des notices des publications pour une personne en respectant une norme bibliographique donnée. Il peut être utilisé pour un affichage sur une fiche annuaire des membres d’un laboratoire.

Le premier laboratoire a avoir utilisé le module SpirHAL est Framespa. Il est possible d’observer un exemple avec la fiche annuaire correspondant à Hélène Débax (membre du laboratoire Framespa) en suivant ce lien.

Les informations suivantes sont nécessaires :

structId: Identifiant HAL du laboratoire de la personne
- peut être une liste d’identifiants HAL
- peut être laissé vide s’il n’est pas connu
norm: nom de la norme bibliographique dans laquelle les notices doivent être présentées
- choix entre APA, MLA, EHESS
- possibilité de laisser vide pour la citation de HAL par défaut
idHal: Identifiant HAL de la personne
researcherName: nom complet de la personne
- utilisé si aucun identifiant HAL n’est renseigné
portal: si un portail HAL est à renseigner pour la recherche
- peut-être laissé vide
adminLink: lien du site d’administration SpirHAL pour la personne, s’il est déployé

HTML pour instancier SpirHAL pour une personne avec son idHAL

<html>
   <head>
      <meta charset="UTF-8" />
      <script type="text/javascript" src="bundle.js"></script>
   </head>
   <body>
         <spirhal-app idhal="20468" portal="univ-tlse2" struct-id="620" norm="EHESS"></spirhal-app>
   </body>
</html>

HTML pour instancier SpirHAL pour une personne avec son nom

<html>
   <head>
      <meta charset="UTF-8" />
      <script type="text/javascript" src="bundle.js"></script>
   </head>
   <body>
         <spirhal-app researcher-name="Hélène Débax" struct-id="620" norm="EHESS"></spirhal-app>
   </body>
</html>

Affichage pour une structure¶

Ce mode permet l’affichage des notices des publications pour une structure, identifiées par un structId dans HAL. Par exemple, FRAMESPA a le structId 620 dans HAL: https://hal.archives-ouvertes.fr/search/index/q/*/structId_i/620/ Les informations suivantes sont nécessaires :

structId: Identifiant HAL de la structure
norm: nom de la norme bibliographique dans laquelle les notices doivent être présentées
- choix entre APA, MLA, EHESS
- possibilité de ne pas le renseigner pour la citation de HAL par défaut
limit: nombre de notices maximales à récupérer par type de notice
portal: si un portail HAL est à renseigner pour la recherche des notices
- peut-être laissé vide
adminLink: lien du site d’administration SpirHAL, s’il est déployé

HTML pour instancier SpirHAL pour une structure avec son nom

<html>
   <head>
      <meta charset="UTF-8" />
      <script type="text/javascript" src="bundle.js"></script>
   </head>
   <body>
      <spirhal-app-structure struct-id="620" norm="APA" limit="20"></spirhal-app-structure>
   </body>
</html>

À propos¶

le code source de SpirHAL est disponible ici.

Ce projet est développé avec la technologie React, et est disponible sous forme de Web component, ce qui permet un déploiement facile et rapide sur tout site web. L’utilisation de cette technologie permet aussi la compatibilité avec la plupart des navigateurs.

Licence Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License