How to: Addons
This document will explain basic flow of Addons in BriskLimbs and we'll build a simple addon to say hello to users on website.
Addons are small bundles of functionality that can be added on top of BriskLimbs core features. There are multiple benefits of developing new features using addons instead of making changes to the core.
- Easy for users to enabled or disable specific functionality
- Core bugs are easy to debug and if a an addon breaks, you can quickly restore site by simply disabling it
- They are easier to developer and maintain
Hooks are functions that can be registered for using in Twig templates. Addon hooks are optional because BriskLimbs supports a global hook function "hook" for calling any PHP function in Twig templates but it is better if you manually register addon hooks for better code readability. Here is how to register addon hook in BriskLimbs
Addon triggers are location throughout BriskLimbs Skin where you can inject functionality directly from your Addon without making changes to skin files. You can also request values to be returned from these locations. These are currently supported locations.
- admin_videos_actions_top
- admin_videos_actions_bottom
- admin_users_actions_bottom
- admin_users_actions_top
- user_videos_actions_top
- user_videos_actions_bottom
- head_start
- head_end
- navbar_before
- navbar_after
- body_before
- body_after
- footer_before
- footer_after
- footer_start
- footer_end
- all_sidebars_top
- all_sidebars_bottom
- watch_sidebar_top
- watch_sidebar_bottom
- browse_sidebar_top
- browse_sidebar_bottom
- channel_sidebar_top
- channel_sidebar_bottom
Here is how to add addon trigger in BriskLimbs
Now that you have basics under the belt, we are ready to get started with building a little addon of our own. Here is what this addon will have. You can grab complete code for HelloWorld Addon here
- A database table to store welcome message
- An admin menu which links to an admin page to update welcome message
- Display message via Hook
- Display message via Trigger
The first thing we need to do is create a new directory under "addons" and name it "helloWorld". You can name it anything you like but let's stick with this tutorial.
An addon is required to have a minimum of three files for it to function. These files are
- plugin.json: core information of addon
- mainfile.php: (in our case helloworld.php): file that will be required for addon to run
- install.php: file that runs on installation to create database tables etc.
Now Go ahead and create plugin.json. This file contains core information of addon. Here is what our file is going to look like.
{
"name" : "hello_world",
"display_name": "HelloWorld",
"file": "helloworld.php",
"author": "Your name",
"autor_website": "https://your_website.com",
"date": "year, month, date",
"description": "This addon says hello to website users",
"version": "1.0",
"state": "Stable"
}
The required fields out of all these are name, display_name and file.
Now create helloworld.php and paste following code in it.
$addons = new Addons();
define('HELLOWORLD_CORE_PATH', __DIR__);
define('HELLOWORLD_CORE_NAME', basename(HELLOWORLD_CORE_PATH));
$pages = HELLOWORLD_CORE_NAME . '|pages';
This will initialise basic values for addon but won't be functional yet. Let's proceed to next step.
Since we need to save our welcome message in database, we'll need to create a new table on plugin installation. So go ahead and create a file install.php and paste following contents.
<?php
global $database;
$table = 'hello_world';
$columns = array(
'id' => array('type' => 'int(1)', 'special' => 'primary'),
'message' => array('type' => 'text')
);
$values = array(
array('message' => 'Welcome to this website')
);
$database->createTable($table, $columns);
$database->insertMulti($table, $values);
This will create a very basic table with just one row and that's where our message will be stored. We are inserting a default welcome message at installation which can be modified later. Now if you go to admin/addons/?list=all you should see this addon listed there. If you install it, a new table will be created as well but we still won't be able to edit or display the message. Let's continue building. We're not far now.
It is time to build our admin area pages. Create a directory pages and create two files welcome.php and welcome.html. Here welcome.php is the file that will handle fetching and updating of message while welcome.html will be used for displaying edit form.
Page following code in welcome.php
<?php
global $limbs;
$addons = new Addons();
if (isset($_POST['message'])) {
$limbs->database->where('id', 1);
$status = $limbs->database->update('hello_world', array('message' => $_POST['message']));
if ($status) {
$parameters['message'] = 'Message updated';
} else {
$parameters['errors'][] = 'Failed to update message';
}
}
$parameters['response'] = $limbs->database->getOne('hello_world');
$parameters['_title'] = 'Edit Message';
$parameters['mainSection'] = 'hello_world';
$addons->display(HELLOWORLD_CORE_NAME, 'pages/welcome.html', $parameters);
Paste following code in welcome.html
{% extends 'layout.html' %}
{% block content %}
<div class="content-wrapper bg-light">
<div class="col-12 grid-margin">
{% if message %}
<div class="alert alert-success">{{message}}</div>
{% endif %}
{% for error in _errors %}
<div class="alert alert-danger">{{error}}</div>
{% endfor %}
<div class="card">
<div class="card-body">
<h4 class="card-title">Edit Welcome Message</h4>
<form name="welcome-message" method="post">
<textarea name="message" placeholder="Your message here" class="form-control" rows="10">{{response.message}}</textarea>
<button type="submit" class="btn btn-gradient-primary">Save</button>
</form>
</div>
</div>
</div>
</div>
{% endblock %}
Our admin area template is ready and now we should add an admin menu to be able to edit the message. We can create an admin menu using addMenu() method. Paste following code at end of helloworld.php
$menu = array(
'hello_world' => array(
'display_name' => 'HelloWorld',
'sub' => array(
'Edit Message' => $pages . '|welcome.php'
)
)
);
$addons->addMenu($menu);
This creates a menu "HelloWorld" with a sub menu "Edit Message" which takes us to welcome.php for editing message. You can change message to anything we like.
We have two options to display this message. We either use "Hooks" and manually edit a skin file or automatically insert message using a "Trigger". This tutorial will show both methods but first we need to add function for displaying message.
Add following code before $menu variable
function sayHello() {
global $limbs;
echo $limbs->database->getOne('hello_world')['message'];
}
So now our helloworld.php looks like this.
<?php
$addons = new Addons();
define('HELLOWORLD_CORE_PATH', __DIR__);
define('HELLOWORLD_CORE_NAME', basename(HELLOWORLD_CORE_PATH));
$pages = HELLOWORLD_CORE_NAME . '|pages';
function sayHello() {
global $limbs;
echo $limbs->database->getOne('hello_world')['message'];
}
$menu = array(
'hello_world' => array(
'display_name' => 'HelloWorld',
'sub' => array(
'Edit Message' => $pages . '|welcome.php'
)
)
);
$addons->addMenu($menu);
- Display using Hooks Place following code anywhere in Skin template files where you'd like this message to appear.
{{hook('sayHello')}}
- Display using Triggers
Let's make this message show at top of sidebar on watch video page. Add following code at end of
helloworld.php
$addons->addTrigger('sayHello', 'watch_sidebar_top');
Now open any video and you should see this message in sidebar.
And that's it for our Addons tutorial. If you have any suggestions, please drop them in comments section below.
