{"id":37,"date":"2015-04-12T18:21:00","date_gmt":"2015-04-12T16:21:00","guid":{"rendered":"https:\/\/daniel.liljeberg.io\/?p=37"},"modified":"2021-04-01T22:02:08","modified_gmt":"2021-04-01T20:02:08","slug":"how-to-develop-plugins-for-osclass","status":"publish","type":"post","link":"https:\/\/daniel.liljeberg.io\/sv\/2015\/04\/12\/how-to-develop-plugins-for-osclass\/","title":{"rendered":"How to develop Plugins for Osclass"},"content":{"rendered":"\n

As described in my earlier post<\/a>, Osclass is a free, open-source, web application written in PHP for classified ads. One of the strong sides of it is that you have the options to create and install custom plugins to extend and alter the behavior of the application. There is an integrated market where existing plugins can be easily downloaded and installed. Here are some of my own creations<\/a> (more are being updated and are on the way).<\/p>\n\n\n\n

I started by creating plugins for my own personal use. Since I was the only one using them I often left configuration options in configuration files instead of building full fledged admin interfaces.<\/p>\n\n\n\n

But as time went by people started asking me if they could have a copy of different plugins I had made. This would require me to add functionality to them to make them easily managed by other people. Often people who weren\u2019t developers.<\/p>\n\n\n\n

One thing that struck me when I was writing new plugins was the official way<\/a> that they are to be written which I thought had several issues. Since I never thought I would make many plugins, and especially not any released ones, I swallowed my pride and stuck to their regime. But now when I found myself planning more plugins I felt I wanted to streamline the experience of creating plugins for Osclass.<\/p>\n\n\n\n

Bellow I will walk you through creating a very simple plugin using the official way<\/em>. Later I will describe the ideas I have come up with to further streamline and isolate the plugins. The plugin we will be building will be a simple Hello World<\/strong> type plugin with the added option that we will dynamically set the message to show the user.<\/p>\n\n\n\n

File structure<\/h2>\n\n\n\n

To create a plugin you first create a folder under the oc-content\/plugins<\/strong> folder, you can call it whatever you want. Within that folder you will need to place at least one file, index.php<\/strong>. <\/em>That is basically the only requirements regarding the file structure. You could add several files and libraries, java script files, css files etc.<\/p>\n\n\n\n

Conventions and guidelines<\/h2>\n\n\n\n

Due to the fact that functions in your index.php<\/strong> will all be public, you do best in choosing a prefix that ensures that your function don\u2019t end up having the same name as any other function. If your plugin would contain a function install()<\/strong> and another plugin would do the same you would run into problems. Whatever convention you choose to pick your prefix is up to you. But prefixing with some developer identifier and\/or the plugin name is one way to go.<\/p>\n\n\n\n

Later when we look at my alternate way of writing plugins we will see how we can pretty much circumvent this issue altogether.<\/p>\n\n\n\n

Information block<\/h2>\n\n\n\n

Each plugin in Osclass will have a information block in their index.php<\/strong> file. Here\u2019s an example of ours. More options exist and depending on your plugin not all will be needed.<\/p>\n\n\n\n

\/*\nPlugin Name: dliTest\nPlugin URI: http:\/\/www.foobar.org\/\nDescription: A small test plugin\nVersion: 1.0.0\nAuthor: Daniel Liljeberg\nAuthor URI: http:\/\/www.danieliljebergorg\/\nShort Name: dliTest\nPlugin update URI: dli-test\nSupport URI: http:\/\/support.foobar.org\n*\/<\/pre>\n\n\n\n
This information is used internally by Osclass and is for example presented in the admin interface.<\/p>\n\n\n\n
Make your plugin installable<\/h2>\n\n\n\n
To make it possible for a plugin to be installed<\/strong> you have to add a piece of code to your index.php<\/strong> file.<\/p>\n\n\n\n
osc_register_plugin(osc_plugin_path(__FILE__), 'dliTest_install');<\/pre>\n\n\n\n
What this does is basically to register our plugin as being able to be installed and when a user chooses to install our plugin Osclass will run the function dliTest_install<\/strong> which we don\u2019t have yet. So let\u2019s add that to our index.php<\/strong>. In the same way we can add a function to be run when our plugin is uninstalled by a user. So we\u2019ll go ahead and do that to.<\/p>\n\n\n\n
\/*\nPlugin Name: dliTest\nPlugin URI: http:\/\/www.foobar.org\/\nDescription: A small test plugin\nVersion: 1.0.0\nAuthor: Daniel Liljeberg\nAuthor URI: http:\/\/www.danieliljebergorg\/\nShort Name: dliTest\nPlugin update URI: dli-test\nSupport URI: http:\/\/support.foobar.org\n*\/\n\n\/\/ Plugin functions\nfunction dliTest_install() {\n}\n\nfunction dliTest_uninstall() {\n}\n\n\/\/ Register hooks\nosc_register_plugin(osc_plugin_path(__FILE__), 'dliTest_install');\nosc_add_hook(osc_plugin_path(__FILE__).\"_uninstall\", 'dliTest_uninstall');<\/pre>\n\n\n\n
Now we are able to install and uninstall our plugin, although it won\u2019t actually do much.<\/p>\n\n\n\n
Hooks<\/h2>\n\n\n\n
Osclass uses the concept of hooks<\/strong> to enable you to hook in different parts of your plugin to be run at different points during the applications execution.<\/p>\n\n\n\n
The normal syntax for registering a hook is<\/p>\n\n\n\n
osc_add_hook('hook_name', 'function_name');<\/pre>\n\n\n\n
Our call to osc_register_plugin<\/strong> in order to make it possible to install our plugin is actually just a special case for registering a hook to handle the installation. But it also handles some other functionality and is therefore wrapped in its own function.<\/p>\n\n\n\n
As you can see the uninstall<\/strong> function above is registered using the normal <\/em>osc_add_hook()<\/strong> function, although it does have a bit of a special syntax where the name must be the your_plugins_folder\/index.php<\/strong>.<\/p>\n\n\n\n
There are a ton of hooks you can use. For instance there are hooks that run in the page header, in the page footer, when the user is visiting an item page, when a new item is posted etc.<\/p>\n\n\n\n
Look here for a complete list of hooks<\/a>.<\/p>\n\n\n\n
So a hook has a name and you supply it a function name. Then it makes code your have written in your plugin run at specific places in the application execution flow. This might look very magical, but it\u2019s actually quite easy. When you register a hook<\/strong> the function name you have provided is added to a list of functions to run when the hook with that name is run. It\u2019s basically like providing it a function pointer, but since php<\/strong> gladly executes a function in a multitude of ways you simply have to store the name of the function to run.<\/p>\n\n\n\n
For example these are all valid in php<\/p>\n\n\n\n
\/\/ Define a function\nfunction helloWorld() {\necho \"Hello World\";\n}\n\n\/\/Calls function\nhelloWorld();\n\n\/\/Also calls function\n$funcName = \"helloWorld\";\n$funcName();<\/pre>\n\n\n\n
Osclass then simply run a function at specific places that run a given hook.<\/p>\n\n\n\n
osc_run_hook(\"header\");<\/pre>\n\n\n\n
Now all functions registered to the header<\/strong> hook will be run at that place.<\/p>\n\n\n\n
Common uses for this is to add things top the html header, like tags, loading scripts etc. Or hooking in and altering forms such as search and the form to post new items.<\/p>\n\n\n\n
Deciding what runs when<\/h3>\n\n\n\n
One of the problems of the hooks is that there is no real way of telling when in the queue of functions to run your specific function is. It could be that it\u2019s very important that you run your code early, before other plugins have been able to run their functions for the same hook. To help facilitate this you can pass an optional third parameter to the osc_register_hook<\/strong> function. The third parameter will let you set the priority on a scale between 1 and 10 for the function you just registered. But do note that a registered function that has the same priority would make it hard for you to know for sure that your function will be the first to run.<\/p>\n\n\n\n
Without knowing for sure I would guess that if two functions have the same priority and register for the same hook, the one registered first will run first. The one registered first will be the one owned by the plugin that was loaded before the other one. And the order in which the plugins load is very likely to be dependent on their alphabetical sorting of their directory name in the oc-content\/plugins<\/strong> folder.<\/p>\n\n\n\n
So PluginA<\/strong> would load before PluginB<\/strong> and if PluginA<\/strong> registered foo<\/strong> to run at the hook header<\/strong> and PluginB<\/strong> registered bar<\/strong> to run at the same hook<\/strong> and they both had the same priority set<\/strong>, foo <\/strong>would most likely be run before bar<\/strong>.<\/p>\n\n\n\n
Make our plugin print something<\/h2>\n\n\n\n
Many plugins simply make use of existing hooks to output at specific places. For instance, to make our plugin write something when we look at the details of an item we could use the item_detail <\/strong>hook. This hook run at the middle of item\u2019s detail page. $item<\/strong> is passed as argument and can be used if needed.<\/p>\n\n\n\n
function dliTest_item_details_hook($item) {\n  echo '<h3>Hello World<\/h3>;\n}\nosc_add_hook('item_detail', 'dliTest_item_detail');<\/pre>\n\n\n\n
But what if we want to our plugin write Hello World<\/strong> in a page we have designed ourselves. In order to do that we will have to complete a couple of more steps.<\/p>\n\n\n\n
Creating a route<\/em> to our file<\/h3>\n\n\n\n
A route is basically a way for you to tell Osclass that<\/p>\n\n\n\n
This url<\/strong> should present the user with this file<\/strong><\/em><\/p>\n\n\n\n
To do that in Osclass we use the function osc_add_route()<\/strong>. Read about it more on Using routes with Osclass<\/a>.<\/p>\n\n\n\n
So, let\u2019s add a quick route to a page called helloWorldPage.php<\/strong> and make the route accept a parameter names message<\/strong> consisting of characters between a-Z<\/strong>. I will name the route similarly to the actual file, but this is in no way needed.<\/p>\n\n\n\n
osc_add_route('helloWorldPage', 'helloWorldPage\/([a-zA-Z]+)', 'helloWorldPage\/{message}', osc_plugin_folder(__FILE__).'helloWorldPage.php');<\/pre>\n\n\n\n
Link to our new route<\/h3>\n\n\n\n
Let\u2019s create a href link in the footer of the page to our new route.<\/p>\n\n\n\n
To do that we register a hook to run a function that will print our link. In order to get the actual url<\/strong> of our route we use the function osc_route_url()<\/strong>. To that we can also pass an array of values so here we decide what our message variable should be.<\/p>\n\n\n\n
function dliTest_footer() {\n  $pageUrl = osc_route_url('helloWorldPage', array('message' => 'Hello World!'));\n  echo '<a href=\"'. echo $pageUrl .'\">Go to hello world!<\/a>';\n} \nosc_add_hook('footer', 'dliTest_footer');<\/pre>\n\n\n\n
Display our message<\/h3>\n\n\n\n
If you refresh you site now you should see a link in your footer. But clicking it won\u2019t quite take us where we want yet, we first have to create our helloWorldPage.php<\/strong> file. Save it in the same folder as your index.php <\/strong>file. Here we extract the message<\/strong> parameter sent using the Params<\/strong> object and echo it.<\/p>\n\n\n\n
<?php\n  $message = Params::getParam('message');\n?>\n\n<h3><?php echo $message?><\/h3><\/pre>\n\n\n\n
Now you will be able to click the link and be taken to the page showing your message.<\/p>\n\n\n\n
Complete listing<\/h2>\n\n\n\n
index.php<\/strong><\/p>\n\n\n\n
\/*\nPlugin Name: dliTest\nPlugin URI: http:\/\/www.foobar.org\/\nDescription: A small test plugin\nVersion: 1.0.0\nAuthor: Daniel Liljeberg\nAuthor URI: http:\/\/www.danieliljebergorg\/\nShort Name: dliTest\nPlugin update URI: dli-test\nSupport URI: http:\/\/support.foobar.org\n*\/\n\n\/\/ Plugin functions\nfunction dliTest_install() {\n}\n\nfunction dliTest_uninstall() {\n}\n\nfunction dliTest_footer() {\n  $pageUrl = osc_route_url('helloWorldPage', array('message' => 'Hello World!'));\n  echo '<a href=\"'. echo $pageUrl .'\">Go to hello world!<\/a>';\n} \nosc_add_hook('footer', 'dliTest_footer');\n\/\/ Register routes \nosc_add_route('helloWorldPage', 'hellowWorldPage\/([a-zA-Z]+), 'helloWorldPage\/{message}', osc_plugin_folder(__FILE__).'helloWorldPage.php'); \n\n\/\/ Register hooks \nosc_register_plugin(osc_plugin_path(__FILE__), 'dliTest_install'); \nosc_add_hook(osc_plugin_path(__FILE__).\"_uninstall\", 'dliTest_uninstall');<\/pre>\n\n\n\n
helloWorldPage.php<\/strong><\/p>\n\n\n\n
<?php\n  $message = Params::getParam('message');\n?>\n\n<h3><?php echo $message?><\/h3><\/pre>\n\n\n\n
Closing thoughts<\/h2>\n\n\n\n
This was a very simple plugin but the basic is the same even for larger plugins. You will end up with more hooks, more files and more routes. But this is what almost every plugin looks like. But keeping it all neat and easy for others to comprehend becomes quite hard when the plugins grow. We will look into this problem and how we can solve it in the next post.<\/p>\n\t\t\t\n\n\n
\n
Comments<\/h3>\n
 \n
\n\t<\/a>\n\t
\n\t