hx-vals dan hx-params — HTMX

hx-vals menambahkan nilai ke request, hx-params mengontrol parameter mana yang dikirim. hx-vals (static values) Approve hx-vals (JavaScript) Submit hx-params…

hx-vals menambahkan nilai ke request dalam bentuk JSON, nilai yang gak ada di kotak isian mana pun. hx-params menyaring parameter mana yang benar-benar dikirim. Bayangin nota di meja Laundry Bu Rini. Saat pelanggan memilih layanan express, Bu Rini mengecap "EXPRESS" di nota: nilai yang gak ditulis di kotak mana pun. Itu hx-vals. Sebelum nota dikirim ke belakang, dia menggunting potongan "perkiraan harga" yang tadi ditunjukkan ke pelanggan, karena bagian belakang menghitung harga sendiri. Itu hx-params.

🧪 Tebakan cepat: Form punya <input name="berat" value="4"> dan hx-vals='{"berat": 10}'. Berat berapa yang diterima server? Jawabannya ada di bagian "hx-vals menang dari field bernama sama".

hx-vals: nilai tambahan dalam JSON

Tombol di papan order gak punya kotak isian, jadi datanya dibawa hx-vals:

<span id="status-12">Dicuci</span>
<button hx-post="/order/12/status" hx-vals='{"status": "Disetrika"}' hx-target="#status-12">
  Tandai disetrika
</button>

Klik mengirim POST /order/12/status dengan body status=Disetrika.
Isinya JSON, dan JSON wajib memakai tanda kutip dua ("). Jadi atributnya dibungkus tanda kutip satu (').
Angka boleh: {"id": 42} mengirim id=42.
Di request GET, nilainya masuk ke URL: <button hx-get="/order" hx-vals='{"page": 2}'> mengirim GET /order?page=2.
hx-vals diwariskan ke elemen di dalamnya. Kalau kuncinya sama, yang paling dekat yang menang.

Di form: digabung dengan field

<form id="terima" hx-post="/order" hx-target="#nota" hx-vals='{"layanan": "express"}'>
  <input name="nama" value="Bu Tini">
  <input name="berat" value="4">
  <input name="perkiraan" value="Rp 28.000" readonly>
  <button>Terima cucian</button>
</form>

Body-nya: nama=Bu%20Tini&berat=4&perkiraan=Rp%2028.000&layanan=express. Nilai dari hx-vals ditaruh di belakang, sesudah field form.

hx-vals menang dari field bernama sama

Dengan hx-vals='{"berat": 10}', body-nya jadi nama=Bu%20Tini&perkiraan=Rp%2028.000&berat=10. Berat 4 dari kotaknya dibuang, dan server menerima 10. Itu jawaban tebakannya. htmx menghapus field yang namanya sama dengan kunci hx-vals, lalu menaruh nilai hx-vals di belakang. Pakai ini dengan sengaja, atau beri kunci yang berbeda.

hx-params: saring yang dikirim

`hx-params`	Body yang dikirim
`*` (bawaan)	`nama=Bu%20Tini&berat=4&perkiraan=Rp%2028.000`
`not perkiraan`	`nama=Bu%20Tini&berat=4`
`nama,berat`	`nama=Bu%20Tini&berat=4`
`none`	(kosong)

not a,b mengirim semua kecuali yang disebut. a,b cuma mengirim yang disebut. none gak mengirim apa pun.
Saringan ini jalan terakhir, sesudah hx-vals digabung. Jadi hx-params="nama,berat" ikut membuang layanan dari hx-vals, dan none membuang semuanya.
hx-params bukan pengaman. Siapa pun bisa mengirim request sendiri lewat DevTools. Server tetap harus menghitung harga sendiri dan mengabaikan perkiraan.

js: nilai dari JavaScript, dan catatan keamanannya

<button hx-post="/order/12/status" hx-vals='js:{jam: new Date().getHours()}'>

Awalan js: membuat isinya dijalankan sebagai JavaScript saat request dibuat. Pukul 09.15, body-nya jam=9.
Karena dijalankan, jangan pernah menaruh teks dari pengguna di dalam js:, misalnya nama pelanggan dari database. Teks yang berisi kode akan ikut jalan, dan itu celah XSS. JSON biasa tanpa js: cuma dibaca, gak dijalankan.
Situs dengan Content Security Policy yang ketat mematikan fitur ini dengan htmx.config.allowEval = false. Nilai js: lalu dilewati, dan htmx memicu htmx:evalDisallowedError.

⚠️ Jebakan yang sering ketemu

Tanda kutip terbalik. hx-vals="{'status': 'Disetrika'}" bukan JSON yang sah. htmx menulis error di Console, dan request-nya gak dikirim sama sekali. Tulis kutip satu di luar, kutip dua di dalam.
Lupa bahwa hx-vals menimpa field. Kunci yang sama dengan nama kotak isian mengganti nilainya tanpa peringatan.
hx-params="none" bersama hx-vals. Gak ada yang terkirim, termasuk nilai hx-vals.
Lupa nilainya di latihan. Tombolnya butuh hx-post="/api/action", hx-vals='{"action": "approve", "id": 42}', dan hx-target="#result" yang menunjuk elemen yang ada.

TL;DR: hx-vals='{"status": "Disetrika"}' menambahkan nilai JSON ke request: ke body untuk POST, ke URL untuk GET (?page=2). Bungkus dengan kutip satu, karena JSON butuh kutip dua, dan JSON yang rusak membuat request gak dikirim. Nilai hx-vals ditaruh sesudah field form dan menimpa field yang namanya sama. hx-params menyaring di akhir: * (bawaan), not perkiraan, nama,berat, atau none, dan ikut menyaring hx-vals. js: menjalankan JavaScript, jadi jangan isi dengan teks dari pengguna.