Datacollectie modifiers
Modifiers zijn doorgaans ontworpen om strings te manipuleren, zoals ucfirst voor het maken van een hoofdletter aan het begin van een string. Echter, er zijn ook modifiers die bedoeld zijn voor het manipuleren van reeksen van objecten. Als je een variabele hebt waarin bijvoorbeeld een verzameling van bestellingen of producten staat, dan kun je met deze collectie-modifiers zo'n verzameling filteren of sorteren.
Let op: het woord collectie heeft een dubbele betekenis! In de context van dit artikel bedoelen we met het woord collectie élke variabele met een verzameling of array van objecten. Dit kunnen dus verzamelingen van profielen, templates, bestellingen, producties, enzovoort zijn. De betekenis is dus ruimer dan wanneer we spreken over collecties binnen de profielenmodule, waar het woord collectie de betekenis heeft van een tweede laag onder een database waarin subprofielen kunnen worden opgeslagen.
Praktisch voorbeeld
Laten we een voorbeeld bekijken van hoe je deze modifiers zou kunnen gebruiken
om een datacollectie van bestellingen te manipuleren. In dit voorbeeld gaan we
uit van {$profile.bestellingen}
, een collectie van subprofielen binnen een
profiel. Elk subprofiel in deze collectie stelt een bestelling voor, met
bijvoorbeeld een status, besteldatum en totaalbedrag als eigenschappen.
{$profile.bestellingen|filter:"status":"afgerond"|orderby:"besteldatum":"desc"|limit:5}
In dit voorbeeld wordt de filter modifier gebruikt om alleen bestellingen te selecteren die tot de status "afgerond" hebben. Vervolgens sorteert de orderby modifier deze producten op basis van hun besteldatum van hoog naar laag. Tot slot beperkt de limit modifier de uitvoer tot de 5 meest recente bestellingen.
Met deze modifiers kun je handig gegevens selecteren en presenteren binnen je mailings. Om de inhoud van het resultaat te bekijken, kun je deze doorlopen met een {foreach}-loop:
{foreach $profile.bestellingen|filter:"status":"afgerond"|orderby:"besteldatum":"desc"|limit:5 as $bestelling}
- Bestelling van {$bestelling.besteldatum} met totaalbedrag {$bestelling.totaalbedrag}
{/foreach}
De meeste modifiers werken op alle soorten datacollecties, zoals verzamelingen van bestellingen, producten of subprofielen. Andere modifiers werken alleen op een specifiek type collectie, zoals profielen of subprofielen. Hieronder zie je beide overzichtelijk in twee tabellen.
Modifiers voor alle datacollecties
Modifier | Beschrijving |
---|---|
filter | filter items in een datacollectie op basis van gegeven criteria |
orderby | sorteer items in een datacollectie op basis van een veld |
map | transformeer items in een datacollectie |
limit | beperk items in een datacollectie op tot een maximum aantal |
first | neem het eerste item uit een datacollectie |
last | neem het laatste item uit een datacollectie |
min | de laagste waarde uit een collectie |
max | de hoogste waarde uit een collectie |
total | de totale waarde uit een collectie |
average | de gemiddelde waarde uit een collectie |
most | de meest voorkomende waarde in een collectie |
unique | verkrijg unieke waarden uit een datacollectie |
Modifiers voor specifieke types collecties
Modifier | Beschrijving |
---|---|
in_selection | filter profielen op basis van een selectie. Werkt enkel op profielverzamelingen. |
in_miniselection | filter subprofielen op basis van een miniselectie. Werkt enkel op subprofielverzamelingen |
Filter
De modifier 'filter' toetst alle data in een datacollectie met een gegeven voorwaarde. Alleen wanneer een veld voldoet aan de gegeven voorwaarde, wordt het doorgelaten door het filter. Je kunt dit gebruiken om bijvoorbeeld een verzameling van producten of bestellingen te reduceren tot alleen de relevante items.
{$profile.bestellingen|filter:totaalbedrag:>:15}
Zoals je in bovenstaand voorbeeld ziet, accepteert de modifier drie parameters: het veld waarop moet worden gefilterd ("totaalbedrag"), de operator (">") en de waarde ("15").
Met de operator bedoelen we de manier waarop het veld moet worden vergeleken, zoals gelijk-aan, kleiner-dan of groter-dan. Mogelijke waarden voor de operator zijn: <, <=, >, >=, =, ==, !=. Extra operators kunnen beschikbaar zijn afhankelijk van het type van de variabele waar je op filtert.
De modifier kan ook met één of twee parameters worden aangeroepen:
{$profile.bestellingen|filter:status:afgerond}
{$profile.producten|filter:sku}
Met twee parameters: hiermee voer je een ==-vergelijking uit. Bijvoorbeeld, {$profile.bestellingen|filter:status:afgerond} filtert de bestellingen met de status "afgerond".
Met één parameter: Hiermee controleer je of veld bestaat in de inkomende data en niet null is. Bijvoorbeeld, {$profile.producten|filter:sku} filtert de producten waarvoor een SKU beschikbaar is.
Opmerking: Dit werkt momenteel alleen voor top-level eigenschappen. Als veldnaam kun je dus geen geneste velden opgeven, zoals "author.nationality".
Ordering
De modifier 'orderby' sorteert alle data in een datacollectie op basis van het gegeven veld in de data waarop deze modifier wordt toegepast.
Deze modifier heeft de vorm: orderby:field:direction. De field parameter bepaalt op welk veld de gegevens gesorteerd moet worden. De direction wordt gebruikt om te specificeren in welke volgorde de data gesorteerd moet worden: asc voor oplopend, desc voor aflopend. Het is mogelijk om de orderby-modifier aan te roepen zonder direction, in welk geval asc wordt ingevuld voor de direction parameter.
{$profile.bestellingen|orderby:"totaalbedrag":"desc"}
{$profile.bestellingen|orderby:"totaalbedrag"}
Opmerking: Dit werkt momenteel alleen voor top-level eigenschappen. Als veldnaam kun je dus geen geneste velden opgeven, zoals "author.nationality".
Map
De modifier map
zet een datacollectie om naar een array van waarden uit één specifiek veld
van elk item in de collectie. Dit is handig als je bijvoorbeeld alleen de prijzen of alleen
de datums van een reeks objecten wilt ophalen.
{foreach $profile.bestellingen|map:"totaalbedrag" as $bedrag}
- Bestelling van €{$bedrag}
{/foreach}
In dit voorbeeld levert map:"totaalbedrag"
een lijst op met alle totaalbedragen uit de
bestellingen. De modifier loopt door de verzameling {$profile.bestellingen} heen, en roept
van elke bestelling de eigenschap {$bestelling.totaalbedrag} aan. Feitelijk is bovenstaande
code dus een alias voor:
{foreach $profile.bestellingen as $bestelling}
- Bestelling van €{$bestelling.totaalbedrag}
{/foreach}
De map
modifier is met name handig als je hem gebruikt in combinatie met andere modifiers:
Gemiddelde bestelwaarde: {$profile.bestellingen|map:"totaalbedrag"|average}
In bovenstaand voorbeeld zorgt de map
modifier er voor dat de lijst van bestellingen
wordt teruggebracht tot een lijst van totaalbedragen, waarna de average
modifier
hier het totaalbedrag van kan berekenen.
Limit
De modifier 'limit' beperkt de hoeveelheid items in een datacollectie. Deze modifier kan beschreven worden als: limit:aantal. De aantal parameter bepaalt het maximale aantal items die er door het filter heen gelaten wordt. Wanneer dit getal bereikt is, wordt de datacollectie afgekapt. Om bijvoorbeeld 5 bestellingen op te halen, gebruik je:
{$profile.bestellingen|limit:5}
First
De modifier 'first' pakt het eerste item uit een datacollectie en maakt daar een gewone variabele. Je gebruikt deze modifier vaak in combinatie met {assign} om een nieuwe variabele aan te maken.
{assign value=$profile.kinderen|first var="eerste_kind"}
Je eerste kind heet {$eerste_kind.naam}
Als je maar één eigenschap nodig hebt, kun je natuurlijk ook de get
-modifier
gebruiken. Hiermee spaar je een aanroep van {assign}
uit:
Je eerste kind heet {$profile.kinderen|first|get:naam}
Last
De modifier 'last' pakt het laatste item uit een datacollectie en maakt daar een gewone variabele. Je gebruikt deze modifier vaak in combinatie met {assign} om een nieuwe variabele aan te maken. Let op: deze modifier werkt niet op elke dataverzameling, omdat niet elke databron even gemakkelijk toegang verschaft tot het laatste item.
{assign value=$profile.kinderen|last var="laatste_kind"}
Je laatste kind heet {$laatste_kind.naam}
Als je maar één eigenschap nodig hebt, kun je natuurlijk ook de get
-modifier
gebruiken. Hiermee spaar je een aanroep van {assign}
uit:
Je laatste kind heet {$profile.kinderen|last|get:naam}
In_selection
De modifier in_selection
filtert een collectie van profielen op basis van een
bestaande selectie. Dit werkt alleen op collecties van profielen binnen
databases, zoals:
{$account.databases.klanten.profiles|in_selection:"Nieuwsbriefinschrijvers"}
In_miniselection
De modifier in_miniselection
filtert een subprofielverzameling op basis van een
miniselectie binnen het profiel. Dit werkt alleen op collecties van
subprofielen, zoals:
{$profile.bestellingen|in_miniselection:"Premium bestellingen"}
Min
De modifier min
haalt de laagste waarde op uit een datacollectie. Vaak gebruik je
deze in combinatie met map
om een specifiek veld te evalueren:
Laagste bestelwaarde: {$profile.bestellingen|map:"totaalbedrag"|min}
In bovenstaand voorbeeld zet map:"totaalbedrag"
de collectie van bestellingen om
in een lijst van totaalbedragen. De min
modifier geeft vervolgens het kleinste
bedrag uit deze lijst terug.
Max
De modifier max
haalt de hoogste waarde op uit een datacollectie. Dit is handig
in combinatie met map
om bijvoorbeeld de grootste bestelling te vinden:
Hoogste bestelwaarde: {$profile.bestellingen|map:"totaalbedrag"|max}
Net als bij min
wordt eerst een lijst van totaalbedragen gemaakt via map
,
waarna max
de grootste waarde selecteert.
Total
De modifier total
telt alle waarden in een datacollectie bij elkaar op. In
combinatie met map
kun je zo bijvoorbeeld de totale omzet berekenen:
Totale omzet: {$profile.bestellingen|map:"totaalbedrag"|total}
Hier wordt eerst een lijst van totaalbedragen gemaakt met map
, waarna total
alle bedragen optelt.
Average
De modifier average
berekent het gemiddelde van alle waarden in een datacollectie.
Meestal gebruik je dit samen met map
:
Gemiddelde bestelwaarde: {$profile.bestellingen|map:"totaalbedrag"|average}
In dit voorbeeld genereert map:"totaalbedrag"
een lijst van totaalbedragen,
waarna average
het gemiddelde van deze bedragen berekent.
Most
De modifier most
bepaalt welk item in een collectie het vaakst voorkomt en geeft dat item terug.
Het resultaat is altijd het laatste item in de collectie dat deze meest voorkomende waarde heeft.
Als je een collectie met eenvoudige waarden hebt (zoals strings of getallen), dan wordt gekeken
welke waarde het vaakst voorkomt.
{$kleuren = ["rood","blauw","rood","groen"]}
{$kleuren|most}
Resultaat: "rood"
(komt het vaakst voor, en de laatste "rood"
wordt teruggegeven). Als de
collectie echter uit objecten bestaat, moet je een eigenschap (property) meegeven waarop geteld wordt.
{$products|most:"kleur"}
Hier wordt gekeken naar de eigenschap kleur
van elk product. De modifier telt per kleur hoe vaak
die voorkomt en geeft het laatste product terug met de meest voorkomende kleur.
Omdat most
een volledig object teruggeeft, kun je daarna alle eigenschappen van dat object
gebruiken. Daarom combineer je most
vaak met {assign}
of de modifier `get
om het resultaat op te slaan in een variabele of direct uit te lezen.
{assign value=$profile.bestellingen|most:"category" var="populair"}
Meest bestelde categorie: {$populair.category}
In dit voorbeeld:
most:"category"
telt hoe vaak elke categorie voorkomt in de bestellingen.- Het meest voorkomende resultaat wordt opgeslagen in de variabele
$populair
. - Je kunt vervolgens rechtstreeks velden van
$populair
gebruiken, zoals.category
.
Korter kan het dus ook:
Meest bestelde categorie: {$profile.bestellingen|most|get:category}
Unique
De modifier unique
zorgt ervoor dat dubbele waarden in een datacollectie
worden verwijderd.
Als je een collectie met eenvoudige waarden hebt (zoals strings of getallen), dan worden de dubbele waarden verwijderd en blijft telkens de eerste waarde behouden:
{$kleuren = ["rood","blauw","rood","groen"]}
{$kleuren|unique}
Resultaat: ["rood","blauw","groen"]
.
Wil je controleren op een specifieke eigenschap van objecten, dan geef je die eigenschap als parameter mee:
{foreach $profile.bestellingen|unique:"url" as $visit}
{$visit.url}
{/foreach}
In dit voorbeeld wordt gekeken naar de eigenschap url
. Als meerdere
bestellingen dezelfde url
hebben, blijft alleen de eerste bestelling met
die waarde behouden.
Wil je liever een ander item behouden dan het eerste, combineer dan unique
met
andere modifiers zoals orderby
:
{foreach $profile.bestellingen|orderby:"id":"desc"|unique:"url" as $visit}
{$visit.url} – {$visit.timestamp}
{/foreach}
In dit voorbeeld worden de bestellingen eerst aflopend gesorteerd op id
,
waarna unique:"url"
alleen de meest recente bestelling per url
overhoudt.
Je kunt unique ook combineren met andere modifiers, zoals filter of limit.