ManaTools Modules
======================================

mpan, ManaTools panel or Mageia Panel if you like,
is basically an application launcher, so everything
executable file can be run really. To get benefit of UI abstraction
though, the "modules" should be written with the use of libYUI, yast
user interface abstraction, so that they can be run using a  Gtk, ncurses
or Qt environment in a transparent manner.
Modules based on libYUi can be written in C++, using the native language,
python, ruby and perl, using libYUI bindings.

ManaTools is written in perl, so it also add a native approach,
for perl modules.

How to write a perl ManaTools module
======================================

ManaTools module are written using Moose wit an OO apporach.
Modules are extension of the ManaTools::Module class.

- Code alignment
As a simple code convention, we add the followin line at the
beginning of the file

# vim: set et ts=4 sw=4:

So that using vim we force to get tabs to be 4 characters
and considered as blanks, so please if you use another editor
and you want to include your code under manatools tree
keep this convention.

- POD
Then add POD to your file, we are trying to pass "make test"
and POD is one of the important tests.
It's not only a matter of test of course, having the manual
and a good documentation of the modules is mandatory.
Remember also that the code could/should be read and understood by
other people, so try to keep POD aligned.

- Internal declaration
Internal functions or methods are "_" predfixed, e.g.
sub _foo {
}

- Module template
Try to keep distinct the GUI layout and the module back-end. Since
the module is a configuration tool for the most, one thing is the
graphic user interface and another is a lower level interface. Such
an approach allows to use shared things also into other projects
that don't want to use YUI bindings for instance.

Meaning that you have to:
1. Define the package name usually like:
   package ManaTools::Module::MyModule;

2. Use Moose and yui, the first to extend Module the latter for libYUI
   bindings.

3. Extend ManaTools::Module defining a "start" method that has to be invocated
   by ManaTools.
   Other important things are icon and name attributes, please have look at other modules
   code and to Moose documentation.

4. Add the module to configuration file so that mpan can load it (see below).

Some share code is into ManaTools::Shared modules, such as Locales to manage localization
or Module back-ends for instance.

A module template example is into extras/module_templete/ directory, where
extras/module_templete/mana_mt is the example script that use and run
the module, while the module itself is
extras/module_templete/ManaTools/Module/ModuleTemplate.pm
The module just show a MessageBox and exit.

- ManaTools configuration (how to run a module)

mpan can be run using a "name" parameter and eventually by forcing a configuration
directory path where to find configuration files.
Default name is mpan, and the name by convention is the place in witch to find
configuration files under /etc.
So mpan will look for:
/etc/mpan/settings.conf
/etc/mpan/categories.conf
categories can also be searched under:
/etc/mpan/categories.conf.d/MyModule.conf

How to run modules is defined into categories.conf or alternatively
MyModule.conf under the related categories.conf.d.
Last method allows to write a Module that is not under the ManaTools
development tree, and easily install, load and run it using mpan.

Categories are icon buttons that can contain more modules, so to have
a old mcc view:
_______________
|C |          |
|A |          |
|T | Modules  |
|E |          |
|G.|          |
---------------
Layout can change in future though.

Let's see an example of a category configuration
<category>
    <title xml:lang="en">Hardware</title>
    <icon>/usr/share/icons/configuration_section.png</icon>
    <module>
        <class>ManaTools::Module::Services</class>
    </module>
    <module>
        <title xml:lang="en">Module name</title>
        <launcher>PATH/to/lunch/module</launcher>
        <icon>absolute/paht/to/module/icon</icon>
    </module>
</category>

Note that icon and logo elements could be absolute or relative
pathnames (e.g. no "/" as first char), if relative the absolute
pathname is evaluated as
File::ShareDir::dist_file(ManaTools::Shared::distName(), 'given/file').

First module is a perl ManaTools::Module extension (Services),
latter is an external one, called "module" and with a full pathname.

As you can see it could be a script, as well as an executable command.
Look at settings.conf and categories.conf for details.