Cartes

Cette page est traduite de l'anglais. En cas de différence, la page anglaise fait foi. Lire la page en anglais

Une carte est une courte liste d’éléments que Lingara dessine dans son propre style. Il n’y a ni champs de saisie, ni images, ni scripts, ni balisage. Une application ne peut placer ni son propre code ni sa propre apparence sur l’écran d’un apprenant : chaque carte se lit donc comme le reste de Lingara. Votre réponse est du JSON : une card contenant ses elements, et éventuellement une tutor_note (voir La note au tuteur).

Les éléments

Chaque élément a un type, qui est l’un de ces huit :

Un lang est une étiquette de langue comme ja, afin que Lingara dessine la bonne écriture. Une valeur qui n’est pas une étiquette de langue est supprimée.

Les limites

• Une carte contient au plus 24 éléments. Les éléments au-delà du 24e sont abandonnés.
• Une liste contient au plus 20 entrées. Les entrées au-delà de la 20e sont abandonnées, et une liste vide est abandonnée.
• Une carte contient au plus 4 boutons. Les boutons au-delà du 4e sont abandonnés.
• Un texte plus long que sa limite est coupé pour tenir et se termine par …. Les caractères sont comptés en valeurs scalaires Unicode.
• Les caractères de contrôle et les forçages de direction sont supprimés de chaque chaîne.
• Un lien dont l’adresse n’est pas en HTTPS, contient un nom d’utilisateur ou pointe vers une adresse IP est abandonné.
• Un bouton dont l’action dépasse 64 caractères, ou utilise autre chose que des lettres, des chiffres, _, ., : et -, est abandonné.
• Un élément sans texte restant après ces règles est abandonné.

Ces règles sont tolérantes : Lingara coupe ou abandonne ce qui ne tient pas et dessine le reste. Les kits appliquent les mêmes règles avant que vous ne répondiez, pour que vous voyiez ce qui changerait.

Analyse stricte

Le vocabulaire est fermé. Un type d’élément inconnu, un champ qu’un élément ne possède pas, une valeur du mauvais type JSON, ou une réponse qui n’est pas du JSON du tout transforme toute la réponse en carte de repli. Lingara ne dessine jamais une partie d’une carte qu’il n’a pas pu lire.

Taille et délai

Une réponse peut faire au plus 32 KiB. Lingara laisse à votre serveur 3 secondes pour répondre à un rendu et 5 secondes pour répondre à une action, et ne réessaie ni l’un ni l’autre. Une réponse doit avoir le statut 200 et un type de contenu JSON. Les redirections ne sont pas suivies.

Boutons et actions

Quand l’apprenant appuie sur un bouton, Lingara envoie à votre serveur une requête d’action portant l’action de ce bouton. Votre serveur répond avec une nouvelle carte, qui remplace l’ancienne. Le même appui peut arriver deux fois : rendez donc chaque action sûre à répéter.

Quand une carte échoue

Quand Lingara ne parvient pas à obtenir une carte qu’il peut dessiner, l’apprenant voit la carte de Lingara « Cette application n’a pas répondu » dans sa langue, ou votre dernière carte valide marquée « Pas à jour ». On ne dit jamais à l’apprenant pourquoi. Vous seul, en tant que propriétaire de l’application, voyez la raison :

• Votre réponse : invalid (pas une carte que Lingara peut lire), empty (plus rien à afficher après les limites) ou too_large (plus de 32 KiB).
• L’accès à votre serveur : timeout, http_error (tout statut autre que 200), transport (un échec de connexion ou de TLS, comme un certificat expiré) ou blocked (un render_url qui mène à une adresse privée ou à une adresse IP littérale).
• Du côté de Lingara : unavailable (Lingara n’a pas pu signer la requête) ou busy (trop de requêtes déjà en cours).

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