[Pieforms-commit] SF.net SVN: pieforms: [252] pieforms-php5/trunk/src/pieform.php
Status: Alpha
Brought to you by:
oracleshinoda
Menu
▾
▴
[Pieforms-commit] SF.net SVN: pieforms: [252] pieforms-php5/trunk/src/pieform.php
|
From: <ora...@us...> - 2007-12-31 01:59:23
|
Revision: 252
http://pieforms.svn.sourceforge.net/pieforms/?rev=252&view=rev
Author: oracleshinoda
Date: 2007-12-30 17:59:27 -0800 (Sun, 30 Dec 2007)
Log Message:
-----------
Foldmarkers, better commenting, and other fixes.
* Updated copyright to 2008
* Added foldmarkers to all methods/functions, using vim's 'vf'
* Improved the json_encode replacement, so if the json extension is not loaded and json_encode is never used, you don't have to have the replacement Services_JSON all set up
* Updated a few function/method comments for spelling, removing references to Mahara or marking functions for deletion.
Modified Paths:
--------------
pieforms-php5/trunk/src/pieform.php
Modified: pieforms-php5/trunk/src/pieform.php
===================================================================
--- pieforms-php5/trunk/src/pieform.php 2007-12-31 01:58:57 UTC (rev 251)
+++ pieforms-php5/trunk/src/pieform.php 2007-12-31 01:59:27 UTC (rev 252)
@@ -20,7 +20,7 @@
* @subpackage core
* @author Nigel McNie <ni...@ca...>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright (C) 2006 Catalyst IT Ltd http://catalyst.net.nz
+ * @copyright (C) 2006-2008 Catalyst IT Ltd http://catalyst.net.nz
*
*/
@@ -44,7 +44,6 @@
* <pre>
* $form = array(
* 'name' => 'myform',
- * 'action' => 'myscript.php',
* 'method' => 'post',
* 'elements' => array(
* // definition of elements in the form
@@ -64,37 +63,25 @@
* }
* </pre>
*
- * Please see https://eduforge.org/wiki/wiki/mahara/wiki?pagename=FormAPI for
+ * Please see http://pieforms.sourceforge.net/doc/html/ for
* more information on creating and using forms.
*
*/
-function pieform($data) { // {{{
+function pieform($data) {/*{{{*/
return Pieform::process($data);
- //
- // @todo stuff to do for forms:
- //
- // - more form element types (inc. types like autocomplete and wyswiyg)
- // - support processing of data before validation occurs (e.g. trim(), strtoupper())
- // - Basic validation is possible as there's a callback function for checking,
- // but some helper functions could be written to make people's job validating
- // stuff much easier (form_validate_email, form_validate_date etc).
- // - Collapsible js for fieldsets
- // - Grippie for textareas
- // - handle multipage forms?
- // - handle a tabbed interface type of form?
- //
-} // }}}
+}/*}}}*/
-if (!function_exists('json_encode')) {
- require_once 'JSON/JSON.php';
+// json_encode replacement, if the user doesn't have this function available
+if (!function_exists('json_encode')) {/*{{{*/
function json_encode($data) {
+ require_once 'JSON/JSON.php';
$json = new Services_JSON();
return $json->encode($data);
}
-}
+}/*}}}*/
/**
- * Pieform throws PieformExceptions, so you can catch them specifically
+ * Pieforms throws PieformExceptions when things go wrong
*/
class PieformException extends Exception {}
@@ -107,11 +94,11 @@
* functions.
*
* For more information on how Pieforms works, please see the documentation
- * at https://eduforge.org/wiki/wiki/mahara/wiki?pagename=FormAPI
+ * at http://pieforms.sourceforge.net/doc/html/
*/
-class Pieform { // {{{
+class Pieform {/*{{{*/
- // {{{ Fields
+ /*{{{ Fields */
/**
* Maintains a tab index across all created forms, to make it easy for
@@ -151,21 +138,21 @@
* @var bool
*/
private $submitted = false;
+
+ /*}}}*/
- // }}}
-
/**
* Processes the form. Called by the {@link pieform} function. It simply
* builds the form (processing it if it has been submitted), and returns
- * the HTML to display the form
+ * the HTML to display the form.
*
* @param array $data The form description hash
* @return string The HTML representing the form
*/
- public static function process($data) { // {{{
+ public static function process($data) {/*{{{*/
$form = new Pieform($data);
return $form->build();
- } // }}}
+ }/*}}}*/
/**
* Sets the attributes of the form according to the passed data, performing
@@ -174,7 +161,7 @@
*
* @param array $data The form description hash
*/
- public function __construct($data) { // {{{
+ public function __construct($data) {/*{{{*/
$GLOBALS['_PIEFORM_REGISTRY'][] = $this;
if (!isset($data['name']) || !preg_match('/^[a-z_][a-z0-9_]*$/', $data['name'])) {
@@ -601,47 +588,48 @@
$this->json_reply(PIEFORM_ERR, array('message' => $message, 'errors' => $json));
}
}
- } // }}}
+ }/*}}}*/
/**
+ * Returns the form name
+ *
+ * @return string
+ */
+ public function get_name() {/*{{{*/
+ return $this->name;
+ }/*}}}*/
+
+ /**
* Returns a generic property. This can be used to retrieve any property
* set in the form data array, so developers can pass in random stuff and
* get access to it.
*
- * @param string The key of the property to return
+ * @param string The key of the property to return. If the property doesn't
+ * exist, null is returned
* @return mixed
*/
- public function get_property($key) { // {{{
+ public function get_property($key) {/*{{{*/
if (array_key_exists($key, $this->data)) {
return $this->data[$key];
}
return null;
- } // }}}
+ }/*}}}*/
/**
- * Returns the form name
- *
- * @return string
- */
- public function get_name() { // {{{
- return $this->name;
- } // }}}
-
- /**
* Returns whether the form has been submitted
*
* @return bool
*/
- public function is_submitted() {
+ public function is_submitted() {/*{{{*/
return $this->submitted;
- }
+ }/*}}}*/
/**
* Returns the HTML for the <form...> tag
*
* @return string
*/
- public function get_form_tag() {
+ public function get_form_tag() {/*{{{*/
$result = '<form class="pieform"';
foreach (array('name', 'method', 'action') as $attribute) {
$result .= ' ' . $attribute . '="' . $this->data[$attribute] . '"';
@@ -652,7 +640,7 @@
}
$result .= '>';
return $result;
- }
+ }/*}}}*/
/**
* Builds and returns the HTML for the form, respecting the chosen renderer.
@@ -665,7 +653,7 @@
* @param boolean Whether to include the <form...></form> tags in the output
* @return string The form as HTML
*/
- public function build($outputformtags=true) {
+ public function build($outputformtags=true) {/*{{{*/
$result = '';
// Builds the HTML each element (see the build_element_html method for
@@ -790,7 +778,7 @@
}
return $result;
- }
+ }/*}}}*/
/**
* Given an element, gets the value for it from this form
@@ -799,7 +787,7 @@
* @return mixed The element's value. <kbd>null</kbd> if no value
* is available for the element.
*/
- public function get_value($element) {
+ public function get_value($element) {/*{{{*/
$function = 'pieform_element_' . $element['type'] . '_get_value';
if (function_exists($function)) {
return $function($this, $element);
@@ -818,7 +806,7 @@
return $element['defaultvalue'];
}
return null;
- }
+ }/*}}}*/
/**
* Retrieves a list of elements in the form.
@@ -827,7 +815,7 @@
*
* @return array The elements of the form
*/
- public function get_elements() {
+ public function get_elements() {/*{{{*/
$elements = array();
foreach ($this->data['elements'] as $name => $element) {
if ($element['type'] == 'fieldset') {
@@ -840,7 +828,7 @@
}
}
return $elements;
- }
+ }/*}}}*/
/**
* Returns the element with the given name. Throws a PieformException if the
@@ -853,14 +841,14 @@
* @return array The element
* @throws PieformException If the element could not be found
*/
- public function get_element($name) {
+ public function get_element($name) {/*{{{*/
foreach ($this->get_elements() as $element) {
if ($element['name'] == $name) {
return $element;
}
}
throw new PieformException('Element "' . $name . '" cannot be found');
- }
+ }/*}}}*/
/**
* Retrieves submitted values from the request for the elements of this form.
@@ -874,7 +862,7 @@
*
* @return array The submitted values
*/
- private function get_submitted_values() {
+ private function get_submitted_values() {/*{{{*/
$result = array();
$global = ($this->data['method'] == 'get') ? $_GET : $_POST;
foreach ($this->get_elements() as $element) {
@@ -891,7 +879,7 @@
}
}
return $result;
- }
+ }/*}}}*/
/**
* Performs simple validation based off the definition array.
@@ -906,7 +894,7 @@
*
* @param array $values The submitted values from the form
*/
- private function validate($values) {
+ private function validate($values) {/*{{{*/
// Call the overall validation function if it is available
if (function_exists('pieform_validate')) {
pieform_validate($this, $values);
@@ -943,9 +931,9 @@
if (is_callable($function)) {
call_user_func_array($function, array($this, $values));
}
- }
+ }/*}}}*/
- private function whichbutton_js() {
+ private function whichbutton_js() {/*{{{*/
$result = "var {$this->name}_btn = null;\n";
$connecteventadded = false;
@@ -969,7 +957,7 @@
}
return $result;
- }
+ }/*}}}*/
/**
* Builds the javascript for submitting the form. Note that the iframe is
@@ -977,7 +965,7 @@
* display: none. Positioning it absolute and 'hidden' has the same effect
* without the breakage.
*/
- private function submit_js() {
+ private function submit_js() {/*{{{*/
$result = <<<EOF
connect($('{$this->name}'), 'onsubmit', function(e) {
if (typeof(tinyMCE) != 'undefined') { tinyMCE.triggerSave(); }
@@ -1077,9 +1065,9 @@
}
return $result . $function($this->name);
- }
+ }/*}}}*/
- public function json_reply($returncode, $message=null) {
+ public function json_reply($returncode, $message=null) {/*{{{*/
$data = array(
'returnCode' => intval($returncode),
'message' => $message
@@ -1090,7 +1078,7 @@
<html><head><script type="text/javascript">function sendResult() { parent.pieformHandler_{$this->name}($result); }</script></head><body onload="sendResult(); "></body></html>
EOF;
exit;
- }
+ }/*}}}*/
/**
* Returns whether a field has an error marked on it.
@@ -1110,10 +1098,10 @@
* @return bool Whether the element has an error
* @throws PieformException If the element could not be found
*/
- public function get_error($name) {
+ public function get_error($name) {/*{{{*/
$element = $this->get_element($name);
return isset($element['error']);
- }
+ }/*}}}*/
/**
* Marks a field has having an error.
@@ -1121,14 +1109,11 @@
* This method should be used to set an error on an element in a custom
* validation function, if one has occured.
*
- * Note that for the Mahara project, your error messages must be passed
- * through {@link get_string} to internationalise them.
- *
* @param string $name The name of the element to set an error on
* @param string $message The error message
* @throws PieformException If the element could not be found
*/
- public function set_error($name, $message) {
+ public function set_error($name, $message) {/*{{{*/
foreach ($this->data['elements'] as &$element) {
if ($element['type'] == 'fieldset') {
foreach ($element['elements'] as &$subelement) {
@@ -1146,7 +1131,7 @@
}
}
throw new PieformException('Element "' . $name . '" could not be found');
- }
+ }/*}}}*/
/**
* Makes an ID for an element.
@@ -1155,12 +1140,12 @@
* an element gets an ID.
*
* The element's existing 'id' and 'name' attributes are checked first. If
- * they are not specified, a random ID is synthesised
+ * they are not specified, a random ID is created
*
* @param array $element The element to make an ID for
* @return string The ID for the element
*/
- public function make_id($element) {
+ public function make_id($element) {/*{{{*/
if (isset($element['id'])) {
return self::hsc($element['id']);
}
@@ -1168,7 +1153,7 @@
return self::hsc($element['name']);
}
return substr(md5(mt_rand()), 0, 4);
- }
+ }/*}}}*/
/**
* Makes a class for an element.
@@ -1182,7 +1167,7 @@
* @param array $element The element to make a class for
* @return string The class for an element
*/
- public function make_class($element) {
+ public function make_class($element) {/*{{{*/
$classes = array();
if (isset($element['class'])) {
$classes[] = $element['class'];
@@ -1198,12 +1183,12 @@
}
// Please make sure that 'autofocus' is the last class added in this
// method. Otherwise, improve the logic for removing 'autofocus' from
- // the elemnt class string in pieform_render_element
+ // the element class string in pieform_render_element
if (!empty($element['autofocus'])) {
$classes[] = 'autofocus';
}
return implode(' ', $classes);
- }
+ }/*}}}*/
/**
* Given an element, returns a string representing the basic attribute
@@ -1228,7 +1213,7 @@
* @param array $exclude Any attributes to explicitly exclude from adding
* @return string The attributes for the element
*/
- public function element_attributes($element, $exclude=array()) {
+ public function element_attributes($element, $exclude=array()) {/*{{{*/
static $attributes = array('accesskey', 'class', 'dir', 'id', 'lang', 'name', 'onclick', 'size', 'style', 'tabindex');
$elementattributes = array_diff($attributes, $exclude);
$result = '';
@@ -1252,21 +1237,21 @@
}
return $result;
- }
+ }/*}}}*/
/**
* Checks if there are errors on any of the form elements.
*
* @return bool Whether there are errors with the form
*/
- public function has_errors() {
+ public function has_errors() {/*{{{*/
foreach ($this->get_elements() as $element) {
if (isset($element['error'])) {
return true;
}
}
return false;
- }
+ }/*}}}*/
/**
* Includes a plugin file, checking any configured plugin directories.
@@ -1275,7 +1260,7 @@
* @param string $name The name of the plugin to include
* @throws PieformException If the given type or plugin could not be found
*/
- public function include_plugin($type, $name) {
+ public function include_plugin($type, $name) {/*{{{*/
if (!in_array($type, array('element', 'renderer', 'rule'))) {
throw new PieformException("The type \"$type\" is not allowed for an include plugin");
}
@@ -1297,7 +1282,7 @@
}
throw new PieformException("Could not find $type \"$name\"");
- }
+ }/*}}}*/
/**
* Return an internationalised string based on the passed input key
@@ -1312,7 +1297,7 @@
* can specify there own i18n strings for rules
* @return string The internationalised string
*/
- public function i18n($plugin, $pluginname, $key, $element) {
+ public function i18n($plugin, $pluginname, $key, $element) {/*{{{*/
if (!in_array($plugin, array('element', 'renderer', 'rule'))) {
throw new PieformException("Invalid plugin name '$plugin'");
}
@@ -1339,7 +1324,7 @@
// We don't recognise this string
return '[[' . $key . ']]';
- }
+ }/*}}}*/
/**
* HTML-escapes the given value
@@ -1347,16 +1332,16 @@
* @param string $text The text to escape
* @return string The text, HTML escaped
*/
- public static function hsc($text) {
+ public static function hsc($text) {/*{{{*/
return htmlspecialchars($text, ENT_COMPAT, 'UTF-8');
- }
+ }/*}}}*/
/**
* Hook for giving information back to the developer
*
* @param string $message The message to give to the developer
*/
- public static function info($message) {
+ public static function info($message) {/*{{{*/
$function = 'pieform_info';
if (function_exists($function)) {
$function($message);
@@ -1364,20 +1349,20 @@
else {
trigger_error($message, E_USER_NOTICE);
}
- }
+ }/*}}}*/
/**
* Makes sure that the javascript callbacks for this form are valid javascript
* function names.
*/
- private function validate_js_callbacks() {
+ private function validate_js_callbacks() {/*{{{*/
foreach (array('presubmitcallback', 'postsubmitcallback', 'jssuccesscallback',
'jserrorcallback', 'globaljserrorcallback') as $callback) {
if ($this->data[$callback] != '' && !preg_match('/^[a-zA-Z][a-zA-Z0-9_]*$/', $this->data[$callback])) {
throw new PieformException("'{$this->data[$callback]}' is not a valid javascript callback name for callback '$callback'");
}
}
- }
+ }/*}}}*/
/**
* Returns elements with errors on them
@@ -1385,7 +1370,7 @@
* @return array An array of elements with errors on them, the empty array
* in the result of no errors.
*/
- public function get_errors() {
+ public function get_errors() {/*{{{*/
$result = array();
foreach ($this->get_elements() as $element) {
if (isset($element['error'])) {
@@ -1393,13 +1378,13 @@
}
}
return $result;
- }
+ }/*}}}*/
/**
* Sets the 'autofocus' property on the first element encountered that has
* an error on it
*/
- private function auto_focus_first_error() {
+ private function auto_focus_first_error() {/*{{{*/
foreach ($this->data['elements'] as &$element) {
if ($element['type'] == 'fieldset') {
foreach ($element['elements'] as &$subelement) {
@@ -1418,7 +1403,7 @@
unset($element['autofocus']);
}
}
- }
+ }/*}}}*/
/**
* Given an element, builds all of the HTML for it - for example, the label
@@ -1433,7 +1418,7 @@
*
* @param array &$element The element to build the HTML for
*/
- private function build_element_html(&$element) {
+ private function build_element_html(&$element) {/*{{{*/
// Set ID and class for elements
$element['id'] = $this->make_id($element);
$element['class'] = $this->make_class($element);
@@ -1466,9 +1451,9 @@
$element['helphtml'] = '<span class="help"><a href="" title="' . Pieform::hsc($element['help']) . '" onclick="return false;">?</a></span>';
}
}
- }
+ }/*}}}*/
-} // }}}
+}/*}}}*/
/**
@@ -1484,11 +1469,14 @@
* {@internal This is separate so that child element types can nest other
* elements inside them (like the fieldset element does for example).}}
*
+ * NOTE: This function is SCHEDULED FOR REMOVAL. Nicer ways of getting built
+ * elements are available
+ *
* @param Pieform $form The form to render the element for
* @param array $element The element to render
* @return string The rendered element
*/
-function pieform_render_element(Pieform $form, $element) {
+function pieform_render_element(Pieform $form, $element) {/*{{{*/
// If the element is pure markup, don't pass it to the renderer
if ($element['type'] == 'markup') {
return $element['value'] . "\n";
@@ -1512,9 +1500,18 @@
}
return $rendererfunction($form, $element);
-}
+}/*}}}*/
-function pieform_get_headdata() {
+/**
+ * Returns an array of HTML elements to be placed in the <head> section of the
+ * page.
+ *
+ * This works for all forms that have been built at the time this function is
+ * called - so call this function after all forms are built!
+ *
+ * @return array
+ */
+function pieform_get_headdata() {/*{{{*/
$htmlelements = array();
foreach ($GLOBALS['_PIEFORM_REGISTRY'] as $form) {
foreach ($form->get_elements() as $element) {
@@ -1527,6 +1524,6 @@
}
return array_unique($htmlelements);
-}
+}/*}}}*/
?>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
