Developing Webware
++++++++++++++++++

This document should outline the details you need to understand to
Webware and WebKit internals, and assist in becoming a more advanced
Webware programmer.

Creating Plugins
================

Each plugin is a Python Package.  WebKit finds plugins using the
``PlugIns`` and ``PluginDirs`` -- see Configuration_.  See also the
`Python tutorial on packages`__ and the ``PlugIn.py`` doc string.

.. __: http://www.python.org/doc/current/tut/node8.html#SECTION008400000000000000000

.. _Configuration: Configuration.html#appserverconfig

A plug-in must have ``__init__.py`` and ``Properties.py`` files. You
can disable a specific plug-in by placing a ``dontload`` file in it.

``__init.py__`` must contain a function like::

    def InstallInWebKit(appServer):
        pass
        
The function doesn't need to do anything, but this gives it the 
opportunity to do something with the AppServer -- for instance, the
PSP plugin uses AppServer.addServletFactory to add a handler for ``.psp`` 
files.

The ``Properties.py`` file should contain a number of assignments::

    name = "Plugin name"
    version = (1, 0, 0)
    docs = [{'name': 'Quick Start Guide', 'file': 'QuickStart.html'},
            {'name': 'Reference Guide, 'file': 'Reference.html'}]
    status = 'beta'
    requiredPyVersion = (2, 0, 0)
    requiredOpSys = 'posix'
    synopsis = """A paragraph-long description of the plugin"""
    WebKitConfig = {
        'examplePages': [
            'Example1',
            'ComplexExample',
            ]
        }
    def willRunFunc():
        if softwareNotInstalled:
            return "some message to that effect"
        else:
            return None         
        
The documents (e.g. ``QuickStart.html``) should be located in a ``Docs/`` subdirectory.  The example pages go in an ``Examples/`` subdirectory.  

A plugin who's ``requiredPyVersion`` or ``requiredOpSys`` aren't satisfied will simply be ignored.  ``requiredOpSys`` should be something returned by ``os.name``, like ``posix`` or ``nt``.  Or you can define a function ``willRunFunc`` to test.  If there aren't requirements you can leave these variables and functions out.

