A Phoenix module is a way of adding an addon to Phoenix that can be enabled/disabled as well as have customizable options that admins can adjust within their module area.
A module in Phoenix requires a couple of files at minimum:
- Module File
- This is the file that will have the module class and logic.
- Language File
- You will want to create a language file for each language that you plan to support. I usually just create an english version but you can choose which ever language you require.
For this example we will just add a javascript alert to the catalog for a simple test.
Create a new file, calling it something that is unique that won’t collide with other modules. (Refer to rules)
We’ll call this file:
ht_zipur_alert_example.php
and we’ll place it in:
catalog/includes/modules/header_tags/
The above path refers to your “catalog” or base directory of your store.
The above path also refers to “header_tags” which is one of the module types.
Here is an example of the file:
<?php
/**
* $Id: ht_zipur_alert_example.php
* $Loc: catalog/includes/modules/header_tags/
*
* zipurAlertExample
* Version: 0.1.0
* Author: Preston Lord
* aka zipurman / zipur.ca / plord@inetx.ca
*
* Modified Date: 08/05/2020
* Created as a module test
* Copyright (c) 2020: Preston Lord - @zipurman
* All rights reserved.
* Released under the GNU General Public License
*/
class ht_zipur_alert_example extends abstract_executable_module {
const CONFIG_KEY_BASE = 'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_';
public function __construct() {
parent::__construct( __FILE__ );
}
public function execute() {
$alerttext = MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT;
$script = <<<js
<script>
alert('{$alerttext}');
</script>
js;
$GLOBALS['oscTemplate']->addBlock( "{$script}", 'footer_scripts' );
}
public function get_parameters() {
return [
'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_STATUS' => [
'title' => 'Enable Information Links Footer Module',
'value' => 'True',
'desc' => 'Do you want to allow Zipur Test Alert to be added to the site?',
'set_func' => "tep_cfg_select_option(['True', 'False'], ",
],
'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT' => [
'title' => 'Alert Message',
'value' => '',
'desc' => 'Your visitors will see this message.',
],
];
}
}
Let’s break down the above module example:
- A comment block should always be added to the top of your file to show the details, author, copyright, etc.
- The class name ht_zipur_alert_example is very important.
This should match the other files in the folder. In this example, all header_tags modules are prepended with a “ht_” - Notice that the class ht_zipur_alert_example extends abstract_executable_module this must be the case for it to adopt all required logic from the parent class.
- At the start of the class you have a defined constant CONFIG_KEY_BASE
- This constant should have a value that is the base for all of your required module variables. For example, MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_STATUS and MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT both start with MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_ so that is why the CONFIG_KEY_BASE is set to this value.
- The __construct() method is called when the ht_zipur_alert_example class is instantiated (started)
- This method simply calls the parent class and its __construct.
- The execute() method is the main part of the module. This is what is called when the module executes.
- In this example, we are simply creating a heredoc block with a script that fires our alert message and then injecting the result into the “footer_scripts” area of the Phoenix core. There are several areas in the Phoenix core you can target.
- The get_parameters() method is used when an admin decides to install/remove/edit the module.
- In this example, an array with 2 sub-arrays are configured.
- MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_STATUS
- This is the above CONFIG_KEY_BASE + STATUS
- This is what will be used as the status indicator for the module (on/off)
- MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT
- This is the above CONFIG_KEY_BASE + TEXT
- This will be used fort our alert text in the execute() method
- MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_STATUS
- You could also add additional configuration options here, each with their own unique name and then use those defined variables in your logic
- In this example, an array with 2 sub-arrays are configured.
That is it. The logic has been greatly simplified from the old way. You can add as many additional configuration items to the get_parameters() as you need. If the module is active, then each of the constants in that array will be available.
Now we need to add a language file. You must match the path to your above module so we will place this file as:
catalog/includes/languages/english/modules/header_tags/ht_zipur_alert_example.php
The language file will then be loaded when the module is loaded.
Here is the file:
<?php
/**
* $Id: ht_zipur_alert_example.php
* $Loc: catalog/includes/languages/english/modules/header_tags/
*
* zipurAlertExample
* Version: 0.1.0
* Author: Preston Lord
* aka zipurman / zipur.ca / plord@inetx.ca
*
* Modified Date: 08/05/2020
* Created as a module test
* Copyright (c) 2020: Preston Lord - @zipurman
* All rights reserved.
* Released under the GNU General Public License
*/
define('MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TITLE', 'Zipur Alert Example');
define('MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_DESCRIPTION', 'Add the Zipur Alert Example to your site.');
In the above example we simply have our defined variables that we use in the module. These ARE NOT the same as the defined keys that we add to the database in the install() of the main class, but these are any language items wrapped around the module that people will see in either the admin configuration or the front-end website visitors.
Also, the defined language items must match the CONFIG_KEY_BASE:
- CONFIG_KEY_BASE + TITLE
- CONFIG_KEY_BASE + DESCRIPTION