Helpcentrum

CheckMarket Scripting Language (CSL)

Geen reacties

CheckMarket biedt een krachtige scriptingtaal aan om je enquêtes en rapporten te verbeteren, zogenaamd de CheckMarket Scripting Language of CSL.

Op haar meest elementaire niveau is de CSL laagdrempelig en eenvoudig te gebruiken. Je kan de scriptingtaal gebruiken om variabelen in je rapport te plaatsen door ze te selecteren in een drop-down menu.

Op haar meest geavanceerde niveau, geeft onze CSL je enorme vrijheid om complexe logica te gebruiken teneinde berekeningen te maken, bepaalde tekstblokken of afbeeldingen te tonen of te verbergen en zo meer. Zet dus je technisch denkhoedje op en laten we erin vliegen … !

Basisbegrippen

Syntax

Variabelen in deze scriptingtaal worden ingesloten door dubbele accolades, zoals deze: {{eenVariabele}}. Deze zijn niet hoofdlettergevoelig, dus {{EenVariabele}} is hetzelfde als {{eenVariabele}}.

Hiërarchie

De variabelen zijn hiërarchisch, je kunt er dus doorheen navigeren door een puntnotatie te gebruiken.
Bijvoorbeeld:

  • Rapporttitel: {{report.title}}
  • Rapportfiltertitel: {{report.filter.title}}
  • Titel van het eerste rapportelement: {{report.elements.1.title}}
  • Titel van het rapportelement met ID 123: {{report.elements.id-123.title}}
  • Label van de eerste antwoordoptie van de vraag van de eerste databron van het eerste rapportelement: {{report.elements.1.data.1.question.answeroptions.1.label}}

Variabelen

Waar vind je de variabelen die beschikbaar zijn?

  • Enquêtevariabelen: vind je achter de knop ‘variabelen’ op de takenbalk in de tekstbewerker van je vragen, e-mails, meldingen, …
    Er is ook een uitgebreide lijst van alle enquêtevariabelen.

 

  • Rapportvariabelen: vind je in de teksteditor van de ReportBuilder door rechts in het eigenschappenvenster onder ‘Opmerkingen’ op de knop Uitvouwen expand icon te klikken. Vervolgens opent zich een teksteditor met het menu Variabelen:

Geavanceerde operatoren

Deze scriptingtaal ondersteunt meer dan enkel variabelen. Door gebruik te maken van speciale operatoren kan je je eigen logica inbouwen. Om je een idee te geven, hieronder een voorbeeld:

{{#if (eq element.title "Kruistabel")}}
  De titel van dit element is Kruistabel.
{{/if}}

In bovenstaand voorbeeld kijken we na of de titel van het rapportelement gelijk is aan “Kruistabel”. Als dit correct is, tonen we “De titel van dit element is Kruistabel”. Als dit niet het geval is, tonen we niets.

Lijst van operatoren

Je kunt blokoperatoren gebruiken om inhoud te tonen/verbergen, afhankelijk van je eigen logica.

OperatorOmschrijving
ifGebruik de if-helper om een blok voorwaardelijk weer te geven. Als de voorwaarde false, null, “”, 0 of [] retourneert, wordt het blok niet getoond.
{{#if (and title description)}}
  Deze tekst wordt enkel getoond als er een titel én een omschrijving is.
{{/if}}
if + elseSpecificeer een else-blok dat dient te worden weergegeven als niet aan de eerste voorwaarde is voldaan.
{{#if contact}}
  <h1>{{contact.firstName}} {{contact.lastName}}</h1>
{{else}}
  <h1>Ongekende respondent</h1>
{{/if}}
else ifCombineer meerdere #if blokken met else if. Het systeem zal elke ‘if’ in volgorde evalueren tot het er één vindt die voldoet aan de voorwaarde (die dus ‘waar’ is) of tot het de ‘else’ (anders) blok bereikt. Zodra één van de ‘if’ blokken waar is, dan worden de daaropvolgende blokken genegeerd, zelfs als deze ook voldoen aan de voorwaarden.
{{#if contact}}
  <h1>{{contact.firstName}} {{contact.lastName}}</h1>
{{else if respondent.questions.yourName}}
  <h1>{{respondent.questions.yourName}}</h1>
{{else}}
  <h1>Ongekende respondent</h1>
{{/if}}
unlessGebruik de unless-helper als omgekeerde van de if-helper. De inhoud wordt dan weergegeven als niet aan de voorwaarde is voldaan (als de waarde false, null, “, 0 of [] is).
{{#unless response}}
<h3 class="opgelet">Opgelet: Er is geen antwoord!</h3>
{{/unless}}
eachBlader door een lijst met de ingebouwde each-operator. In het blok kan je dit gebruiken om te verwijzen naar het doorzochte element of om onmiddellijk onderliggende eigenschappen te gebruiken.
<ul>
  {{#each report.elements}}
    <li>{{title}}</li>
  {{/each}}
</ul>
each + elseSamen met een each-operator, kan je optioneel een else-sectie voorzien die enkel getoond word als de lijst leeg is.
{{#each report.elements}}
  <h2>{{title}}</h2>
{{else}}
  <p>Geen elementen in deze lijst!</p>
{{/each}}

Door gebruik te maken van logische operatoren kan je variabelen vergelijken en controleren. Deze operatoren worden het vaakst gebruikt binnen blokoperatoren zoals #if.

Logische operatoren worden ingesloten tussen haakjes, zoals: (eq element.title “Kruistabel”). Het eerste woord is de operator, gevolgd door de voorwaarden. De condities kunnen variabelen, platte tekst of nummers zijn. Tekst moet tussen enkele aanhalingstekens geplaatst worden.

OperatorOmschrijving
andGebruik dit als alle condities waar moeten zijn.
{{#if (and share filter)}}
  Deze tekst is enkel zichtbaar als dit een share is én er een filter actief is.
{{/if}}
orGebruik dit als een van de condities waar moet zijn.
{{#if (or share filter)}}
   Deze tekst is enkel zichtbaar als dit een share is
   óf als er een filter actief is.
{{/if}}
eqGebruik dit om te controleren of twee condities gelijk zijn.
{{#if (eq element.title "Kruistabel")}}
  De elementtitel is Kruistabel!
{{/if}}
neGebruik dit om te controleren of twee condities niet gelijk zijn.
{{#if (ne element.title "Kruistabel")}}
  De elementtitel is niet Kruistabel!
{{/if}}
ltGebruik dit om te controleren of de eerste voorwaarde kleiner is dan de tweede.
{{#if (lt counter 12)}}
  De teller-waarde ({{counter}}) is kleiner dan 12!
{{/if}}
gtGebruik dit om te controleren of de eerste voorwaarde groter is dan de tweede.
{{#if (gt counter 12)}}
  De teller-waarde ({{counter}}) is groter dan 12!
{{/if}}
leGebruik dit om te controleren of de eerste voorwaarde gelijk of kleiner is dan de tweede.
{{#if (le counter 12)}}
  De teller-waarde ({{counter}}) is kleiner dan of gelijk aan 12!
{{/if}}
geGebruik dit om te controleren of de eerste voorwaarde groter dan of gelijk is aan de tweede.
{{#if (ge counter 12)}}
  De teller-waarde ({{counter}}) is groter dan of gelijk aan 12!
{{/if}}
containsGebruik dit om te controleren of de tekst van de eerste voorwaarde, de tweede voorwaarde bevat.
{{#if (contains element.title "gelukkig")}}
De elementtitel bevat het woord "gelukkig".
{{/if}}

Gebruik wiskundige operatoren om met getallen te werken. Je kunt berekeningen uitvoeren of bepalen hoe cijfers dienen te worden weergegeven.

OperatorOmschrijving
addTel twee of meer getallen op.
10 + 5 = {{add 10 5}}
Resultaat: 10 + 5 = 15
subtractTrek twee of meer getallen af.
10 - 5 = {{subtract 10 5}}
Resultaat: 10 - 5 = 5
multiplyVermenigvuldig twee of meer getallen.
10 * 5 = {{multiply 10 5}}
Resultaat: 10 * 5 = 50
divideDeel twee of meer getallen.
10 / 5 = {{divide 10 5}}
Resultaat: 10 / 5 = 2
averageAverage two or more numbers.
The average of the numbers 1,2,3,4 = {{average 1 2 3 4}}
Result: (1+2+3+4) / 4 = 2.5
sqrtTrek de vierkantswortel uit een getal.
De vierkantswortel van 25 is {{sqrt 25}}
Resultaat: De vierkantswortel van 25 is 5
powBereken het eerste getal tot de macht van het tweede.
Drie tot de tweede macht is {{pow 3 2}}
Resultaat: Drie tot de tweede macht is 9
modBereken de rest na deling van het eerste getal door het tweede.
5 % 4 = {{mod 5 4}}
Resultaat: 5 % 4 = 1
absGeef de absolute waarde van een getal weer.
De absolute waarde van -10 is {{abs -10}}
Resultaat: De absolute waarde van -10 is 10
roundRond een getal af volgens het aantal opgegeven cijfers. Als er geen cijfers zijn opgegeven, wordt het getal afgerond op 0 cijfers na de komma.
De eerste afgeronde waarde is {{round 25.9999}}, de tweede is {{round 12.123456 2}}
Resultaat: De eerste afgeronde waarde is 26. De tweede is 12.12
randomGenereer een willekeurig getal tussen de gespecificeerde cijfers.
Een willekeurig getal tussen 5 en 10 is {{random 5 10}}
Resultaat: Een willekeurig getal tussen 5 en 10 is bijvoorbeeld 8
random + excludeGenereer een willekeurig getal en sluit daarbij specifieke waarden uit. U kunt zoveel waarden uitsluiten als u wenst.
Een willekeurig getal tussen 5 en 10, 
waarbij 7 en 8 worden uitgesloten {{random 5 10 7 8}}
Resultaat: Een willekeurig getal tussen 5 en 10,
waarbij 7 en 8 worden uitgesloten, is bijvoorbeeld 9
countToon een telling van het aantal items uit een lijst (array).
Er zijn {{count report.elements}} elementen in dit rapport.
Resultaat: Er zijn 3 elementen in dit rapport
kFormatteer een nummer in een K-notatie.
{{k 12468}}
Resultaat: 12K
decKies expliciet een decimaal scheidingsteken.
{{dec 12.3 ","}}
Resultaat: 12,3

Gebruik deze operatoren voor het tonen of bewerken van datums en tijden.

OperatorOmschrijving
currentDateGeef de huidige datum en tijd weer in de datumnotatie en tijdzone van de enquête eigenaar.
Vandaag is het {{currentDate}}.
Resultaat: Vandaag is het 08/17/2000 4:14 PM.
.isoVoeg toe aan elke datum om de datum in ISO-indeling te krijgen. Dit formaat is machinaal leesbaar. Gebruik dit bij pre-filling.
Vandaag is het {{currentDate.iso}}.
Resultaat: Vandaag is het 2000-08-17 16:14.
.utcVoeg toe aan elke datum om de datum in ISO 8601-indeling in de UTC-tijdzone te krijgen. Dit formaat is machinaal leesbaar en kan gebruikt worden bij het verzenden van een datum naar een database of API
Vandaag is het {{currentDate.utc}}.
Resultaat: Vandaag is het 2000-08-17T14:14Z.
.dateVoeg toe aan elke datum om alleen de datum weer te geven zonder de tijd.
Vandaag is het {{currentDate.date}}.
Resultaat : Vandaag is het 08/17/2000.
.timeVoeg toe aan elke datum om alleen de tijd weer te geven zonder de datum.
Het is nu {{currentDate.time}}.
Resultaat: Het is nu 4:14 PM.
.year
.month
.day
.hour
Voeg toe aan elke datum om een deel ervan weer te geven.
Je bent geboren in {{contact.dateOfBirth.year}}.
Resultaat: Je bent geboren in 1970.
dateFormatToon een datum in een opgegeven formaat.
Uw geboortedatum: {{dateFormat contact.dateOfBirth "d MMMM yyyy"}}
Resultaat: Uw geboortedatum: 12 februari 1987

Enkele voorbeelden van formaten die je kunt gebruiken:

d: 17-8-2000
D: donderdag 17 augustus 2000
f: donderdag 17 augustus 2000 16:32
F: donderdag 17 augustus 2000 16:32:32
g: 17-8-2000 16:32
G: 17-8-2000 16:32:32
m: 17 augustus
r: do, 17 aug 2000 16:32:32 GMT
s: 2000-08-17T16:32:32
t: 16:32
T: 16:32:32
u: 2000-08-17 16:32:32Z
U: donderdag 17 augustus 2000 14:32:32
y: augustus 2000
dddd, dd MMMM yyyy: donderdag, 17 augustus 2000
dddd, dd MMMM: donderdag, 17 augustus
M/yy: 8-00
dd-MM-yy: 17-08-00
dateAddTel een tijdspanne op bij een datum.
Benodigde parameters: datum, aantal tijdseenheden die je wilt toevoegen (aftrekken kan d.m.v. een negatieve waarde) en de tijdseenheid zelf.
De tijdseenheid moet één van deze zijn (in het Engels): year, month, day, hour, minute en second.
Voor {{dateFormat (dateAdd respondent.dateResponded 3 "day") "D"}} 
krijg je zeker een antwoord van ons.
Resultaat: Voor donderdag 17 augustus 2000 krijg je zeker een antwoord van ons.

Opmerking: de datum wordt steeds teruggegeven in het ISO 8601 formaat. Gebruik dateFormat om de datum op een andere manier weer te geven.

dateDiffBereken het verschil tussen twee datums.
Benodigde parameters: startdatum, einddatum en tijdseenheid.
De tijdseenheid moet één van deze zijn (in het Engels): year, month, day, hour, minute en second.
We hebben je {{dateDiff contact.dateInvited currentDate "day"}} 
dagen geleden uitgenodigd.
Resultaat: We hebben je 3 dagen geleden uitgenodigd.

Gebruik deze operatoren om tekst weer te geven of te bewerken.

OperatorOmschrijving
upperCaseZet de tekst om in hoofdletters.
{{upperCase "Een beetje tekst"}}
Resultaat: EEN BEETJE TEKST
lowerCaseZet de tekst om naar kleine letters.
{{lowerCase "Een beetje TEKST"}}
Resultaat: een beetje tekst
trimVerwijder witruimte aan het begin en aan het einde van tekst.
{{trim "  Een beetje tekst  "}}
Resultaat: Een beetje tekst
urlEncodeMaak tekst geschikt voor URLs.
{{urlEncode "Een beetje tekst?"}}
Result: Een%20beetje%20tekst%3F

Gebruik dit wanneer je variabelen gebruikt in URLs die mogelijk spaties, schuine strepen of speciale karakters gebruiken. Getallen dienen niet omgezet (url-geëncodeerd) te worden.
Je kunt deze parameter bijvoorbeeld gebruiken bij een vertakking naar een externe URL of bij een link op de dankpagina.

Gebruik popups of popovers om extra informatie te tonen wanneer de respondent op een link klikt. Gebruik popups voor langere tekst of afbeeldingen, gebruik popovers voor korte stukjes informatie of om een woord te verduidelijken.

Opmerking: deze operatoren zijn enkel beschikbaar in de enquête-interface en rapporten.

OperatorOmschrijving
iconToon een icoontje. Gebruik dezelfde benaming als bij Font Awesome.
{{icon "far fa-star"}}

Resultaat:

modalToon een link om een pop-up venster te openen.
Klik {{modal "hier" "tekst in pop-up."}} voor meer informatie.
Resultaat: Klik hier voor meer informatie. 
Resultaat in het pop-up venster: Deze tekst bevindt zich in de pop-up.

Een icoon toevoegen is ook mogelijk.

Klik {{modal "hier" "tekst in pop-up" icon="fas fa-info-circle"}}!

Als de tekst binnen het pop-up venster lang is, kan je ook de variant #modal gebruiken:

{{#modal "klik hier"}}
Deze tekst kan langer zijn en kan opmaak, aanhalingstekens en variabelen bevatten.
{{/modal}}
tooltipToon een tooltip of tekstballon wanneer je de muis over iets beweegt.
Dit is een {{tooltip "NPS" "Net Promotor Score"}} vraag. 
Resultaat: Dit is een NPS vraag.
Resultaat in de tooltip: Net Promotor Score

Opmerking: aangezien er geen muis is bij mobiele apparaten, wordt een tooltip daar geactiveerd door te klikken.

Tooltips worden standaard boven de link getoond. Je kunt de locatie echter kiezen door één van volgende opties mee te geven: left, right, top of bottom.

{{tooltip "Klik hier" "Dit wordt rechts getoond" position="right"}}

Een icoon toevoegen is ook mogelijk. Voeg de FontAwesome-klasse van het icoontje dat je wilt gebruiken toe als laatste parameter.

{{tooltip "Klik hier" "Tekst hier" position="top" icon="fas fa-info-circle"}}

Als de tekst binnen de tooltip lang is, kan je ook de variant #tooltip gebruiken:

{{#tooltip "Klik hier"}}
Deze tekst kan langer zijn en kan opmaak, aanhalingstekens en variabelen bevatten.
{{/tooltip}}
popoverEen pop-over is hetzelfde als een tooltip, maar kan enkel geactiveerd worden door te klikken, niet via een mouse-over.
Dit is een {{popover "NPS" "Net Promotor Score"}} vraag.
Resultaat: Dit is een NPS vraag.
Resultaat in de pop-over: Net Promotor Score


Zie volgend artikel voor meer voorbeelden en informatie:
Tooltips, popovers en modale vensters

Gebruik tijdelijke variabelen om grote functies in kleinere delen te splitsen.

Deze variabelen worden nergens opgeslagen, ze zijn enkel tijdelijk beschikbaar binnen dezelfde pagina.

OperatorOmschrijving
setBewaar een tijdelijke waarde. Je dient een naam en een waarde te specificeren.
{{set "mijnSom" (add 1 2)}}

Om een langere tekst te bewaren kan je ook de variant #set gebruiken:

{{#set "mijnTekst"}}
Deze tekst kan langer zijn en opmaak, aanhalingstekens en variabelen bevatten.
{{/set}}

Opmerking: op dit moment wordt er nog niets weergegeven. Gebruik onderstaande functie om deze variabele op te halen.

getHaal een tijdelijke waarde op, gebruik makend van de naam die je eerder via de set operator hebt gegeven.
{{get "mijnSom"}}
Resultaat: 3

Het is mogelijk om tekst met opmaak (HTML) te combineren met CSL. Als je een variabele gebruikt die HTML-opmaak bevat, wordt die tekst met opmaak (HTML) getoond:

{{survey.questions.myDataLabel.text}}
Voorbeeldtekst met een cursief gedeelte.

Indien gewenst kan je ook alle HTML-opmaak verwijderen en alles als platte tekst weergeven door .unformatted te gebruiken:

{{survey.questions.myDataLabel.text.unformatted}}
Voorbeeldtekst met een cursief gedeelte.

Je kan ook tekst geschikt maken voor URLs door .urlEncoded te gebruiken:

{{survey.questions.myDataLabel.text.urlEncoded}}
Voorbeeldtekst%20met%20een%20cursief%20gedeelte.

Je kan al deze operatoren combineren om meer geavanceerde logica te creëren.

Een voorbeeld:

{{#if (lt element.statistics.1.nps element.statistics.2.nps)}}
Je NPS-score is lager dan de NPS-score van de volledige groep. Gelieve het NPS-actieplan te bekijken.
{{/if}}

Vertaling: ‘Als de NPS van jouw regio lager is dan de benchmark van de hele groep, toon dan een bericht’. Dat zou betekenen dat dit element twee gegevensbronnen heeft, beide van dezelfde NPS-vraag. De tweede gegevensbron is ingesteld als een benchmark, zodat deze niet beïnvloed wordt door de share filter. Aangezien gegevensbron 1 wél beïnvloed is door de share filter, kunnen de twee scores vergeleken worden.

Hulp nodig?

De CheckMarket Scripting Language biedt zeer vele toepassingsmogelijkheden, die wij uiteraard niet allemaal gratis kunnen ondersteunen. Het eigen gebruik van onze scriptingtaal (CSL) is inbegrepen in al onze prijsformules, en daarnaast bieden onze specialisten graag ondersteuning aan klanten die dat wensen.

Wil je geavanceerde enquêterapporten maken maar heb je hier zelf geen tijd voor? Heb je hulp nodig met het programmeren van een enquête of een rapport? Laat gerust een van onze projectmanagers dit voor je doen.

Vraag een prijsofferte 

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.