1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>shellmod: Building co-managers</TITLE>
<LINK HREF="intro-5.html" REL=next>
<LINK HREF="intro-3.html" REL=previous>
<LINK HREF="intro.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="intro-5.html">Next</A>
<A HREF="intro-3.html">Previous</A>
<A HREF="intro.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4. Building co-managers</A></H2>
<P>Co-managers are exciting. They allows one to add functionalities
to Linuxconf right where it belongs, instead of adding new
sub-menus.
<P>
<H2><A NAME="ss4.1">4.1 Principles</A>
</H2>
<P>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.
<P>A co-manager must provide 4 functions:
<P>
<UL>
<LI>Adding fields to the dialog. Here the co-manager will
probably add a new section and few fields. It is not forced
to add anything.</LI>
<LI>Add validation. The co-manager may do all kind of validation
not only on its own fields. The admin is not allowed to
commit any changes to the user account until all co-managers
agree.</LI>
<LI>Save the inputs. The co-manager must save the value
of the fields it manages. User account co-managers have to
preserver information on a per user basis.</LI>
<LI>Delete information associated to the user account/information
record when it is deleted.</LI>
</UL>
<P>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.
<P>
<H2><A NAME="ss4.2">4.2 Registering the co-manager</A>
</H2>
<P>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".
<P>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:
<P>
<BLOCKQUOTE><CODE>
<PRE>
# Register as a co-manager in the user account dialog
echo comanager ufct user
</PRE>
</CODE></BLOCKQUOTE>
<P>The function prefix is ufct. One must create four functions
according to this prefix:
<P>
<UL>
<LI>ufct-setupdia</LI>
<LI>ufct-validate</LI>
<LI>ufct-save</LI>
<LI>ufct-deluser</LI>
</UL>
<P>
<P>
<H2><A NAME="ss4.3">4.3 The various functions</A>
</H2>
<P>
<H3>setupdia</H3>
<P>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.
<P>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.
<P>You define a section with the newf_title opcode
<P>
<BLOCKQUOTE><CODE>
<PRE>
qecho newf_title "Mailing lists" 1 - "Mailing lists"
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>validate</H3>
<P>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
<P>
<BLOCKQUOTE><CODE>
<PRE>
echo retcode 0
</PRE>
</CODE></BLOCKQUOTE>
<P>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.
<P>
<BLOCKQUOTE><CODE>
<PRE>
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
</PRE>
</CODE></BLOCKQUOTE>
<P>
<P>
<H3>save</H3>
<P>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).
<P>Other shell variable also contain information related to this
dialog (see dialog context below).
<P>
<H3>deluser</H3>
<P>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.
<P>
<H2><A NAME="ss4.4">4.4 Dialog context</A>
</H2>
<P>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 ?).
<P>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:
<P>
<DL>
<DT><B>domain</B><DD><P>The virtual email domain is passed. For the main domain, this
variable is set to /.
<DT><B>is_new</B><DD><P>This is a flag telling you if this is a new account (name is
empty) or not.
<DT><B>name</B><DD><P>This is the user id.
</DL>
<P>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.
<P>
<HR>
<A HREF="intro-5.html">Next</A>
<A HREF="intro-3.html">Previous</A>
<A HREF="intro.html#toc4">Contents</A>
</BODY>
</HTML>
|
