Roberto Suarez Soto wrote:
I've got two suggestions (both of them for 0.24; maybe any of these is already covered in 0.25, specially with the TODO stuff):

- Some documentation about how to make plugins. I know a bit of Perl, but digging into some of the already present plugins is a bit confusing. Some little guide about the basics would be a godsent.

Took some time in the air to type out some more details, see attached files, one with current state + example and one with plan for extension of plugin interface. If only laptop batteries lasted for the whole of a 12h flight I could have done a lot more :( anyway, back in european time zone now.

- I miss a "Link below this page" button (or shortcut, or whatever). I.e., a button like the "Link" one, but that links a page below the current one, not at the same level.

Might be a nice exercise to implement this one as a plugin :) Defined button and call Link on the pageview. I can see the use case for this request, but I don't know which keybinding to use for this.

Note that the link button works as a format toggle (same as bold and italic) which this feature could not do that easily.


====== Plugins ======

See [[:Usage:Plugins]] for information on the available plugins.
See [[TODO:PluginInterface]] for planned improvements.

Zim has a simple plugin system to extend the functionality. Plugins are just 
perl scripts that are installed in a directory where zim can find them. If the 
user chooses to use the plugin the script is loaded during program 
initialization. The script can add some code to zim directly or it can load a 
module with the functionality.

===== Locations =====
Plugin scripts should be installed in ''XDG_DATA_DIR/zim/plugins/'' this means 
that by default they will be located in ''/usr/share/zim/plugins'' or 
''/usr/local/zim/plugins''. Users can install their own plugins in 
''~/.local/share/zim/plugins''. ( For more information on this directory scheme 
have a look at the freedesktop 
specification]]. )

If the plugin uses it's own perl module this module should be installed in the 
normal perl library path.

Any custom icons you need should be put in ''XDG_DATA_DIR/pixmaps/zim/'', they 
will be loaded automatically as stock icons. You can use the basename of the 
icon file as the stock name.

===== Object structure =====
The main purpose of plugins is to add new functionality in the user interface. 
Adding stuff to the data backend is done by adding new modules to the backend. 
Of course there are cases where a plugin can be used to load specific backend 
modules. However you should realize that since plugins are only loaded by the 
user interface the result will be that these backend modules then are not 
available when using for example the command line export function.

The picture below shows schematically where the plugins go in the stack of 


Plugins can extend the GUI classes or add new GUI components. For an overview 
of the GUI classes see [[UserInterface]], for an overview of the classes see 
[[Notebook]], and for the filesystem classes see [[FileSystem]]. For detailed 
documentation of each class look for the inline POD documentation. For example 
type "''perldoc Zim::GUI''" in a terminal to see the methods defined in the 
main GUI object.

===== Example =====
Below an example is given of a plugin defining a new menu item. See 
[[../]] for the full template.

To access the application objects "''Zim::GUI->current()''" can be called from 
the plugin script. This will return the main application object which hold 
references to all other objects in use. A standard start of a plugin script 
would be:

        use strict;
        use Zim::Utils; # import util functions

        my $app = Zim::GUI->current;

Typically plugins start with defining a new menu item. This is done using by 
calling "''$app->add_actions()''" and "''$app->add_ui()''". These methods are 
defined in in the ''Zim::GUI::Component'' base class and are wrappers for the 
''Gtk2::UIManager ''functionality. We wrap the action definition with the 
"''__actions()''" function in order to make them translatable. So we can add an 
action to the "Tools" menu using:

        my $actions = __actions( q{
        MyAction        gtk-open        My Action       .       Execute my 
        } );

        $app->add_ui( q{
                <menubar name='MenuBar'>
                        <menu action='ToolsMenu'>
                                <menuitem action='MyAction'/>
        </ui> } );

Now the actual code for this action goes in a subroutine called 
"''MyAction()''". This method will be called when the menu item is clicked but 
also serves as public interface that might be called by other plugins.

===== Random remarks =====

**Error handling**
The plugin script should return ''true'' when successful. When the script does 
not return ''true'' or dies the user gets an error dialog and the plugin will 
not be loaded again next time zim starts. If your plugin has dependencies it is 
nice to check them and trow an error dialog explaining to the user what went 
wrong before returning ''false''. See for the TrayIcon plugin for an example.

**Autoloading a module**
For small plugin functions all the code goes directly in the plugin script. 
Larger plugins will be easier to maintain when the logic goes into a separate 
perl module and the plugin script is used to load this module. Zim autoloads 
modules from the ''Zim::GUI::'' namespace, so when the module defines for 
example a dialog that only needs to be loaded after the user clicks a menu item 
the script is used to add the menu items while it trusts the module with the 
dialog code to be loaded when needed. This is how the Calendar and TODOList 
plugins work. Typically modules in the ''Zim::GUI::'' namespace inherit from 
''Zim::GUI::Component'' and define a single interface component, e.g. a dialog 
or a pane in the main interface.

**Adding a section to the config file**
Zim uses ini-style config files that can have multiple sections. So it makes 
sense for plugins that have config items to define a new section to store their 
config items. See [[ConfigFiles]] to determine which kind of config items go in 
which config file. There are two convenience routines to get a hash that maps 
to a section in one of these files: ''init_settings()'' and ''init_state()'' 
which are defined in ''Zim::GUI::Component''. These can be called on the 
''$app'' object from the plugin script or can be used during initialization of 
a module. For example the EquationEditor plugin uses this to set config items 
for the latex and dvipng commands that are used.

**Use signals as hooks for new functionality**
The idea is that you can connect to signals to trigger new functionality. 
Basically triggering an action trough a menu or toolbar item also emits a 
signal, but here the signal is wrapped by default already and will call the 
like named module. The main application object and the main notebook object 
also emit signals for events like loading a new page - see the POD 
documentation. And of course all the Gtk widget have signals for various 
events. This is used by for example the Calendar plugin to know when a page is 
loaded for a date and update the dialog to show the corresponding month.
use strict;
use Zim::Utils;

# This file gives a template for a simple plugin
# that adds just one function to the Tools menu.

=head1 NAME

[name of this plugin]


[Description of functionality provided by this plugin]

=head1 ABOUT

[Name of this plugin] - [Version number]

[Name and email of the author]

Copyright (c) [year(s)] [Name author(s)]. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.


# get main application object
my $app  = Zim::GUI->current;

# define action attributes (translatable !),
# separate by TAB, use "." for undefined
my $actions = __actions( 
# name		icon name	menu label	key binding	tooltip
MyAction	gtk-open	My Action	.	Execute my action
} );

# add actions to interface

# add actions to the menu layout
# see source of Zim::GUI for complete menu structure
$app->add_ui( q{
	<menubar name='MenuBar'>
		<menu action='ToolsMenu'>
			<menuitem action='MyAction'/>
</ui> } );

return 1;

# callbacks for the actions go below, method name should be the same as
# the action name

=head1 ACTIONS

=over 4

=item C<MyAction()>

[Some description of what this method does]


sub MyAction {
	print "Some action triggered !\n";



====== PluginInterface ======

**Summary:** document, use signals more extensively and use POD for info.

**short term:**
* Documentations (See e.g.
        * ~~document adding new actions~~
        * Document overloading existing actions (see below)
        * Document using standard methods from and - any others ?
        * Document how to add new formatting modules
* Keep current structure with plugin scripts to allow various checks before 
loading module
        * use "singleton" signal for registering unplug method
        * idem for registering method to show preferences popup
        * base class for plugins could automatically connect these signals and 
map to methods
        * (maybe have way to register these signals without using array for 
optimization ?)
* Turn all action methods for all zim classes into signal handlers
        * autoload should check for any signal handlers and return after the 
first that returns TRUE
        * method in the class as default handler
        * this allows overloading actions without currying the method
        * (move AUTOLOAD from to
* Use POD to store meta data in plugin file
        * two sections to show in tabs in dialog: description and about
        * machine readable section with requirements
                * disable the plugin and show message when requirements fail

**Long term:**
* Installer package that handles plugin file, libs and docs
        * also do translations
* Finalize and document how to get alternative views for the pageview
* Come up with a way to add alternative views to side pane (integrate with 
search drop down (seperator between views and searches) and optionally have 
tabs ?)
* Come up with a way to have a bottom view with alternative views.
Mailing list:
Post to     :
Unsubscribe :
More help   :

Reply via email to