Kreatívy

Každé umiestnenie má vlastnú skupinu kreatív s jediným súborom a variantom display orezaným (cover) na šírku × výšku umiestnenia. Obrázok priraďte a načítajte, alebo ho rovno vykreslite — obrázok, ak existuje, inak textovú reklamu:

// Attach (or replace) the creative for a placement — model, id, or slug.
$ad->addCreative($request->file('banner'), 'sidebar');   // an UploadedFile or a file path

$ad->creativeFor('sidebar');                 // ?Media (placement-specific, then generic)
$ad->creativeUrl('sidebar');                 // display-variant URL, or '' / fallback when empty
$ad->creativeUrl('sidebar', '');             // the original

// Responsive <img> when a creative exists, else the text-ad fallback (name + description + price).
echo Advertisements::render($ad, 'sidebar', ['class' => 'ad']);
echo $ad->renderCreative('sidebar', ['class' => 'ad']); // the same, from the model

Skupiny

Skupiny sa volajú {creative_bucket_prefix}:{slug-umiestnenia} a k nim patrí všeobecná skupina {fallback_bucket} bez rozmerov. Každá prijíma JPEG, PNG, WebP, GIF a AVIF, drží jediný súbor (nové nahratie nahradí starý) a ak sú nastavené, použije media.disk a media.responsive_widths. Umiestnenie bez rozmerov dostane variant display bez zmeny veľkosti.

$ad->creativeBucketName('sidebar');   // "creative:sidebar"
$ad->fallbackCreativeBucket();        // "creative"
$ad->displayVariant();                // "display"

// A generic, size-less creative for any placement without its own image:
$ad->addMedia($request->file('banner'))->toMediaBucket($ad->fallbackCreativeBucket());

• creativeFor() — obrázok konkrétneho umiestnenia, potom všeobecná kreatíva (ak je media.use_fallback_bucket zapnuté), inak null.
• creativeUrl() — predvolene URL variantu display; zadajte iný názov variantu alebo '' pre originál. Ak nič nie je priradené, vráti záložnú URL skupiny alebo ''.
• Advertisements::render($ad, $placement) — responzívny <img> so srcset (alt predvolene z názvu reklamy), ak existuje obrázková kreatíva, inak textovú reklamu. $ad->renderCreative() je skratka pre to isté volanie.

Záložná textová reklama

Bez obrázkovej kreatívy vykreslí render() Blade view advertisements::text-ad: div.advertisement-text-ad v rozmeroch umiestnenia s atribútom data-advertisement, ktorý obsahuje názov, vyplnený popis a cenu naformátovanú v aktívnom jazyku. Na úpravu vzhľadu view publikujte alebo nasmerujte media.text_ad_view na vlastný — neexistujúci view skončí zreteľnou chybou InvalidArgumentException.

php artisan vendor:publish --tag="advertisements-views"
# → resources/views/vendor/advertisements/text-ad.blade.php

• $advertisement — vykresľovaná Advertisement.
• $placement — nájdené ?Placement.
• $attributes — pole odovzdané do render() alebo renderCreative().

Atribúty vykreslenia

Textová reklama použije na svojom <div> každý odovzdaný atribút, escapovaný: class a style pripojí k vlastným (class="advertisement-text-ad ad"), ostatné pridá alebo nimi prepíše predvolené. Pri obrázku ich dostane responzívny <img> z media-library, ktorý prijíma class, alt (predvolene názov reklamy) a sizes.

Vlastný renderer

Advertisements::render() ide cez naviazaný RoundlyConsulting\Advertisements\Contracts\CreativeRenderer. Celý reťazec vykresľovania vymeníte naviazaním vlastnej implementácie:

use Illuminate\Support\HtmlString;
use RoundlyConsulting\Advertisements\Contracts\CreativeRenderer;
use RoundlyConsulting\Advertisements\Models\Advertisement;
use RoundlyConsulting\Advertisements\Models\Placement;

final class NativeAdRenderer implements CreativeRenderer
{
    public function render(Advertisement $advertisement, Placement|int|string $placement, array $attributes = []): HtmlString
    {
        return new HtmlString(view('ads.native', ['ad' => $advertisement])->render());
    }
}

// AppServiceProvider::register()
$this->app->bind(CreativeRenderer::class, NativeAdRenderer::class);

Kreatívy sú riadky Media z media-library, takže na ne platí všetko, čo tento balík ponúka — varianty, responzívny srcset, súkromné a dočasné URL.