Difference between revisions of "How to Make a New Hook"

From Phoenix Cart User Guide
 
(38 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
<span class="btn-grey"><historylink type="back">&#129032; Back</historylink></span>
+
<div class="btn btn-grey btn-back">{{#fas:arrow-left}} Back</div> <div class="btn btn-grey btn-faq">{{#fas:question-circle}} FAQ Tips & Tricks</div>
−
<span class="btn-grey" style="color:#0088dd;">'''&#x1F809; [[FAQS TIPS & TRICKS]]'''</span>
 
 
<hr>
 
<hr>
 +
__TOC__
 +
__FORCETOC__
 +
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 and inserts its output wherever it is called in the core code.
+
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.
+
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.
  
−
In this simple example, a message is displayed in the shop on checkout_confirmation.php.
+
These hook calls can be seen in
  
−
That page is not modular, so a content module cannot be used so a hook is needed.
+
https://github.com/CE-PhoenixCart/PhoenixCart/blob/master/templates/default/includes/components/template_top.php
  
−
Looking at checkout_confirmation.php:
+
and
  
−
https://github.com/CE-PhoenixCart/Phoenix/blob/master/templates/default/includes/pages/checkout_confirmation.php#L159
+
https://github.com/CE-PhoenixCart/PhoenixCart/blob/master/templates/default/includes/components/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:
 +
<pre>$hooks->cat('injectRedirects')</pre>
 +
This hook call is in '''template_top.php''' and shows '''injectRedirects''' as the Action.
 +
 
 +
So it is calling for hooks 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:
 +
 
 +
<pre>$hooks->cat('injectSiteStart')</pre>
 +
 
 +
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:
 +
 
 +
<pre>$hooks->cat('injectBodyStart')</pre>
 +
 
 +
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 will inject the code into all pages.
 +
 
 +
 
 +
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:
 +
<pre>$hooks->cat('injectBodyStart')</pre>
 +
 
 +
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 &rarr; Configuration &rarr; My Store &rarr; 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:
 +
<pre>
 +
<?php
 +
class hook_shop_siteWide_pageTopMessage {
 +
    function listen_injectBodyStart() {
 +
        $output = PAGE_TOP_MESSAGE;
 +
        return $output;
 +
    }
 +
}
 +
</pre>
 +
 
 +
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:
 +
<pre><?php
 +
const PAGE_TOP_MESSAGE = '<div class="alert-info text-center p-2">Example Message</div>';</pre>
 +
 
 +
This hook will result in this:
 +
 
 +
<div class="mainpage_box">
 +
[[File:nav-content-module-8.png|link=|1500px]]
 +
</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 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:
 
A hook call can be seen already in place:
  
−
<pre>echo $OSCOM_Hooks->call('siteWide', 'injectFormDisplay');</pre>
+
<pre>echo $hooks->cat('injectFormDisplay');</pre>
  
−
This shows '''siteWide''', the Group and '''injectFormDisplay''', the Action.
+
This shows '''injectFormDisplay''' as 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.
 
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.
+
Note that 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.
  
 +
In this case it is named '''Cmessage.php'''
  
−
So, I need to name my new hook file according to the sorting rules explained by ecartz in the previous posts.
+
The new file is created in '''/templates/override/includes/hooks/shop/checkout_confirmation/'''
  
−
The rules are numbers, then uppercase letters (in alphabetical order), then _, then lowercase letters.
+
The following code is saved in the file:
 +
<pre>
 +
<?php
 +
class hook_shop_checkout_confirmation_Cmessage {
 +
    function listen_injectFormDisplay() {
 +
        $output = MESSAGE_CHECKOUT_CONFIRMATION;
 +
        return $output;
 +
    }
 +
}
 +
</pre>
  
−
I want my message to show before MATC so eventually decided to name it Cmessage.php
+
The output has been defined in an associated language file with '''MESSAGE_CHECKOUT_CONFIRMATION'''
  
−
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).
+
So, create a language file, '''Cmessage,php''', in '''/templates/override/includes/languages/english/hooks/shop/checkout_confirmation/'''
−
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:
 
  
 +
The following code is saved in the file:
 +
<pre><?php
 +
const MESSAGE_CHECKOUT_CONFIRMATION = '<div class="alert-danger text-center my-2 p-2">Example Message</div>';</pre>
  
 +
This results in this:
 
<div class="mainpage_box">
 
<div class="mainpage_box">
 
[[File:hook1.png|link=]]
 
[[File:hook1.png|link=]]
 
</div>
 
</div>
 +
 +
----
 +
 +
===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:
 +
<pre> echo $hooks->cat('message');
 +
</pre>
 +
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:
 +
<pre> function listen_injectFormDisplay() {</pre>
 +
to:
 +
<pre> function listen_message() {</pre>
 +
 +
This is now listening for the '''message''' action created in the hook call and results in this:
 +
 +
<div class="mainpage_box">
 +
[[File:hook3.png|link=]]
 +
</div>
 +
  
  

Latest revision as of 11:33, 1 October 2024

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

https://github.com/CE-PhoenixCart/PhoenixCart/blob/master/templates/default/includes/components/template_top.php

and

https://github.com/CE-PhoenixCart/PhoenixCart/blob/master/templates/default/includes/components/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: 

$hooks->cat('injectRedirects')

This hook call is in template_top.php and shows injectRedirects as the Action.

So it is calling for hooks 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: 

$hooks->cat('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: 

$hooks->cat('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 will inject the code into all pages.


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: 

$hooks->cat('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() {
        $output = PAGE_TOP_MESSAGE;
        return $output;
    }
}

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 $hooks->cat('injectFormDisplay');

This shows injectFormDisplay as 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.

Note that 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.

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 = MESSAGE_CHECKOUT_CONFIRMATION;
        return $output;
    }
 }

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 $hooks->cat('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 Cart User Guide, like CE Phoenix Cart, is free to use but is maintained by unpaid volunteers.

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
Retrieved from ‘https://phoenixcart.org/phoenixcartwiki/index.php?title=How_to_Make_a_New_Hook&oldid=5326’