Kartu

Halaman ini diterjemahkan dari bahasa Inggris. Jika keduanya berbeda, halaman bahasa Inggris yang benar. Baca halaman bahasa Inggris

Kartu adalah daftar pendek elemen yang digambar Lingara dengan gayanya sendiri. Tidak ada input, gambar, skrip, atau markup. Aplikasi tidak dapat menaruh kodenya sendiri atau tampilannya sendiri di layar pelajar, sehingga setiap kartu terlihat seperti bagian Lingara lainnya. Balasan Anda berupa JSON: sebuah card yang memuat elements-nya, dan secara opsional sebuah tutor_note (lihat Catatan untuk tutor).

Elemen

Setiap elemen memiliki type, yaitu salah satu dari delapan berikut:

lang adalah tag bahasa seperti ja, agar Lingara menggambar aksara yang benar. Nilai yang bukan tag bahasa akan dihapus.

Batasan

• Sebuah kartu memuat paling banyak 24 elemen. Elemen setelah yang ke-24 dibuang.
• Sebuah daftar memuat paling banyak 20 item. Item setelah yang ke-20 dibuang, dan daftar kosong juga dibuang.
• Sebuah kartu memuat paling banyak 4 tombol. Tombol setelah yang ke-4 dibuang.
• Teks yang lebih panjang dari batasnya dipotong agar muat dan diakhiri dengan …. Karakter dihitung sebagai Unicode scalar value.
• Karakter kontrol dan karakter penimpa arah (direction override) dihapus dari setiap string.
• Tautan yang alamatnya bukan HTTPS, memuat nama pengguna, atau menunjuk ke alamat IP akan dibuang.
• Tombol yang action-nya lebih panjang dari 64 karakter, atau menggunakan apa pun selain huruf, angka, _, ., :, dan -, akan dibuang.
• Elemen yang tidak menyisakan teks setelah aturan ini diterapkan akan dibuang.

Aturan ini bersifat toleran: Lingara memotong atau membuang yang tidak muat dan menggambar sisanya. Kit menerapkan aturan yang sama sebelum Anda membalas, sehingga Anda dapat melihat apa yang akan berubah.

Parsing ketat

Kosakatanya tertutup. Tipe elemen yang tidak dikenal, field yang tidak dimiliki elemen, nilai dengan tipe JSON yang salah, atau balasan yang sama sekali bukan JSON akan mengubah seluruh balasan menjadi kartu pengganti. Lingara tidak pernah menggambar sebagian kartu yang tidak dapat dibacanya.

Ukuran dan waktu

Balasan paling besar 32 KiB. Lingara memberi server Anda waktu 3 detik untuk menjawab render dan 5 detik untuk menjawab aksi, dan tidak mencoba ulang keduanya. Balasan harus berstatus 200 dan bertipe konten JSON. Pengalihan (redirect) tidak diikuti.

Tombol dan aksi

Saat pelajar menekan tombol, Lingara mengirimkan permintaan aksi ke server Anda yang membawa action tombol itu. Server Anda menjawab dengan kartu baru, yang menggantikan kartu lama. Tekanan yang sama bisa tiba dua kali, jadi pastikan setiap aksi aman untuk diulang.

Saat kartu gagal

Saat Lingara tidak bisa mendapatkan kartu yang dapat digambarnya, pelajar melihat kartu “Aplikasi ini tidak menjawab” milik Lingara sendiri dalam bahasa mereka, atau kartu baik terakhir Anda yang ditandai “Tidak terbaru”. Pelajar tidak pernah diberi tahu alasannya. Hanya Anda, sebagai pemilik aplikasi, yang melihat alasannya:

• Balasan Anda: invalid (bukan kartu yang dapat dibaca Lingara), empty (tidak ada yang tersisa untuk ditampilkan setelah batasan diterapkan) atau too_large (lebih dari 32 KiB).
• Menjangkau server Anda: timeout, http_error (status apa pun selain 200), transport (kegagalan koneksi atau TLS, seperti sertifikat kedaluwarsa) atau blocked (render_url yang mengarah ke alamat privat atau alamat IP literal).
• Sisi Lingara: unavailable (Lingara tidak dapat menandatangani permintaan) atau busy (terlalu banyak permintaan yang sedang diproses).

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