Schede

Questa pagina è tradotta dall'inglese. Se le due versioni differiscono, fa fede la pagina in inglese. Leggi la pagina in inglese

Una scheda è un breve elenco di elementi che Lingara disegna nel proprio stile. Non ci sono campi di input, immagini, script né markup. Un’app non può mettere il proprio codice né il proprio aspetto sullo schermo di uno studente, quindi ogni scheda si legge come il resto di Lingara. La tua risposta è JSON: una card che contiene i suoi elements e, facoltativamente, una tutor_note (vedi La nota per il tutor).

Gli elementi

Ogni elemento ha un type, che è uno di questi otto:

Elemento	Campi	Cosa mostra
`heading`	`text`, `level`	Un titolo. `level` è 1 o 2, e qualsiasi altro valore diventa 2. Il suo testo è lungo al massimo 80 caratteri.
`text`	`text`, `lang`	Un paragrafo di al massimo 600 caratteri. È l’unico punto in cui un a capo viene conservato.
`term`	`word`, `reading`, `gloss`, `lang`	Una parola da imparare. Solo `word` è obbligatorio. La parola è lunga al massimo 60 caratteri, la lettura 120 e la glossa 160.
`list`	`items`	Fino a 20 voci. Ogni voce è un `text` o un `term`, con gli stessi campi dell’elemento con quel nome.
`progress`	`value`, `label`	Una barra di avanzamento. `value` va da 0 a 1, e l’etichetta è lunga al massimo 60 caratteri.
`divider`		Una linea tra le parti della scheda.
`button`	`label`, `action`, `style`	Un pulsante che invia la sua `action` al tuo server. `style` è `primary` o `secondary`, e l’etichetta è lunga al massimo 32 caratteri.
`link`	`label`, `url`	Un link che lo studente apre nel proprio browser, dopo che Lingara glielo ha chiesto. L’etichetta è lunga al massimo 60 caratteri.

Un lang è un tag di lingua come ja, così che Lingara disegni la scrittura giusta. Un valore che non è un tag di lingua viene rimosso.

I limiti

Una scheda contiene al massimo 24 elementi. Gli elementi dopo il 24° vengono scartati.
Un elenco contiene al massimo 20 voci. Le voci dopo la 20ª vengono scartate, e un elenco vuoto viene scartato.
Una scheda contiene al massimo 4 pulsanti. I pulsanti dopo il 4° vengono scartati.
Un testo più lungo del suo limite viene tagliato per farlo stare e termina con …. I caratteri vengono contati come valori scalari Unicode.
I caratteri di controllo e le forzature di direzione vengono rimossi da ogni stringa.
Un link il cui indirizzo non è HTTPS, contiene un nome utente o punta a un indirizzo IP viene scartato.
Un pulsante la cui action è più lunga di 64 caratteri, o usa qualcosa di diverso da lettere, cifre, _, ., : e -, viene scartato.
Un elemento a cui non resta testo dopo queste regole viene scartato.

Queste regole sono tolleranti: Lingara taglia o scarta ciò che non sta e disegna il resto. I kit applicano le stesse regole prima che tu risponda, così puoi vedere cosa cambierebbe.

Analisi rigorosa

Il vocabolario è chiuso. Un tipo di elemento sconosciuto, un campo che un elemento non ha, un valore del tipo JSON sbagliato o una risposta che non è affatto JSON trasforma l’intera risposta in una scheda di ripiego. Lingara non disegna mai una parte di una scheda che non è riuscita a leggere.

Dimensioni e tempi

Una risposta può essere al massimo di 32 KiB. Lingara concede al tuo server 3 secondi per rispondere a un rendering e 5 secondi per rispondere a un’azione, e non ritenta né l’uno né l’altra. Una risposta deve avere stato 200 e un content type JSON. I reindirizzamenti non vengono seguiti.

Pulsanti e azioni

Quando lo studente preme un pulsante, Lingara invia al tuo server una richiesta di azione che porta la action di quel pulsante. Il tuo server risponde con una nuova scheda, che sostituisce la vecchia. La stessa pressione può arrivare due volte, quindi rendi ogni azione sicura da ripetere.

Quando una scheda non riesce

Quando Lingara non riesce a ottenere una scheda che può disegnare, lo studente vede la scheda di Lingara «Questa app non ha risposto» nella sua lingua, oppure la tua ultima scheda valida segnata come «Non aggiornata». Allo studente non viene mai detto perché. Solo tu, in quanto proprietario dell’app, vedi il motivo:

La tua risposta: invalid (non è una scheda che Lingara può leggere), empty (non resta nulla da mostrare dopo i limiti) o too_large (più di 32 KiB).
Il raggiungimento del tuo server: timeout, http_error (qualsiasi stato diverso da 200), transport (un errore di connessione o di TLS, come un certificato scaduto) o blocked (un render_url che porta a un indirizzo privato o a un indirizzo IP letterale).
Il lato di Lingara: unavailable (Lingara non è riuscita a firmare la richiesta) o busy (troppe richieste già in corso).

TypeScriptRustGoJavaKotlinRubyPHP

TypeScript

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

Rust

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
}

Java

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

Kotlin

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

Ruby

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

PHP

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