Polja obrazca: Combo Box

1. Pregled in namen

Stanje: [Live]. Referenca: DevExpress-ov ASPxComboBox (pari besedilo+vrednost, izbiren prost vnos besedila).

2. Predpogoji

3. Pojmi

Osnova brez JS: nativen <select>. Brez JavaScripta combo box izriše nativen <select><option>…</option></select> — povsem funkcionalen, vključno s tipkovniškim iskanjem po prvi črki brskalnika. scripts/formfields.js (postopno izboljšanje) bi pri $opts['filterable'] => true čez seznam možnosti postavil iskalno besedilno polje — osnovni <select> ostane polje POST.

4. Prvi koraki

echo $widgets->comboBox([
    'name'    => 'engine',
    'label'   => 'Podatkovni pogon',
    'value'   => 'sqlite',
    'options' => [
        ['value' => 'sqlite', 'label' => 'SQLite'],
        ['value' => 'mysql',  'label' => 'MySQL'],
        ['value' => 'pgsql',  'label' => 'PostgreSQL'],
    ],
]);

Napačno: uporabiti allowUserInput ⇒ true brez strežniške validacije glede na znan seznam vrednosti, kadar vrednost nato konča v poizvedbi SQL (glej odsek 7, Varnost).

5. Uporaba

Potreba	Vzorec
Fiksen seznam vrednosti	`options` brez `allowUserInput`
Seznam vrednosti z rezervo prostega besedila	`allowUserInput ⇒ true` — izriše `<input list>`+`<datalist>` namesto `<select>`
Poljubna vsebina pojavnega okna namesto fiksnega seznama	Dropdown Editor

6. API referenca

Metoda comboBox(array $opts): string v helper_plugin_wkfluentui_widgets.

7. Parametri, možnosti in stanja

Ključ	Tip	Pomen
`options`	array `[['value' => string, 'label' => string], …]`	seznam možnosti, `label` ubežan prek `hsc()`
`allowUserInput`	bool	dovoli prosto besedilo ob seznamu (analogno `ASPxComboBox.AllowUserInput`) — zahteva dodatno besedilno polje, saj nativen `<select>` ne pozna prostega vnosa: pri `true` polje namesto tega izriše `<input list="…">` z `<datalist>` (nativni ustreznik HTML5)
`filterable`	bool	sprotno filtriranje seznama možnosti prek tipkovnice (postopno izboljšanje JS)

Varnost: allowUserInput ⇒ true brez strežniške validacije glede na znan seznam vrednosti, kadar vrednost nato konča v poizvedbi SQL (CWE-89) — prosto besedilo iz combo box ni nič bolj zaupanja vredno kot katero koli drugo polje obrazca.

8. Popolni primeri

echo $widgets->comboBox([
    'name'            => 'oznaka',
    'label'           => 'Oznaka',
    'options'         => $znaneOznake,
    'allowUserInput'  => true,
]);

9. Omejitve in robni primeri

Nobenih onkraj strani funkcij.

10. Dostopnost in združljivost

Celoten pregled: Accessibility.

11. Odpravljanje težav

Se ne uporablja.

12. Sorodne teme

predstavitveni pregled — vsaka kategorija
Polja obrazca: Dropdown Editor — prosta vsebina namesto seznama besedilo+vrednost
Polja obrazca: osnove — skupna pogodba polj