Cartões

Esta página é uma tradução do inglês. Se as duas diferirem, a página em inglês é a correta. Ler a página em inglês

Um cartão é uma lista curta de elementos que o Lingara desenha no seu próprio estilo. Não há campos de entrada, imagens, scripts nem marcação. Uma aplicação não pode colocar o seu próprio código nem o seu próprio aspeto no ecrã de um aprendente, por isso cada cartão lê-se como o resto do Lingara. A sua resposta é JSON: um card que contém os seus elements e, opcionalmente, uma tutor_note (consulte A nota para o tutor).

Os elementos

Cada elemento tem um type, que é um destes oito:

Um lang é uma etiqueta de idioma como ja, para que o Lingara desenhe a escrita certa. Um valor que não seja uma etiqueta de idioma é removido.

Os limites

• Um cartão contém no máximo 24 elementos. Os elementos depois do 24.º são descartados.
• Uma lista contém no máximo 20 itens. Os itens depois do 20.º são descartados, e uma lista vazia é descartada.
• Um cartão contém no máximo 4 botões. Os botões depois do 4.º são descartados.
• Um texto mais longo do que o seu limite é cortado para caber e termina em …. Os caracteres são contados como valores escalares Unicode.
• Os caracteres de controlo e as substituições de direção são removidos de todas as cadeias de texto.
• Um link cujo endereço não seja HTTPS, contenha um nome de utilizador ou aponte para um endereço IP é descartado.
• Um botão cuja action tenha mais de 64 caracteres, ou use algo além de letras, dígitos, _, ., : e -, é descartado.
• Um elemento sem texto restante depois destas regras é descartado.

Estas regras são tolerantes: o Lingara corta ou descarta o que não cabe e desenha o resto. Os kits aplicam as mesmas regras antes de responder, para que possa ver o que mudaria.

Análise estrita

O vocabulário é fechado. Um tipo de elemento desconhecido, um campo que um elemento não tem, um valor do tipo JSON errado ou uma resposta que nem sequer é JSON transforma a resposta inteira num cartão de recurso. O Lingara nunca desenha parte de um cartão que não conseguiu ler.

Tamanho e tempo

Uma resposta pode ter no máximo 32 KiB. O Lingara dá ao seu servidor 3 segundos para responder a uma renderização e 5 segundos para responder a uma ação, e não repete nenhuma das duas. Uma resposta tem de ter o estado 200 e um tipo de conteúdo JSON. Os redirecionamentos não são seguidos.

Botões e ações

Quando o aprendente carrega num botão, o Lingara envia ao seu servidor um pedido de ação com a action desse botão. O seu servidor responde com um cartão novo, que substitui o anterior. O mesmo toque pode chegar duas vezes, por isso torne cada ação segura de repetir.

Quando um cartão falha

Quando o Lingara não consegue obter um cartão que possa desenhar, o aprendente vê o cartão do próprio Lingara «Esta aplicação não respondeu» no seu idioma, ou o seu último cartão válido marcado como «Desatualizado». Nunca se diz ao aprendente porquê. Só o programador, como proprietário da aplicação, vê o motivo:

• A sua resposta: invalid (não é um cartão que o Lingara consiga ler), empty (nada para mostrar depois dos limites) ou too_large (mais de 32 KiB).
• O acesso ao seu servidor: timeout, http_error (qualquer estado diferente de 200), transport (uma falha de ligação ou de TLS, como um certificado expirado) ou blocked (um render_url que leva a um endereço privado ou a um endereço IP literal).
• O lado do Lingara: unavailable (o Lingara não conseguiu assinar o pedido) ou busy (demasiados pedidos já em curso).

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