README

Toon actueel aanbod uit Verkoopmachine in een Statamic-site. De add-on haalt de inhoud op aan de hand van één ingestelde clientslug en rendert die als een toegankelijk, gegroepeerd overzicht met deeplinks naar Koemarkt.

De eerste versie ondersteunt:

Vee-advertenties;
aankomende Rundveeveilingen waarbij de ingestelde client betrokken is.

De opzet is bewust uitbreidbaar: de API retourneert groepen met items. Nieuwe advertentiesoorten kunnen daardoor worden toegevoegd zonder dat een bestaande Statamic-template of tag hoeft te veranderen.

Vereisten

PHP 8.3 of hoger;
Statamic 6;
een bereikbare Verkoopmachine API met de v1 client-content endpoints.

Voor productie gebruikt de add-on standaard https://www.verkoopmachine.nl/api/v1.

Installatie

Installeer de package in de Statamic-site zodra deze via Packagist of een private Composer-repository beschikbaar is:

composer require tinusg/verkoopmachine-statamic

Publiceer daarna de stylesheet:

php artisan vendor:publish --tag=verkoopmachine-statamic

De CSS komt terecht op:

public/vendor/verkoopmachine-statamic/css/verkoopmachine.css

Lokale ontwikkeling

Bij lokale ontwikkeling kan de package als Composer path-repository worden gekoppeld. Vervang het pad door de locatie van de package naast de Statamic-site.

composer config repositories.verkoopmachine-statamic path ../verkoopmachine-statamic
composer require tinusg/verkoopmachine-statamic:'*@dev'

Publiceer de assets opnieuw nadat de CSS van de package is gewijzigd:

php artisan vendor:publish --tag=verkoopmachine-statamic --force

Configuratie

Open in het Statamic-control-panel de instellingen van de add-on en vul de Client slug in. Bijvoorbeeld:

middelveld-machines

De slug is de publieke identifier van de Verkoopmachine-client; het is niet de bedrijfsnaam. Bij het opslaan controleert de add-on via de API of de client bestaat.

Bestaat de slug niet, dan wordt de instelling niet opgeslagen en verschijnt de melding: Deze client slug bestaat niet in Verkoopmachine.
Is de API tijdelijk onbereikbaar, dan wordt ook niet opgeslagen. De melding maakt onderscheid tussen een onbekende slug en een niet-uitvoerbare controle.

De instelling wordt door Statamic opgeslagen in:

resources/addons/verkoopmachine-statamic.yaml

Een handmatig voorbeeld:

client_slug: middelveld-machines

Gebruik bij voorkeur het control panel. Daarmee blijft de server-side slugvalidatie altijd actief.

Omgevingsvariabelen

Deze variabelen zijn optioneel. De getoonde waarden zijn de standaardwaarden.

VERKOOPMACHINE_API_URL=https://www.verkoopmachine.nl/api/v1
VERKOOPMACHINE_CONNECT_TIMEOUT=3
VERKOOPMACHINE_TIMEOUT=8
VERKOOPMACHINE_CACHE_SECONDS=300
VERKOOPMACHINE_STALE_CACHE_SECONDS=86400

Voor een lokale Verkoopmachine-installatie kan bijvoorbeeld dit worden gebruikt:

VERKOOPMACHINE_API_URL=https://www.verkoopmachine.test/api/v1

Maak na een wijziging aan .env zo nodig de Laravel-configcache leeg:

php artisan config:clear

Weergave op een pagina

Laad de stylesheet één keer in de <head> van de globale Statamic-layout:

{{ verkoopmachine:styles }}

Plaats de stylesheet vóór de eigen site-CSS of Vite-bundel. Daardoor heeft site-eigen CSS bij gelijke specificiteit voorrang.

Gebruik vervolgens de overzichtstag waar het aanbod moet verschijnen:

{{ verkoopmachine:overview }}

Standaard toont de tag maximaal zes items per groep, voor zowel Vee als Rundveeveilingen.

Parameters

types is een pipe-gescheiden lijst met gewenste groepen. limit geldt per groep en ligt altijd tussen 1 en 24.

{{ verkoopmachine:overview types="vee" limit="3" }}

{{ verkoopmachine:overview types="vee|rundveeveilingen" limit="12" }}

Beschikbare typen in deze versie:

Type	Inhoud	Deeplink
`vee`	Publiek zichtbare Vee-advertenties van de client	Koemarkt-advertentie
`rundveeveilingen`	Publiek zichtbare, toekomstige Rundveeveilingen van de client	Koemarkt-veiling

Als er geen actuele inhoud beschikbaar is, toont de add-on een neutrale lege-status. Bij een ontbrekende configuratie of niet beschikbare API toont hij een korte foutmelding, zonder technische foutdetails aan bezoekers bloot te stellen.

Opbouw en styling

Alle markup van de add-on staat binnen:

<section data-verkoopmachine>
    <!-- add-on inhoud -->
</section>

Alle meegeleverde selectors zijn hierop gescoped met :where(...). De add-on legt dus geen globale reset, headings of linkstijl op aan de rest van de site.

CSS-variabelen

Pas de uitstraling bij voorkeur aan via de variabelen op de wrapper:

[data-verkoopmachine] {
    --vm-accent: #0f766e;
    --vm-border: #99f6e4;
    --vm-muted: #475569;
    --vm-surface: #f8fafc;
    --vm-radius: 1rem;
    --vm-shadow: 0 10px 25px rgb(15 23 42 / 0.1);
}

Gerichte overrides

Omdat de basisselectors met :where() een lage specificiteit hebben, zijn gerichte overrides overzichtelijk:

[data-verkoopmachine] .vm-grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
}

[data-verkoopmachine] .vm-card {
    border-radius: 0;
}

[data-verkoopmachine] .vm-group__heading {
    border-bottom: 2px solid var(--vm-accent);
    padding-bottom: 0.5rem;
}

Plaats deze regels in de eigen stylesheet van de Statamic-site, ná {{ verkoopmachine:styles }}. Pas de gepubliceerde CSS in public/vendor niet rechtstreeks aan: een volgende vendor:publish --force overschrijft die.

Beschikbare CSS-hooks

Hook	Functie
`[data-verkoopmachine]`	Wrapper en CSS-variabelen
`.vm-group`	Eén inhoudsgroep
`.vm-group__heading`	Kop met groepsnaam en totaal
`.vm-grid`	Responsive kaartgrid
`.vm-grid--vee`	Grid voor Vee-advertenties
`.vm-grid--rundveeveilingen`	Grid voor Rundveeveilingen
`.vm-card`	Klikbare kaart/deeplink
`.vm-card__image`	Hoofdfoto van een advertentie
`.vm-card__body`	Tekstgedeelte van een kaart
`.vm-card__facts`	Lijst met kenmerken
`.vm-message`	Lege status of foutmelding
`.vm-message--error`	Foutmelding

Verkoopmachine API

De add-on gebruikt de volgende read-only endpoints:

GET /api/v1/clients/{slug}
GET /api/v1/clients/{slug}/content?types=vee,rundveeveilingen&limit=6&locale=nl

De eerste endpoint valideert de instelling. De tweede retourneert een client en een lijst groepen. Iedere groep bevat een key, label, total en items. Een item bevat onder meer title, summary, image_url, display en url. De URL is een volledige deeplink naar de passende Koemarkt-pagina.

De API geeft uitsluitend publieke, zichtbare inhoud terug. De add-on verstuurt geen API-sleutel en verwacht geen persoonlijke of contactgegevens in de response.

Caching en beschikbaarheid

Elke unieke combinatie van clientslug, typen, limiet en taal wordt vijf minuten gecached. Dat beperkt HTTP-verzoeken tijdens drukbezochte pagina's.

Na een succesvolle response bewaart de add-on daarnaast een fallback-versie, standaard 24 uur. Is de API tijdelijk niet beschikbaar, dan toont de add-on de laatst bekende inhoud. Alleen wanneer er geen bruikbare cache is, verschijnt de foutmelding op de pagina.

Problemen oplossen

De slug wordt afgewezen

Controleer of de slug precies overeenkomt met de Verkoopmachine-client en of VERKOOPMACHINE_API_URL naar de juiste omgeving wijst. Test desgewenst:

curl -i "https://www.verkoopmachine.nl/api/v1/clients/jouw-client-slug"

Een 404 betekent dat de slug niet bestaat of niet actief beschikbaar is.

Geen aanbod zichtbaar

Controleer achtereenvolgens:

Of de slug is opgeslagen in de add-oninstellingen.
Of de client publiek zichtbare Vee-advertenties of toekomstige Rundveeveilingen heeft.
Of de gewenste types niet zijn beperkt in de tag.
Of de API bereikbaar is vanaf de Statamic-server.

Leeg aanbod is geen fout: de tag toont dan de lege-status.

De layout bevat geen styling

Controleer of {{ verkoopmachine:styles }} in de globale layout staat en of het bestand bestaat in:

public/vendor/verkoopmachine-statamic/css/verkoopmachine.css

Publiceer de assets opnieuw wanneer het bestand ontbreekt.

Ontwikkeling en tests

Installeer afhankelijkheden in de package en voer de testset uit:

composer install
vendor/bin/phpunit --do-not-cache-result

De tests controleren onder andere de slugvalidatie, de API-aanroep en de fallback naar verouderde cache. Test daarnaast in de consumerende Statamic-site dat een pagina met {{ verkoopmachine:overview }} de verwachte inhoud en deeplinks rendert.

Uitbreiden met nieuwe typen

Nieuwe advertentiesoorten horen als nieuwe groepen in de Verkoopmachine API beschikbaar te komen. Houd daarbij dezelfde groeps- en itemstructuur aan. Zodra de API het type accepteert, kan de tag het doorgeven via types, bijvoorbeeld:

{{ verkoopmachine:overview types="vee|rundveeveilingen|nieuw-type" }}

Voeg voor een nieuw type ook een gerichte API-test, voorbeelddata en eventueel een .vm-grid--nieuw-type CSS-override toe.

tinusg / verkoopmachine-statamic

Package info

Security

Statistics