This documents explains how to create a pluggable wizard plugin


Production plugin
-----------------
Creating a production step consists of 3 steps.

* Marking the plugin as a production plugin

To mark a plugin, you need to add a <wizard> tag as a child of the <component>
in the registry file of the plugin.

Attributes:
type: the kind of plugin,"audio-producer" or "video-producer". You need to have
      both a video-producer and an audio-producer for a component providing
      both with the feeder being unique for each of the wizard tags.
_description: the description of the plugin. This will be shown in the
              user interface and is translatable (the prefix of _ makes
	      intltool able to pick it up)
feeder: name of feeder provides this producer stream.

Example:

  <wizard type="audio-producer" _description="Test audio source"
          feeder="default" />

* Adding the wizard step

A new <entry> tag needs to be added to the child of <entries>.
The type attribute must contain "wizard".

Example:

  <entry type="wizard" location="audiotest_wizard.py"
         function="AudioTestWizardPlugin" />

* Writing the Step

Create a new file called XXX_wizard.py, for example audiotest_wizard.py.

You need to define the following classes:
 * plugin: the entry point
 * step: part of the wizard which can configure the component
 * model: An AudioProducer (or VideoProducer) subclass

The plugin is the entry point, which takes a wizard instance.
You will also create the model here, which you pass in to the step
The getProductionStep method takes one argument, which is the type of the
production component. This can be used to provide the correct wizard step
for a component that provides both video and audio. If getProductionStep()
returns None, then there will be no configuration page shown for that step.

class AudioTestWizardPlugin(object):
    def __init__(self, wizard):
       self.wizard = wizard
       self.model = TestAudioProducer()

    def getProductionStep(self, type):
       return TestAudioSourceStep(self.wizard, self.model)

The model part is pretty easy, it needs to subclass AudioProducer and
define the component_type class attribute:

class TestAudioProducer(AudioProducer)
    component_type = 'audiotest-producer'

The step is slightly more complicated.
You need inherit from AudioSourceStep or VideoSourceStep.
glade_file needs to point to an absolute filename and the window has to be named
window1.
The icon is optional.

class TestAudioSourceStep(AudioSourceStep):
    name = _('Test Audio Source')
    glade_file = os.path.join(os.path.dirname(os.path.abspath(__file__)),
                              'audiotest-wizard.glade')

    # WizardStep

    def setup(self):
    	...

        self.add_proxy(self.model.properties, [...])

Additionally a worker_changed method is needed which updates the worker
attribute on the model.
Optionally you can check for the presence of an element here.

    def worker_changed(self, worker):
        self.model.worker = worker
        self.wizard.require_elements(worker, 'audiotestsrc')


Conversion plugin
-----------------
TODO


Consumption plugin
------------------
TODO


HTTP plugin
-----------
TODO


Bundle
------

You will also need to distribute the plugin. Using a glade file is
highly recommended for a production plugin.

Example:

  <bundle name="audiotest-wizard">
      <dependencies>
          <dependency name="audiotest-base" />
          <dependency name="component" />
      </dependencies>

      <directories>
          <directory name="flumotion/component/producers/audiotest">
              <filename location="audiotest-wizard.glade" />
              <filename location="audiotest_wizard.py" />
          </directory>
      </directories>
  </bundle>

If you add a plugin to outside of flumotion, do not forget that the
bundle attribute "project" needs to be added.

Distributing
------------

Added python sources files should go into component_PYTHON and
Added glade files should go into to component_DATA.

All files which contains translatable strings should also be added to
po/POTFILES.in.

