Creating a basic plugin

From Sohowiki
(Difference between revisions)
Jump to: navigation, search
Line 54: Line 54:
 
  $plugin_icon = "my_plugin_icon.gif"
 
  $plugin_icon = "my_plugin_icon.gif"
  
==Zip your plugin folder==
+
==Recap: This is what your plugin folder should look like==
At this point your plugin is essentially done.  
+
At this point your plugin is essentially done.
  
 
Your plugin folder should look like this now...
 
Your plugin folder should look like this now...
  
HELLO_WORLD/
+
<pre>hello-world/
*install_manifest.php
+
install_manifest.php
*main_menu-helloworld.php
+
main_menu-helloworld.php</pre>
  
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...".
+
Using winzip, winrar, or other simliar archive app, zip-up your hello-world folder. 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
+
For purposes of example, name your .zip file *hello-world.zip*
  
==Good to go!==
+
==You're ready==
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.
+
Your plugin is finished and ready to rock. Log-in to ''/sohoadmin'' and upload/install your hello-world.zip via the Plugin Manager.
  
Then check out the main menu.
+
Then view your website, and you should see the "Hello, World" javascript alert.
 
+
 
+
==Notes/Afterwards==
+
*Considering that we just wanted to add a line of text, using the [[Hook_overwrite|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.
+
 
+
===sample_module.php===
+
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)...
+
'''sohoadmin/program/modules/sample_module.php'''
+
 
+
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.
+
  
 
[[Category:Plugins]]
 
[[Category:Plugins]]

Revision as of 17:51, 17 October 2013

Contents

Introduction

This tutorial will walk you through the creation of a basic plugin that opens a javascript alert box with the text "Hello World" in it on every page of your website (annoying, I know, but at least you'll know it's working).

You'll need...

  1. A website with Soholaunch (Pro or Ultra) installed on it.
  2. Your favorite code editor (for php)
  3. Comfort editing basic php code
  4. Some comfort with Soholaunch's file structure will help, but is not essential.
  5. FTP access to your website

Create a folder for your plugin

Create a folder on your computer called "hello-world". All of your plugin's files will go in this folder.

Find the hook you want to attach your custom file to

Open Your FTP client and log-in to your test site. For this example, we're going to add code to your soho-created website's html. The file below builds the website's html...

public_html/sohoadmin/client_files/pgm-realtime_builder.php

Open that file, and scroll all the way to the bottom. You'll see this line...

# Add stuff to final html
eval(hook("pgm-realtime_builder.php:add-to-final-html"));

That's what a hook looks like in the Soholaunch source code. This is where your file will be included. The text inside the hook() function call (pgm-realtime_builder.php:add-to-final-html) is the hook id that you need for your plugin's install_manifest.php file.

Create your include file

In your hello-world folder, create a file called hello-world.php (note: actual filename doesn't matter). This file will contain add a javascript alert to the $template_footer variable's contents. The $template_footer variable contains all of the website html from the page content downward (so all content that gets swapped-in for #content#, as well as the template html that follows #content# in the template file).

Contents of hello-world.php...

<?php
$template_footer .= '<script>alert("Hello, World.");</script>';
?>

Create an install_manifest.php for your plugin

The install_manifest.php is the configuration file for your plugin. Every Soholaunch plugin has an install_manifest.php. This file is read by Soholaunch when the user installs the plugin. It tells Soholaunch how to display your plugin (title, author, etc), and where to hook its files into. "install_manifest.php".

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"

Here's what our install_manifest.php is going to look like...

<?php
$plugin_folder 		= "hello-world";
$plugin_title 		= "Hello World";
$plugin_version 	= "2.0";
$plugin_author 		= "Soholaunch.com, Inc.";
$plugin_homepage 	= "http://example.com";
$plugin_description 	= "Adds drag and drop 'Hello World' item to the Page Editor";

/* Include my hello-world.php file at *this* location (specified by hook id found in the Soholaunch source code) */
hook_attach("hello-world.php", "pgm-realtime_builder.php:add-to-final-html");
?>

Optional: Plugin icon

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"

Recap: This is what your plugin folder should look like

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

You're ready

Your plugin is finished and ready to rock. Log-in to /sohoadmin and upload/install your hello-world.zip via the Plugin Manager.

Then view your website, and you should see the "Hello, World" javascript alert.

Personal tools