webpad Plugin Documentation

About webpad plugins
Installing a plugin
Configuring a plugin
Writing your own plugin

About webpad plugins

Blogging support in webpad is provided through a collection of plugins. You can write your own plugins for webpad to access other sources of information. Some ideas might be:

Access information stored in a company database for editing,
Access email stored on your server in IMAP mailboxes,
Extend the blogging support to other blogging platforms,
Automatically check a file out from CVS and edit it, then check it back in when you save it.

All plugins work in a similar fashion - they provide access to a listing of some sort, allow the user to select a specific 'file', then trigger an 'open' sequence to load that 'file' into the edit window. If the user clicks 'Save', it saves back to the plugin's data source. Plugins should also allow a user to save back to them, using the normal 'Save/Save As' operations within webpad.

All plugins are stored in the /plugins/ directory in webpad's installation directory, and are accessed through the 'My Plugins' option in the Locations Bar in 'Open File' and 'Save' windows.

Installing a new plugin

Installing a plugin within webpad is just a simple process of copying the files to the right location, and putting a single entry in the configuration.php file.

All plugins should be installed in the /plugins/ directory inside webpad, within a directory of their own:

webpad_install/
     plugins/
          plugin1/
          plugin2/

The name you use for the directory within /plugins/ is important. It should be unique, and preferably short and easy to use in a number of locations (See: Writing your own plugin for more reasons why). Inside your plugin directory, there will need to be at least 2 files:

code.php
icon.gif

Each of these files is used by webpad for different things, and is required for the plugin to work properly. webpad uses icon.gif as the icon to display next to the plugin in the 'My Plugins' listing. code.php should contain all core operational functions for the plugin (See: Writing your own plugin for more details).

Additional files for the plugin may be installed into this directory, or if a collection of plugins are going to use common files, then another directory at the plugins level may optionally be created. For example, the pre-installed blogging plugins share a number of files, located in the /plugins/_blogging/ directory. Directories which are not an actual plugin (such as shared code directories) should be prefixed with an underscore (_) to prevent them from being listed as an available plugin.

Configuring a plugin

All plugins provide the information required to configure them directly to the Settings page. This process is described in Writing your own plugin. Once a plugin is installed, accessing the Settings page should give you the option to 'Add' a new plugin configuration, and then enter your settings for that particular plugin.

Writing your own plugin

webpad's plugin architecture allows you to easily add your own plugins for accessing data from other sources. As mentioned in About webpad plugins, there are a number of different ways you might choose to use this functionality, or I'm sure you can come up with your own.

For the sake of the following section, assume we're dealing with a plugin called "myPlugin" (so all files for the plugin should be in /plugins/myPlugin/)

NOTE: In all plugin files, you should always use dirname(__FILE__) for your include and require statements to avoid relative directory name problems during operation.

Required functions/files

Every plugin must have the following files in its directory:

code.php
icon.gif

code.php

This file contains the main code of the plugin. Required functions in this file are:

myPlugin_validate_plugin($plugin)

Accepts a single parameter $plugin, which is the array of configuration options from $config['plugins'] for this specific plugin. This function should confirm that the $plugin array contains all the information it needs to operate, and then return true if it does, or false if it doesn't. If it returns false, the plugin will not be listed as available.

myPlugin_get_fields()

Returns an array detailing what fields are required to configure this plugin. This function is called by the Settings page to determine what fields are displayed as part of the configuration for this plugin. The array passed back should look something like this;

$fields = array();
$fields[] = array('name'=>'nameOfField', 
                  'type'=>['text' | 'password' | 'checkbox' | 'radio' | 'select'], 
                  'options'=>[false | array('val1'=>'LabelOne', 'val2=>'LabelTwo')] );

options are only required for checkbox, radio and select field types, for text and password, it should be set to false. The function should simply define the array, and then return it; the Settings interface will handle everything from there.

myPlugin_get_title($plugin)

This function accepts the same complete array of plugin configuration information, and should return a string containing the title to be displayed in the listing of available plugins. Keep in mind that multiple copies of the same plugin may be configured, so you should return a unique title, based on the specific configuration in the $plugin array.

myPlugin_listing($plugin, $id)

This function is responsible for generating a complete listing of available 'files' within this plugin, and is called from browse_plugin.php for a specific plugin/configuration. Based on the details in $plugin, which is plugin number $id to be configured, it should generate a listing, and return the HTML to display details for this plugin. See Common items/operations to implement for more details on what you should be aiming to implement here.

myPlugin_open()

This function takes no parameters, so it should rely solely on $_SESSION variables to determine which file was requested and other details. It should return a string containing the entire file to be loaded into webpad. If you'd like to pass a message back to the user upon success/failure, declare global $javascript_msg; and set it to a string containing your message. If it starts with a "@", then it is an error message. It will be alert'ed (without the @) and used as the window.status.

myPlugin_save($name, $str)

This function takes 2 parameters, which should be enough, when combined with the available $_SESSION variables, to save the contents of the edit window to the specified destination with this plugin. Once the item is saved, this function should return the new filename for this file (or the old one if it hasn't changed). If you'd like to pass a message back to the user upon success/failure, declare global $javascript_msg; and set it to a string containing your message. If it starts with a "@", then it is an error message. It will be alert'ed (without the @) and used as the window.status.

icon.gif

This is the icon used in the 'My Plugins' listing of available plugins. The image should be 18 x 18 px, on a white background. If you like, a 2px drop shadow done at 120^o in black, at 75% opacity may also be added.

Functions and variables

All functions should be prefixed with the plugin's name (e.g. myPlugin_my_function_to_do_something())
If you need to use additional $_SESSION variables, they should be named like this to avoid naming conflicts: $_SESSION['plugin_myPlugin_*']
There are some global variables that you might need to access, especially in opening and saving data to/from your plugin:
- $_SESSION['filename'] contains the actual filename of the current file, including any relevant path information.
- $_SESSION['display_filename'] contains the name used to display in the window title. This is normally just the actual file name (no path information)
- $_SESSION['plugin_identifier'] is the best place to store your information if you don't need additional variables. This variable is made available purely for the active plugin to manipulate. You can use an internal string separator to store multiple things in there at once.
- $_SESSION['plugin'] should always contain the index number of the active plugin (the index for its configuration within $config['plugins'])
- $config (you will need to declare this as global within your functions) contains all configuration data for webpad
- $config['plugins'][$_SESSION['plugin']] should contain all configuration data for the active plugin

Common items/operations to implement

Server and FTP Server files are listed with the icon /images/files_file.gif which is 19 x 18 px on a white background, and has align="absmiddle" applied to it.
You should be able to open a 'file' using a double-click of the mouse. This is triggered using the ondblclick event handler to select the file and trigger a form submission at the same time.
You can include the colored selection code in your listings using the JavaScript samples in /js/files.js
To access the plugins toolbar (See: Accessing the plugins toolbar for more info), you should include /js/plugins.js in any additional plugin pages you create.
To make any additional plugin browsing pages look like other file-listing pages, you can include /css/files.css
It's a good idea to update the 'active plugin' value yourself using something like this (where x is the numbered index of this plugin):
parent.document.file.plugin.value = x;
You can (and should) update the 'current directory' box above the browse window using JavaScript like this:
parent.document.file.current_dir.value = 'Current Directory Title Here';
If you don't want the user to be able to edit the filename in a save or open operation, you can make the filename field read only using this:
parent.document.file.filename.readOnly = true;
To reference the content of the active file, you need to access this:
top.opener.parent.frames.wp_edit.document.edit.wp_document.value

Accessing the plugins toolbar

You can modify the contents of the toolbar on the plugins browse window. There is room for up to 3 additional tools (you can't modify the far-left icon, which is for changing the active plugin). The following JavaScript functions are available if you include /js/plugins.js in your plugins pages (it is already included when myPlugin_listing() is called).

add_plugin_tool(icon, href, tooltip, position)

Using this function, you can add a tool to the toolbar for interacting with your plugin. icon is a filename for the icon to use in the toolbar. The image should be a transparent background gif, over a matte to the hex code #3A85E1. It should be 25 x 25px. href is the exact HREF to apply as a link to the icon (probably something like javascript:do_something();). tooltip will become the TITLE attribute of the link, and will appear if the user hovers over it for a second. position is a number from 1 to 3, representing the position to place this tool at. 1 is closest to the 'Change Active Plugin' tool (far left) and 3 is far right.

remove_plugin_tool(position)

This will remove (clear) the tool at position. position should be a number from 1 to 3 representing which tool to remove.

clear_plugin_tools()

This function will simply clear all plugin tools (positions 1 - 3).