Kaarten

Deze pagina is vertaald uit het Engels. Als de twee verschillen, is de Engelse pagina juist. Lees de Engelse pagina

Een kaart is een korte lijst elementen die Lingara in zijn eigen stijl tekent. Er zijn geen invoervelden, afbeeldingen, scripts of opmaak. Een app kan geen eigen code en geen eigen uiterlijk op het scherm van een leerder zetten, dus elke kaart leest als de rest van Lingara. Je antwoord is JSON: een card met zijn elements, en optioneel een tutor_note (zie De tutornotitie).

De elementen

Elk element heeft een type, dat een van deze acht is:

Een lang is een taaltag zoals ja, zodat Lingara het juiste schrift tekent. Een waarde die geen taaltag is, wordt verwijderd.

De limieten

• Een kaart bevat maximaal 24 elementen. Elementen na het 24e worden weggelaten.
• Een lijst bevat maximaal 20 items. Items na het 20e worden weggelaten, en een lege lijst wordt weggelaten.
• Een kaart bevat maximaal 4 knoppen. Knoppen na de 4e worden weggelaten.
• Tekst die langer is dan zijn limiet wordt ingekort en eindigt op …. Tekens worden geteld als Unicode-scalaire waarden.
• Besturingstekens en richtingsoverschrijvingen worden uit elke string verwijderd.
• Een link waarvan het adres geen HTTPS is, een gebruikersnaam bevat of naar een IP-adres wijst, wordt weggelaten.
• Een knop waarvan de action langer is dan 64 tekens, of iets anders gebruikt dan letters, cijfers, _, ., : en -, wordt weggelaten.
• Een element waarin na deze regels geen tekst meer over is, wordt weggelaten.

Deze regels zijn vergevingsgezind: Lingara kort in of laat weg wat niet past en tekent de rest. De kits passen dezelfde regels toe voordat je antwoordt, zodat je kunt zien wat er zou veranderen.

Strikt parsen

De woordenschat is gesloten. Een onbekend elementtype, een veld dat een element niet heeft, een waarde van het verkeerde JSON-type, of een antwoord dat helemaal geen JSON is, verandert het hele antwoord in een fallback. Lingara tekent nooit een deel van een kaart die het niet kon lezen.

Grootte en tijd

Een antwoord mag maximaal 32 KiB zijn. Lingara geeft je server 3 seconden om een render te beantwoorden en 5 seconden om een actie te beantwoorden, en probeert geen van beide opnieuw. Een antwoord moet status 200 en een JSON-contenttype hebben. Redirects worden niet gevolgd.

Knoppen en acties

Wanneer de leerder op een knop drukt, stuurt Lingara je server een actieverzoek met de action van die knop. Je server antwoordt met een nieuwe kaart, die de oude vervangt. Dezelfde druk kan twee keer aankomen, dus maak elke actie veilig om te herhalen.

Als een kaart mislukt

Als Lingara geen kaart krijgt die het kan tekenen, ziet de leerder Lingara’s eigen kaart “Deze app heeft niet geantwoord” in zijn taal, of je laatste goede kaart gemarkeerd als niet actueel. De leerder krijgt nooit te horen waarom. Alleen jij, als eigenaar van de app, ziet de reden:

• Je antwoord: invalid (geen kaart die Lingara kan lezen), empty (niets meer te tonen na de limieten) of too_large (meer dan 32 KiB).
• Je server bereiken: timeout, http_error (elke status behalve 200), transport (een verbindings- of TLS-fout, zoals een verlopen certificaat) of blocked (een render_url die naar een privé- of IP-letterlijk adres leidt).
• De kant van Lingara: unavailable (Lingara kon het verzoek niet ondertekenen) of busy (al te veel verzoeken onderweg).

function todayCard(streak: number): Card {
  return card()
    .heading("Today's five", 1)
    .term({ word: "雨", reading: "yǔ", gloss: "rain", lang: "zh" })
    .list([item.text("Review 3 words"), item.term({ word: "二", reading: "èr" })])
    .button(`Done (${streak})`, "done")
    .build(); // Throws CardLimitError naming the rule the relay would clamp.
}

fn today_card(title: &str, lang: &str) -> Result<lingara_apps::Card, BoxError> {
    Ok(card()
        .heading(title, 1)
        .term(Term::new("雨").reading("yǔ").gloss("rain").lang(lang))
        .list([item::text("Say it aloud"), item::term(Term::new("下雨").gloss("to rain"))])
        .button("Next word", "next")
        .build()?)
}

card, err := lingaraapps.NewCard().
	Heading("Today", 1).
	Term(lingaraapps.Term{Word: "雨", Reading: "yǔ", Gloss: "rain", Lang: "zh"}).
	List(
		lingaraapps.Item.Text("Say it aloud three times."),
		lingaraapps.Item.Term(lingaraapps.Term{Word: "雨天", Gloss: "rainy day", Lang: "zh"}),
	).
	Button("Next", "next").
	Build()
if err != nil {
	// A *lingaraapps.CardLimitError names the rule the card breaks,
	// such as text_length or list_items. Nothing is cut for you.
	return lingaraapps.Card{}, err
}

import com.getlingara.apps.Card;
import com.getlingara.apps.Item;

Card card =
    Card.card()
        .heading("Today's five", 1)
        .term("雨", "yǔ", "rain", "zh")
        .list(Item.text("Say it aloud"), Item.term("二", "èr", "two", "zh"))
        .button("Next", "next")
        .build(); // a CardLimitException names the first rule the card breaks

import com.getlingara.apps.kotlin.Card
import com.getlingara.apps.kotlin.card

val c =
    card {
        heading("Today's five", 1)
        term("雨", reading = "yǔ", gloss = "rain", lang = "zh")
        list(item.text("Say it aloud"), item.term("二", reading = "èr", gloss = "two", lang = "zh"))
        button("Next", "next")
    } // a CardLimitException names the first rule the card breaks

def self.today_card(streak)
  Lingara::Apps.card
    .heading("Today's five", 1)
    .term(word: "雨", reading: "yǔ", gloss: "rain", lang: "zh")
    .list([Lingara::Apps.item.text("Review 3 words"), Lingara::Apps.item.term(word: "二", reading: "èr")])
    .button("Done (#{streak})", "done")
    .build # Raises Lingara::Apps::CardLimitError naming the rule Lingara would clamp.
end

use Lingara\Apps\Card;
use Lingara\Apps\Generated\Card as CardModel;
use Lingara\Apps\Item;

function todayCard(int $streak): CardModel
{
    return Card::create()
        ->heading("Today's five", 1)
        ->term('雨', reading: 'yǔ', gloss: 'rain', lang: 'zh')
        ->list([Item::text('Review 3 words'), Item::term('二', reading: 'èr')])
        ->button("Done ({$streak})", 'done')
        ->build(); // Throws CardLimitException naming the rule the relay would clamp.
}