Een app publiceren als portal
Doel
Geef een app die je al hebt getekend een eigen webadres, zodat mensen die niet in je organisatie zitten — klanten, sollicitanten, het publiek — hem kunnen openen zonder zich ook maar bij het platform aan te melden.
Voordat je begint
Je hebt twee dingen nodig, en zonder het eerste kun je de portal niet opslaan:
- Een Studio-app. Een portal publiceert een tekening; hij bevat er zelf geen. Zie Een Studio-app maken.
- Een aangepaste API voor alles wat de portal leest. Een portal leest nooit rechtstreeks uit een tabel — zie Wat een portal kan lezen hieronder voor de reden. Toont je portal alleen tekst en afbeeldingen, dan kun je dit overslaan.
Stappen
- Open je oplossing en kies Portals.
- Druk op Nieuw.
- Geef hem een naam. Zo noemen jij en je collega's hem; bezoekers zien die naam niet, want alles wat een bezoeker ziet, is getekend.
- Kies de app die je wilt publiceren uit de lijst. Alleen apps in deze omgeving verschijnen.
- Typ een webadres. Alleen het eerste deel —
acme-support, niet het hele adres. De rest van het adres hoort bij je Parsware-installatie, en de hint onder het vak laat zien hoe het uiteindelijke adres eruit komt te zien. - Kies bij Wie kan het openen wie hem kan openen. Iedereen betekent dat het adres direct je app opent; Mensen die zich aanmelden zet er een aanmeldformulier voor — zie Bezoekers vragen zich aan te melden.
- Vink bij Wat het kan lezen de aangepaste API's aan die deze portal mag aanroepen.
- Kies bij Bezoekers handelen als de beveiligingsrollen die elke bezoeker van deze portal heeft. Zie Welke tabellen een portal mag aanraken.
- Laat Gepubliceerd uitgevinkt zolang je nog bezig bent, en vink het aan wanneer het adres moet gaan antwoorden.
- Druk op Opslaan.
Wat een portal kan lezen
Een portal leest via de aangepaste API's die je opgeeft, en via niets anders. Hij kan niet rechtstreeks uit een tabel lezen, en er is geen instelling die dat toestaat.
Dat is bewust zo. Een scherm tekenen mag nooit per ongeluk een manier worden om een tabel op het openbare internet te zetten. Een aangepaste API is iets wat iemand met opzet heeft geschreven: die bepaalt wat een buitenstaander mag zien, in een script dat je kunt lezen. Een tabel is gewoon een tabel.
Heeft een scherm op je portal dus gegevens nodig, dan is de volgorde: definieer de aangepaste API, vink hem aan in de lijst van de portal en laat je scherm via die API lezen.
De API in je scherm noemen
Een portalscherm noemt het contract dat het leest, in plaats van een tabel:
loadRecords("api:par_articles@1", "articles", { top: 20, orderBy: "par_name" })
api: zegt dat dit een aangepaste API is; par_articles is de logische naam; @1 is de versie,
omdat twee versies van één API twee verschillende contracten zijn. Dezelfde vorm werkt voor
getRecord, createRecord, updateRecord en deleteRecord — welke je aanroept, bepaalt wat het
platform doet, en de eigen HTTP-methode van de API moet daarop kunnen antwoorden. Een
createRecord die naar een API wijst die alleen leest, mislukt zodra het scherm hem uitvoert.
In de lijst met apps leest een getekend scherm zijn tabellen rechtstreeks — zo werkt de app van
iemand die is aangemeld, en daarom kan hij pagineren en filteren. Op een portal bestaat die deur
niet. Een scherm dat api: noemt, opent dus wel op de portal maar weigert in de shell, en zegt dat
ook, in plaats van een lege lijst te tonen.
Wil je één tekening op beide plekken, dan heb je twee schermen nodig. Dat is de afweging die het platform bewust heeft gemaakt: je portal leest via een contract dat jij hebt geschreven, en dat contract bepaalt wat een buitenstaander ziet.
Je API moet voor een lijst antwoorden met { "rows": [...], "total": 12 }. Antwoordt hij iets
anders, dan toont het scherm een lege lijst in plaats van een foutmelding, zodat een fout in één
API nooit een hele portal breekt.
De lijst is een toestemming, geen plattegrond. Een API aanvinken zegt dat deze portal hem mag aanroepen — meer niet. Je scherm bepaalt wanneer, door hem te noemen. Een API die je niet hebt aangevinkt, wordt geweigerd, ook als een scherm erom vraagt. Zo wordt een fout in een tekening nooit een open deur.
Schrijven vereist bezoekers die zich aanmelden — of een uitdaging. Een API die op POST, PATCH, PUT of DELETE antwoordt, is alleen aan te roepen als Wie kan het openen op mensen die zich aanmelden staat, omdat er op een open portal niemand is aan wie je een wijziging kunt toeschrijven. De enige manier om daaromheen te komen, staat in de volgende sectie.
Vraag degene die je Parsware-installatie beheert of de portalhost de scope heeft gekregen die je aangepaste API vereist. Elke aangepaste API noemt er een, en de portalhost houdt die namens je bezoekers vast — zonder die scope wordt elke leesopdracht geweigerd en toont de pagina gewoon niets.
Welke tabellen een portal mag aanraken
De aangepaste API's die je aanvinkt, bepalen welke contracten een pagina mag aanroepen. Bezoekers handelen als bepaalt welke tabellen die contracten vervolgens mogen lezen en schrijven — met dezelfde beveiligingsrollen die je je eigen collega's geeft, met dezelfde rechten.
Geef een portal een eigen rol die precies toekent wat zijn API's nodig hebben — bijvoorbeeld Lezen en Maken op Cases — in plaats van een rol die je medewerkers gebruiken. Elke bezoeker van de portal heeft die rol, aangemeld of niet.
Kies je niets, dan bereikt de portal niets. De lijsten zijn leeg en bij elke keer opslaan staat er Dat kon niet worden opgeslagen. Dat is de veilige kant, en het is het eerste wat je controleert als een portal niets toont op een pagina die er goed uitziet.
Op een portal die bezoekers laat aanmelden, houdt het niet op bij de rol. Heeft de tabel een regel die zegt welke rijen van wie zijn — zie Bepalen welke records een bezoeker ziet — dan wordt elke bezoeker beperkt tot de rijen van zijn eigen bedrijf, nadat de rol hem heeft binnengelaten.
De rol van platformbeheerder wordt hier nooit aangeboden. Een bezoeker met die rol zou de hele omgeving in handen hebben.
Iedereen je iets laten sturen
Vink Laat iedereen je dingen sturen aan — dat verschijnt alleen zolang Wie kan het openen op Iedereen staat — en een bezoeker zonder account kan schrijven, zolang zijn browser eerst even aan een puzzel werkt die bewijst dat het geen script is.
Dat maakt een contactformulier mogelijk. Zonder deze optie mag een portal die iedereen kan openen wel lezen maar niet schrijven, wat betekent dat je iemand vraagt een account te maken voordat die je een bericht kan sturen — en dat is geen contactformulier.
Er valt niets te tekenen en de bezoeker hoeft niets te doen. Geen vakje om aan te vinken, geen wiebelig woord om te lezen, geen foto's van verkeerslichten. Het platform geeft de browser een klein rekensommetje; een laptop is ermee klaar voordat je het merkt, een oude telefoon doet er even over en toont onder de knop We controleren of je een mens bent… terwijl hij bezig is. Er wordt niets over de bezoeker verzameld, en niets op de pagina komt van de server van een ander bedrijf.
Wat het tegenhoudt en wat niet. Het maakt massale inzendingen duur: een script dat duizend formulieren per uur kon versturen, moet nu voor elk ervan echt werk verrichten, dus in de praktijk verstuurt het er veertig. Het houdt niet iemand tegen die vastberaden is en echte browsers wil draaien — en geen enkel vinkje, waar dan ook, houdt dat tegen, hoe het ook heet. Zie het als een spamfilter met tanden, niet als een slot.
Drie dingen die het niet verandert:
- Wat er aangeroepen kan worden. Alleen de aangepaste API's die je hierboven hebt aangevinkt, precies zoals eerst.
- Wat er geschreven kan worden. Het eigen aanvraagschema van de API bepaalt nog steeds welke velden een bezoeker mag invullen. Een contract dat een onderwerp en een bericht accepteert, accepteert een onderwerp en een bericht.
- Wie iemand is. Er is niemand aangemeld, dus er is niets geverifieerd. Slaat je API een e-mailadres op dat de bezoeker heeft getypt, dan is dat een adres dat iemand heeft getypt. Waar dat ertoe doet, vraag je bezoekers om zich aan te melden.
portal-contact-form in samples/solutions/ is precies dit: een open portal, één schrijfactie, een
bestand dat eraan is gekoppeld, en een pagina in de site zelf die uitlegt waar je naar moet kijken.
De portal openen
Zodra een portal een adres heeft, toont de lijst het als een koppeling, en Portal openen in de opdrachtbalk opent het in een nieuw tabblad. Open je de portal om te bewerken, dan verschijnt hetzelfde adres onder het vak Webadres, met twee kleine knoppen ernaast: de ene opent de portal, voor als je ernaar wilt kijken, en de andere kopieert het adres, voor als je het naar iemand anders wilt sturen. Geen van beide toont tekst — het adres is lang, en labels ernaast zouden de tweede knop naar een eigen regel duwen — dus beweeg de muis over een van beide en hij zegt wat hij is.
Het adres verschijnt pas als het is opgeslagen. Zolang je nog een label typt, laat de hint onder het vak zien hoe het uiteindelijke adres eruit komt te zien; een koppeling op basis van iets wat je nog niet hebt opgeslagen, zou naar een portal wijzen die er niet is.
Bedient je installatie geen portals, dan is er geen adres om te openen en blijft de hint staan waar de koppeling zou komen. Vraag het aan degene die je Parsware-installatie beheert.
Die zin gaat nooit over je portal — het is het platform dat zegt dat het geen antwoord kon geven, en je tekening, je adres en de schakelaar Gepubliceerd doen er niet toe. Het is een van twee dingen, en beide zijn de zaak van degene die je installatie beheert: de services liggen eruit, of de portalhost krijgt geen referentie van Parsware. Een verkeerd adres zegt iets heel anders ("Hier is niets gepubliceerd"), dus je kunt ze aan de pagina zelf van elkaar onderscheiden.
Wat een bezoeker ziet
Twee dingen aan een portalpagina zijn van het platform en niet van jou, en het is goed ze allebei te kennen voordat iemand je ernaar vraagt.
Een portal opent donker. Je eigen apps in Parsware openen licht, omdat je daar een hele werkdag zit; een portal is waar een onbekende binnenkomt via een link in een bericht, meestal op een telefoon, en donker is dan de vriendelijkere eerste indruk. In de bovenhoek van elke portalpagina zweeft een kleine knop licht/donker — rechts in het Engels, links in het Perzisch en Arabisch — en de eerste keer dat een bezoeker erop drukt, is dat vanaf dan zijn keuze: de browser onthoudt het, en de donkere standaard gaat nooit in tegen iemand die al heeft gekozen.
Je kunt nog steeds je eigen schakelaar tekenen. setTheme("light") en setTheme("dark") zijn
beschikbaar voor elke handler op een getekend scherm, en een knop die jij tekent en die in de hoek
werken op dezelfde instelling. Die in de hoek is het minimum, zodat een portal leesbaar is voordat
iemand eraan denkt er zelf een te tekenen.
En de tekening past zich aan. Een scherm wordt op een bepaald formaat getekend, maar niet op dat formaat getoond: blokken die over de hele pagina lopen, houden hun afstand tot elke marge en laten het midden meegeven, en dingen die naast elkaar zijn getekend, houden hun aandeel in de breedte. Een portal past dus in het venster waarin hij wordt geopend, op elke breedte, en niets valt buiten de pagina.
Wat aanpassen niet kan, is herschikken. Twee kolommen die naast elkaar zijn getekend, blijven naast elkaar — op een telefoon zijn het twee smalle kolommen, niet één kolom met de tweede onder de eerste. Doet een portal ertoe op telefoons, teken dan een scherm voor een telefoon: daarvoor zijn de drie voorbeelden Een portal op een desktop / tablet / telefoon.
Over het adres
Eén adres antwoordt voor één portal, over de hele installatie. Niet één per omgeving — één in totaal. Er staat één voordeur voor alle omgevingen, en die bepaalt aan de hand van het adres waar een aanvraag naartoe gaat.
Dat heeft één gevolg dat je tegenkomt zodra je voor het eerst een oplossing promoveert:
Importeer je dezelfde oplossing in Test of Productie, dan antwoordt het adres waar hij om vraagt al voor de omgeving waarin je hem hebt gebouwd. De portal komt dus zonder adres en uitgeschakeld aan, en staat in deze lijst als Heeft een adres nodig.
Dit is geen fout, en er is niets misgegaan met je oplossing. Je ontwikkelportal en je productieportal hadden altijd al verschillende adressen nodig. Open de portal in de nieuwe omgeving, geef hem daar het adres dat je wilt, en vink Gepubliceerd aan.
Een portal kan ook antwoorden op een adres dat van je eigen organisatie is — portal.acme.com —
dat je toevoegt onder Je eigen domeinen en waarvan je vervolgens bewijst dat het van jou is.
Zie Je eigen domein gebruiken.
In- en uitschakelen
Gepubliceerd is het enige vinkje in de makerportal waarbij "aan" betekent: iedereen ter wereld die het adres kent, kan dit zien. Daarom:
- Het staat eerst uit, en blijft uit tot jij het aanzet.
- Het kan niet worden aangezet zolang de portal geen adres heeft — er zou niets zijn om op te antwoorden. Een eigen domein telt pas als adres als het is geverifieerd, om dezelfde reden: op een niet-geverifieerd domein antwoordt niets.
- Uitzetten zorgt ervoor dat het adres direct niet meer antwoordt. De app die het publiceert, blijft ongemoeid.
Een portal verwijderen
Een portal verwijderen zorgt ervoor dat het adres niet meer antwoordt en maakt dat adres vrij voor iets anders. De app wordt niet verwijderd — de tekening blijft een app die je eigen mensen in de shell kunnen openen, en dat is precies waarom publiceren iets anders is dan tekenen.