How to Make a New Hook
<historylink type="back">🠈 Back</historylink> 🠉 FAQS 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-danger text-center my-2 p-2">Example Message</div>';
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 only into that specific page.
It will display a message in the shop on checkout_confirmation.php
Looking at 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.
So, I need to name my new hook file according to the sorting rules explained by ecartz in the previous posts.
The rules are numbers, then uppercase letters (in alphabetical order), then _, then lowercase letters.
I want my message to show before MATC so eventually decided to name it Cmessage.php
To make the most of the template system, I created that new file in /templates/override/includes/hooks/shop/checkout_confirmation/ (I had to create the directories to follow that structure). The file could be in whatever template that is being used, that is, whatever has been selected in admin->Configuration->My Store->Template Selection. In that file I used the code:
<?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 class name hook_shop_checkout_confirmation_Cmessage must follow the same structure as the hook file location, that is, shop/checkout_confirmation/Cmessage The function listen_ is followed by the Action in the hook call, in this instance, injectFormDisplay
The output, that is, what is shown on the page has been defined in an associated language file with MESSAGE_CHECKOUT_CONFIRMATION So, I created a file, Cmessage,php, in /templates/override/includes/languages/english/hooks/shop/checkout_confirmation/ In that file I used the code:
<?php const MESSAGE_CHECKOUT_CONFIRMATION = '<div class="alert-danger text-center my-2 p-2">Example Message</div>';
This results in this:
[attachment=0]Screenshot 2021-02-25 173924.png[/attachment]
So, what if I didn't want the message to show down by MATC?
I made a copy of /templates/default/includes/pages/checkout_confirmation.php and saved that to /templates/override/includes/pages/checkout_confirmation.php
I edited that new file (it will never be overwritten in updates) to include a new hook call in the place I want the message to appear.
In this case I added:
<?php echo $OSCOM_Hooks->call('checkout_confirmation', 'message');?>
after Line 31 https://github.com/CE-PhoenixCart/Phoenix/blob/master/templates/default/includes/pages/checkout_confirmation.php#L31 checkout_confirmation is the Group, that is, /hooks/shop/checkout_confirmation/ message is the Action, I could name it whatever but keep it unique and meaningful.
So now, in /templates/override/includes/hooks/shop/checkout_confirmation/Cmessage.php I change the code from:
function listen_injectFormDisplay() {
to:
function listen_message() {
This results in this:
[attachment=0]Screenshot 2021-02-25 181035.png[/attachment]
And I feel good!
Hooks cannot be disabled or turned on and off like content modules, they are always on but with this simple hook example, it can be made to disappear by emptying the language constant in the language file, like this:
<?php const MESSAGE_CHECKOUT_CONFIRMATION = '';
Please visit again soon for additions and changes
Phoenix Cart User Guide, like CE Phoenix Cart, is free to use but is maintained by unpaid volunteers.
All other content is the reserved Intellectual Property and Copyright of phoenixcart.org
