NS vertrektijden app

Inleiding

Als je nog niet met de Eigen Apps hebt gewerkt, adviseren we je om eerst de pagina's over deze functionaliteit door te lezen:

• Eigen Apps Maken
• Eigen Apps Gebruiken
• Transformatielogica Gids

Dat maakt het makkelijker om het hier beschreven voorbeeld te begrijpen.

Achtergrond

In dit voorbeeld maken we een app die een tabel toont met de vertrektijden van NS treinen vanaf een bepaald station. De gebruiker van de app kan kiezen uit een lijst van relevante stations en kiezen hoeveel treinen in de tabel getoond worden.

De NS verstrekt de vertrektijden die in de app gebruikt zullen worden via een Application Program Interface (API). Het gebruik van deze API is gratis, maar de NS verlangt wel dat je een gebruikersaccount aanmaakt om toegang te krijgen tot deze API.

Aanmaken van een NS API account

Om een gebruikersaccount aan te maken voor de NS API kun je naar deze pagina gaan.

Doel van de app

Het doel van deze app is het tonen van vertrektijden van NS-treinen van een specifiek station. Je kunt apps als deze maken in het Eigen apps gedeelte van de Instellingen pagina. Je kunt bij het maken van de app vrij kiezen welke informatie die de NS verstrekt je wilt tonen en hoe je deze informatie wilt vertonen.

Het ophalen en verversen van de gegevens wordt automatisch door Playr gedaan. Jij moet zelf bepalen en beschrijven welke informatie je wilt gebruiken en hoe je deze wilt tonen. Dit doe je voor een deel met de eigenschappen die de Eigen app je biedt en deels in JavaScript code.

In dit voorbeeld is een app uitgewerkt die informatie over vertrektijden toont in een tabel. Dit voorbeeld is met kleine aanpassingen direct te gebruiken. Je kunt er hopelijk ook veel inspiratie uit halen om ook andere apps te zelf te maken die andere informatie van het internet ophalen en op jouw schermen tonen.

Creëren van de NS app

Hier volgt stap voor stap hoe je, met minimale aanpassingen, een eigen app kunt maken die vertrektijden van treinen op voor jou relevante stations zal tonen.

Instellingen

Maak in de sectie Eigen apps een nieuwe app aan en noem die b.v. "NS Vertrektijden". We maken gebruik van de Reisinformatie API. Configureer de eigenschappen van de app als volgt:

We maken voor deze app gebruik van twee Geavanceerde opties. Deze opties zijn nodig om toegang te krijgen tot de NS servers die de informatie over de vertrektijden verstrekken.

We maken voor deze app gebruik van twee App-specifieke eigenschappen. Dat zijn velden die bij het gebruik van de app op een pagina ingesteld kunnen worden om zo de App een specifieke uiterlijk en toepassing te geven. Om de App-specifieke eigenschappen te kunnen instellen klik je op Tonen en dan op de App-specifieke eigenschap toevoegen knop. Voor de precieze betenenis van de inhoud van de Selecteerbare opties, Standaard en Test kolommen zie de Transformatielogica Gids

De transformatielogica

De onderstaande JavaScript code voert de transformatie van de gegevens, die terugkomen van de servers van de NS, naar een tabel, die op een TV scherm getoond kan worden, uit. Het commentaar in de code licht de transformatie stap voor stap toe.

// Een article is nodig om alle tekst die die getoond gaat wordem in onder te brengen
var uitvoer = app.createArticle();

if (app.input && app.input.payload && app.input.payload.departures) {
  var treinen = app.input.payload.departures;

  // Maak een tabel met kopregel
  var kopregel = ["Vertrektijd", "Spoor", "Bestemming", "Trein", "Via"];
  var tabel = app.createTable([2,1,2,2,2], app.format.alignCenter(kopregel));
  // Maak de lijnen van de tabel 2 pixels breed , NS blauw en zorg dat de tekst niet tegen de lijnen komt
  var nsBlauw = "#00387b";
  tabel.borderColor(nsBlauw).borderWidth(1).padding(1);

  // Bepaal het aantal regels dat getoond gaat worden
  var aantalRegels = Math.min(app.props.aantalRegels, treinen.length);

  // Vul de regels van de tabel
  for (var i = 0; i < aantalRegels; i++) {
    var trein = treinen[i];
    var geplandeVertrekTijd = moment(trein.plannedDateTime);
    var actueleVertrekTijd = moment(trein.actualDateTime);
    // We leiden de vertraging af uit het verschil tussen de actuele vertrektijd
    // en de geplande vertrektijd (in minuten)
    var vertraging = actueleVertrekTijd.diff(geplandeVertrekTijd, "minutes");
    var vertragingTekst = vertraging <= 0 ? "" : " +" + vertraging;
    var treinSoort = trein.product ? trein.product.longCategoryName : "";
    var route = [];
    for (var r = 0; r < trein.routeStations.length; r++) {
      route.push(trein.routeStations[r].mediumName);
    }

    tabel.addRow([
      // We plakken de geplande vertrektijd en eventuele vertragingsaanduiding
      // aan elkaar, waarbij de vertraging in rood wordt weergegeven. 
      // We doen dit in een block om ervoor te zorgen dat ze op één regel komen te staan.
      app.createBlock(
        app.format.bold(geplandeVertrekTijd.format('LT')) +
        app.format.textColor(vertragingTekst, "red")
      ).alignContentCenter(),
      app.format.alignCenter(trein.plannedTrack),
      trein.direction,
      treinSoort,
      app.format.relativeTextSize(route.join(", "), 0.8)
    ]);
  }
  // Voeg de tabel toe aan de uitvoer
  uitvoer.add(tabel);
} else {
  // De request is niet goed gegaan, toon de fout
  uitvoer.add("Geen actuele reisinformatie beschikbaar");
}

// Als laatste stap voegen we de uitvoer toe aan de output van de app
app.output.addArticle(uitvoer);

Vormgeving

Het is niet mogelijk een achtergrondkleur in te stellen voor een Eigen app. Het is voor deze app wel toepasselijk om de achtergrond op de pagina in te stellen op NS geel: #f7d417, je kunt deze kleur instellen als Voorbeeld achtergrondkleur om een zo goed mogelijk beeld te krijgen van he één en ander er uit komt te zien op de pagina.

Voorbeeld

Klik nu op het verversicoontje naast het webadres om de vertrektijdentabel weer te geven. Als alles goed is gegaan zou deze nu zo moeten uitzien:

Sla de nieuwe app op met Opslaan & terug en activeer de app door het schuifje in de lijst op groen te zetten:

Gebruik van de app

Ga nu terug naar je dashboard en open een pagina in de paginaontwerper. Links zie je nu een Eigen apps sectie met de nieuwe vertrektijden-app. Als je deze op de pagina sleept zie je dat je het station en het aantal regels kunt selecteren. Klik op het verversicoontje om te zien dat de lijst met vertrektijden gevuld wordt.