Karten

Diese Seite ist aus dem Englischen übersetzt. Wenn die beiden voneinander abweichen, ist die englische Seite maßgeblich. Englische Seite lesen

Eine Karte ist eine kurze Liste von Elementen, die Lingara in seinem eigenen Stil zeichnet. Es gibt keine Eingabefelder, Bilder, Skripte oder Markup. Eine App kann weder ihren eigenen Code noch ihr eigenes Aussehen auf den Bildschirm eines Lernenden bringen, daher liest sich jede Karte wie der Rest von Lingara. Ihre Antwort ist JSON: eine card mit ihren elements und optional eine tutor_note (siehe Die Tutor-Notiz).

Die Elemente

Jedes Element hat einen type, der einer dieser acht ist:

Ein lang ist ein Sprach-Tag wie ja, damit Lingara die richtige Schrift zeichnet. Ein Wert, der kein Sprach-Tag ist, wird entfernt.

Die Grenzen

• Eine Karte enthält höchstens 24 Elemente. Elemente nach dem 24. werden verworfen.
• Eine Liste enthält höchstens 20 Einträge. Einträge nach dem 20. werden verworfen, und eine leere Liste wird verworfen.
• Eine Karte enthält höchstens 4 Buttons. Buttons nach dem 4. werden verworfen.
• Text, der länger als seine Grenze ist, wird passend gekürzt und endet auf …. Zeichen werden als Unicode-Skalarwerte gezählt.
• Steuerzeichen und Richtungsüberschreibungen werden aus jeder Zeichenkette entfernt.
• Ein Link, dessen Adresse nicht HTTPS ist, einen Benutzernamen enthält oder auf eine IP-Adresse zeigt, wird verworfen.
• Ein Button, dessen action länger als 64 Zeichen ist oder etwas anderes als Buchstaben, Ziffern, _, ., : und - verwendet, wird verworfen.
• Ein Element, das nach diesen Regeln keinen Text mehr hat, wird verworfen.

Diese Regeln sind nachsichtig: Lingara kürzt oder verwirft, was nicht passt, und zeichnet den Rest. Die Kits wenden dieselben Regeln an, bevor Sie antworten, sodass Sie sehen, was sich ändern würde.

Striktes Parsen

Das Vokabular ist geschlossen. Ein unbekannter Elementtyp, ein Feld, das ein Element nicht hat, ein Wert vom falschen JSON-Typ oder eine Antwort, die überhaupt kein JSON ist, macht die gesamte Antwort zu einer Ersatzkarte. Lingara zeichnet nie einen Teil einer Karte, die es nicht lesen konnte.

Größe und Zeit

Eine Antwort darf höchstens 32 KiB groß sein. Lingara gibt Ihrem Server 3 Sekunden, um auf ein Rendering zu antworten, und 5 Sekunden, um auf eine Aktion zu antworten, und wiederholt keins von beiden. Eine Antwort muss den Status 200 und einen JSON-Content-Type haben. Weiterleitungen werden nicht verfolgt.

Buttons und Aktionen

Wenn der Lernende einen Button drückt, sendet Lingara Ihrem Server eine Aktionsanfrage mit der action dieses Buttons. Ihr Server antwortet mit einer neuen Karte, die die alte ersetzt. Derselbe Druck kann zweimal ankommen, machen Sie also jede Aktion gefahrlos wiederholbar.

Wenn eine Karte fehlschlägt

Wenn Lingara keine Karte bekommt, die es zeichnen kann, sieht der Lernende Lingaras eigene Karte „Diese App hat nicht geantwortet“ in seiner Sprache oder Ihre letzte gültige Karte, als „Nicht aktuell“ markiert. Der Lernende erfährt nie, warum. Nur Sie als Besitzer der App sehen den Grund:

• Ihre Antwort: invalid (keine Karte, die Lingara lesen kann), empty (nach den Grenzen bleibt nichts zum Anzeigen übrig) oder too_large (mehr als 32 KiB).
• Die Verbindung zu Ihrem Server: timeout, http_error (jeder Status außer 200), transport (ein Verbindungs- oder TLS-Fehler, etwa ein abgelaufenes Zertifikat) oder blocked (eine render_url, die zu einer privaten Adresse oder einer IP-Literal-Adresse führt).
• Lingaras Seite: unavailable (Lingara konnte die Anfrage nicht signieren) oder busy (zu viele Anfragen bereits in Bearbeitung).

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.
}