Eigen apps maken

In de instellingensectie kies je in de rechterkolom Eigen apps om de lijst van eigen apps te openen die je gecreëerd hebt. Je kunt eigen apps toevoegen, bewerken en bestaande eigen apps verwijderen, voorop gesteld dat ze niet in gebruik zijn.

Hoe het werkt is dat je je eigen Javascript code schrijft om gegevens uit de online bron te transformeren naar één of meerdere "artikelen". Een "artikel" komt overeen met een nieuwsartikel en kan ofwel één voor één bij elke paginaverversing worden weergeveven of als een lichtkrant van meerdere opeenvolgende artikelen.

Basiseigenschappen

Je begint met het configureren van een aantal basiseigenschappen. Sommige hiervan vormen de kern van de app, hetgeen betekent dat ze niet kunnen worden aangepast door de eindgebruiker. Andere basiseigenschappen kunnen wel worden aangepast door de eindgebruiker en de waarden die je hier configureert zullen de standaard waarden zijn in de paginaontwerper.

Eigenschap Uitleg Kan worden aangepast door de eindgebruiker
Webadres van de gegevensbron Het webadres (URL) van de JSON of XML gegevensbron zoals deze beschikbaar is op het internet. Je kunt app-specifieke eigenschappen tussen dubbele accolades als variabelen in het adres gebruiken.
Als de server een XML structuur retourneert dan wordt deze geconverteerd naar een JSON structuur zodat deze data eenvoudig kan worden gebruikt in de transformatielogica.
Nee
Verversicoon (Her)laad de nieuwsbron en laat het volgende artikel zien of start de ticker. N.v.t.
Bron alleen toegankelijk binnen mijn netwerk (Alleen voor aanvraagmethod "GET") Geeft aan dat de gegevensbron zich binnen je eigen netwerk (intranet) bevindt en dat deze niet via het publieke internet kan worden benaderd. Als de afspeelapparaten op hetzelfde interne netwerk zitten moeten ze in staat zijn de gegevens via deze weg te bereiken. Het is belangrijk dat de bron-server de juiste CORS configuratie heeft. Je hebt één configuratie voor allowed origin http://*.playr.biz en één voor https://*.playr.biz nodig met:
  • Allowed method: GET, PUT en POST
  • Allowed header: *
Nee
Aanvraagmethod Kies hier de HTTP aanvraagmethod (request method). Dit zal in bijna alle gevallen GET zijn. Nee
Aanvraagtekst (Alleen voor aanvraagmethode "POST" of "PUT") Configureer welke datastructuur naar de server wordt verstuurd met de HTTP POST of HTTP PUT aanvraag. Nee
Stijl Zet de manier waarop je wilt dat je artikelen worden weergegeven:
  • Als een enkel bericht
  • Als een lichtkrant
  • Als een verticale lichtkrant
Specifieke individuele artikelstijlen kunnen door de eindgebruiker worden gekozen als hij/zij de app gebruikt in de paginaontwerper.
Nee
Basis lettertype Zet het basis lettertype van de app, waarvan je kunt afwijken met de fontType opmaakfunctie in de transformatielogica. Ja
Basis tekstgrootte Zet het basis tekstgrootte van de app, waarvan je kunt afwijken met de relativeTextSize opmaakfunctie in de transformatielogica. Ja
Basis Regelafstand (Alleen voor "Enkel bericht" of "Verticale lichtkrant" stijl) Stelt de ruimte tussen de regels in. Ja
Basis tekstkleur Zet het basis tekstkleur van de app, waarvan je kunt afwijken met de textColor opmaakfunctie in de transformatielogica. Ja
Uitlijning Stel de manier in waarop je de tekst in de app wil uitlijnen: links, centraal, naar rechts of uitgevuld. Ja

Geavanceerde Opties

De geavanceerde opties sectie geeft je een aantal specifieke parameters die je nodig kan hebben op je app correct te laten werken.

Eigenschap Uitleg Kan worden aangepast door de eindgebruiker
Verversingsinterval Hiermee kun je instellen met welke frequentie de app de gegevensbron vraagt voor nieuwe gegevens. Nee
Content type Sommige gegevensbronnen vereisen dat je specifiek aangeeft in welk formaat je het antwoord wilt onvangen. Hiermee kun je dat specificeren. Nee
Authorisatie type Als je gegevensbron vereist dat je moet worden geautoriseerd, dan kun je hiermee aangeven op welke manier je dat wilt doen. De opties zijn:
  • Geen
  • Basic authentication
  • Authorization header
  • Generieke header
  • Oauth2
Nee
Basic auth. gebruikersnaam Wanneer de bron "basic authentication" vereist, kun je hiermee de gebruikersnaam instellen. Nee
Basic auth. wachtwoord Wanneer de bron "basic authentication" vereist, kun je hiermee het wachtwoord instellen. Nee
Authorization header Wanneer de bron een "authorization header" vereist, kun je dit hier specificeren. Nee
Generic header Als de bron een eigen header voor authenticatie nodig heeft, kun je dit veld gebruiken om de waarde op te geven. Het formaat is [header naam1]: [header waarde1], [header naam2]: [header waarde2], b.v. Subscription-Key: 34A55dd8fd8ad9a4345fb46d42, API-key: acme. Nee
OAuth provider Wanneer de bron vereist dat een OAuth2 connectie wordt gemaakt, dan selecteer je hier de geconfigureerde OAuth provider. Je kunt OAuth provider configuraties maken en bewerken door op het tandwieltje te klikken. Het test account dat is verbonden met de geselecteerde OAuth provider is ook het account dat zal worden gebruikt als deze app gebruikt wordt door de eindgebruiker.
Als je eenmaal een OAuth provider met een test OAuth account hebt geselecteerd, moet je er nog voor zorgen dat het "access token" dat bij het test account hoort wordt doorgegeven in de communicatie met de gegevensbron. Doorgaans vereist een gegevensaanbieder dat het access token òf als een URL parameter wordt doorgegeven òf in een authorization header. Hoe dan ook, je kunt hiervoor de voorgedefinieerde systeemeigenschap gebruiken die {{accessToken}} heet, zodat Playr op die plek het jusite acccess token invult. B.v. als URL: https://api.geonames.org/SearchJSON?placename={{locationName}}&accessToken={{accessToken}} of als authorization header: Bearer {{accessToken}}.
Nee

Transformatielogica

Transformatielogica wordt geschreven in de programmeertaal Javascript. Er zijn een aantal basisobjecten en functies beschikbaar die het mogelijk maken om de gegevens uit de gegevensbron op te maken. Hoe je correcte transformatielogica schrijft lees je in de transformatielogica gids.

App-specifieke Eigenschappen

Naast de basiseigenschappen kun je ook je eigen app-specifieke eigenschappen maken die je kunt gebruiken in het webadres van de gegevensbron, alsmede je transformatielogica. Hierdoor kan de eindgebruiker het gedrag van de app aanpassen wanneer deze op een specifieke pagina wordt gebruikt.

App-specifieke Eigenschappen Maken

Elke app-specifieke eigenschap wordt gedefinieerd door:

  1. Type: definieert primair de manier waarop de eindgebruiker de eigenschap in de paginaontwerper kan configureren:
    1. boolean: staat voor een waar/onwaar waarde (true/false) die kan worden geconfigureerd met een selectievakje dat aan of uit kan worden gezet
    2. enumeration: vertegenwoordigt een lijst met selecteerbare opties. Het formaat van de selecteerbare opties is [waarde1,label1],[waarde2,label2],...(etc.), waarbij de waarden de enige dingen zijn die je gebruikt in het webadres en de transformatielogica. De labels worden alleen getoond aan de eindgebruiker wanneer hij de app configureert. Over het algemeen wil je dat waarden en labels uit letters (en mogelijk cijfers) bestaan. In dat geval moet je ze tussen aanhalingstekens plaatsen. Bijvoorbeeld ["NY","New York"],["LA","Los Angeles"], ["SF","San Francisco"] toont de eindgebruiker een lijst met drie namen van steden. De code van de geselecteerde stad is beschikbaar in je app. De standaard en test waarden moeten niet binnen aanhalingstekens worden geplaatst, dus je kunt gewoon (b.v.) NY invullen.
      Je kunt de gebruiker ook meerdere opties laten kiezen. In dat geval zijn de default en test waarden gewoon een door komma's gescheiden lijst, bijvoorbeeld NY,LA.
    3. integer: staat voor een getal tussen een minimum en een maximum dat kan worden geconfigureerd met zowel een schuifregelaar als een invoerveld
    4. string: staat voor een reeks letters en/of cijfers dat kan worden geconfigureerd met een invoerveld
  2. Naam: het exacte label dat in de paginaontwerper wordt weergegeven wanneer de eindgebruiker de app configureert
  3. Standaard: de standaardwaarde die de eigenschap heeft wanneer deze niet expliciet is geconfigureerd
  4. Test: dit wordt alleen gebruikt voor het testen van je transformatielogica op de pagina voor het maken van je eigen app.

App-specifieke Eigenschappen Gebruiken

Je kunt aan app-specifieke eigenschappen refereren door hun "camelized" naam. Dit betekent dat de naam als volgt wordt getransformeerd:

  1. de eerste letter wordt een kleine letter
  2. als de naam uit meerdere woorden bestaat (gescheiden door spaties, streepje of underscore), dan worden ze samengevoegd waarbij elk woord beginnent met een hoofdletter

Bijvoorbeeld:

"Locatienaam" => "locatieNaam"
"CODE" => "cODE"
"App-specifieke eigenschap" => "appSpecifiekeEigenschap"

In Het Webadres

In het webadres van de gegevensbron kun je een eigenschap opnemen door deze in dubbele accolades te plaatsen: {{locatieNaam}}.

Bijvoorbeeld:

https://api.geonames.org/SearchJSON?placename={{locatieNaam}}&username=demo

In het geval van een multi-select enumeration eigenschap is de waarde een door komma's gescheiden lijst van gekozen opties.

In De Transformatielogica

In de transformatielogica kun je naar de eigenschap verwijzen via het app.props-object, op de volgende manier: app.props.locatieNaam.

In De Aanvraagtekst Request Body

Je kunt de app-specifieke eigenschappen in de aanvraagtekst verwerken op eenzelfde manier als in het webadres: door deze in dubbele accolades te plaatsen. Maar dit gaat zelfs een stapje verder: je kunt je aanvraagtekst als een Mustache template schrijven, wat je extra mogelijkheden geeft, zoals conditioneel renderen van tekst.

Dynamische Waarden Met Code

In sommige gevallen is een vooraf ingestelde waarde niet voldoende en moet je een dynamische of berekende waarde meegeven in een verzoek. Hiervoor kun je stukjes Javascript code gebruiken (wat ook de basis is voor transformatielogica) in zowel het webadres als de request body. De code dient geplaatst in een blok dat start met [[= en eindigt met ]]. Bijvoorbeeld:

<StartDate>[[= new Date().toISOString()]]</StartDate>

Ook meerdere regels zijn mogelijk. In dat geval is het resultaat van de laatste regel de waarde die gebruikt wordt. Bijvoorbeeld:

<AuthToken>[[=
  var key = "foobar";
  var secret = "12345678";
  var param = new Date().toISOString();
  MD5(key + secret + param); // Het resultaat hiervan verschijnt in AuthToken
]]
</AuthToken>

Handige Javascript Libraries

Twee handige Javascript libraries die standaard beschikbaar zijn in deze code zijn:

  • Momentjs: voor makkelijke datumbewerkingen
  • MD5: voor het berekenen van hash waarden, b.v. voor autorisatie

Zo kun je met MomentJS makkelijk geformatteerde datum en tijd strings maken:

<StartDate>[[= moment().format("DD-M-YYYY")]]</StartDate>

App-specifieke Eigenschappen In Code

Je kunt ook de waarden van app-specifieke eigenschappen in je code gebruiken, door in je code deze eigenschappen te gebruiken zoals hierboven beschreven: tussen dubbele accolades, bijvoorbeeld:

<EndDate>[[= moment().add({{dagenVooruit}},'days').format("DD-M-YYYY")]]</EndDate>

Input-/Foutcontrole

De Input-/foutcontrole sectie is standaard is ingeklapt, maar kan worden geopend en weer gesloten door op de titel te klikken. Als deze geopend is dan toont ze de laatste input die is verkregen uit de gegevensbron op een navigeerbare manier. Dit maakt het een stuk makkelijker om de juiste gegevens te vinden die je nodig hebt in je transformatielogica.

De Fouten sectie toont fouten die eventueel optreden bij het ophalen van gegevens of het uitvoeren van de transformatielogica.

Voorbeeld

In een "mini pagina" wordt de gegenereerde output vertoont, zoals deze zal uitzien bij het gebruik van de app. Als je op het Verversicoon klikt dan wordt het volgende geformatteerde bericht vertoont of de lopende lichtkrant met de geformatteerde output.

Standaard heeft de voorbeeldpagina een witte achtergrond, maar als je een app maakt met lichte kleuren om specifiek (standaard) te gebruiken op een donkere achtergrond, dan kun je de Voorbeeld achtergrondkleur kleurenkiezer gebruiken de app tegen een gepaste achtergrond te kunnen zien.

OAuth Providers

Binnen je bedrijf kun je meerdere OAuth providers configureren. Een OAuth provider is een configuratie om toegang te krijgen tot een OAuth2 app die je hebt geconfigureerd op een specifieke website van een gegevensaanbieder. Laten we bijvoorbeeld zeggen dat je toegang wilt tot de LinkedIn-API. Dan moet je een LinkedIn-account hebben waarmee je naar de LinkedIn-ontwikkelaarssectie gaat. Daar maak je een nieuwe "app" aan waarmee je namens jezelf toegang hebt tot de LinkedIn gegevens. Je hebt niet veel nodig om zo'n "app" te configureren; het belangrijkste is dat je de juiste callback URL; deze moet zijn:

https://playr.biz/auth/oauth2_generic/callback

Aan de Playr kant moet je de onderstaande instellingen configureren:

Eigenschap Uitleg
Naam Geef jouw OAuth provider een passende naam, aangezien deze in het keuzevakje wordt weergegeven bij het configureren van je app. Bijvoorbeeld "LinkedIn".
Client ID Vul de client ID/key in van de OAuth2-app die je hebt gemaakt bij de gegevensaanbieder.
Klantengeheim Vul de client secret in van de OAuth2-app die je hebt gemaakt bij de gegevensaanbieder.
User info URL Vul het volledige webadres in van waar de OAuth2-gebruikersinfo bij deze gegevensaanbieder kan worden opgevraagd.
Authorization URL Vul de volledige OAuth2 authorization URL van deze gegevensaanbieder in.
Token URL Vul de volledige OAuth2 token URL van deze gegevensaanbieder in.
Scope Vul de scope in waarvoor je toestemming vraagt. Deze moet overeenkomen met de scopes die je hebt opgegeven in de app van een derde partij. Als er meerdere trefwoorden moeten worden opgegeven, dan scheidt je deze over het algemeen met een spatie. Bijvoorbeeld r_liteprofile r_emailaddress r_organization_social.
Pad naar e-mail (optioneel) Het pad naar het attribuut in het user-info antwoord waar het e-mailadres van de gebruiker kan worden gevonden. Bijvoorbeeld wanneer het antwoord zoiets is als { user: { info: { e-mail: "foo@bar.com", firstName: "Foo", lastName: "Bar" }}}}, geef dan het pad op, met behulp van een voorwaartse schuine streep: user/info/email.
Pad naar voornaam (optioneel) Het pad naar het attribuut in het user-info antwoord waar de voornaam van de gebruiker kan worden gevonden. In het geval van het bovenstaande voorbeeld, specificeer het pad met behulp van een voorwaartse schuine streep: user/info/firstName.
Pad naar achternaam Het pad naar het attribuut in het user-info antwoord waar de achternaam van de gebruiker kan worden gevonden. In het geval van het bovenstaande voorbeeld van de gebruikersinfo, specificeer het pad met behulp van een voorwaartse schuine streep: user/info/lastName.
Testaccount Zodra de provider correct is geconfigureerd, moet je je eigen gebruikersaccount aan dit account koppelen, zodat de gegevens namens jou kunnen worden opgevraagd. Dit kan worden gedaan door op de knop Koppel testaccount te klikken. Merk op dat dit ook het account is dat zal worden gebruikt tijdens het afspelen van de app waarin deze OAuth provider wordt gebruikt.