Module guide
Hooks are a dynamic way of manipulating with almost all aspects of pluck. The system is based on functions, and is very flexible. Do you want to add an extra menu in the admin panel? You are now able to do that. This document will show the idea behind hooks, and how to use them to develop your own modules.
The current system of hooks has been introduced in pluck 4.7. This means old 4.6.x modules will not work with the pluck 4.7 series.
Start by creating a new folder in data/modules. This will also be the prefix we will use for every function in the module. But more about that later.
Now, create a PHP file in the module folder, with the same name as the module folder. If your folder is test, your file will be test.php. You should now have an empty file here: data/modules/test/test.php
The first function needed for every module, is an info function. It looks like this:
function PREFIX_info() {
$module_info = array(
'name' => 'Test module',
'intro' => 'Created to show the new hooks.',
'version' => '0.1',
'author' => 'Anders Jørgensen',
'website' => 'http://spirit55555.dk',
'icon' => 'images/test.png',
'compatibility' => '4.7'
);
return $module_info;
}
You can change the info as you like.
Two things you should note:
- The module name does not have to be the same as the folder.
- PREFIX is the name of the module folder. In this case it should be test. All functions should start with that, or else they won't work.
The module now shows up in options -> manage modules, but it's not "hooking" anything yet.
Developers can run hooks anywhere they want in pluck. In the core, in themes and even in modules. That will be explained later, because right now, we are focusing on how to add something to an existing hook.
This tutorial will show how to add some CSS in the admin panel, so the font color becomes <hi #ff00ff>pink or any other color you like.
There is a hook called admin_header_main between <head> and </head>. Sounds like the perfect place to inject some CSS.
Add the following code to your PHP file:
function PREFIX_admin_head_main() {
echo '<style type="text/css">body {color: pink;}</style>';
}
And that's it! You don't have to do anything more. This is how every hook works. Just create a function starting with PREFIX_, and then the hook name (in this case it was admin_header_main). For a list of all available hooks, see the list of hooks.
Now that we have explained the basic idea behind hooks, let's move on. Now we want to add some pages to the admin center. For this, we need to create a new file, called data/modules/PREFIX/PREFIX.admin.php. So in the case of our module named test, the file will be data/modules/test/test.admin.php.
Once we have created this new file, let's start by providing pluck with a list of pages we want to create:
function PREFIX_pages_admin() {
$module_page_admin[] = array(
'func' => 'test',
'title' => 'Main admin page of module'
);
$module_page_admin[] = array(
'func' => 'somepage',
'title' => 'Title of some other admin page'
);
return $module_page_admin;
}
As you can see, we need to define two things for each page:
- func - short name for the page, without spaces. Is used in URLs.
- title - full title of the page.
Maybe you noticed that we created a page with the func-variable the same as our module PREFIX (in our case test). This will be the main page of our module, and because of this pluck will automatically create a link for it on the module page (see main menu -> modules). The URL for this main page will be admin.php?module=PREFIX, so in our case admin.php?module=test. It's not required to create a main page, so if you don't need it you can skip it.
All other pages then the main page will have an URL like this: admin.php?module=PREFIX&page=PAGE, so in our case it will be admin.php?module=test&page=some-other-page.
The only thing we still need to do is add some code for the pages, because right now they are empty. The code for a page looks like this:
function PREFIX_page_admin_PAGE() {
echo 'Hello there!';
}
So in the case of our module, the complete code of data/modules/test/test.admin.php will look like this:
function test_pages_admin() {
$module_page_admin[] = array(
'func' => 'test',
'title' => 'Main admin page of module'
);
$module_page_admin[] = array(
'func' => 'somepage',
'title' => 'Title of some other admin page'
);
return $module_page_admin;
}
function test_page_admin_test() {
echo 'Hello there! This is the test page of my module.';
}
function test_page_admin_test() {
echo 'Hi! This is some other admin page in my module.';
}
We can not only add code and/or pages to the admin center, but we can do the same for the website. Code for the website will be defined in yet another file we need to create: data/modules/PREFIX/PREFIX.site.php, so in our case data/modules/test/test.site.php.
Let's start by adding the PREFIX_theme_main() function. This function will be executed when your module has been added to a page. So in our case, the code will look something like:
function test_theme_main() {
echo 'Hi! My module has been included in this page.';
}
Ok, that was not so hard. Now we are going to add some pages to the website. This works exactly the same as in the admin center, so let's give a quick example:
function test_pages_site() {
$module_page_site[] = array(
'func' => 'firstpage',
'title' => 'First page'
);
$module_page_site[] = array(
'func' => 'secondpage',
'title' => 'Second page'
);
return $module_page_site;
}
function test_page_site_firstpage() {
echo 'Hello there! This is the first site page of my module.';
}
function test_page_site_secondpage() {
echo 'Hi! This is the second site page of my module.';
}
In the website area, module pages can only be displayed with a site page specified. Not just any site page will work, but only site pages in which the module has been included by the user. Now we can access the module pages on the website with the URLs index.php?file=some-page&module=test&page=firstpage and index.php?file=some-page&module=test&page=secondpage.
In some cases, parameters will be passed to the PREFIX_theme_main() function. This concerns the following two parameters (also in this specific order):
- theme area - the theme area in which the module has been included. This parameter is only set when the module has been included site-wide in a specific theme area (these theme areas are set in the theme, see the theming guide for more info). If the module is included in a page, this parameter is set to null.
- category - the category that should be displayed for the module. This parameter is only set when you have configured your module to use categories, and the user has specified a category for your module. Otherwise, the parameter is set to null. For more information on how to use categories in your module, see below.
If you want, you can use these parameters in your module. You need to call these parameters in the specific order that is mentioned above. An example of what this could look like:
function test_theme_main($area, $category) {
if (!isset($area))
echo 'This module is not included site-wide in a theme area, but in a page.';
else
echo 'This module is included in the theme area '.$area;
if (!isset($category))
echo 'No category has been specified for this module, so maybe we want to show all categories.';
else
echo 'The specified category for this module is '.$category;
}
Pluck offers you the possibility to specify categories for your module. When including a module in a page, users will be able to choose from the categories you provided them with, but they can also choose to specify no category and include your module as a whole. In the above example, you can see how you can call the category parameter provided by the user. But you also need to let pluck know which categories are available for your module, so that pluck can show them to the user.
Specifying categories is fairly simple, and is done in the info function of your module. We just put all the categories in an array, like this:
function test_info() {
$module_info = array(
'name' => 'Test module',
'intro' => 'Created to show the new hooks.',
'version' => '0.1',
'author' => 'Anders Jørgensen',
'website' => 'http://spirit55555.dk',
'icon' => 'images/test.png',
'compatibility' => '4.7',
'categories' => array('category-1', 'category-2')
);
return $module_info;
}
Now, users will be able to choose the categories "category-1" and "category-2" for your module.
Some of the hooks not only allow you to insert your own code in different places, but also allow you to change pluck system parameters. We can, for example, decide to use our module to change the theme that is being used by pluck. Take a look at this code, in data/modules/PREFIX/PREFIX.php (in our case data/modules/test/test.php):
function test_site_theme($page_theme) {
$page_theme = 'our-new-theme';
}
As you can see, we used the hook site_theme for this function. Inside the parantheses, we put the variable we are going to use to pass the new theme to pluck. We chose for the variable $page_theme, but you can choose anything you like. Of course you can use any PHP-code you want inside the function. Maybe you want a different theme for Christmas time?
function test_site_theme($page_theme) {
if (date('F') == 'December') {
$page_theme = 'christmas-theme';
}
}
Also good to know, is that the variable we choose between the parentheses ($page_theme, in our case) contains the current setting of the parameter we can change. We can use this in our code. See this (not very useful) example:
function test_site_theme($page_theme) {
//We don't like the default theme, let's change it in something else.
if ($page_theme == 'default') {
$page_theme = 'something-else';
}
}
For a full overview of filter hooks, see the list of hooks. You will also find the normal hooks there.
A demo of a simple module https://github.com/pluck-cms/simple