Jimmy Aumard
Trails Logo

Bien démarrer avec Trails

Salut tout le monde ! Voici mon premier tutoriel, alors soyez indulgents s’il vous plaît :).
Vous allez apprendre à créer un projet Trails, comprendre la structure d’un projet Trails et quelques informations de base à ce sujet. N’hésiter pas à commenter si j’ai oublié quelque chose ou si je ne suis pas assez clair.

NOTE: Pour ce tutoriel je suppose que vous avez déjà installé Node.js 4.0.0 (ou plus), des connaissances sur le MVC et Javascript seront un plus.

Trails qu’est-ce c’est ?

Trails est un nouveau framework MVC pour Node.js, écrit en ES2015 (ES6). C’est un framework modulaire qui s’adapte à vos framework de développement de tous les jours. Trails est une sorte de colle qui lie vos framework en un seul et les font travailler ensemble.

Installation

Trails utilise yeoman pour générer un projet basique. Si vous ne l’avez pas déjà installé, faite-le comme ceci :

npm install -g yo

Et maintenant il faut installer le générateur yeoman de Trails :

npm install -g generator-trails

Et maintenant vous êtes prêts pour votre première application ! 🙂

Créer un project

C’est très simple, suivez le guide 😉 :

mkdir tutoTrails;
cd tutoTrails;
yo trails;

Vous devriez voir quelque chose comme ça :
.Web server choice

La première est le choix du serveur web, par défaut Trails utilise Hapi mais est compatible avec express4, koa et bien plus.
Le choix de ce web serveur influera sur l’écriture de vos policies et controllers, mais nous verrons cela plus tard.

Les autres é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 tutoTrails
. 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 a votre projet, séparé par des virgules
. Votre nom/organisation github
. Votre site web
. Licence du projet

Après tout cela le générateur créera la structure de votre projet Trails et installera les dépendances (npm install).
.Project generated

Lancer le project

Le générateur vous donne déjà la réponse à la fin de la génératon, il suffit de faire :

npm start

Votre serveur tourne maintenant sur le port 3000, vous devriez ceci voir dans votre console :
.Start log

Et si vous ouvrez l’URL http://localhost:3000 vous devriez voir :
.Hello Trails.js !

Pour stopper le serveur il faut faire deux fois ctrl+c.

Structure du projet

C’est cool votre serveur tourne 🙂 Maintenant il faut découvrir comment il fonctionne. La structure de votre projet ressemble à ceci :

.Project structure

API

Comme je l’ai dit plus haut, Trails est un framework MVC. MVC, pour « Modèle, Vue, Contrôleur », c’est le nom donné à une manière d’organiser son code. C’est une façon d’appliquer le principe de séparation des responsabilités, en l’occurrence celles du traitement de l’information et de sa mise en forme.

  • Modèle : il représente un objet contenant la donnée métier. Il peut parfois avoir des fonctionnalités supplémentaires afin d’avertir le contrôleur que les données ont changé.
  • Vue : elle représente la visualisation de la donnée contenue dans le modèle.
  • Contrôleur : il agit avec le modèle et la vue. Il contrôle le flux de données du modèle et le met à jour lorsque celui-ci change dans la vue. La vue et le modèle ne dialoguent pas entre eux.

Ici dans Trails la structure est banale, il y a un dossier api qui contient vos controllers, models, policies et services.

Comme vous l’avez remarqué, le modèle MVC a été un peu altéré pour ajouter 2 nouvelles couches, les policies qui s’éxécute avant les contrôleurs et les services qui rendent les contrôleurs plus lisibles en contenant le code métier.

Regardons un peu plus en détails les fichiers générés par défaut.

Modèles

L’écriture des modèles dépendra du choix de votre ORM, par défaut Trails utilise Waterline, nos modèles doivent donc être définis comme ceci (http://waterline.js.org/docs/models/models.html) :

'use strict'

const Model = require('trails-model')

/**
 * User
 *
 * @description A User model
 */
module.exports = class User extends Model {
  static schema() {
    return {
      username: 'string'
    }
  }
}

Waterline s’occupera de créer la base de donnée ainsi que les tables.

Vous pouvez utiliser le générateur pour créer de nouveaux modèles avec cette commande :
yo trails:model myModelName

ATTENTION: si vous n’utilisez pas la commande, n’oubliez pas d’ajouter votre modèle dans api/models/index.js.

Controlleurs

Si vous vous souvenez bien, nous avons choisi Hapi comme serveur web, il faut donc maintenant que nos contrôleurs soit écrits comme Hapi l’attend.
Regardons cela de plus près dans ViewController.js :

'use strict'

/**
 * @module ViewController
 *
 * @description Default Controller included with a new Trails app
 * @see {@link http://trailsjs.io/doc/api/controllers}
 * @this TrailsApp
 */
module.exports = class ViewController {

  /**
   * 
   */
  helloWorld (request, reply) {
    reply('Hello Trails.js !')
  }
}

Plutôt simple 🙂 Une fonction avec un objet requête et réponse, pour plus d’informations vous pouvez regarder la documentation de Hapi (http://hapijs.com/api).

Cette fonction est celle qui est appelée lorsque vous ouvrez http://localhost:3000 dans votre navigateur. Mais comment est mapper l’url / avec cette méthode ? Nous allons voir ça dans la section Config.

Vous pouvez créer de nouveaux contrôleurs avec cette commande :
yo trails:controller myControllerName

ATTENTION: si vous n’utilisez pas la commande, n’oubliez pas d’ajouter votre modèle dans api/controllers/index.js.

Services

Les services sont le cerveau de votre projet, il contiennent tout votre code métier. Leur définition ressemble à ceci (DefaultService.js) :

'use strict'


const _ = require('lodash')
const Service = require('trails-service')

/**
 * @module DefaultService
 *
 * @description Default Service included with a new Trails app
 * @see {@link http://trailsjs.io/doc/api/services}
 * @this TrailsApp
 */
module.exports = class DefaultService extends Service {

  /**
   * Return some info about this application
   */
  getApplicationInfo() {
    return {
      app: this.pkg.version,
      node: process.version,
      libs: process.versions,
      trailpacks: _.map(_.omit(this.packs, 'inspect'), pack => {
        return {
          name: pack.name,
          version: pack.pkg.version
        }
      })
    }
  }
}

And the service can be called from controller like this : this.api.services.DefaultService.getApplicationInfo() (see DefaultController.js)

Vous pouvez créer de nouveaux services avec cette commande :
yo trails:service myServiceName

ATTENTION: si vous n’utilisez pas la commande, n’oubliez pas d’ajouter votre modèle dans api/services/index.js.

Policies

Les policies sont, comme leur nom l’indique, présents pour faire la police 🙂 Ils s’exécutent avant les contrôleurs afin de vérifier certaines régles dont vous avez besoin (vérification de session utilisateur, vérification de droits acl, vérification des données).

Comme pour les contrôleurs les policies doivent être écrits pour Hapi :

'use strict'

/**
 * @module Default
 * @description Test document Policy
 */
module.exports = class Default {
  info(request, reply) {
    reply()
  }
}

Mais comment mapper cette fonction avec mon contrôleur ? Nous verrons ça dans la section Config.

Vous pouvez créer une nouvelle policie avec la commande :
yo trails:policy myPolicyName

ATTENTION: si vous n’utilisez pas la commande, n’oubliez pas d’ajouter votre modèle dans api/policies/index.js.

Config

Le dossier config contient toute la configuration de votre projet, découpé en petits fichiers, chacun servant à configurer une partie du serveur. Par exemple vous pouvez changer le port du serveur web dans config/web.js ou le template engine dans config/views.js.

  • env : ici vous pouvez mettre les fichiers de configuration par environnement (production, test…), ces fichiers écraserons la configuration de base.
  • database : Informations de votre base de donnée, type, stratégie de migration, host, port…
  • footprints : Options pour votre API REST, ajouter un prefix, activer/désactiver certains footprint
  • i18n : Configuration du support multi langue, paramétrer le langage par défaut et charger vos traductions
  • locales : Dossier pour vos fichiers de langue (au format json)
  • log : Options du logger pour votre projet, par défaut Winston est utilisé
  • main : Vous permet de choisir les trailpacks* à charger au lancement du projet (ici Hapi par exemple pour le serveur web)
  • policies : Vous permet de mapper vos policies avec vos contrôleurs
  • routes : Vous permet de mapper vos ccontrôleurs avec les url que vous souhaitez
  • session : Options pour gérer vos sessions, stratégies, cookie, web token…
  • views : Vous permet de configurer votre template engine (jade, ejs, mustache…)
  • web : Options pour le serveur web, comme le port d’écoute
  • webpack : Configuration pour construire vos ressources (assets), il faut fournir une configuration qui correspond a webpack, je vous laisse regarder la documentation de celui ci (http://webpack.github.io/docs/configuration.html)

NOTE: trailpacks*, tous les modules utilisé par Trails sont appelé Trailpack. Par exemple pour utiliser Hapi comme serveur web, Trails utilise le Trailpack nommé trailpack-hapi. N’hésitez pas à regarder sur npm pour trouver des Trailpack interessant.

ATTENTION: si vous ajouté un fichier de configuration, n’oubliez pas d’ajouter votre modèle dans config/index.js.

Maintenant vous avez de quoi faire un projet Trails simple par vous même. Au boulot ! 🙂

Plus ?

Avez vous remarqué que lorsque vous lancez votre projet vous aviez trails> ?

Essayez de taper app, app.api.controllers, app.api.services ou même get('/api/v1/default/info'). Cool hein ?

A plus tard pour un prochain tutoriel 😉 un peu plus compliqué cette fois ^^

Laisser un commentaire

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