Creating a basic plugin

From Sohowiki
Revision as of 18:36, 18 May 2006 by 70.155.66.187 (Talk)
Jump to: navigation, search

Contents

Introduction

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" header.

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...

public_html/sohoadmin/program/main_menu.php

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 install_manifest.php

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:

  1. Information - plugin title, author, etc
  2. Instructions - "hook me in here, here, and here"

Include basic descriptive info

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.";

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...

hook_overwrite("sohoadmin/program/main_menu.php", "main_menu-helloworld.php");

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...

HELLO_WORLD/

  • install_manifest.php
  • main_menu-helloworld.php

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.


Notes/Afterwards

  • 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.
Personal tools