documented status messages

lam/docs/devel/FAQ.htm

@@ -58,6 +58,46 @@ really logged in and not calling the scripts by hand?</span></big><br>
 successfully logged in to LAM the variable <span
  style="font-weight: bold; color: rgb(204, 0, 0);">$_SESSION['loggedIn']</span>
 is set to true.<br>
+<br>
+<big><span style="font-weight: bold;"><br>
+<br>
+Q: What is the command for these error/warning/info messages?</span></big><br>
+<br>
+<big><span style="font-weight: bold;">A:</span></big> Your script must
+include status.inc (automatically included for account
+modules) to display these messages.<br>
+The command is <span style="font-weight: bold;">StatusMessage(&lt;type&gt;,
+&lt;headline&gt;, &lt;text&gt;[, &lt;variables&gt;])</span>.<br>
+<br>
+<span style="font-weight: bold;">Parameters:</span><br>
+<ul>
+  <li><span style="font-weight: bold;">&lt;type&gt;:</span> message
+type ("ERROR", "WARN", "INFO")</li>
+  <li><span style="font-weight: bold;">&lt;headline&gt;:</span>
+headline for the message (may include format tags)<br>
+  </li>
+  <li><span style="font-weight: bold;">&lt;type&gt;:</span> text for
+the message (may include format tags)</li>
+  <li><span style="font-weight: bold;">&lt;variables&gt;:</span>
+optional, array of variables to include in headline/text<br>
+The positions in headline/text must be marked with %s before.</li>
+</ul>
+<br>
+<span style="font-weight: bold;">Format of special tags:</span><br>
+<ul>
+  <li><span style="font-weight: bold;">{bold}</span>text<span
+ style="font-weight: bold;">{endbold}:</span> "text" is printed bold</li>
+  <li><span style="font-weight: bold;">{color=#123456}</span>text<span
+ style="font-weight: bold;">{endcolor}:</span> "text" is printed in
+given color</li>
+  <li><span style="font-weight: bold;">{link=http://nodomain.org}</span>text<span
+ style="font-weight: bold;">{endlink}:</span> This will add a link to
+http://nodomain.org which will be labeled "text"<br>
+  </li>
+</ul>
+<br>
+<br>
+<br>
 </div>
 </div>
 </body>

lam/docs/devel/other_libs.htm

@@ -28,7 +28,14 @@ They allow to have translated descriptions of the most common
 attributes.<br>
 <br>
 <h2><a name="status"></a>Status messages (status.inc)</h2>
+Status.inc provides the function <span
+ style="font-weight: bold; font-style: italic;">StatusMessage()</span>
+which can be used to display error, warning and information messages.<br>
+The function uses preg_replace() to convert the special tags to HTML
+tags. The message variables are included with printf().<br>
 <br>
+The parameters of <span style="font-weight: bold; font-style: italic;">StatusMessage()
+</span>are described in the developer FAQ.<br>
 <br>
 <h2><a name="treeSchema"></a>Tree view and schema browser</h2>
 The files tree.inc and schema.inc contain functions which are needed by

lam/lib/status.inc

@@ -3,7 +3,7 @@
 $Id$
 
   This code is part of LDAP Account Manager (http://www.sourceforge.net/projects/lam)
-  Copyright (C) 2003  Michael Duergner
+  Copyright (C) 2003 - 2004  Michael Duergner
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -24,23 +24,27 @@ $Id$
  * LDAP Account Manager status messages.
  * 
  * @author Michael Dürgner
- * @version 0.5
  * @package lib
- * @copyright Copyright (C) 2003-2004 Michael Dürgner
- * @license GPL
  */
 
 /**
  * This function prints a short status message. It can be used to print INFO,
  * WARN and ERROR messages at the moment.
+ *
+ * The headline and text may be formated with special tags:
+ * <br>
+ * <br><b>{bold}, {endbold}:</b> All text between these tags is printed bold.
+ * <br><b>{color=#123456}, {endcolor}:</b> All text between these tags is printed in the given color.
+ * <br><b>{link=http://nodomain.org}, {endlink}:</b> A link with the given target is created. The link text is the text between the tags.
  * 
- * @param string The type of the message to be printed. It must be one of
+ * @param string $MessageTyp The type of the message to be printed. It must be one of
- * the following types: 'INFO', 'WARN' or 'ERROR'. Every other type will lead
+ * the following types: 'INFO', 'WARN' or 'ERROR'.
- * to an error message indicating an invalid message type.
+ * <br> Every other type will lead to an error message indicating an invalid message type.
- * @param string The headline of the status message.
+ * @param string $MessageHeadline The headline of the status message.
- * @param string The text of the status message. It may be formatted with
+ * <br> It may be formatted with special color/link/bold tags. 
- * the syntax specified by the other functions in this file. 
+ * @param string $MessageText The text of the status message.
- * @param array The variables that are used to replace the spacers in the
+ * <br> It may be formatted with special color/link/bold tags. 
+ * @param array $MessageVariables The variables that are used to replace the spacers (%s) in the
  * submitted text. This parameter is optional.
  */
 function StatusMessage($MessageTyp,$MessageHeadline,$MessageText,$MessageVariables = array()) {
@@ -94,7 +98,7 @@ function StatusMessage($MessageTyp,$MessageHeadline,$MessageText,$MessageVariabl
  * 
  * @access private
  * 
- * @param string The text that is used to search for replaceable strings.
+ * @param string $MessageString The text that is used to search for replaceable strings.
  * 
  * @return string The processed text.
  */
@@ -107,7 +111,7 @@ function parseMessageString($MessageString) {
   * 
  * @access private
  * 
- * @param string The text that is used to search for {bold} and {endbold} tags.
+ * @param string $text The text that is used to search for {bold} and {endbold} tags.
  * 
  * @return string The submitted text with {bold} and {endbold} replaced with
  * the appropriate HTML tages <b> and </b> 
@@ -123,9 +127,9 @@ function boldText($text) {
  * 
  * @access private
  * 
- * @param string 
+ * @param string $text The text that is used to search for {color} and {endcolor} tags.
  * 
- * @return string 
+ * @return string Input string with HTML-formatted color tags
  */
 function colorText($text) {
 	$pattern = "/\{color=#?([0-9,a-f,A-F]{6})\}([^{]*)\{endcolor\}/"; // Regular expression matching {color=#[HEX-Value]}[Text]{endcolor} or {color=[HEX-Value]}[Text]{endcolor}
@@ -138,9 +142,9 @@ function colorText($text) {
  * 
  * @access private
  * 
- * @param string 
+ * @param string $text The text that is used to search for {link} and {endlink} tags.
  * 
- * @return string 
+ * @return string Input string with HTML-formatted link tags
  */
 function linkText($text) {
 	$pattern = "/\{link=([^}]*)\}([^{]*)\{endlink\}/"; // Regular expression matching {link=[Link-Target]}[Text]{endlink}