Tovább a tartalomhoz
Tudástár

Kérdőívek készítése QML-lel

Ez az útmutató bemutatja, hogyan készíthet kérdőíveket QML-lel (Questionnaire Markup Language), amely egy YAML-alapú nyelv összetett kérdőívekhez, formális ellenőrzéssel, dinamikus folyamatvezérléssel és adatvalidálással.

Kérdőívszerkesztő az Armigerben

Az Armiger böngészős szerkesztője: a projektböngésző és az MI-generálás csevegője (balra), a QML-kód (középen), a folyamatábra és a kiválasztott kérdés élő előnézete (jobbra).

Minden QML-kérdőív ezzel a szerkezettel kezdődik:

qmlVersion: "2.0"
questionnaire:
title: "Your Survey Title"
blocks:
- id: b_first_section
title: "First Section"
items:
- id: q_first_question
kind: Question
title: "Your first question"
input:
control: Radio
labels:
1: "Option 1"
2: "Option 2"

A qmlVersion mező adja meg, hogy a dokumentum a QML melyik főverziójához készült. A jelenlegi főverzió a 2, ezért "2.0" értéket adjon meg (vagy "2.1" értéket, ha a legújabb opcionális funkciókat is használni szeretné). A régi 1.x nyelvtanhoz írt dokumentumok már nem tölthetők be, ezeket migrálni kell. A teljes nyelvtant, az elemtípusokat és a haladó blokkokat a QML-szintaxis referenciája ismerteti.

Egy blokknak három feladata van:

  • Csoportosítás: az összetartozó kérdéseket egy szakaszba gyűjti.
  • Elágazás: az előfeltétele a benne lévő összes kérdésre érvényes, így egyetlen feltétel dönti el, hogy a válaszadó látja-e a teljes szakaszt.
  • Ismétlés: egy Roster blokk a kérdéseit minden kiválasztott entitásra egyszer teszi fel (lásd: Haladó blokktípusok).

A legegyszerűbb felhasználás a csoportosítás:

blocks:
- id: b_demographics
title: "About You"
items:
# Questions about the respondent
- id: b_preferences
title: "Your Preferences"
items:
# Questions about preferences

A blokkoknak saját előfeltételeik is lehetnek. Ha egy blokknak van előfeltétele, az automatikusan a blokk minden elemére vonatkozik – nem kell ugyanazt a feltételt minden kérdésnél megismételnie.

blocks:
- id: b_employment
title: "Employment Details"
precondition:
- predicate: q_employed.outcome == 1
items:
- id: q_job_title
kind: Question
title: "What is your job title?"
input:
control: Dropdown
labels:
1: "Manager"
2: "Professional"
3: "Technician"
- id: q_years_employed
kind: Question
title: "How many years have you worked there?"
input:
control: Editbox
min: 0
max: 50

Ebben a példában a q_job_title és a q_years_employed is örökli a blokk q_employed.outcome == 1 előfeltételét. Az elemek saját, további előfeltételeket is megadhatnak – a blokk előfeltétele és az elemszintű előfeltételek együtt érvényesülnek.

Bevált gyakorlatok:

  • Használjon beszédes, b_ előtaggal kezdődő azonosítókat (pl. b_demographics, b_experience)
  • Csoportosítsa a tematikusan összetartozó kérdéseket
  • Ha lehetséges, a függőségeket tartsa blokkon belül
  • Ha két vagy több kérdésnek ugyanaz a megjelenítési feltétele, tegye őket saját blokkba, és a feltételt egyszer, a blokknál írja meg; elemszintű előfeltételt csak az adott kérdésre jellemző feltételhez használjon
  • A blokk előfeltétele a blokk előtti kérdések válaszait és változóit olvassa, ezért a blokkot az azt eldöntő kérdés után helyezze el

Alapértelmezés szerint a blokk egy Group, amely minden elemét egyszer kérdezi meg. Két opcionális változat dinamikusabb kérdőívekhez nyújt megoldást:

  • Ismétlődő szakaszok (Roster) – egy kérdéssort minden kiválasztott elemre megismétel (például ugyanazokat a részleteket kérdezi meg a válaszadó által elfogyasztott minden étkezésről vagy minden családtagról).
  • Adaptív kiválasztás (count) – egy Group blokkot úgy korlátoz, hogy csak az első N szóba jövő elemet kérdezze meg (például egy nagyobb kérdéskészletből 3 kérdést mutat).

Mindkettőt részletesen, példákkal ismerteti a QML-szintaxis referenciája.

A QML négy elemtípust támogat:

Szöveget jelenít meg válasz gyűjtése nélkül:

- id: q_intro
kind: Comment
title: "Please answer honestly. Your responses are confidential."

Egy kérdést tesz fel, és egy választ gyűjt:

- id: q_age
kind: Question
title: "What is your age?"
input:
control: Editbox
min: 18
max: 120
Szekció neve “3. QuestionGroup (több összetartozó kérdés)”

Több kérdést tesz fel azonos válaszformátummal:

- id: q_satisfaction
kind: QuestionGroup
title: "Rate your satisfaction with:"
questions:
- "Customer service"
- "Product quality"
- "Delivery speed"
input:
control: Radio
labels:
1: "Very Dissatisfied"
2: "Dissatisfied"
3: "Neutral"
4: "Satisfied"
5: "Very Satisfied"

Sorok és oszlopok szerinti formátumban gyűjti a válaszokat:

- id: q_skills
kind: MatrixQuestion
title: "Rate your proficiency in:"
rows:
- "Python"
- "JavaScript"
- "SQL"
columns:
- "Beginner"
- "Intermediate"
- "Advanced"
input:
control: Radio
labels:
1: "No experience"
2: "Some experience"
3: "Proficient"

Minden kérdésnek meg kell adnia, hogyan gyűjti a válaszokat.

Kétértékű választás:

input:
control: Switch
on: "Yes"
off: "No"

Egy lehetőség kiválasztása több közül:

input:
control: Radio
labels:
1: "Option A"
2: "Option B"
3: "Option C"

Nulla vagy több lehetőség kiválasztása:

input:
control: Checkbox
labels:
1: "Feature A"
2: "Feature B"
4: "Feature C"
8: "Feature D"

Tömör kiválasztás sok lehetőség közül:

input:
control: Dropdown
labels:
1: "High School"
2: "Bachelor's"
3: "Master's"
4: "PhD"
left: "Education:"

Szabad számbevitel:

input:
control: Editbox
min: 0
max: 1000000
left: "Annual income: $"

Vizuális kiválasztás egy skála mentén:

input:
control: Slider
min: 0
max: 10
step: 1
labels:
0: "Not at all"
5: "Somewhat"
10: "Extremely"

Intervallum kiválasztása két csúszkafogóval (-tól -ig). A válasz egy [low, high] pár, ahol min <= low <= high <= max.

input:
control: Range
min: 0
max: 100
step: 5
labels:
0: "Minimum"
50: "Mid"
100: "Maximum"
default: [20, 80]

Nyitott, kvalitatív válaszokhoz használja a Textarea vezérlőt. Minden más vezérlővel ellentétben az eredménye karakterlánc, nem egész szám – ezért nem használható elágazási logikában vagy formális ellenőrzésben (ha egy előfeltétel, utófeltétel vagy kódblokk egy Textarea eredményére hivatkozik, az tervezési hiba). Olyan megjegyzésekhez, javaslatokhoz vagy magyarázatokhoz használja, amelyeket később el szeretne olvasni vagy kódolni.

input:
control: Textarea
placeholder: "Tell us more..."
maxLength: 500

A placeholder (az üres mezőben megjelenő tippszöveg) és a maxLength (karakterkorlát) egyaránt elhagyható.

Kérdések feltételes megjelenítése (előfeltételek)

Szekció neve “Kérdések feltételes megjelenítése (előfeltételek)”

Előfeltételekkel a korábbi válaszoktól függően jeleníthet meg kérdéseket:

- id: q_has_car
kind: Question
title: "Do you own a car?"
input:
control: Switch
- id: q_car_brand
kind: Question
title: "What brand is your car?"
precondition:
- predicate: q_has_car.outcome == 1
input:
control: Dropdown
labels:
1: "Toyota"
2: "Honda"
3: "Ford"

A q_car_brand kérdés csak akkor jelenik meg, ha a válaszadó „Igen”-nel válaszolt arra, hogy van-e autója.

Összetett előfeltételek:

precondition:
- predicate: q_age.outcome >= 25 and q_employment.outcome in [1, 2, 3]

Az elágazások áttekintése: a diagram fanézete

Szekció neve “Az elágazások áttekintése: a diagram fanézete”

A QML melletti folyamatábrának két nézete van, amelyek között a bal felső sarokban található Sorrend és Fa gombokkal válthat.

  • A Sorrend (az alapértelmezett) minden kérdést abban a sorrendben mutat, ahogyan az interjú felteszi őket, mellettük a feltételeikkel.
  • A Fa ugyanezeket a kérdéseket elágazásokként mutatja. Az azonos feltételű kérdések – akár a blokkjukon szerepel a feltétel, akár minden kérdésnél megismétlődik – egy ágat alkotnak, és az az ág, amelynek feltétele csak egy másikon belül teljesülhet, annak belsejében jelenik meg. Egy szűrőkérdés „igen” és „nem” ágai egymás mellett láthatók, az a kiegészítő kérdés pedig, amelyet csak az „igen” ágon tesznek fel, ebbe az ágba ágyazva jelenik meg.

Az összefüggéseket a Z3 bizonyítja, nem a szövegből következtetünk rájuk. A fát a rendszer akkor számítja ki, amikor átvált rá, ezért az első váltás eltart egy pillanatig; ha nem számítható ki, a diagram a sorrendnézetben marad, és megmondja, miért. Minden ág címkéje azt jelzi, mit állapított meg a Z3:

Jelölés Jelentés
vagy-vagy Ez az ág és a szomszédja soha nem érvényes egyszerre: a válaszadó vagy az egyik, vagy a másik utat járja be
párhuzamos Mindkettő érvényes lehet ugyanarra a válaszadóra: opcionális szakaszok, amelyeket akár mindkettőt is feltehetnek
? kizáró, ? beágyazott, ? teljesül A Z3 nem tudta eldönteni (például egy olyan feltételnél, amelyet nem tud teljesen kifejezni, vagy egy olyannál, amely egy válaszra vagy számított értékre vonatkozik az interjú két különböző pontján): az ág ott jelenik meg, ahol bizonyított, a jelölés pedig megmondja, mi maradt eldöntetlen
soha / mindig Az ág feltétele soha nem teljesülhet, illetve mindig teljesül

Két azonos feltételszövegű kérdés csak akkor alkot egy ágat, ha a feltétel mindkettőnél ugyanazt jelenti: ha a kettő között egy kódblokk megváltoztat egy változót, amelyet a feltétel olvas, mindkettő saját ágat kap.

Az utófeltételek nem ágaznak el, ezért mindkét nézetben a kérdéseik mellett maradnak.

A válaszok ellenőrzése (utófeltételek)

Szekció neve “A válaszok ellenőrzése (utófeltételek)”

Utófeltételekkel biztosíthatja a logikai következetességet:

- id: q_household_size
kind: Question
title: "How many people live in your household?"
input:
control: Editbox
min: 1
max: 20
- id: q_children
kind: Question
title: "How many children under 18 live in your household?"
postcondition:
- predicate: q_children.outcome < q_household_size.outcome
hint: "Number of children must be less than household size"
input:
control: Editbox
min: 0
max: 15

Ha egy válaszadó érvénytelen adatot ad meg (pl. 5 gyereket egy háromfős háztartásban), megjelenik a tippüzenet.

A QML beágyazott Python-kódot tesz lehetővé számításokhoz és dinamikus logikához.

A codeInit segítségével állíthatja be a nyilvántartásra szolgáló segédváltozókat:

questionnaire:
codeInit: |
total_score = 0
risk_level = 0

Kódblokkokat csatolhat az elemekhez számítások futtatásához:

- id: q_satisfaction
kind: Question
title: "Rate your overall satisfaction (0-10)"
codeBlock: |
# Calculate satisfaction category
if q_satisfaction.outcome >= 9:
satisfaction_category = 3 # Promoter
elif q_satisfaction.outcome >= 7:
satisfaction_category = 2 # Passive
else:
satisfaction_category = 1 # Detractor
# Add to running total
total_score += q_satisfaction.outcome
input:
control: Slider
min: 0
max: 10

A QML-kód sandboxban fut, de a Pythonnak csak egy részhalmaza fordítható le arra a formális (Z3) modellre, amely a kérdőívét ellenőrzi. Maradjon ezen a részhalmazon belül, hogy a logikájára kiterjedjen az ellenőrzés:

✓ Ellenőrzött részhalmaz:

  • Aritmetika: +, -, *, //, %
  • Összehasonlítások: <, <=, >, >=, ==, != (láncolva is, pl. 0 < x < 10)
  • Tartalmazás: in, not in (pl. q_x.outcome in [1, 2, 3])
  • Logikai műveletek: and, or, not
  • Feltételes utasítások: if, elif, else
  • Háromoperandusú kifejezések: x = 1 if condition else 0
  • For ciklusok: for i in range(n) (n ≤ 20)
  • Lista-, tuple- és halmazliterálok (≤ 20 elem)
  • Tuple-kibontás: a, b = 1, 0
  • Értékadás: x = value, x += value
  • Beépített függvények: range(), abs(), int(), bool()
  • Eredmények elérése: q_age.outcome

✗ Az ellenőrzött részhalmazon kívül (lásd az alábbi megjegyzést):

  • Importok, függvények, osztályok
  • While ciklusok, break, continue
  • Szótárműveletek
  • Karakterlánc-metódusok
  • Listaértelmezések (list comprehension)
  • Print utasítások (a rendszer jelzés nélkül figyelmen kívül hagyja őket)

A kérdéseket a korábbi válaszok alapján fokozatosan jelenítse meg. Blokkszintű előfeltételekkel elkerülheti, hogy ugyanazt a feltételt minden elemnél meg kelljen ismételnie:

- id: b_screening
items:
- id: q_employed
kind: Question
title: "Are you currently employed?"
input:
control: Switch
- id: b_employment
precondition:
- predicate: q_employed.outcome == 1
items:
- id: q_job_title
kind: Question
title: "What is your job title?"
input:
control: Dropdown
labels:
1: "Manager"
2: "Professional"
3: "Technician"
- id: q_years_employed
kind: Question
title: "How many years have you worked there?"
input:
control: Editbox
min: 0
max: 50

A q_job_title és a q_years_employed automatikusan örökli a blokk előfeltételét – csak akkor jelennek meg, ha a válaszadónak van munkája.

Pontszámok kiszámítása és a válaszadók kategorizálása:

questionnaire:
codeInit: |
risk_score = 0
blocks:
- id: b_assessment
items:
- id: q_factor1
kind: Question
title: "Do you smoke?"
codeBlock: |
if q_factor1.outcome == 1:
risk_score += 20
input:
control: Switch
- id: q_factor2
kind: Question
title: "Do you exercise regularly?"
codeBlock: |
if q_factor2.outcome == 0:
risk_score += 15
input:
control: Switch
- id: q_result
kind: Comment
title: "Assessment complete"
codeBlock: |
if risk_score >= 30:
risk_category = "high"
elif risk_score >= 15:
risk_category = "moderate"
else:
risk_category = "low"

Biztosítsa a válaszok minőségét elemek közötti ellenőrzéssel:

- id: q_age
kind: Question
title: "Your age"
input:
control: Editbox
min: 18
max: 100
- id: q_work_experience
kind: Question
title: "Years of work experience"
postcondition:
- predicate: q_work_experience.outcome <= (q_age.outcome - 16)
hint: "Work experience cannot exceed your potential working years"
input:
control: Editbox
min: 0
max: 60
  • Legyen konkrét: „Mennyi a háztartása éves jövedelme?” a „Jövedelem?” helyett
  • Használjon megfelelő vezérlőket: Editbox a pontos számokhoz, Slider a szubjektív értékelésekhez
  • Állítson be reális tartományokat: a min/max értékek tükrözzék a valós korlátokat
  • Adjon kontextust: a mértékegységekhez és pontosításokhoz használja a left/right szöveget
  • Tartsa együtt az összetartozó elemeket ugyanabban a blokkban
  • A sorrend számít: a kérdéseknek meg kell előzniük azokat a helyeket, ahol hivatkoznak rájuk
  • Tesztelje az összes útvonalat: győződjön meg róla, hogy minden kérdés elérhető
  • Állítson be értéktartomány-korlátokat a beviteli vezérlő min/max értékeivel
  • Használjon utófeltételeket a logikai következetességhez
  • Adjon hasznos tippeket: az egyértelmű hibaüzenetek eligazítják a válaszadókat
  • Gondoljon a szélsőséges esetekre: mi történik, ha valaki szélsőséges értéket ad meg?
  • Inicializáljon korán: a változókat a codeInit részben állítsa be
  • Törekedjen az egyszerűségre: az összetett számításokban nehéz megtalálni a hibát
  • Gondoljon a hatókörre: minden változó globális
  • Teszteljen alaposan: futtassa a kérdőív-ellenőrzőt

A rendszer a QML-kérdőíveket automatikusan ellenőrzi a következők szempontjából:

  • Elérhetőség: elérhető-e minden kérdés?
  • Konzisztencia: teljesíthetők-e az ellenőrzési szabályok?
  • Körök: alkotnak-e kört a függőségek?
  • Teljesség: van-e legalább egy érvényes kitöltési útvonal?

Az ellenőrző matematikai elemzéssel (SMT-megoldással) még az élesítés előtt felismeri a tervezési hibákat.

A matematikai részleteket az Elmélet fejezet tartalmazza.

Ha ugyanazt a kérdőívet több nyelven szeretné felvenni, másolás helyett adjon hozzá fordításokat: a fordítás csak a szöveget cseréli le, így az ellenőrzés, az elágazások és a válaszkódok az Ön által írt kérdőívhez kötődnek.

qmlVersion: "2.0"
questionnaire:
title: "Customer Feedback Survey"
codeInit: |
nps_score = 0
follow_up_needed = 0
blocks:
- id: b_intro
title: "Welcome"
items:
- id: q_welcome
kind: Comment
title: "Thank you for taking our survey. It will take about 3 minutes."
- id: b_experience
title: "Your Experience"
items:
- id: q_nps
kind: Question
title: "How likely are you to recommend us? (0 = Not at all, 10 = Extremely likely)"
codeBlock: |
nps_score = q_nps.outcome
if nps_score <= 6:
follow_up_needed = 1
input:
control: Slider
min: 0
max: 10
labels:
0: "Not likely"
5: "Maybe"
10: "Very likely"
- id: q_reason
kind: Question
title: "What is the primary reason for your score?"
precondition:
- predicate: follow_up_needed == 1
input:
control: Dropdown
labels:
1: "Product quality"
2: "Customer service"
3: "Pricing"
4: "Other"
- id: q_aspects
kind: QuestionGroup
title: "Please rate these aspects:"
questions:
- "Product quality"
- "Customer service"
- "Value for money"
input:
control: Radio
labels:
1: "Poor"
2: "Fair"
3: "Good"
4: "Excellent"
- id: b_closing
title: "Thank You"
items:
- id: q_comments
kind: Comment
title: "Thank you for your valuable feedback!"