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

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


Style Guidelines
================

Webware developers are requested to observe the rules defined
in the `Webware Style Guidelines`__.

__ ../../Docs/StyleGuidelines.html


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.

__ Configuration.html#appserver-config
__ http://www.python.org/doc/current/tut/node8.html#SECTION008400000000000000000

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.