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

Modifiers voor specifieke types collecties

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.

Count

De modifier count geeft je het aantal items terug wat in een datacollectie aanwezig is.

{$profile.naamcollectie|count}

Dit geeft je een numerieke waarde terug van het aantal subprofielen. In het geval van 0 zijn er geen subprofielen aanwezig.