Creating a basic plugin
This tutorial will walk you through the creation of a basic plugin that adds the text "Hello World" to Pro Edition's Main Menu, next to the "Basic Features Group" heading.
Stuff you should have for this tutorial...
- A website with Soholaunch Pro Edition installed on it that you can screw around with. All feature modules should be enabled.
- FTP client and FTP access to your test site
- Some kind of code/text editor to edit php files with (Dreamweaver, UltraEdit, PHP Edit, Emacs, Notepad, etc.)
- Mild-to-moderate web skillz (html, css, and at least some dabbling with php)
- Some level of familiarity with Pro Edition's various folders and files (i.e. sohoadmin)
Create a folder for your plugin
Pop open Windows Explorer (or Mac/Linux equivalent) and create a folder on your local PC called "HELLO_WORLD". All of your plugin's files will go in this folder.
Download the source file you want to modify
Open Your FTP client and log-in to your test site. For this example, we want to modify Pro Edition's main menu, so download this file from your test site...
Stick this file in the "HELLO_WORLD" folder you created on your PC, and rename it to something like "main_menu-helloworld.php" (actual filename doesn't really matter, as long as you recognize it as your modified version of main_menu.php).
Modify source file
No pull up the file in your trusty code editor.
Do a ctrl+f (find) on "Basic Features Group", and you should get to a line that looks something like...
<td class="fgroup_title"><? echo lang("Basic Features Group"); ?></td>
Modify this line so it looks like this:
<td class="fgroup_title"><? echo lang("Basic Features Group"); ?> - Hello World</td>
Save the file.
Create an install_manifest.php for your plugin
Still in your code editor, create a new blank document (i.e. ctrl + n) and save to your HELLO_WORLD folder as "install_manifest.php".
install_manifest.php is the file that Pro Edition reads to know what to do when it attempts to install your plugin. All plugins must have a valid install_manifest.php in their folder.
There are two types of content in any given install_manifest.php:
- Information - plugin title, author, etc
- Instructions - "hook me in here, here, and here"
Include basic descriptive info about your plugin
Let's start with the information part. Copy-paste the following lines into your new (and completely empty at this point) install_manifest.php file...
# PLUGIN INFO $plugin_folder = "HELLO_WORLD"; $plugin_title = "Hello World"; $plugin_version = "1.0"; $plugin_author = "John Smith"; $plugin_homepage = "http://example.com"; # Description text $plugin_description = "Adds '- Hello World!' next to the 'Basic Features Group' on the main menu.";
Additional (optional) stuff you can also include
Custom icon image for your plugin
If you'd like your plugin to have it's own icon displayed next to it's name in the Plugin Manager (instead of the default puzzle piece graphic), include the image file in your plugin folder, and add a line like this to your install_manifest.php...
$plugin_icon = "my_plugin_icon.gif"
Tell Pro Edition how to plug-in your plugin
This is the part where you tell Pro Edition how and where to plug-in your plugin (heh). So our specific task at the moment is to tell Pro Edition (through our install manifest) to add our "- Hello World" change to the main menu.
Add this line to your install_manifest.php file...
The hook_overwrite function tells Pro Edition to use your version of main_menu.php (main_menu-helloworld.php) instead of the regular one.
Completed install manifest
Here's what your completed install_manifest.php file should look like...
<? # PLUGIN INFO $plugin_folder = "HELLO_WORLD"; $plugin_title = "Hello World"; $plugin_version = "1.0"; $plugin_author = "John Smith"; $plugin_homepage = "http://example.com"; # Description text $plugin_description = "Adds '- Hello World!' next to the 'Basic Features Group' on the main menu."; # Replace main_menu.php with my custom-modified version hook_overwrite("sohoadmin/program/main_menu.php", "main_menu-helloworld.php"); ?>
Zip your plugin folder
At this point your plugin is essentially done.
Your plugin folder should look like this now...
Using winzip, winrar, or other simliar archive app, zip-up your HELLO_WORLD folder. So for example if you've got zip options on your right-click menu in Windows, you'd right-click on your HELLO_WORLD folder and click "Add to archive...".
For purposes of example, name your .zip file hello_world_plugin-v1.zip
Good to go!
Your plugin is finished and ready to rock. Log-in to Pro Edition and upload/install your hello_world_plugin-v1.zip via the Plugin Manager.
Then check out the main menu.
- Considering that we just wanted to add a line of text, using the hook_overwrite method to replace the entire main_menu.php file with our own copy was more than a little excessive. Once you get comfortable with the basics, you'll be using hook_replace for this kind of thing. It's also usually better to use hook_replace over hook_overwrite because it tends to be much more forward-compatible and software update-friendly.
If you're going to create a management module for your plugin, a great place to start is by making a copy of the following file (added in v4.9 r36)...
With this file you already have the basic structure of a Soholaunch feature module. A quick way to start building your module is to make a copy of this file, rename it as (i.e.) mymodule.php, then stick a link to sohoadmin/program/modules/mymodule.php somewhere on the Main Menu (by hacking sohoadmin/program/main_menu.php) so you can access it as you're developing it. Just don't run Software Updates while you're working on it via this method though or you'll lose your main menu hack. Then when you're done you can come back to this guide and figure out how to wrap it as a plugin with an install_manifest.php.