Creating a basic plugin

From Sohowiki
(Difference between revisions)
Jump to: navigation, search
(Notes/Afterwards)
(Create an install_manifest.php for your plugin)
 
(56 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
==Introduction==
 
==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" heading.
+
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).
  
'''Stuff you should have for this tutorial...'''
+
'''[http://soholaunch.com/media/hello-world.zip Download the example plugin]'''
*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
+
'''You'll need...'''
*Some kind of code/text editor to edit php files with (Dreamweaver, UltraEdit, PHP Edit, Emacs, Notepad, etc.)
+
#A website with Soholaunch (Pro or Ultra) installed on it.
*Mild-to-moderate web skillz (html, css, and at least some dabbling with php)
+
#Your favorite code editor (for php)
*Some level of familiarity with Pro Edition's various folders and files (i.e. sohoadmin)
+
#Comfort editing basic php code
 +
#Some comfort with Soholaunch's file structure will help, but is not essential.
 +
#FTP access to your website
  
 
==Create a folder for your plugin==
 
==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.
+
Create a folder on your computer called ''hello-world''. All of your plugin's files will go in this folder.
  
==Download the source file you want to modify==
+
==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 want to modify Pro Edition's main menu, so download this file from your test site...
+
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...
<pre>public_html/sohoadmin/program/main_menu.php</pre>
+
<pre>public_html/sohoadmin/client_files/pgm-realtime_builder.php</pre>
  
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).
+
Open that file, and scroll all the way to the bottom. You'll see this line...
 +
<pre># Add stuff to final html
 +
eval(hook("pgm-realtime_builder.php:add-to-final-html"));</pre>
  
==Modify source file==
+
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.
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...
+
==Create your include file==
<pre>
+
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).
<td class="fgroup_title"><? echo lang("Basic Features Group"); ?></td>
+
</pre>
+
  
Modify this line so it looks like this:
+
Contents of hello-world.php...
<pre>
+
<pre><?php
<td class="fgroup_title"><? echo lang("Basic Features Group"); ?> - Hello World</td>
+
$template_footer .= '<script>alert("Hello, World.");</script>';
</pre>
+
?></pre>
 
+
Save the file.
+
  
 
==Create an install_manifest.php for your plugin==
 
==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".  
+
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 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'':
 
+
There are two types of content in any given install_manifest.php:
+
 
#'''Information''' - plugin title, author, etc
 
#'''Information''' - plugin title, author, etc
 
#'''Instructions''' - "hook me in here, here, and here"
 
#'''Instructions''' - "hook me in here, here, and here"
  
===Include basic descriptive info about your plugin===
+
Here's what our install_manifest.php is going to look like...
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...
+
<pre><?php
<pre>
+
# This should match your plugin's folder name
# PLUGIN INFO
+
$plugin_folder = "hello-world";
$plugin_folder = "HELLO_WORLD";
+
$plugin_title = "Hello World";
+
$plugin_version = "1.0";
+
$plugin_author = "John Smith";
+
$plugin_homepage = "http://example.com";
+
  
# Description text
+
# These are just for display to the user, you can define them however you see fit (html allowed)
$plugin_description = "Adds '- Hello World!' next to the 'Basic Features Group' on the main menu.";
+
$plugin_title = "Hello World";
</pre>
+
$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";
  
===Additional (optional) stuff you can also include===
+
# This creates a link on the admin panel to the script specified (helloworld_settings.php)
 +
$plugin_options_link = "helloworld_settings.php";
  
====Custom icon image for your plugin====
+
# This creates a button & description on the admin panel to the script specified (helloworld_settings.php)
 +
$data['enabled_button_link'] = "helloworld_settings.php";
 +
$data['button_caption_text'] = "Hello World Settings";
 +
hook_special("main_menu_button", $data);
 +
 
 +
/* 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");
 +
?></pre>
 +
 
 +
====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...
 
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"
 
  $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...
+
====Optional: Plugin Options Link====
<pre>
+
This adds a link to your plugin's settings page. The .php file should be inside your plugin directory.
hook_overwrite("sohoadmin/program/main_menu.php", "main_menu-helloworld.php");
+
$plugin_options_link="my_plugins_settings.php";
</pre>
+
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===
+
==Recap: This is what your plugin folder should look like==
Here's what your completed install_manifest.php file should look like...
+
At this point your plugin is essentially done.
<pre>
+
<?
+
# 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");
+
?>
+
</pre>
+
 
+
==Zip your plugin folder==
+
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...".
+
 
+
For purposes of example, name your .zip file hello_world_plugin-v1.zip
+
  
==Good to go!==
+
Using winzip, winrar, or other similar archive app, zip-up your ''hello-world'' folder (the folder itself, not just the contents). In Windows, you'd right-click on the ''hello-world'' folder and click "Add to archive..."
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.
+
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.
  
==Notes/Afterwards==
+
Then view your website, and you should see the "Hello, World" javascript alert.
*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 better to use [[hook_replace]] because it's way more forward-compatible.
+
  
 
[[Category:Plugins]]
 
[[Category:Plugins]]

Latest revision as of 12:39, 4 December 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).

Download the example plugin

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.

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
# This should match your plugin's folder name
$plugin_folder 		= "hello-world";

# These are just for display to the user, you can define them however you see fit (html allowed)
$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";

# This creates a link on the admin panel to the script specified (helloworld_settings.php)
$plugin_options_link = "helloworld_settings.php";

# This creates a button & description on the admin panel to the script specified (helloworld_settings.php)
$data['enabled_button_link'] = "helloworld_settings.php";
$data['button_caption_text'] = "Hello World Settings";
hook_special("main_menu_button", $data);

/* 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"


Optional: Plugin Options Link

This adds a link to your plugin's settings page. The .php file should be inside your plugin directory. $plugin_options_link="my_plugins_settings.php";

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 similar archive app, zip-up your hello-world folder (the folder itself, not just the contents). In Windows, you'd right-click on the 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