Co-managers are exciting. They allows one to add functionalities to Linuxconf right where it belongs, instead of adding new sub-menus.
A co-manager is a component that participate in a dialog. It may add fields and validation. The most common case is the user account dialog, where several co-managers participate. The most visible one is the mailconf module, which insert a complete section to handle email aliases. Another is the pppdialin module which add a section to deal with PPP parameters.
A co-manager must provide 4 functions:
Note that the co-managers have been created with user accounts in mind, but the concept is more general than that. Change "user account" above for "record" and you get a more general picture.
Linuxconf must be notified that a co-manager exists for a given dialog. Dialogs are identified by a small key. For example, the key for the user account dialog is "user".
A shellmod co-manager must provide four functions, using the same prefix. When registering the co-manager, you provide the function prefix and the dialog key. This is done with in the register function Here is an example:
# Register as a co-manager in the user account dialog echo comanager ufct user
The function prefix is ufct. One must create four functions according to this prefix:
This function is called when building the dialog. You can use any opcode normally used to define a dialog. You do not have to define the dialog yourself (echo DIALOG) as it is implicitly defined.
While you can simply add fields in the dialog, one will generally define a new dialog section. Unless you do that, your new field will be appended in the current section, which can be any section.
You define a section with the newf_title opcode
qecho newf_title "Mailing lists" 1 - "Mailing lists"
This function receives all field value (entered by the user). Each field correspond to a shell variable, so you can test their value directly. You must use the "retcode" opcode to tell if the validation was successful. Here is an example
echo retcode 0
Any value different from 0 is taken as a validation failure. Any error must be reported with the "error" opcode. You may also use the "setcurfield" to jump to a specific field.
if [ "$a1" = "valid" ] ; then echo retcode 0 else echo setcurfield a1 echo retcode -1 echo error \"sample.sh: Invalid value, enter the word valid\" fi
All field's value are returned to your script as shell variable. The save function must do various things with the information. It can either save it in a file, or perform some actions (send an email to an administrator about the required changes for example).
Other shell variable also contain information related to this dialog (see dialog context below).
This function name is a bit miss-leading. It means that the record must be deleted (in general, a user account). You must use the information from the dialog context (see below) to perform the required deletion.
A co-manager is handling one part of a larger dialog. To properly manage its part, the co-manager must know other information about the current dialog. For example, to enhance the user account dialog, one must know the user account (user id) being edited as well as the domain (is it a virtual email domain user account ?).
This extra infomation is passed as shell variable, so readily usable. The available information is dialog dependent. For user account co-managers, the following variables are provided:
The virtual email domain is passed. For the main domain, this variable is set to /.
This is a flag telling you if this is a new account (name is empty) or not.
This is the user id.
One way to learn the information available to your script is by running it in debug mode under Linuxconf. You enable this mode from Linuxconf user interface, in control file and system/shell module management/shellmod configuration.