Developers: Working with PHP Scripts

Heads up! This article contains PHP code and is intended for developers. We offer this code as a courtesy, but don't provide support for code customizations or 3rd party development.

There are cases where you’d like to silently post data to an external URL after a popup closes, display content fetched from the database or even modify a box option before it’s displayed to the visitor.

With the PHP Scripts feature all the aforementioned scenarios are now possible. Let's see how that works.

EngageBox fires certain types of events during runtime and enables you to execute PHP when these events occurred just like in the Actions section but this time the events are fired on the server-side. With the proper knowledge of PHP, you can do just about anything and customize the behavior of the popup to fit your needs.

Events

The PHP Scripts area consits of the following 4 sections that are triggered on certain events.

Before Render

The PHP script added in this area is executed after the box passes the Publishing Assignments check and before the box's layout is rendered. This is rather useful when you want to modify a box option conditionally. For instance, you could modify the box trigger depending on the visitor’s device type or change the background color based on the current time.

Modify the Transition In Effect

$transitionInEffect = $someVar ? 'transition.fadeIn' : 'callout.shake';
$box->params['animationin'] = $transitionInEffect;

Modify the Width

$width = $someVar ? '500px' : '250px';
$box->params['width'] = $width;

After Render

The PHP script added in this area is executed after the box's layout is rendered. This is rather useful if you want to modify, append or replace certain parts in the HTML layout. For instance, you could use this event to replace a placeholder variable included in the box HTML with data fetched from a database table.

Open

The PHP script added in this area is executed every time the box opens. You could use this event to connect to a database or trigger a workflow in a 3rd party app.

Close

The PHP script added in this area is executed every time the box is closed. This is rather useful when you want to populate a row in the database and let the respective app know that a visitor has closed a popup.

Frequently Asked Questions

Can I include PHP files within my code?

The PHP Scripts sections allows you to include any external file from within your joomla installation as long as you have the correct path. This is quite useful if you need to use the same PHP code on multiple boxes, you can place the code in a php file and include it in your box's PHP Scripts section.

include JPATH_SITE . '/path/to/file.php';
// Your code here

Is it possible to execute Javascript instead of PHP?

The PHP Scripts feature is based on events fired in the server-side and you can use it to write PHP only. To execute Javascript use the Run Javascript action available in Actions.

Note: For debugging purposes you can always use die(); statements after echo or var_dump() commands. For example: var_dump($post); die();