Creare un pacchetto con Meteorite

Approfondimento 9.5

Percentuale Tradotta

In questo capitolo imparerai:

  • Creare un pacchetto per l'appilcazione.
  • Scrivere dei test per il pacchetto.
  • Rilasciare il pacchetto su Atmosphere.
  • Dopo che abbiamo creato uno schema riutilizzabile per la gestione dei nostri errori, possiamo creare un pacchetto e condividerlo con gli altri sviluppatori della comunità di Meteor.

    Come prima cosa dobbiamo preparare la struttura del pacchetto. Lo inseriamo in una cartella chiamate packages/errors/, in questo modo si crea un pacchetto personalizzato che l'applicazione utilizzerà automaticamente. (È possibile che abbiate notato che Meteorite installa i pacchetto tramite symlinks nella cartella packages/).

    In seguito, creiamo il file package.js, nel quale viene detto a Meteor come deve utilizzare il pacchetto e quali simboli vengono esportati, cioè quali oggetti vengono resi disponibili all'applicazione.

    Package.describe({
      summary: "A pattern to display application errors to the user"
    });
    
    Package.on_use(function (api, where) {
      api.use(['minimongo', 'mongo-livedata', 'templating'], 'client');
    
      api.add_files(['errors.js', 'errors_list.html', 'errors_list.js'], 'client');
    
      if (api.export)
        api.export('Errors');
    });
    
    packages/errors/package.js

    Aggiungiamo tre file al pacchetto, prendendoli direttamente da Microscope e aggiungendo solo un namespace appropriato e un API leggeremente più chiara:

    Errors = {
      // Local (client-only) collection
      collection: new Meteor.Collection(null),
    
      throw: function(message) {
        Errors.collection.insert({message: message, seen: false})
      },
      clearSeen: function() {
        Errors.collection.remove({seen: true});
      }
    };
    
    
    packages/errors/errors.js
    <template name="meteorErrors">
      {{#each errors}}
        {{> meteorError}}
      {{/each}}
    </template>
    
    <template name="meteorError">
      <div class="alert alert-error">
        <button type="button" class="close" data-dismiss="alert">&times;</button>
        {{message}}
      </div>
    </template>
    
    packages/errors/errors_list.html
    Template.meteorErrors.helpers({
      errors: function() {
        return Errors.collection.find();
      }
    });
    
    Template.meteorError.rendered = function() {
      var error = this.data;
      Meteor.defer(function() {
        Errors.collection.update(error._id, {$set: {seen: true}});
      });
    };
    
    packages/errors/errors_list.js

    Testing the package out with Microscope

    Ora testeremo le modifiche localmente per assicurarci che tutto funzioni. Per aggiungere il pacchetto all'applicazione, eseguiamo nel terminale meteor add errors ed eliminiamo i file esistenti che ora sono superflui:

    $ rm client/helpers/errors.js
    $ rm client/views/includes/errors.html
    $ rm client/views/includes/errors.js
    
    removing old files on the bash console

    Dobbiamo fare qualche piccola modifica per utilizzare correttamente l'API:

    Router.onBeforeAction(function() { Errors.clearSeen(); });
    
    lib/router.js
      {{> header}}
      {{> meteorErrors}}
    
    client/views/application/layout.html
    Meteor.call('post', post, function(error, id) {
      if (error) {
        // display the error to the user
        Errors.throw(error.reason);
    
    
    client/views/posts/post_submit.js
    Posts.update(currentPostId, {$set: postProperties}, function(error) {
      if (error) {
        // display the error to the user
        Errors.throw(error.reason);
    
    client/views/posts/post_edit.js

    Commit 9-5-1

    Created basic errors package and linked it in.

    Una volta terminate queste modifiche, la situazione dovrebbe essere tornata a com'era prima della creazione del pacchetto.

    Come scrivere dei test

    Il primo passo nello sviluppo di un pacchetto è quello di testarlo in un'applicazione, ma quello successivo è di scrivere una serie di test per verificarne il corretto funzionamento. Meteor fornisce Tinytest, un sistema di test integrato, che semplifica l'esecuzione di questi test e ci aiuta a stare tranquillo al momento di condividere il nostro pacchetto con altri sviluppatori.

    Creiamo ora un file nel quale, utilizzando Tinytest, faremo dei test sul codice creato per gestire gli errori:

    Tinytest.add("Errors collection works", function(test) {
      test.equal(Errors.collection.find({}).count(), 0);
    
      Errors.throw('A new error!');
      test.equal(Errors.collection.find({}).count(), 1);
    
      Errors.collection.remove({});
    });
    
    Tinytest.addAsync("Errors template works", function(test, done) {
      Errors.throw('A new error!');
      test.equal(Errors.collection.find({seen: false}).count(), 1);
    
      // render the template
      UI.insert(UI.render(Template.meteorErrors), document.body);
    
      // wait a few milliseconds
      Meteor.setTimeout(function() {
        test.equal(Errors.collection.find({seen: false}).count(), 0);
        test.equal(Errors.collection.find({}).count(), 1);
        Errors.clearSeen();
    
        test.equal(Errors.collection.find({seen: true}).count(), 0);
        done();
      }, 500);
    });
    
    packages/errors/errors_tests.js

    In questi test stiamo verificando le funzioni di base di Meteor.Errors e controllando che il codice renderizzato nel template funzioni ancora.

    Non ci dilungheremo nella spiegazione di come scrivere i test per i pacchetti di Meteor (dato che l'API non è ancora definitiva), ma speriamo che si capisca sufficientemente come funziona il codice precedente.

    Per dire a Meteor come eseguire i testi, aggiungiamo nel file package.js il seguente codice:

    Package.on_test(function(api) {
      api.use('errors', 'client');
      api.use(['tinytest', 'test-helpers'], 'client');
    
      api.add_files('errors_tests.js', 'client');
    });
    
    packages/errors/package.js

    Commit 9-5-2

    Added tests to the package.

    Possiamo poi eseguirli da terminale con:

    $ meteor test-packages errors
    
    Terminal
    Passing all tests
    Passing all tests

    Come rilasciare il pacchetto

    Rendiamo ora disponibile in nostro pacchetto al mondo intero attraverso Atmosphere.

    Come prima cosa, aggiungiamo un file smart.json per passare a Meteorite e Atmosphere i dettagli più importanti del pacchetto:

    {
      "name": "errors",
      "description": "A pattern to display application errors to the user",
      "homepage": "https://github.com/tmeasday/meteor-errors",
      "author": "Tom Coleman <tom@thesnail.org>",
      "version": "0.1.0",
      "git": "https://github.com/tmeasday/meteor-errors.git",
      "packages": {
      }
    }
    
    packages/errors/smart.json

    Commit 9-5-3

    Added a smart.json

    Inseriamo dei metadati per segnalare informazioni sul pacchetto, fra i quali una descrizione per spiegare a cosa è utile, l'indirizzo di dove è posizionata la repository Git e un numero di versione iniziale. Se il nostro pacchetto dipendesse da altri presenti su Atmosphere, possiamo creare una sezione "packages" per descrivere le dipendenze.

    Una volta sistemato tutto, il rilascio è molto semplice. Dobbiamo creare un repository Git, caricarlo su di un server Git remoto e mettere il link nel file smart.json.

    Per fare questi passaggi con GitHub bisogna creare un nuovo repository e seguire il procedimento standard per caricare il codice del pacchetto in quella repository. Infine utilizzare il comando mrt release per pubblicarlo:

    $ git init
    $ git add -A
    $ git commit -m "Created Errors Package"
    $ git remote add origin https://github.com/tmeasday/meteor-errors.git
    $ git push origin master
    $ mrt release .
    Done!
    
    Terminal (run from within `packages/errors`)

    Nota: i nomi dei pacchetti devono essere unici. Se avete seguito il procedimento parola per parola e utilizzato lo stesso nome per il pacchetto, verrà segnalato un conflitto e il rilascio non avrà successo. Tuttavia nel prossimo futuro i pacchetti Atmosphere saranno preceduti da quello dell'autore in modo che questo non si verifichi.

    Seconda Nota: dovrete crearvi un utente su http://atmosphere.meteor.com, perché all'esecuzione di mrt release . vi verranno richiesti username e password.

    Ora che abbiamo rilasciato il pacchetto, possiamo eliminarlo dal progetto e installarlo di nuovo usando Meteorite:

    $ rm -r packages/errors
    $ mrt add errors
    
    Terminal (run from the top level of the app)

    Commit 9-5-4

    Removed package from development tree.

    Meteorite ora dovrebbe scaricare il nostro pacchetto per la prima volta, ottimo lavoro!