Jimmy Aumard
Trails logo

Créer un Trailpack pour Trails

Salut les gens ! Ici vous allez apprendre à créer un module Trailpack pour Trails, nous verrons ensemble la structure d’un projet ainsi que comment exécuter et tester notre module avant de le publier sur npm. J’espère que vous êtes prêts pour ça !

NOTE: Pour ce tutoriel je suppose que vous avez déjà installé Node.js 4.0.0 (ou plus), et que vous avez déjà un projet Trails créé (voir Bien demarrer avec trails).

Qu’est-ce qu’un Trailpack ?

Si vous avez suivi mon premier tutoriel attentivement, alors vous le savez déjà ! Mais bon pour les mauvais élèves un Trailpack est simplement un module qui étend les posibilités de Trails. Cela peut être un serveur web comme express4, un exécuteur de tâches comme grunt ou gulp…

Installation

Un Trailpack peut être généré avec yeoman. Si vous ne l’avez pas encore installé, faites-le maintenant :

npm install -g yo

Nous avons aussi besoin du générateur de Trailpack :

npm install -g generator-trailpack

Vous êtes maintenant prêts pour votre premier Trailpack ! 🙂

Créer un projet

Toujours aussi simple, suivez le guide :

mkdir myTrailpack;
cd myTrailpack;
yo trailpack;

Les étapes sont simplement les informations requises par le package.json de votre projet, dans l’ordre :

. Le nom du projet, par défaut c’est le nom du projet, ici on laisse myTrailpack
. Description du projet
. URL des sources du projet
. Nom de l’auteur, vous donc 🙂
. E-mail de l’auteur
. Page perso de l’auteur
. Mot clé correspondant à votre projet, séparé par des virgules
. Votre nom/organisation github
. Votre site web
. Licence du projet

Après avoir renseigné tout ça, le générateur va créer la structure de votre projet et installer les dépendances (npm install).
Projet créé

Structure du projet

Vous devriez avoir quelque chose comme :
Structure du projet

API

Tout comme Trails vous pouvez utiliser le générateur yeoman pour générer vos fichiers :

yo trailpack:api apiName;
yo trailpack:model modelName;
yo trailpack:controller controllerName;
yo trailpack:policy policyName;
yo trailpack:service serviceName;

ATTENTION: si vous n’utilisez pas yo pour générer vos API alors n’oublié pas de les ajouter dans index.js de chaque partie models/index.js, controllers/index.js… En effet Trails charge ces fichiers comme cela, du coup si votre fichier n’est pas dans un index.js il sera ignoré.

Configuration

Vous pouvez créer vos propres fichiers de configuration dans ce dossier, il y a déjà un fichier trailpack.js, ce fichier vous permet de dire à Trails les API et configurations que vous voulez rendre accessibles dans le projet Trails (dans le champ provides). Mais ce fichier vous permet aussi de configurer le cycle de vie de votre Trailpack, si celui-ci a besoin d’attendre l’initialisation de l’orm ou fournit lui-même un événement utile pour d’autres Trailpack, vous le renseignez ici. Le fichier ressemble à ceci :

/**
 * Trailpack Configuration
 *
 * @see {@link http://trailsjs.io/doc/trailpack/config
 */
module.exports = {

  /**
   * API and config resources provided by this Trailpack.
   */
  provides: {
    api: {
      controllers: [ ]
      // ...
    },
    config: [ ]
  },

  /**
   * Configure the lifecycle of this pack; that is, how it boots up, and which
   * order it loads relative to other trailpacks.
   */
  lifecycle: {
    configure: {
      /**
       * List of events that must be fired before the configure lifecycle
       * method is invoked on this Trailpack
       */
      listen: [ ],

      /**
       * List of events emitted by the configure lifecycle method
       */
      emit: [ ]
    },
    initialize: {
      listen: [ ],
      emit: [ ]
    }
  }
}

Maintenant voyons comment notre Trailpack peut interagir avec un serveur Trails.

La classe Trailpack

Elle est la pièce maitresse de votre projet et se situe dans le fichier index.js. Elle permet à votre Trailpack d’interagir avec un serveur Trails. Le fichier généré ressemble à ceci :

const Trailpack = require('trailpack')

module.exports = class Archetype extends Trailpack {

  /**
   * TODO document method
   */
  validate () {

  }

  /**
   * TODO document method
   */
  configure () {

  }

  /**
   * TODO document method
   */
  initialize () {

  }

  constructor (app) {
    super(app, {
      config: require('./config'),
      api: require('./api'),
      pkg: require('./package')
    })
  }
}

ATTENTION : si vous voulez créer un Trailpack qui offre une compatibilité avec un serveur web ou un ORM, vous devez alors utiliser trailpack-webserver / trailpack-datastore au lieu de trailpack et implémenter les méthodes utiles. Pour plus d’informations sur ces Trailpacks : trailpack-webserver and trailpack-datastore

Première chose à faire est de renommer votre classe Archetype par celui de votre Trailspack (ici MyTrailpack). Vous pouvez voir qu’il y a trois méthodes :

  • validate
  • configure
  • initialize

Voyons en détails ces méthodes.

La fonction validate

Cette fonction est la première à être appelée, vous pouvez y vérifier la configuration de votre Trailpack (si celui-ci en a besoin), par exemple le Trailpack d’hapi vérifie la configuration du serveur web dans config/web.js ainsi qu’il n’y ait pas d’autre serveur web d’installé. Dans ce tutoriel nous allons rester simples et juste mettre une log.

validate () {
    this.app.config.log.logger.info('My Trailpack is valid')
    return Promise.resolve()
}

A la fin de la méthode nous appelons Promise.resolve() afin de dire à Trails que notre Trailpack est valide, et au contraire si la configuration n’est pas bonne nous appellerons Promise.reject().

La fonction configure

Les fichiers de configuration étant corrects, la méthode configure est ensuite appelée, cette méthode est appelée après les événements dont votre Trailpack est en attente (que vous avez configuré dans config/trailpack.js). Vous pouvez donc configurer votre Trailpack, toujours par rapport à Hapi, celui-ci créé le serveur web, configure les url et map les contrôleurs et policies

configure () {
    this.app.log.info('My Trailpack is configured')
    return Promise.resolve()
}

A la fin de la méthode nous appelons Promise.resolve() afin de dire à Trails que notre Trailpack est configuré, et au contraire si la configuration n’est pas bonne nous appellerons Promise.reject().

La fonction initialize

C’est la dernière méthode à être appelée, ici vous pouvez faire ce pour quoi votre Trailpack est prévu ^^, Hapi démarre le serveur web sur le host et le port configuré dans la méthode configure par exemple.

initialize () {
    this.app.log.info('My Trailpack is initialized')
    return Promise.resolve()
}

A la fin de la méthode nous appelons Promise.resolve() afin de dire à Trails que notre Trailpack est initialisé, et au contraire si la configuration n’est pas bonne nous appellerons Promise.reject().

C’est bien beau tout ça mais maintenant qu’on sait comment interagir avec un serveur Trails, comment on exécute et test notre Trailpack ?

Exécuter et tester

Pour réaliser cela nous avons besoin d’un projet Trails et de quelques lignes de commande npm 🙂

Tout d’abord il faut installer localement et globalement notre Trailpack avec cette commande :

cd myTrailpack;
npm link;

Ensuite il faut aller dans le projet Trails et installer notre Trailpack :

cd myTrails;
npm link myTrailpack;

Maintenant il ne reste qu’à configurer Trails pour qu’il charge notre Trailpack, pour cela il faut éditer config/main.js de Trails et ajouter notre Trailpack dans packs comme ceci :

/**
 * Trailpack Configuration
 * (app.config.main)
 *
 * @see http://trailsjs.io/doc/config/main
 */
module.exports = {

  /**
   * Order does *not* matter. Each module is loaded according to its own
   * requirements.
   */
  packs: [
    require('trailpack-core'),
    require('trailpack-repl'),
    require('trailpack-router'),
    require('trailpack-hapi'),
    require('myTrailpack')
  ]
}

Il suffit de démarrer votre serveur avec npm start et vous verrez les logs de votre Trailpack :

Trailpack logs

Et voilà ! Vous avez maintenant les connaissances pour créer de nouveaux Trailpack de la mort qui tue ! Mais attention ne perdez pas trop de temps pour rien et regardez d’abord sur npm s’il n’existe déjà pas un Trailpack pour ce que vous voulez faire 😉

A plus tard pour de nouvelles aventures !

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *