ComusThumbz Documentation
HTML Markdown Print/PDF Plain Text
Admin Login

Documentation Menu


Admin Access

Banner Zones

Overview

The Banner Zones page allows administrators to create and manage advertising placement zones (also called "placements" or "slots") throughout the website. Each zone represents a specific location where banners can be displayed.

Key Features

  • Create unlimited banner placement zones
  • Define maximum banner limits per zone
  • Assign unique zone codes for template integration
  • Track banner counts and statistics per zone
  • Toggle zone status (active/inactive)
  • Copy existing zones to create new ones quickly

How Zones Work

  1. Create a Zone - Define a placement location with a unique code
  2. Assign Banners - Banners are assigned to zones via the Add Banner page
  3. Display in Templates - Use zone codes in frontend templates to display banners
  4. Track Performance - Monitor which zones perform best

 

Note: Zones must be created before banners can be assigned to them. The zone code is used in template files to display banners in the correct location.

 

System Requirements

PHP Extensions Required

Extension Purpose Check Command
mysqli Database connectivity php -m \ grep mysqli
json AJAX response handling php -m \ grep json
session CSRF protection and authentication Built-in

PHP Functions Used

Function Purpose
mysqlirealescapestring() SQL injection prevention
mysqlibegintransaction() Transaction support for safe deletes
mysqlicommit() / mysqlirollback() Transaction management
pregmatch() Zone code validation
strtoupper() Zone code normalization
jsonencode() / jsondecode() AJAX communication
htmlspecialchars() XSS prevention

Database Requirements

  • MySQL/MariaDB with InnoDB engine (for transaction support)
  • User must have SELECT, INSERT, UPDATE, DELETE permissions on tblBannerPlacements

External Dependencies

Dependency Version Purpose
Bootstrap 5.x UI framework
Font Awesome 6.x Icons
jQuery 3.x AJAX handling

Accessing the Page

Navigation Path

  1. Log into the admin panel
  2. Navigate to Advertising section in the main menu
  3. Click Banner Zones (or Placements)

Direct URL

https://yourdomain.com/ct/admin/bannerzones.php

Required Permissions

  • Must be logged in as an administrator
  • Session must be active with valid authentication

[Screenshot: Admin sidebar showing Advertising menu with Banner Zones option highlighted]

Page Layout

Header Section

The page header contains:

Element Description
Page Title "Banner Zones" with icon
Add Zone Button Green button to open the add zone modal

[Screenshot: Banner Zones page header with Add Zone button]

Statistics Cards

Four summary cards display at the top of the page:

Card Description Color
Total Zones Total number of zones in the system Blue
Active Zones Number of currently active zones Green
Inactive Zones Number of disabled zones Red
Total Banners Sum of all banners across all zones Purple

[Screenshot: Statistics cards showing zone and banner counts]

Zone List Table

The main content area displays a responsive table with all zones:

Column Description
Zone Name Human-readable name of the zone
Zone Code Unique identifier used in templates (displayed in monospace font)
Description Optional description of where this zone appears
Banners Count of banners assigned vs maximum allowed
Status Toggle switch showing active/inactive state
Actions Edit, Copy, and Delete buttons

[Screenshot: Zone list table showing multiple zones with statistics]

Zone Management

Understanding Zone Codes

Zone codes are unique identifiers used to reference zones in frontend templates. They follow strict formatting rules:

Valid Zone Code Format:

  • Uppercase letters (A-Z)
  • Numbers (0-9)
  • Underscores ()
  • No spaces or special characters

 

Examples:

Valid Invalid
HEADERBANNER Header Banner (spaces)
SIDEBARTOP1 sidebar-top (lowercase, hyphens)
VIDEO300X250 video@sidebar (special characters)
Configuration Required: Zone codes are automatically converted to uppercase when saved. The system validates the format using the regex pattern: /^[A-Z0-9]+$/

 

Banner Count Display

Each zone shows its banner utilization:

Banners: 2 / 5 (40%)

This indicates:

  • 2 banners currently assigned
  • 5 maximum banners allowed
  • 40% utilization rate

 

 

Note: When a zone reaches its maximum banner limit, no additional banners can be assigned to it until existing banners are removed or the limit is increased.

 

Status Toggle

Each zone has an active/inactive toggle switch:

  • Green (Active) - Zone can display banners on the frontend
  • Gray (Inactive) - Zone is disabled, no banners will display

 

Warning: Disabling a zone immediately stops all banner displays for that zone on the frontend. Use caution when deactivating zones with active advertising campaigns.

 

Adding a New Zone

Step 1: Open the Add Zone Modal

Click the green "Add Zone" button in the page header.

[Screenshot: Add Zone button highlighted]

Step 2: Fill in Zone Details

The modal form contains the following fields:

Zone Name (Required)

Field Details
Label Zone Name
Type Text input
Max Length 100 characters
Validation Required, cannot be empty
Example "Homepage Sidebar Banner"
Tip: Use descriptive names that indicate where the zone appears on the website. This helps when assigning banners later.

Zone Code (Required)

Field Details
Label Zone Code
Type Text input
Max Length 50 characters
Validation Required, unique, uppercase letters/numbers/underscores only
Example "HOMEPAGESIDEBAR"
Configuration Required: The zone code must be unique across all zones. If you enter a code that already exists, you'll see a validation error.

Description (Optional)

Field Details
Label Description
Type Textarea
Max Length Unlimited
Validation Optional
Example "300x250 banner slot on homepage sidebar, visible on desktop only"
Tip: Include dimension requirements and visibility notes in the description to help when creating banners for this zone.

Max Banners (Required)

Field Details
Label Max Banners
Type Number input
Default 1
Min Value 1
Validation Required, must be positive integer
Example 3

This setting controls how many banners can be assigned to this zone. If rotation is implemented:

  • 1 = Single static banner
  • 2+ = Multiple banners for rotation

 

Note: Setting a higher max banners value allows for banner rotation or A/B testing within a single zone.

 

Active Status

Field Details
Label Active
Type Checkbox
Default Checked (active)
Validation None

When checked, the zone is immediately active and can display banners.

Step 3: Save the Zone

Click the "Save Zone" button to create the zone.

Success Response:

  • Modal closes automatically
  • Zone list refreshes to show the new zone
  • Success toast notification appears

 

Error Response:

  • Error message displays in the modal
  • Form remains open for correction
  • Common errors: duplicate zone code, missing required fields

 

[Screenshot: Add Zone modal with filled form fields]

Editing Zones

Accessing Edit Mode

  1. Find the zone in the list table
  2. Click the pencil icon (Edit) button in the Actions column

[Screenshot: Edit button highlighted in Actions column]

Edit Modal

The edit modal is identical to the add modal but pre-populated with existing zone data:

  • Zone Name - Current name (editable)
  • Zone Code - Current code (editable, but see warning below)
  • Description - Current description (editable)
  • Max Banners - Current limit (editable)
  • Active Status - Current status (editable)

 

Warning: Changing a zone code will NOT automatically update frontend templates. If you change a zone code, you must also update all template files that reference the old code.

 

Saving Changes

Click "Save Zone" to apply changes. The zone list will refresh automatically.

[Screenshot: Edit Zone modal with existing zone data]

Copying Zones

Using the Copy Feature

The copy feature allows you to quickly create a new zone based on an existing one:

  1. Find the source zone in the list
  2. Click the copy icon (Copy) button in the Actions column
  3. A new Add Zone modal opens with pre-filled data from the source zone

What Gets Copied

Field Copied? Notes
Zone Name Yes Appended with " (Copy)"
Zone Code No Must enter a new unique code
Description Yes Exact copy
Max Banners Yes Same value
Active Status Yes Same status
Note: Zone codes are never copied because they must be unique. You'll need to enter a new zone code for the copied zone.

[Screenshot: Copy Zone modal showing pre-filled data with empty zone code field]

Copy Use Cases

  • Creating similar zones for different pages (e.g., SIDEBARTOPHOMEPAGE, SIDEBARTOPVIDEOS)
  • Setting up test zones alongside production zones
  • Creating backup zones before making changes

Deleting Zones

Delete Process

  1. Find the zone in the list
  2. Click the trash icon (Delete) button in the Actions column
  3. Confirm the deletion in the popup dialog

Confirmation Dialog

A confirmation dialog appears with the message:

Are you sure you want to delete this zone?
All banners assigned to this zone will become unassigned.

 

Warning: Zone deletion is permanent and cannot be undone. Ensure no active advertising campaigns depend on this zone before deleting.

 

What Happens to Assigned Banners

When a zone is deleted:

The zone record is removed from tblBannerPlacements

  • All banners previously assigned to this zone have their placementid set to NULL
  • Banners are NOT deleted, only unassigned
  • Unassigned banners can be reassigned to other zones

 

 

Note: Before deleting a zone, consider reassigning its banners to another zone first to maintain campaign continuity.

 

Delete Restrictions

Deletion will fail if:

  • Database transaction fails
  • User lacks delete permissions
  • CSRF token is invalid

 

[Screenshot: Delete confirmation dialog]

Zone Code Implementation

Using Zone Codes in Templates

Zone codes are used in frontend template files to display banners. Here's how to implement them:

PHP Implementation Example

<?php
// Include banner display function
requireonce 'includes/bannerfunctions.php';

// Display banners for a specific zone
echo displayBannerZone('SIDEBARTOP');
?>

 

Sample Banner Display Function

function displayBannerZone($zonecode) {
    global $conn;

// Get zone info
$zonequery = "SELECT placementid, isactive FROM tblBannerPlacements
WHERE zonecode = ? AND isactive = 1";
$stmt = mysqliprepare($conn, $zonequery);
mysqlistmtbindparam($stmt, 's', $zonecode);
mysqlistmtexecute($stmt);
$zoneresult = mysqlistmtgetresult($stmt);

if (!$zone = mysqlifetchassoc($zoneresult)) {
return ''; // Zone not found or inactive
}

// Get active banners for this zone
$bannerquery = "SELECT FROM tblBannerAssets
WHERE placementid = ? AND status = 'active'
ORDER BY RAND() LIMIT 1";
$stmt = mysqliprepare($conn, $bannerquery);
mysqlistmtbindparam($stmt, 'i', $zone['placementid']);
mysqlistmtexecute($stmt);
$bannerresult = mysqlistmtgetresult($stmt);

if ($banner = mysqlifetchassoc($bannerresult)) {
// Return banner HTML
return renderBanner($banner);
}

return '';
}

 

Template Integration Examples

Header Zone:

<header>

    <nav><!-- Navigation --></nav>

    <div class="header-banner-zone">

        <?php echo displayBannerZone('HEADERBANNER'); ?>

    </div>

</header>

 

Sidebar Zone:

<aside class="sidebar">

    <div class="banner-slot">

        <?php echo displayBannerZone('SIDEBARTOP'); ?>

    </div>

    <!-- Other sidebar content -->

    <div class="banner-slot">

        <?php echo displayBannerZone('SIDEBARBOTTOM'); ?>

    </div>

</aside>

 

Video Player Zone:

<div class="video-container">

    <video id="player"><!-- Video --></video>

</div>

<div class="below-player-banner">

    <?php echo displayBannerZone('VIDEOBELOW'); ?>

</div>

 

 

Configuration Required: Always check if the zone is active before attempting to display banners. Inactive zones should return empty content.

 

Best Practices

Zone Naming Conventions

 

Tip: Use a consistent naming convention for zone codes to make template integration easier.

 

Recommended Format: [LOCATION][POSITION][SIZE/TYPE]

Example Meaning
HEADERTOP Header area, top position
SIDEBARLEFT300X250 Left sidebar, 300x250 size
VIDEOBELOWLEADERBOARD Below video, leaderboard format
FOOTERCENTER Footer area, center position
MOBILEINTERSTITIAL Mobile interstitial popup

Zone Planning

Before creating zones, plan your advertising layout:

  1. Identify all banner locations on your website
  2. Document dimensions required for each location
  3. Determine rotation needs (single vs multiple banners)
  4. Consider device targeting (desktop, mobile, tablet)
  5. Group similar locations under common zone codes if appropriate

Performance Considerations

 

Note: Each zone query adds a database call. For high-traffic pages, consider caching banner content.

 

Caching Recommendations:

  • Cache banner output for 5-15 minutes
  • Invalidate cache when banners are updated
  • Use separate caches for different zones

 

Zone Limits

Recommendation Value Reason
Max zones per page 5-8 Too many zones slow page load
Max banners per zone 3-5 More banners reduce individual impressions
Zone code length 20-30 chars Balance readability and brevity

Troubleshooting

Common Issues

Zone Code Already Exists

Error: "Zone code already exists"

Cause: Attempting to create or update a zone with a code that's already in use.

Solution:

  1. Check existing zones for the duplicate code
  2. Choose a different, unique code
  3. If updating, verify you're not accidentally using another zone's code

 

Zone Not Displaying Banners

Symptoms: Zone exists but no banners appear on frontend.

Checklist:

  1. ☐ Is the zone active? (Check status toggle)
  2. ☐ Are banners assigned to this zone? (Check banner count)
  3. ☐ Are assigned banners active? (Check banner status)
  4. ☐ Is the zone code correct in templates? (Case-sensitive check)
  5. ☐ Is the display function working? (Test with debug output)

 

 

Error: Zone codes are case-sensitive in templates. SIDEBARTOP is different from sidebartop.

 

Cannot Delete Zone

Error: "Failed to delete zone"

Possible Causes:

  1. Database transaction failed
  2. Foreign key constraints preventing deletion
  3. CSRF token expired

 

Solution:

  1. Refresh the page and try again
  2. Check database error logs
  3. Verify user has delete permissions

 

Max Banners Limit Reached

Symptoms: Cannot assign more banners to a zone.

Solution:

  1. Edit the zone and increase the max banners limit
  2. Or remove existing banners from the zone
  3. Or create a new zone for additional banners

 

Database Queries for Debugging

Check Zone Status

SELECT placementid, placementname, zonecode, isactive, maxbanners
FROM tblBannerPlacements
WHERE zonecode = 'YOURZONECODE';

Count Banners per Zone

SELECT
    p.zonecode,
    p.placementname,
    p.maxbanners,
    COUNT(b.assetid) as assignedbanners
FROM tblBannerPlacements p
LEFT JOIN tblBannerAssets b ON p.placementid = b.placementid
GROUP BY p.placementid
ORDER BY p.zonecode;

Find Zones with No Banners

SELECT p.zonecode, p.placementname
FROM tblBannerPlacements p
LEFT JOIN tblBannerAssets b ON p.placementid = b.placementid
WHERE b.assetid IS NULL;

Find Unassigned Banners

SELECT assetid, bannername, status
FROM tblBannerAssets
WHERE placementid IS NULL;

Translatable Strings

The following strings should be added to backendtranslations.md for internationalization:

Page Title and Navigation

bannerzonestitle = "Banner Zones"
bannerzonesdescription = "Manage advertising placement zones"

Buttons and Actions

btnaddzone = "Add Zone"
btnsavezone = "Save Zone"
btneditzone = "Edit"
btncopyzone = "Copy"
btndeletezone = "Delete"
btncancel = "Cancel"

Form Labels

labelzonename = "Zone Name"
labelzonecode = "Zone Code"
labeldescription = "Description"
labelmaxbanners = "Max Banners"
labelactive = "Active"
labelstatus = "Status"

Table Headers

thzonename = "Zone Name"
thzonecode = "Zone Code"
thdescription = "Description"
thbanners = "Banners"
thstatus = "Status"
thactions = "Actions"

Statistics Cards

stattotalzones = "Total Zones"
statactivezones = "Active Zones"
statinactivezones = "Inactive Zones"
stattotalbanners = "Total Banners"

Messages and Notifications

msgzonesaved = "Zone saved successfully"
msgzonedeleted = "Zone deleted successfully"
msgzonestatusupdated = "Zone status updated"
msgconfirmdelete = "Are you sure you want to delete this zone?"
msgdeletewarning = "All banners assigned to this zone will become unassigned."

Error Messages

errorzonenotfound = "Zone not found"
errorzonecodeexists = "Zone code already exists"
errorzonecodeinvalid = "Zone code must contain only uppercase letters, numbers, and underscores"
errorzonenamerequired = "Zone name is required"
errorzonecoderequired = "Zone code is required"
errormaxbannersinvalid = "Max banners must be a positive number"
errordeletefailed = "Failed to delete zone"
errorsavefailed = "Failed to save zone"

Placeholders

placeholderzonename = "Enter zone name"
placeholderzonecode = "e.g., SIDEBARTOP"
placeholderdescription = "Optional description of this zone"
placeholdermaxbanners = "Enter maximum banners"

Help Text

helpzonecode = "Unique code used in templates. Use uppercase letters, numbers, and underscores only."
helpmaxbanners = "Maximum number of banners that can be assigned to this zone."
helpactive = "Only active zones will display banners on the frontend."

Modal Titles

modaladdzone = "Add New Zone"
modaleditzone = "Edit Zone"

Changelog

Date Version Changes
2025-01-02 1.0 Initial documentation

This documentation is part of the ComusThumbz Admin Guide series.*

Related Pages