enhanced documentation and added list of defaults for input options

Author: jonasjonas

abstracts/input.php

@@ -24,54 +24,178 @@ abstract class input extends element
      * @brief Input element type - HTML input type attribute.
      **/
     protected $type;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default string $label
+     *     Sets the label for the input
+     **/
     /**
      * @brief Input element - HTML label
      **/
     protected $label;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default string $marker
+     *     Sets marker character(s) that gets display on required fields.
+     **/
+    /**
+     * @brief Input element - HTML marker text that marks required fields
+     **/
+    protected $marker;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default bool $required
+     *     Sets wether an input is required to hold a value to be valid
+     **/
     /**
      * @brief True if the input element is required to hold a value to be valid.
      **/
     protected $required;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default bool $disabled
+     *     Enables/disables an input
+     **/
+    /**
+     * @brief wether a input element will be disabled
+     **/
+    protected $disabled;
+
     /**
      * @brief Name of the parent HTML form. Used to identify the element once it's rendered.
      **/
     protected $formName;
+
     /**
      * @brief Input elements's value.
      **/
     protected $value = null;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default string|function $validator
+     *     Sets the validator for the input.
+     *     - When $validator starts and ends with "/" e.g. "/[a-z0-9]/" the 
+     *       validator will be a depage::htmlform::validators::regEx
+     *     - When it is a plain string it will be a the validator with the name 
+     *       $validator out of the namespace depage::htmlform::validators.
+     *     - If the $validator is callable then the validator will be a
+     *       depage::htmlform::validators::closure
+     **/
     /**
      * @brief Holds validator object reference.
      **/
     protected $validator;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default string $class
+     *     Class name or class names that gets added to wrapper paragraph.
+     **/
     /**
      * @brief class for paragraph
      **/
     protected $class;
+
     /**
      * @brief HTML classes attribute for rendering the input element.
      **/
     protected $classes;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default bool $autofocus 
+     *     sets current input to get autofocus on a page. If you set the 
+     *     autofocus to more than one input - The first one gets the focus.
+     **/
     /**
      * @brief HTML autofocus attribute
      **/
     protected $autofocus = false;
+
     /**
-     * @brief HTML autocapitalize attribute
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default bool $autocapitalize 
+     *     Enables/disables autocapitalizion (mostly on mobile devices)
      **/
+    /**
+     * @brief HTML autocapitalize attribute
+     */
     protected $autocapitalize;
+
     /**
-     * @brief HTML autocorrect attribute
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default bool $autocorrect
+     *      Enables/disables autocorrection
      **/
+    /**
+     * @brief HTML autocorrect attribute
+     */
+
     protected $autocorrect;
     /**
-     * @brief HTML autocomplete attribute
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default bool $autocomplete
+     *     Used to enable/disable autocorrect
      **/
+    /**
+     * @brief HTML autocomplete attribute
+     */
     protected $autocomplete;
+
     /**
      * @brief HTML pattern attribute
      **/
     protected $pattern;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default string $errorMessage
+     *     Sets the message that will be displayed in case of invalid input
+     **/
+    /**
+     * @brief Message that gets displayed in case of invalid input
+     **/
+    protected $errorMessage;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default string $helpMessage
+     *     Optional help message that may be used for extra information e.g. tooltips.
+     *     These string will be html escaped.
+     **/
+    /**
+     * @brief Extra help message
+     **/
+    protected $helpMessage;
+
+    /**
+     * @addtogroup htmlformInputDefaults
+     *
+     * @default string $helpMessageHtml
+     *     Optional help message that may be used for extra information e.g. tooltips.
+     *     These string won't be escaped as therefor has to be valid html.
+     **/
+    /**
+     * @brief Extra hep message in html format
+     **/
+    protected $helpMessageHtml;
     // }}}
 
     // {{{ __construct()
@@ -98,7 +222,7 @@ public function __construct($name, $parameters, $form)
 
     // {{{ setDefaults()
     /**
-     * @brief   Collects initial values across subclasses.
+     * @brief  Sets the default values for input elements
      *
      * The constructor loops through these and creates settable class
      * attributes at runtime. It's a compact mechanism for initialising
@@ -301,7 +425,7 @@ public function setRequired($required = true)
     /**
      * @brief   Sets the HTML disabled-attribute of the current input element.
      *
-     * @param  bool $dіsabled HTML disabled-attribute
+     * @param  bool $disabled HTML disabled-attribute
      * @return void
      **/
     public function setDisabled($disabled = true)

documentation/Doxyfile

@@ -229,7 +229,10 @@ TAB_SIZE               = 8
 # newlines.
 
 ALIASES                = "intro=<div class=\"intro\">" \
-                         "endintro=</div>"
+                         "endintro=</div>" \
+                         "default=@param " \
+                         "license=@par License:\n" \
+                         "copyright=@par Copyright:\n"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"

elements/address.php

@@ -17,7 +17,8 @@
  * - a state
  * - a country select
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/boolean.php

@@ -18,7 +18,10 @@
  * be clicked to sumbit the form succesfully. It may e.g. be used for specific
  * terms a user has to accept to register.
  *
- * @section usage
+ * @see depage::htmlform::elements::multiple
+ *
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/country.php

@@ -19,7 +19,8 @@
  * An optional 'priority' parameter moves countries to the top of the select based on the DEPAGE_LANG locale:
  * e.g. 'de' => array('de','at'), 'en' => array('au','gb','ca','us')
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/creditcard.php

@@ -15,15 +15,16 @@
  * Class to get a user creditcard information. It generates a fieldset
  * that consists of
  *
- *     - a creditcard-type (like 'Visa', 'MasterCard' or 'American Express')
- *     - a field for the creditcard-number
- *     - a field for the expiry-date
- *     - a field for the card-owner
+ * - a creditcard-type (like 'Visa', 'MasterCard' or 'American Express')
+ * - a field for the creditcard-number
+ * - a field for the expiry-date
+ * - a field for the card-owner
  *
- * At the moment this input only checks the formatting of the numbers but not if
+ * At the moment this input only checks the formatting of the numbers but not, if
  * it is a valid creditcard.
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/email.php

@@ -14,7 +14,8 @@
  *
  * Class for the HTML5 input-type "email".
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/fieldset.php

@@ -17,7 +17,8 @@
  * Class for the HTML fieldset element. Can be used to group other elments
  * together.
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/hidden.php

@@ -14,7 +14,8 @@
  *
  * Class for the HTML input-type "hidden".
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/html.php

@@ -14,7 +14,8 @@
  *
  * Class for custom HTML code sections.
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/multiple.php

@@ -17,7 +17,11 @@
  * Class for multiple-choice type HTML elements. Has the same return value,
  * regardless of skin type (checkbox or select).
  *
- * @section usage
+ * @see depage::htmlform::elements::single
+ * @see depage::htmlform::elements::boolean
+ *
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/number.php

@@ -14,7 +14,8 @@
  *
  * Class for HTML5 input type "number".
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/password.php

@@ -15,7 +15,8 @@
  * Class for the HTML input type "password". Entered characters are masked with
  * asterisks or bullets (depends on browser).
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/placeholder.php

@@ -14,7 +14,8 @@
 /**
  * @brief Adds a placeholder for a form element
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/placeholdermultiple.php

@@ -12,7 +12,8 @@
 /**
  * @brief Placeholder for form multiple form values.
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/range.php

@@ -14,7 +14,8 @@
  *
  * Class for HTML5 input type "range".
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/richtext.php

@@ -15,7 +15,8 @@
  * adds a textarea-element with additional richtext-functionality
  * added by javascript
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/single.php

@@ -17,7 +17,8 @@
  * Class for radio-like HTML elements. Has the same return value, regardless
  * of skin type (radio or select).
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php

elements/state.php

@@ -15,7 +15,8 @@
  *
  * Option values are 4-digit alpha ISO state codes.
  *
- * @section usage
+ * Usage
+ * -----
  *
  * @code
     <?php