View source for KTp/Components/Accounts KCM Creating Plugins

== Understanding The Account Mangler ==

=== Overview ===

Each IM protocol has a different set of options it wouldn't make sense to set up a server for the bonjour protocol for example.

Each of these options has to be presented to the user, in order to do this we need to make a KDE plugin which has a different form for each, and a different validator.

Our resident genius George wrote a plugin that automatically builds a form for every type of protocol, however it has no knowledge of which fields are important or being able to come up with user friendly names for these parameters. Therefore it should only be used as a fallback mechanism.

=== User Friendliness ===

Being KDE the whole experience should be as user friendly as possible. In order to please everyone every plugin supplies two 'interfaces'. 

The first is the standard configuration and contains the simple parameters. Anything mandatory should be in here (i.e username and password for MSN). There should be no advanced terminology here. It should be simple enough for anyone to use.

A plugin can optionally supply an advanced options widget. This should be used for those options that 95% of users won't want to change (i.e the server address of MSN, or "use-http-proxy"). Advanced terms such as "STUN server" can be used here. Do not duplicate items already in the standard configuration.

Either of these can be a tabbed widget containing several pages of options.

=== Writing a plugin (a summary) ===

The best way to start is simply to copy the butterfly or gabble folder. From here rename everything to the name of the plugin you wish to implement.

From here, then work out which parameters your plugin needs to support configuring. Split these into "main" and "advanced". Update the forms in QtDesigner as best applicable.

From here it should be a fairly straightforward job to update the code to use these new fields.

=== Writing a plugin (in depth) ===

A plugin needs 3 classes. 

The first must inherit from AbstractAccountUiPlugin, there will be one of these per connection manager. This will say which connection manager and protocols this plugin supports. The main function here is called accountUi which will return an AbstractAccountUi instance for a given connection manager, protocol pair.

The second in the Ui must inherit from AbstractAccountUi, there should be one of these for each protocol that the given connection manager supports. The main methods here are mainOptionsWidget and advancedOptionsWidget which will return AccountParameter widgets. Also for advanced options to show, hasAdvancedOptionsWidget has to be implemented and return true.

Then there will be one or two of classes which inherit from AbstractAccountParametersWidget per protocol, one of these for the standard configuration, one for the advanced configuration.

=== Why are some protocols listed twice in the Add Account List ===

In telepathy lots of programs (connection managers) supply your interface to the protocol. i.e a program called "butterfly" will be the link between telepathy and MSN. However sometimes two programs are both capable of supplying a protocol, this causes it to be in the list twice.