How to Make a New Hook

From Phoenix User Guide
Back
FAQ Tips & Tricks


The pre-placed hook calls or injection points throughout the core files enable code to be inserted or injected at those points with a hook file.

This is one of the features of CE Phoenix Cart that make it the most flexible ecommerce software available.

A hook file listens for that hook call and inserts its output wherever it is called in the core code.

There are existing hook calls throughout the core code but a page could be copied and edited to add a hook call and saved to your selected template.

These hook calls can be seen in /templates/default/includes/components/template_top.php and template_bottom.php as well as in many other specific files in both the admin and shop side.

The hook calls will look like, for an example:

$OSCOM_Hooks->call('siteWide', 'injectRedirects');

This hook call is in template_top.php and shows siteWide, the Group and injectRedirects, the Action.

So it is calling for hooks in the /hooks/shop/siteWide/ directory that are listening for injectRedirects.

It can be seen that it is the first hook call in the file and so would allow code to be injected to redirect the page to another.

The next hook call in template_top.php can be seen between the <head></head> tags:

echo $OSCOM_Hooks->call('siteWide', 'injectSiteStart');

So this would allow code to be injected between those tags.

The next hook call in template_top.php can be seen just after the <body> tag but before the navigation modules are called:

echo $OSCOM_Hooks->call('siteWide', 'injectBodyStart');

So this would allow code to be injected before the navigation modules.

Look further in the template_top.php and template_bottom.php files to see more hook calls and where they are placed in the code to see where hooks will be injected.


In the above examples, hooks in the /hooks/shop/siteWide directory will inject the code into all pages.

To inject code only into a specific page or pages, code can be added to the hook file that dictates otherwise - see /templates/default/includes/hooks/shop/siteWide/MATC.php for an example.

Alternatively, for example, to inject code only to checkout_confirmation.php, a hook file can be saved to a /hooks/shop/checkout_confirmation/ directory.

So, for some examples of usage...



Example 1

In this simple example, a hook is created to listen for an existing shop siteWide hook call so it will be injected into all pages of the shop.

It will display a message in all pages of the shop, at the top above the navigation bar.

As mentioned above, there is an existing hook call that allows code to be injected before the navigation bar:

echo $OSCOM_Hooks->call('siteWide', 'injectBodyStart');

So, we make a hook file to listen for that call.

To make the most of the template system, this new file is created in /templates/override/includes/hooks/shop/siteWide/

The directories might need to be created to follow that structure.

The file could be created in whatever template that is being used, that is, whatever has been selected in admin → Configuration → My Store → Template Selection.

The new hook file is named, for example, pageTopMessage.php - keep the name unique and meaningful.

The following code is saved in the file:

<?php
class hook_shop_siteWide_pageTopMessage {
    function listen_injectBodyStart() {
        $this->load_lang();
        $output = PAGE_TOP_MESSAGE;
        return $output;
    }
    function load_lang() {
        require language::map_to_translation('hooks/shop/siteWide/pageTopMessage.php');
      }
}

The class name hook_shop_siteWide_pageTopMessage must follow the same structure as the hook file location, that is, /hooks/shop/siteWide/pageTopMessage.php - notice the singular hook and the omission of .php in the class name.

The function listen_ is followed by the Action in the hook call, in this instance, injectBodyStart

The output, that is, what is shown on the page has been defined in an associated language file with PAGE_TOP_MESSAGE

So, create a file, pageTopMessage.php, in /templates/override/includes/languages/english/hooks/shop/siteWide/

The following code is saved in the file:

<?php
const PAGE_TOP_MESSAGE = '<div class="alert-info text-center p-2">Example Message</div>';

This hook will result in this:

Nav-content-module-8.png


Example 2

In this simple example, a hook is created to listen for an existing hook call on a specific page so it will be injected into that position only into that specific page.

It will display a message in the shop on checkout_confirmation.php

Looking at the template file for checkout_confirmation.php:

https://github.com/CE-PhoenixCart/PhoenixCart/blob/master/templates/default/includes/pages/checkout_confirmation.php

A hook call can be seen already in place:

echo $OSCOM_Hooks->call('siteWide', 'injectFormDisplay');

This shows siteWide, the Group and injectFormDisplay, the Action.

It can be seen that the hook call is placed just before the Finalise Order button so that is where the hook file output will be inserted.

There is already a hook file that listens for that call - MATC.php that shows the Legal agreements.

When more than one hook file is injected at one hook call position they will be loaded sorted by their name.

The sort rules are numbers, then uppercase letters (in alphabetical order), then _, then lowercase letters.

This message is intended to show before MATC.php so must have a name that sorts before uppercase M.

Therefore, in this case it is named Cmessage.php

The new file is created in /templates/override/includes/hooks/shop/checkout_confirmation/

The following code is saved in the file:

 <?php
 class hook_shop_checkout_confirmation_Cmessage { 
    function listen_injectFormDisplay() {
        $output = null;
        $this->load_lang();
        $output .= MESSAGE_CHECKOUT_CONFIRMATION ;
        return $output;
    }
    function load_lang() {
        require language::map_to_translation('hooks/shop/checkout_confirmation/Cmessage.php');
      }
 }

The output has been defined in an associated language file with MESSAGE_CHECKOUT_CONFIRMATION

So, create a language file, Cmessage,php, in /templates/override/includes/languages/english/hooks/shop/checkout_confirmation/

The following code is saved in the file:

<?php
const MESSAGE_CHECKOUT_CONFIRMATION = '<div class="alert-danger text-center my-2 p-2">Example Message</div>';

This results in this:

Hook1.png


Example 3

In cases where a hook call does not exist in a file or at a position required, it can be added.

In this simple example, a hook is created to listen for a hook call that is created on a specific page so it will be injected into that position only into that specific page.

A copy is made of /templates/default/includes/pages/checkout_confirmation.php and saved to /templates/override/includes/pages/checkout_confirmation.php

Edit that new file (it will never be overwritten in updates) to include a new hook call in the place where the hook will be injected.

In this case add:

echo $OSCOM_Hooks->call('checkout_confirmation', 'message');

after Line 30:

https://github.com/CE-PhoenixCart/PhoenixCart/blob/master/templates/default/includes/pages/checkout_confirmation.php#L30

This would allow code to be injected after the page heading and any message stack alert messages and before the order details.

Another hook file can be created but for this example the hook file created in Example 2 /templates/override/includes/hooks/shop/checkout_confirmation/Cmessage.php is edited to change the code from:

 function listen_injectFormDisplay() {

to:

 function listen_message() {

This is now listening for the message action created in the hook call and results in this:

Hook3.png



Construction.png
This page is in progress
Please visit again soon for additions and changes

Phoenix User Guide is a continuing work in progress.
If you have any suggestions for content correction, improvement or inclusion please email us:
Contact.png
not a clickable link to prevent spam

Phoenix Cart User Guide, like CE Phoenix Cart, is free to use but is maintained by unpaid volunteers.
If you have found it useful, please donate to the coffee pot!
Use this link to donate whatever you want.

Donate with Paypal

"Phoenix" and the Phoenix Logo are copyright G. Burton.
Code references are licensed under a Commons Attribution-NonCommercial-ShareAlike 2.0 UK: England & Wales License.
All other content is the reserved Intellectual Property and Copyright of phoenixcart.org
PROTECTED BY COPYSCAPE ANTI-PLAGIARISM
uk-unlimited-728x90.gif