Title: Guidelines for Writing Templates and Wizards
Status: Current
Created: 16 September 2001

Introduction
============

Templates and Wizards are Python scripts conforming to a basic design.


Wizard/Template Packages
========================

A valid package must contain at least three elements:

  1) The package must import the TemplateBase package, or a proper derivative.
     All of the base classes and convenience methods are defined in TemplateBase.

        from gnue.designer.TemplateBase import *

     Note: Individual tools override TemplateBase, so you should import:

        from gnue.designer.<PACKAGE>.TemplateSupport import *

     So, if you are writing a forms template/wizard, the line would be:

        from gnue.designer.forms.TemplateSupport import *

     Or, for reports:

        from gnue.designer.reports.TemplateSupport import *



  2) A single class must be exposed that inherits a TemplateBase class.
     Each product defines its own TemplateBase.  The class is usually named
     as <Package>Template (e.g., FormTemplate, ReportTemplate, etc), although
     this is not a hard rule.

        class SimpleFormTemplate(FormTemplate):


  3) A definition dictionary names TemplateInformation provides Designer with

        TemplateInformation = {
            'Product': 'forms',
            'BaseClass' : SimpleFormTemplate,
            'Name' : 'Simple form wizard',
            'Description' : 'Creates a simple single-source entry table.',
            'Version' : '0.0.1',
            'Behavior': WIZARD
        }



Wizards vs Templates
====================

The basic difference, from an end-user's viewpoint, between a wizard and a
template is that a wizard interacts with the user (to get data or to at least
provide feedback) whereas a template simply performs an action without any
sort of user intervention.

From the developer's viewpoint, a template only implements the Start() and
Finalize() methods, whereas the wizard also implements the GetStep() and
ValidateStep() methods, and the FIRST_STEP attribute. Details on these
various methods will be provided in the Implementation Class section.



Definition Dictionary
=====================

The Definition Dictionary is a summary of your template/wizard's behavior.
It must, at a minimum, define the following keys:

  1) 'Product'        This is a string containing either 'forms' or
                      'reports'.

  2) 'BaseClass'      This is the name of your implementation class.
                      Designer will create an instance of this class when
                      this wizard/template is run.

  3) 'Behavior'       This should either be the constant WIZARD or TEMPLATE,
                      depending on the desired behavior of the wizard.
                      Templates do not prompt for user input and, as such,
                      do not have to implement the FIRST_STEP, GetStep, and
                      ValidateStep attributes in the BaseClass. Only the
                      Start and Finalize methods are needed for Templates.

  4) 'Name'           A string defining the name of your wizard.

                      NOTE: It is VERY important that in any references to a
                      "<insert type here> wizard", the word "wizard" must be
                      in lower case, as many proper names such as "Foobar
                      Wizard" have been trademarked. (No, this is not a
                      joke -- got to love IP law :)


The following keys are recommended, but do not affect the behavior of the
wizard/template:

  5) 'Description'    A short description of the behavior of this wizard.
                      This is displayed in the list of available wizards.

  6) 'Author'         The name of the wizard/template's author.

  7) 'Version'        The version number of this wizard/template.


A sample TemplateInformation dictionary:

        TemplateInformation = {
            'Product': 'forms',
            'BaseClass' : MyFormTemplate,
            'Name' : My form wizard',
            'Description' : 'Creates a simple single-source entry table.',
            'Version' : '0.0.1',
            'Author' : 'The GNUe Designer Team',
            'Behavior': WIZARD
        }


Implementation Class
====================

Start()
-------
Never, ever, EVER overwrite the __init__ method in your implementation.
TemplateBase may (will?) change the __init__ implementation as new
features are added.  Maintenance would be a headache if every wizard
had to update it's __init__ call each time TemplateBase changed.

However, the Start() method provides a similar runtime initialization
mechanism. Start() is called before your wizard/template is processed.
This is a good place to perform any needed variable initializations or
other checks. Start() takes only one argument, the rootObject, which is
either an empty form or report.  It is the responsibility of your wizard
to save a reference to this rootObject for use in the Finalize() method.


Finalize()
----------
You can be guaranteed to have an empty <form|report> object passed to the
Start method. As stated above, it is the responsibility of your Start()
method to save a reference to this rootObject for use in Finalize().
If you successfully create your object, Finalize() should return a TRUE
value.  Otherwise, return false.

If a TRUE value is returned, Designer assumes that the root object now
contains a valid form or report.



GetStep()
---------
TODO


ValidateStep()
--------------
TODO



Convenience Methods
===================



