How to Show a Configurable Popup Message on Frontend Pages in CakePHP 2.x

Step-by-step tutorial to implement a configurable welcome popup in CakePHP 2.x (tested with 2.10.22). Includes database schema, controller, model, views, element, layout includes and enhancements.

The concept of displaying a welcome message or popup to your website visitors is very common today. It could be a subscription prompt, special product deal, discount alert, or even a simple welcome message for new users.

In this tutorial, we will learn how to create a fully configurable welcome popup in CakePHP 2.x, using simple logic and a lightweight jQuery popup plugin.

Prerequisites

• A working CakePHP 2.x installation (tested on 2.10.22).
• Basic understanding of MVC (Model, View, Controller).
• Access to your MySQL database.
• Familiarity with HTML, PHP and jQuery.

Step 1: Create the Database Table

Create a table called popups to store popup configuration (title, content, first visit flag, delay).

CREATE TABLE IF NOT EXISTS `popups` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `title` varchar(200) NOT NULL,
  `content` text NOT NULL,
  `firstvisit` tinyint(2) NOT NULL,
  `delay` int(10) NOT NULL,
  PRIMARY KEY (`id`)
);

INSERT INTO `popups` (`id`, `title`, `content`, `firstvisit`, `delay`) VALUES
(1, 'Main title goes here', 'Lorem Ipsum is simply dummy text of the printing and typesetting industry...', 0, 5000);

Step 2: Controller — PopupsController.php

Create app/Controller/PopupsController.php. This controller manages admin updates and provides a display() method used on frontend pages.

<?php
class PopupsController extends AppController {

  public function index() {
    $data = $this->Popup->find('first');
    $this->set('data', $data);
    if (!$data) {
      throw new NotFoundException(__('Invalid Request'));
    }

    if ($this->request->is(array('post', 'put'))) {
      if ($this->Popup->save($this->request->data)) {
        $this->Session->setFlash(__('Your settings have been updated.'));
        return $this->redirect(array('action' => 'index'));
      }
      $this->Session->setFlash(__('Unable to update your changes.'));
    }

    if (!$this->request->data) {
      $this->request->data = $data;
    }
  }

  public function display() {
    $data = $this->Popup->find('first');
    return $data;
  }
}
?>

Tip: For admin separation, place an admin-prefixed controller file src/Controller/Admin/PopupsController.php or use CakePHP admin routing to keep frontend and backend responsibilities clear.

Step 3: Model — Popup.php

Create the model at app/Model/Popup.php for validation rules and simple content checks.

<?php
class Popup extends AppModel {
  public $validate = array(
    'title' => array(
      'notBlank' => array(
        'rule' => array('notBlank'),
        'message' => 'Title is required'
      )
    ),
    'content' => array(
      'notBlank' => array(
        'rule' => array('notBlank'),
        'message' => 'Popup Content is required'
      ),
      'avoidCertainTags' => array(
        'rule' => array('avoidCertainTags'),
        'message' => 'Please enter proper content'
      )
    ),
    'delay' => array(
      'notBlank' => array(
        'rule' => array('notBlank'),
        'message' => 'Delay is required'
      )
    )
  );

  public function avoidCertainTags($check) {
    $value = array_values($check)[0];
    return preg_match('/^[^*<>[\]{}\\;@$]+$/', $value);
  }
}
?>

Step 4: Admin View — index.ctp

Create a simple admin form in app/View/Popups/index.ctp to edit popup settings.

<?php
  echo $this->Form->create();
  echo $this->Form->input('title');
  echo $this->Form->input('content', array('type' => 'textarea'));
?>
<label>First Time Only</label>
<?php
  echo $this->Form->checkbox('firstvisit');
  echo $this->Form->input('delay');
  echo $this->Form->input('id', array('type' => 'hidden'));
  echo $this->Form->end('Save');
?>

Step 5: Frontend Element — popup.ctp

Create the element used on frontend layouts: app/View/Elements/popup.ctp. This checks cookie and shows popup once or every visit based on settings.

<?php
$data = $this->requestAction('/Popups/display');
$show_popup = 1;

if ($data['Popup']['firstvisit'] == '1') {
  if (!isset($_COOKIE['jquery_popup'])) {
    setcookie('jquery_popup', 'jQuery Popup', time() + 2592000); // 30 days cookie
  } else {
    $show_popup = 0;
  }
}

if ($show_popup == 1) { ?>
  <div class="p_anch">
    <div class="js__p_start"></div>
  </div>
  <div class="p_body js__p_body js__fadeout"></div>
  <div class="popup js__popup js__slide_top">
    <a href="#" class="p_close js__p_close" title="CLOSE"></a>
    <div class="p_title"><?php echo $data['Popup']['title'];?></div>
    <div class="p_content">
      <p><?php echo $data['Popup']['content'];?></p>
    </div>
  </div>
<?php } ?>

<script type="text/javascript">
  var delaytime = '<?php echo $data['Popup']['delay'];?>';
  function pageSet() {
    $(".js__p_start").simplePopup();
  }
  $(window).load(function() {
    setTimeout(pageSet, delaytime);
  });
</script>

Step 6: Include Element in Layout

Edit app/View/Layouts/default.ctp and add the script/css includes plus the element:

echo $this->Html->script('jquery-1-10-2.min');
echo $this->Html->script('jquery.popup');
echo $this->Html->css('jquery.popup');
echo $this->element('popup');

Tip: If your theme already loads jQuery, skip the explicit jQuery include and ensure jquery.popup.js loads after the main jQuery file.

Step 7: Add Supporting Files (webroot)

Place these files in webroot:

webroot
├── css
│   └── jquery.popup.css
├── js
│   ├── jquery.popup.js
│   └── jquery-1-10-2.min.js
└── img
    └── close.png

Example CSS (simple):

.popup {
  background: #fff;
  border-radius: 10px;
  padding: 20px;
  width: 400px;
  box-shadow: 0 0 15px rgba(0,0,0,0.3);
}
.p_title { font-size: 20px; margin-bottom: 10px; }
.p_close { float: right; text-decoration: none; }

Step 8: Admin Route Example

Add a route for admin edit page (optional):

Router::connect('/admin/popups', array('controller' => 'popups', 'action' => 'index', 'admin' => true));

This gives admin URL: http://yoursite.com/admin/popups.

Step 9: Testing

Open any frontend page. The popup should appear after the configured delay.

If you set first visit only, test by clearing cookies or using a private/incognito window.

Enhancements & Ideas

To make the popup feature more powerful, consider:

• Start & end date fields for timed campaigns.
• Multi-language support for bilingual sites.
• A/B testing to try different messages and measure conversions.
• AJAX save in admin to update settings without page reload.
• Different display positions (center, banner, slide-in).
• Use Bootstrap modal or another modern UI for smoother visuals.
• Integrate with Mailchimp or other newsletter services for subscriptions.

Why these enhancements help

Adding scheduling and analytics helps you run limited-time offers maintainably. Multi-language support increases audience reach, and A/B testing helps improve conversion rates. AJAX and modern UI make admin and user experience smoother.

Download Source Code

You can download the sample package used in this tutorial: