Datacollections are a great way of organizing similar data like for example faq entries, customer reviews, etc..

If you have a FAQ datacollection for example, you can make an infinite amount of entries within this datacollection, representing your FAQ entries. All of these entries will have the same amount and types of elements that you have specified. Remember that a datacollection consists of entries. The datacollection holds the global settings and the entries within the datacollection hold the specific FAQ entries in this example.

Adding a datacollection only requires a name. After adding the datacollection, you can click 'configure' and then 'add element'.

Adding an element to a datacollection works in the same way as when you would add an element to a section or form for example. You simply choose the type of element, specify a name and optionally a tooltip and validation.

These elements will be presented to the content manager when they add a datacollection entry.

Then click save and the datacollection is ready for use.

To add a datacollection entry, go to the specific datacollection in the CMS and click 'add entry'.

Now all of the elements you added to this datacollection are presented.
When the user has completed all required fields, and saves the entry, it will be stored.

Remember that new entries are unpublished by default, meaning they are not visible on the website. If you want to publish an entry, edit the entry and toggle the published status.

You can however also add entries using the Webigniter client. So if you need to programatically add entries to your datacollections, you can use the addDatacollectionEntry() method. This is a sample code on how to add a datacollection entry.

    $data['name'] = 'Paul';
    $data['rating'] = '8';
    $data['short'] = 'excellent company';
    $data['date'] = '12-01-2024';
    $data['published'] = true;

    $webigniter->addDatacollectionEntry('reviews', $data);

This adds an entry to the 'reviews' datacollection. Be aware that the keys in the $data array must correspond with the handles of the elements in the datacollection. The published key is reserved and should hold a boolean (true/false) to determine whether the entry should be published or remain draft.

All data is validated before creation, when there are validation errors, they are added to the flashdata array errors. So if for example you forget to specify a mandatory field, this is how you can display error messages...

<?php
if($webigniter->getFlashData('errors')) {
   foreach($webigniter->getFlashData('errors') as $error) {
      echo $error."<br>";
   }
}
?>

Datacollections are only usefull if you can include them in you sections. This is how you can include the datacollection data in your section(s).

<?php
$faq_items = $webigniter->getDatacollectionEntries(handle: 'FAQ', limit: 10);
foreach($faq_items['entries'] as $faq_item):?>
   <h1><?=$faq_item['data']['question'];?></h1>
   <p><?=$faq_item['data']['answer'];?></p>
<?php endforeach; ?>

The handle can be found in the datacollections overview in the CMS, when logged in as an admin.

Let's brake it down into piecies.

The PHP foreach statement tells the section to loop through all entries and store each entry in the variable $faq_item. 
Within the foreach a Webigniter method is called: $webigniter->getDatacollectionEntries(handle: 'FAQ', limit: 10).
This will get the FAQ entries from the datacollection with the handle 'FAQ. Limit: 10 means that it will retreive no more that 10 entries of this datacollection. You can also add:
unpublished: true to also retreive unpublished entries.
limit : limit the number of entries to retrieve.
offset : specify the offset for the entries list.
orderBy: datacollection field name to order the results by.
orderType: specify how you want to order the results (allowed values: ASC, DESC and RAND).
filterBy: datacollection field names you want to use for filtering (must be an array, ['name', 'title'] for example).
filterValue: specify the value the filtered fields should contain (also an array, ['john', 'mark'] for example.

When orderType is ASC or DESC, specify an orderBy, this is not necessary when orderType is RAND.
You can also use id in the filterBy parameter to search for a specific entry.

Now that we have our faq items stored in $faq_item, we can start displaying our entries.
All data provided by the user in the CMS is stored in $faq_item['data'], this means you can display the entry data, by using <?=$faq_item['data']['question'];?> to display the element in the entry with the name 'question'. In this case the element 'question' is a simple text element, so I can access by just using 'question', other element types may need a different approach, check the manual to find out how each elementtype should be retreived.

There are also 3 extra elements added to every entry by default, 'id', 'created_at' and 'updated_at'. These three can be displayed using <?=$faq_item['id'];?>, <?=$faq_item['created_at'];?>and <?=$faq_item['updated_at'];?>.

$faq_items (the array with the resultset) also holds two extra keys: 'numEntries' and 'totalEntries'. These can be displayed using <?=$faq_items['numEntries'];?> and <?=$faq_items['totalEntries'];?>. numEntries will be the amount of found entries with all filters used, totalEntries is the total number of entries within the datacollection, regardless of filters.