Banners

The module creates named advertising spaces and selects for each public display one available banner. Images are not copied to the module directory: Links to files in the shared media library are saved.

Quick start

Open Modules → Banners → Advertising Spaces.
Create a place, for example Site header, with the code header-main.
Add a banner, select an image, a link and that ad space.
Insert a tag into a document, block, category or template:

[mod_banner:header-main]

For compatibility, the location ID and the [mod_banners:CODE] form are supported, but stable system code is more convenient: it does not change when moving content between installations.

Selection strategies

Strategy	Behavior
By weight	The probability of selection is proportional to the weight of the active banner.
By chance	All available banners have the same probability.
Evenly	The banner with the lowest total number of impressions is selected.

Before choosing, the status of the place and banner, the beginning and end of the period are checked, impression limit and click limit. 0 in the limit field means "no limit".

Public templates

The ad space template receives the tags:

[tag:category-id] [tag:category-code] [tag:category-title]
[tag:banner-id] [tag:banner]

Banner template gets:

[tag:id] [tag:title] [tag:image] [tag:webp] [tag:picture]
[tag:url] [tag:click-url] [tag:alt] [tag:target]
[tag:width] [tag:height]

To count the click, the link must use [tag:click-url]. [tag:url] contains the final address and is intended for metadata or its own JavaScript, but navigating directly to it does not increment the counter.

API and hooks

GET /api/v1/banners/{code} returns the selected HTML in JSON and is suitable for dynamic banner change without rebooting. The response is not cached, but successful selection is considered a showing.

Filter banners.rendering receives an array:

array(
	'banner' => $banner,
	'html' => $html,
)

The handler can modify html and return an array. Do not repeat the select request inside this hook: the display is already committed.

Delete

Deleting an advertising space cascades deletes its banners and statistics. Files in /uploads and the thumbnails created for them remain in the media library. Uninstall module deletes all three module tables.

2.4 KiB Raw Blame History