Écrire ou contribuer à la nomenclature

Pré requis : Installer Aptana

  1. Avoir un compte Github
  2. Télécharger Aptana (ou votre IDE préféré)
  3. Cloner le dépôt de code Ekylibre
  4. Ouvrir le code dans Aptana
Types d'objets Objets SQL Exemples d'identifiant Exemple d'objet
Nomenclature Table varieties <#Nomenclature @name='varieties'>
Property Column varieties.itis_tsn <#Property @nomenclature='varieties' @name='itis_tsn'>
Item Record varieties#bos_taurus_primigenius <#Item @nomenclature='varieties' @name='bos_taurus_primigenius' @itis_tsn='45646'>

Exemple de visualisation de la nomenclature varieties :

name itis_tsn
bos_taurus_primigenius 45646
bos_taurus_taurus 45647

Processus

Cette procédure intervient en générale :

  • À la demande d'un client, par exemple lorsqu'il possède une espèce ou une variété qui n'existe pas encore dans Ekylibre

Principe général

Les nomenclatures sont une base de données où chaque nomenclature peut être assimilée à une table (au sens SQL du terme), il est possible d'y ajouter des propriétés (ou colonnes) et des lignes. L'identifiant de chaque ligne est un nom unique (au lieu d'un chiffre entier).

Pour tracer les évolutions de la nomenclature et pouvoir ainsi les répercuter de manière fiable dans les outils exploitant ces données, il faut enregistrer chaque changement dans ce que l'on appelle des migrations (se trouvant dans db/nomenclatures/migrate). Une migration permet de changer tout ou partie des nomenclatures. Les migrations sont ordonnées dans le temps et peuvent en effet reposer les unes sur les autres chronologiquement parlant.

Avec ces fichiers de migrations qui créent les nomenclatures (structures et données), il est possible de produire en sortie une base de données finale (db/nomenclatures/db.xml).

Créer une migration

Pour écrire, une migration, il faut commencer par générer un fichier de migration

$ rails g nomenclature_migration add_pharaon_wheat
      create  db/nomenclatures/migrate/20150817221116_add_pharaon_wheat.xml

Cela va produire un fichier vide prêt à l'emploi :

db/nomenclatures/migrate/20150817221116_add_pharaon_wheat.xml
<?xml version="1.0" encoding="utf-8"?>
<migration name="Add pharaon wheat">
  <!-- Add your changes here -->
</migration>

Les migrations sont écrite en XML pour plus d’interopérabilité et de réusabilité.

Écrire une migration

Un certain nombre de balise permet de modifier la base de nomenclatures.

Exemple

<?xml version="1.0"?>
<migration name="Fix hordeum">
  <!-- Permet de créer une nomenclature -->
  <nomenclature-creation nomenclature="abilities"/>
  <!-- Permet de modifier une nomenclature -->
  <nomenclature-change nomenclature="abilities" translateable="false"/>
  <!-- Permet de supprimer une nomenclature -->
  <nomenclature-removal nomenclature="ununsed_abilities"/>  
  <!-- Permet de créer une propriété (colonne) dans la nomenclature -->  
  <property-creation property="abilities.parameters" type="choice_list" choices="variety, issue_nature"/>
  <!-- Permet de changer le nom, le parent et les propriétés de l'élément -->
  <item-change item="varieties#hordeum_hibernum" name="hordeum_hexastichum" parent="hordeum_vulgare"/>
  <!-- Permet de fusionner l'élément à l'intérieur d'un autre (into) -->
  <item-merging item="varieties#hordeum_vulgare_hexastichum" into="hordeum_hexastichum"/>
  <!-- Permet de créer un nouvel élément -->
  <item-creation item="varieties#hordeum_hexastichum_abondance"      parent="hordeum_hexastichum"/>
</migration>

Notations

Il y a 3 types d'objets dans la base :

  • Nomenclature : notée par son nom directement. Exemple : abilities
  • Propriété : notée par son nom préfixé de la nomenclature et d'un .. Exemple : abilities.parameters
  • Élément : noté par son nom préfixé de la nomenclature et d'un #. Exemple : abilities#kill

Balises

Les attributs comportant une étoile (*) sont obligatoires.

<nomenclature-creation>
  • nomenclature* : Nom de la nomenclature
  • notions : Notions associées
<nomenclature-change>
  • nomenclature* : Nom de la nomenclature
  • name : Nouveau nom
  • notions : Nouvelles notions associées
<nomenclature-removal>
  • nomenclature* : Nom de la nomenclature
<property-creation>
  • property* : Identifiant de la propriété
  • type : string, decimal, item, choice, item_list, choice_list, date
  • required : Obligatoire (true ou false)
  • choices : Liste utilisée par les types choice ou choice_list
  • fallbacks : Fallback de valeur entre propriétés
  • default : Valeur par défaut si non renseigné
<property-change>
  • property* : Identifiant de la propriété
  • name : Nouveau nom
  • tous les autres attributs de la création
<item-creation>
  • item* : Identifiant de l'élément
  • parent : Élément parent (hiérarchie)
  • propriété : Les autres attributs peuvent porter le nom des propriétés définis dans la nomenclature
<item-change>
  • item* : Identifiant de l'élément
  • name : Nouveau nom
  • tous les autres attributs de la création

Exécuter une migration

Exécuter la ou les migrations met à jour la base de données “Nomenclatures”, les traductions et génère les migrations pour le logiciel.

rake nomen:migrate

En général, ensuite il faut exécuter la migration logicielle :

rake db:migrate

Et quoiqu'il arrive, il faut “nettoyer” le code :

rake clean

Ajouter les traductions

La commande rake clean pré-renseigne les fichiers de traductions. Il faut trauire d'abord dans la langue de référence (l'anglais (eng)) puis refaire un rake clean.

Les traductions des nomenclatures se trouvent dans config/locales/*/nomenclatures.yml. Les nouvelles traduction seront précédées de “# ”.

Ajouter une image

Si une nouvelle espèce a été ajoutée, il faut également ajouter l'image associée à la production.

1) Pour trouver une image libre et gratuite : pixabay.com

2) Enregistrer l'image, la recadrer puis la redimensionner pour obtenir un carré de 300×300 pixels.

Sur Gimp :

  • Dessiner une sélection carrée
  • Ctrl+c puis Ctrl+shift+v
  • Clique droit sur l'image –> Échelle et taille de l'image

3) Ajouter l'image dans Ekylibre

  • Fichier –> Exporter
  • Enregistrer l'image au format jpeg dans ekylibre/app/assets/images/varieties et la nommer par le nom latin identique à celui de la nomenclature