| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 |
<html><head><title>Module HowTo - Account pages</title> |
| 3 |
|
| 4 |
|
| 5 |
|
| 6 |
<link rel="stylesheet" type="text/css" href="style/layout.css"><link rel="shortcut icon" type="image/x-icon" href="images/favicon.ico"></head><body> |
| 7 |
<div style="text-align: center;"> |
| 8 |
<h1>Module HowTo - Account pages<br> |
| 9 |
</h1> |
| 10 |
<br> |
| 11 |
<br> |
| 12 |
<div style="text-align: left;"><br> |
| 13 |
<h2>1. Loading the LDAP attributes<br> |
| 14 |
</h2> |
| 15 |
Every time the user selects an existing account to modify LAM will load |
| 16 |
the complete LDAP entry of it. Your module then should select the |
| 17 |
attributes which are useful for it.<br> |
| 18 |
There are two variables in <span style="font-style: italic;">baseModule</span> |
| 19 |
which should be used to store the attributes. The <span style="font-weight: bold;">$attributes</span> variable stores the |
| 20 |
current attributes including changes the user made. The <span style="font-weight: bold;">$orig</span> variable stores the attributes |
| 21 |
as they were originally when the account was loaded. This allows you to |
| 22 |
see what changes were made.<br> |
| 23 |
<br> |
| 24 |
The <span style="font-weight: bold;">load_attributes()</span> function |
| 25 |
in your module gets the complete attribute list from LDAP.<br> |
| 26 |
In most cases you will not need to implement this function because the |
| 27 |
parent class baseModule loads attributes based on your meta data.<br> |
| 28 |
<br> |
| 29 |
<span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> |
| 30 |
<br> |
| 31 |
The <span style="font-style: italic;">ieee802Device</span> uses an |
| 32 |
object class and the <span style="font-style: italic;">'macAddress'</span> |
| 33 |
attribute. Therefore we will save these two values.<br> |
| 34 |
<br> |
| 35 |
<table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> |
| 36 |
<tbody> |
| 37 |
<tr> |
| 38 |
<td style="vertical-align: top;"> /**<br> |
| 39 |
* This function loads all needed attributes into the |
| 40 |
object.<br> |
| 41 |
*<br> |
| 42 |
* @param array $attr an array as it is returned from |
| 43 |
ldap_get_attributes<br> |
| 44 |
*/<br> |
| 45 |
<span style="font-weight: bold;">function</span> <span style="color: rgb(255, 0, 0);">load_attributes</span>($attr) {<br> |
| 46 |
|
| 47 |
$this->attributes['objectClass'] = array();<br> |
| 48 |
|
| 49 |
$this->attributes['macAddress'] = array();<br> |
| 50 |
$this->orig['objectClass'] = |
| 51 |
array();<br> |
| 52 |
$this->orig['macAddress'] = |
| 53 |
array();<br> |
| 54 |
if (isset($attr['objectClass'])) {<br> |
| 55 |
|
| 56 |
$this->attributes['objectClass'] = $attr['objectClass'];<br> |
| 57 |
|
| 58 |
$this->orig['objectClass'] = $attr['objectClass'];<br> |
| 59 |
}<br> |
| 60 |
if (isset($attr['macAddress'])) {<br> |
| 61 |
|
| 62 |
$this->attributes['macAddress'] = $attr['macAddress'];<br> |
| 63 |
|
| 64 |
$this->orig['macAddress'] = $attr['macAddress'];<br> |
| 65 |
}<br> |
| 66 |
return 0;<br> |
| 67 |
}<br> |
| 68 |
</td> |
| 69 |
</tr> |
| 70 |
</tbody> |
| 71 |
</table> |
| 72 |
<br> |
| 73 |
<br> |
| 74 |
<h2>2. Page display</h2> |
| 75 |
Now that you have defined your subpages you will need one function for |
| 76 |
each page to display it. The function must return <span style="font-style: italic;">meta HTML code</span> as defined in the <span style="font-style: italic;">modules specification</span>.<br> |
| 77 |
This function is called <span style="font-weight: bold;">display_html_<page |
| 78 |
name>()</span> where <span style="font-style: italic;"><page |
| 79 |
name></span> is the name of your subpage.<br> |
| 80 |
<br> |
| 81 |
See also baseModule::addSimpleInputTextField() and |
| 82 |
baseModule::addMultiValueInputTextField()/processMultiValueInputTextField() |
| 83 |
if you only want to add some simple text fields.<br> |
| 84 |
<br> |
| 85 |
<span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> |
| 86 |
<br> |
| 87 |
The |
| 88 |
<span style="font-style: italic;">ieee802Device</span> |
| 89 |
module has only one subpage called <span style="font-style: italic;">'attributes'</span>.<br> |
| 90 |
<br> |
| 91 |
The first half of the code displays the existing MAC addresses and the |
| 92 |
second an input field for new values.<br> |
| 93 |
The variable <span style="font-style: italic;">$this->attributes</span> |
| 94 |
contains the LDAP attributes which are useful for this module.<br> |
| 95 |
<br> |
| 96 |
<table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> |
| 97 |
<tbody> |
| 98 |
<tr> |
| 99 |
<td style="vertical-align: top;"> /**<br> |
| 100 |
* This function will create the meta HTML code to |
| 101 |
show a page with all attributes.<br> |
| 102 |
*<br> |
| 103 |
* @return htmlElement HTML meta data<br> |
| 104 |
*/<br> |
| 105 |
<span style="font-weight: bold;">function</span> <span style="color: rgb(255, 0, 0);">display_html_attributes</span>() {<br> $return = new htmlTable();<br> |
| 106 |
$macCount = 0;<br> |
| 107 |
// list current MACs<br> |
| 108 |
if (isset($this->attributes['macAddress'])) {<br> |
| 109 |
$macCount = sizeof($this->attributes['macAddress']);<br> |
| 110 |
for ($i = 0; |
| 111 |
$i < sizeof($this->attributes['macAddress']); $i++) {<br> |
| 112 |
|
| 113 |
$return->addElement(new htmlOutputText(_('MAC |
| 114 |
address')));<br> |
| 115 |
|
| 116 |
$macInput = new htmlInputField('macAddress' . $i, |
| 117 |
$this->attributes['macAddress'][$i]);<br> |
| 118 |
$macInput->setFieldSize(17);<br> |
| 119 |
$macInput->setFieldMaxLength(17);<br> |
| 120 |
$return->addElement($macInput);<br> |
| 121 |
|
| 122 |
$return->addElement(new htmlButton('delMAC' . $i, |
| 123 |
'del.png', true));<br> |
| 124 |
|
| 125 |
$return->addElement(new htmlHelpLink('mac'), |
| 126 |
true);<br> |
| 127 |
}<br> |
| 128 |
}<br> |
| 129 |
// input box for new MAC<br> |
| 130 |
$return->addElement(new htmlOutputText(_('New MAC address')));<br> |
| 131 |
$newMacInput = new htmlInputField('macAddress', '');<br> |
| 132 |
$newMacInput->setFieldSize(17);<br> |
| 133 |
$newMacInput->setFieldMaxLength(17);<br> |
| 134 |
$return->addElement($newMacInput);<br> |
| 135 |
$return->addElement(new htmlButton('addMAC', 'add.png', true));<br> |
| 136 |
$return->addElement(new htmlHelpLink('mac'));<br> |
| 137 |
$return->addElement(new htmlHiddenInput('mac_number', $macCount));<br> |
| 138 |
return $return;<br> |
| 139 |
}<br> |
| 140 |
</td> |
| 141 |
</tr> |
| 142 |
</tbody> |
| 143 |
</table> |
| 144 |
<br> |
| 145 |
<br> |
| 146 |
<h2>3. Processing input data<br> |
| 147 |
</h2> |
| 148 |
Every time the user clicks on a submit button while your page is |
| 149 |
displayed LAM will call a function in your module.<br> |
| 150 |
This function is called <span style="font-weight: bold;">process_<page |
| 151 |
name>()</span> where <span style="font-style: italic;"><page |
| 152 |
name></span> is the name of your subpage.<br> |
| 153 |
<br> |
| 154 |
If all input data is ok then return an empty array. If you return one or more error messages then the user will be |
| 155 |
redirected to your page.<br> |
| 156 |
<br> |
| 157 |
<span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> |
| 158 |
<br> |
| 159 |
The |
| 160 |
<span style="font-style: italic;">ieee802Device</span> |
| 161 |
module has only one subpage called <span style="font-style: italic;">'attributes'</span> |
| 162 |
and therefore only <span style="font-style: italic;">process_attributes()</span>.<br> |
| 163 |
<br> |
| 164 |
The function checks the input fields and fills the LDAP attributes. If |
| 165 |
all is ok it will enable the user to move to another module page.<br> |
| 166 |
<br> |
| 167 |
<table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> |
| 168 |
<tbody> |
| 169 |
<tr> |
| 170 |
<td style="vertical-align: top;"> /**<br> |
| 171 |
* Write variables into object and do some regex |
| 172 |
checks<br> |
| 173 |
*<br> |
| 174 |
* @param array $post HTTP-POST values<br> |
| 175 |
*/<br> |
| 176 |
<span style="font-weight: bold;">function</span> <span style="color: rgb(255, 0, 0);">process_attributes</span>($post) {<br> |
| 177 |
$errors = array();<br> |
| 178 |
|
| 179 |
$this->attributes['macAddress'] = array();<br> |
| 180 |
// check old MACs<br> |
| 181 |
if (isset($post['mac_number'])) {<br> |
| 182 |
for ($i = 0; |
| 183 |
$i < $post['mac_number']; $i++) {<br> |
| 184 |
|
| 185 |
if (isset($post['delMAC' . $i])) continue;<br> |
| 186 |
|
| 187 |
if (isset($post['macAddress' . $i]) && |
| 188 |
($post['macAddress' . $i] != "")) {<br> |
| 189 |
|
| 190 |
// check if address has correct |
| 191 |
format<br> |
| 192 |
|
| 193 |
if (!get_preg($post['macAddress' |
| 194 |
. $i], 'macAddress')) {<br> |
| 195 |
|
| 196 |
$message = |
| 197 |
$this->messages['mac'][0];<br> |
| 198 |
|
| 199 |
$message[] = |
| 200 |
$post['macAddress' . $i];<br> |
| 201 |
|
| 202 |
$errors[] = $message;<br> |
| 203 |
|
| 204 |
}<br> |
| 205 |
|
| 206 |
|
| 207 |
$this->attributes['macAddress'][] = $post['macAddress' . $i];<br> |
| 208 |
|
| 209 |
}<br> |
| 210 |
}<br> |
| 211 |
}<br> |
| 212 |
// check new MAC<br> |
| 213 |
if (isset($post['macAddress']) |
| 214 |
&& ($post['macAddress'] != "")) {<br> |
| 215 |
// check if |
| 216 |
address has correct format<br> |
| 217 |
if |
| 218 |
(get_preg($post['macAddress'], 'macAddress')) {<br> |
| 219 |
|
| 220 |
$this->attributes['macAddress'][] = |
| 221 |
$post['macAddress'];<br> |
| 222 |
}<br> |
| 223 |
else {<br> |
| 224 |
|
| 225 |
$message = |
| 226 |
$this->messages['mac'][0];<br> |
| 227 |
|
| 228 |
$message[] = $post['macAddress'];<br> |
| 229 |
|
| 230 |
$errors[] = $message;<br> |
| 231 |
}<br> |
| 232 |
}<br> |
| 233 |
|
| 234 |
$this->attributes['macAddress'] = |
| 235 |
array_unique($this->attributes['macAddress']);<br> |
| 236 |
return $errors;<br> |
| 237 |
}<br> |
| 238 |
</td> |
| 239 |
</tr> |
| 240 |
</tbody> |
| 241 |
</table> |
| 242 |
<br> |
| 243 |
<br> |
| 244 |
<h2>4. Defining that your module is ready for user input and LDAP |
| 245 |
add/modify</h2> |
| 246 |
In most cases you will not need to implement these functions. The <span style="font-style: italic;">baseModule</span> will return <span style="font-style: italic;">true</span> for both functions.<br> |
| 247 |
<br> |
| 248 |
<span style="text-decoration: underline;"><br> |
| 249 |
There are two functions which control the module status:</span><br style="text-decoration: underline;"> |
| 250 |
<br> |
| 251 |
The <span style="font-weight: bold;">module_ready()</span> function |
| 252 |
has to |
| 253 |
return <span style="font-style: italic;">true</span> if the user may |
| 254 |
move to your module page. If it is <span style="font-style: italic;">false</span> |
| 255 |
the user will be shown an error message that your module is not yet |
| 256 |
ready. You can use this if your module depends on input data from other |
| 257 |
modules (e.g. you need the user name from posixAccount first).<br> |
| 258 |
<br> |
| 259 |
The second function is |
| 260 |
<span style="font-weight: bold;">module_complete()</span>. The user |
| 261 |
cannot do the LDAP operation if one or more modules return <span style="font-style: italic;">false</span>. This defines if all needed |
| 262 |
input data for your module was entered.<br> |
| 263 |
Use this function if you want to check that all required attributes are |
| 264 |
set.<br> |
| 265 |
<br> |
| 266 |
<span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> |
| 267 |
<br> |
| 268 |
The <span style="font-style: italic;">sambaSamAccount</span> |
| 269 |
module needs the user's <span style="font-style: italic;">uidNumber</span> |
| 270 |
and <span style="font-style: italic;">gidNumber</span> before it can |
| 271 |
accept input and the account needs a <span style="font-style: italic;">sambaSID</span> |
| 272 |
before it can be saved.<br> |
| 273 |
<br> |
| 274 |
<table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> |
| 275 |
<tbody> |
| 276 |
<tr> |
| 277 |
<td style="vertical-align: top;"> /**<br> |
| 278 |
* This function is used to check if this module page |
| 279 |
can be displayed.<br> |
| 280 |
* It returns false if a module depends on data from |
| 281 |
other modules which was not yet entered.<br> |
| 282 |
*<br> |
| 283 |
* @return boolean true, if page can be displayed<br> |
| 284 |
*/<br> |
| 285 |
<span style="font-weight: bold;">function</span> <span style="color: rgb(255, 0, 0);">module_ready</span>() {<br> |
| 286 |
if |
| 287 |
($_SESSION[$this->base]->module['posixAccount']->attributes['gidNumber'][0]=='') |
| 288 |
return false;<br> |
| 289 |
if |
| 290 |
($_SESSION[$this->base]->module['posixAccount']->attributes['uidNumber'][0]=='') |
| 291 |
return false;<br> |
| 292 |
if |
| 293 |
($this->attributes['uid'][0]=='') return false;<br> |
| 294 |
return true;<br> |
| 295 |
}<br> |
| 296 |
<br> |
| 297 |
/**<br> |
| 298 |
* This functions is used to check if all settings |
| 299 |
for this module have been made.<br> |
| 300 |
*<br> |
| 301 |
* @return boolean true, if settings are complete<br> |
| 302 |
*/<br> |
| 303 |
<span style="font-weight: bold;">function</span> <span style="color: rgb(255, 0, 0);">module_complete</span>() {<br> |
| 304 |
if (!$this->module_ready()) |
| 305 |
return false;<br> |
| 306 |
if |
| 307 |
($this->attributes['sambaSID'][0] == '') return false;<br> |
| 308 |
return true;<br> |
| 309 |
}<br> |
| 310 |
<br> |
| 311 |
</td> |
| 312 |
</tr> |
| 313 |
</tbody> |
| 314 |
</table> |
| 315 |
<br> |
| 316 |
<br> |
| 317 |
<h2>5. Saving the LDAP attributes<br> |
| 318 |
</h2> |
| 319 |
In most cases you will not have to implement this option if you use <span style="font-weight: bold;">$this->attributes</span> and <span style="font-weight: bold;">$this->orig</span> to manage the LDAP |
| 320 |
attributes. The <span style="font-style: italic;">baseModule</span> |
| 321 |
will generate the save commands for you.<br> |
| 322 |
<br> |
| 323 |
When all modules report that they are ready for LDAP add/modify and the |
| 324 |
user clicks on the add/modify button your module will be asked what |
| 325 |
changes have to be made.<br> |
| 326 |
This is done in the function <span style="font-weight: bold;">save_attributes()</span>.<br> |
| 327 |
<br> |
| 328 |
<span style="font-weight: bold; text-decoration: underline;">Example:</span><br style="font-weight: bold; text-decoration: underline;"> |
| 329 |
<br> |
| 330 |
The <span style="font-style: italic;">kolabUser</span> module uses |
| 331 |
this function to make sure that its object class is saved. Other |
| 332 |
modules (e.g. quota) use it build the lamdaemon commands.<br> |
| 333 |
<br> |
| 334 |
<table style="width: 100%; text-align: left;" class="mod-code" border="0" cellpadding="2" cellspacing="2"> |
| 335 |
<tbody> |
| 336 |
<tr> |
| 337 |
<td style="vertical-align: top;"> /**<br> |
| 338 |
* Returns a list of modifications which have to be |
| 339 |
made to the LDAP account.<br> |
| 340 |
*<br> |
| 341 |
* @return array list of modifications<br> |
| 342 |
* <br>This function returns an array with 3 |
| 343 |
entries:<br> |
| 344 |
* <br>array( DN1 ('add' => array($attr), |
| 345 |
'remove' => array($attr), 'modify' => array($attr)), DN2 .... )<br> |
| 346 |
* <br>DN is the DN to change. It may be |
| 347 |
possible to change several DNs (e.g. create a new user and add him to |
| 348 |
some groups via attribute memberUid)<br> |
| 349 |
* <br>"add" are attributes which have to be |
| 350 |
added to LDAP entry<br> |
| 351 |
* <br>"remove" are attributes which have to be |
| 352 |
removed from LDAP entry<br> |
| 353 |
* <br>"modify" are attributes which have to |
| 354 |
been modified in LDAP entry<br> |
| 355 |
*/<br> |
| 356 |
function save_attributes() {<br> |
| 357 |
// add object class if needed<br> |
| 358 |
if |
| 359 |
(!isset($this->attributes['objectClass']) || |
| 360 |
!in_array('kolabInetOrgPerson', $this->attributes['objectClass'])) {<br> |
| 361 |
|
| 362 |
$this->attributes['objectClass'][] = 'kolabInetOrgPerson';<br> |
| 363 |
}<br> |
| 364 |
return parent::save_attributes();<br> |
| 365 |
}<br> |
| 366 |
</td> |
| 367 |
</tr> |
| 368 |
</tbody> |
| 369 |
</table> |
| 370 |
<br> |
| 371 |
<br> |
| 372 |
<span style="font-weight: bold;"></span> |
| 373 |
<h2><span style="font-weight: bold;"></span></h2> |
| 374 |
</div> |
| 375 |
</div> |
| 376 |
</body></html> |