From bc13c208fe1e7fc375bfe96becbaac8934c7e263 Mon Sep 17 00:00:00 2001 From: Ralf Becker Date: Sun, 13 Feb 2005 13:03:36 +0000 Subject: [PATCH] fixed inline documentation, works very nice now --- etemplate/inc/class.db_tools.inc.php | 232 +++++++++++----------- etemplate/inc/class.editor.inc.php | 28 +-- etemplate/inc/class.so_sql.inc.php | 249 ++++++++++++------------ etemplate/inc/class.uietemplate.inc.php | 76 ++++---- etemplate/inc/class.xul_io.inc.php | 54 ++++- 5 files changed, 359 insertions(+), 280 deletions(-) diff --git a/etemplate/inc/class.db_tools.inc.php b/etemplate/inc/class.db_tools.inc.php index f0bd8083b6..cb013a4773 100644 --- a/etemplate/inc/class.db_tools.inc.php +++ b/etemplate/inc/class.db_tools.inc.php @@ -12,6 +12,13 @@ /* $Id$ */ + /** + * db-tools: creats and modifys eGroupWare schem-files (to be installed via setup) + * + * @package etemplate + * @author RalfBecker-AT-outdoor-training.de + * @license GPL + */ class db_tools { var $public_functions = array @@ -56,12 +63,9 @@ /* $Id$ */ '; - /*! - @function db_tools - @syntax db_tools( ) - @author ralfbecker - @abstract constructor of class - */ + /** + * constructor of class + */ function db_tools() { $this->editor = CreateObject('etemplate.etemplate','etemplate.db-tools.edit'); @@ -75,12 +79,9 @@ $GLOBALS['phpgw_info']['apps']['etemplate']['title'].' - '.lang('DB-Tools'); } - /*! - @function edit - @syntax edit( $content='',$msg='' ) - @author ralfbecker - @abstract this is the table editor (and the callback/submit-method too) - */ + /** + * table editor (and the callback/submit-method too) + */ function edit($content='',$msg = '') { if (isset($_GET['app'])) @@ -234,17 +235,15 @@ array('posted_table' => $this->table,'posted_app' => $this->app,'changes' => $this->changes)); } - /*! - @function needs_save - @syntax needs_save( $cont='',$posted_app='',$posted_table='',$edited_table='' ) - @author ralfbecker - @abstract checks if table was changed and if so offers user to save changes - @param $cont the content of the form (if called by process_exec) - @param $posted_app the app the table is from - @param $posted_table the table-name - @param $edited_table the edited table-definitions - @result only if no changes - */ + /** + * checks if table was changed and if so offers user to save changes + * + * @param array $cont the content of the form (if called by process_exec) + * @param string $posted_app the app the table is from + * @param string $posted_table the table-name + * @param string $edited_table the edited table-definitions + * @return only if no changes + */ function needs_save($cont='',$posted_app='',$posted_table='',$edited_table='') { if (!$posted_app && is_array($cont)) @@ -326,15 +325,14 @@ return True; // dont continue in edit } - /*! - @function has_single_index - @syntax has_single_index( $col,$index ) - @author ralfbecker - @abstract checks if there is an index (only) on $col (not a multiple index incl. $col) - @param $col column name - @param $index ix or uc array of table-defintion - @result True if $col has a single index - */ + /** + * checks if there is an index (only) on $col (not a multiple index incl. $col) + * + * @param string $col column name + * @param array $index ix or uc array of table-defintion + * @param string &$options db specific options + * @return True if $col has a single index + */ function has_single_index($col,$index,&$options) { foreach($index as $in) @@ -355,14 +353,14 @@ return False; } - /*! - @function table2content - @syntax table2content( $table ) - @author ralfbecker - @abstract creates content-array from a $table - @param $table table-definition, eg. $phpgw_baseline[$table_name] - @result content-array - */ + /** + * creates content-array from a table + * + * @param array $table table-definition, eg. $phpgw_baseline[$table_name] + * @param array &$columns returns array with column-names + * @param bool $extra_index add an additional index-row + * @return array content-array to call exec with + */ function table2content($table,&$columns,$extra_index=False) { $content = $columns = array(); @@ -414,15 +412,14 @@ return $content; } - /*! - @function content2table - @syntax content2table( $content ) - @author ralfbecker - @abstract creates table-definition from posted content - @param $content posted content-array - @note It sets some reasonalbe defaults for not set precisions (else setup will not install) - @result table-definition - */ + /** + * creates table-definition from posted content + * + * It sets some reasonalbe defaults for not set precisions (else setup will not install) + * + * @param array $content posted content-array + * @return table-definition + */ function content2table($content) { if (!is_array($this->data)) @@ -547,15 +544,12 @@ return $table; } - /*! - @function read - @syntax read( $app,&$phpgw_baseline ) - @author ralfbecker - @abstract includes $app/setup/tables_current.inc.php - @param $app application name - @param $phpgw_baseline where to put the data - @result True if file found, False else - */ + /** + * includes $app/setup/tables_current.inc.php + * @param string $app application name + * @param array &$phpgw_baseline where to return the data + * @return boolean True if file found, False else + */ function read($app,&$phpgw_baseline) { $file = PHPGW_SERVER_ROOT."/$app/setup/tables_current.inc.php"; @@ -578,6 +572,14 @@ return True; } + /** + * returns an array as string in php-notation + * + * @param array $arr + * @param int $depth for idention + * @param string $parent + * @return string + */ function write_array($arr,$depth,$parent='') { if (in_array($parent,array('pk','fk','ix','uc'))) @@ -628,15 +630,13 @@ return $def; } - /*! - @function write - @syntax write( $app,$phpgw_baseline ) - @author ralfbecker - @abstract writes tabledefinitions $phpgw_baseline to file /$app/setup/tables_current.inc.php - @param $app app-name - @param $phpgw_baseline tabledefinitions - @return True if file writen else False - */ + /** + * writes tabledefinitions $phpgw_baseline to file /$app/setup/tables_current.inc.php + * + * @param string $app app-name + * @param array $phpgw_baseline tabledefinitions + * @return boolean True if file writen else False + */ function write($app,$phpgw_baseline) { $file = PHPGW_SERVER_ROOT."/$app/setup/tables_current.inc.php"; @@ -683,16 +683,13 @@ return True; } - /*! - @function setup_version - @syntax setup_version( $app,$new = '',$tables='' ) - @author ralfbecker - @abstract reads and updates the version and tables info in file $app/setup/setup.inc.php - @param $app the app - @param $new new version number to set, if $new != '' - @param $tables new tables to include, if $tables != '' - @return the version or False if the file could not be read or written - */ + /** + * reads and updates the version and tables info in file $app/setup/setup.inc.php + * @param string $app the app + * @param string $new new version number to set, if $new != '' + * @param string $tables new tables to include (comma delimited), if != '' + * @return the version or False if the file could not be read or written + */ function setup_version($app,$new = '',$tables='') { //echo "

etemplate.db_tools.setup_version('$app','$new','$tables')

\n"; @@ -792,16 +789,14 @@ return $new; } - /*! - @function update - @syntax update( $app,$current,$version ) - @author ralfbecker - @abstract updates file /$app/setup/tables_update.inc.php to reflect changes in $current - @param $app app-name - @param $current new tabledefinitions - @param $version new version - @return True if file writen else False - */ + /** + * updates file /$app/setup/tables_update.inc.php to reflect changes in $current + * + * @param string $app app-name + * @param array $current new tabledefinitions + * @param string $version new version + * @return boolean True if file writen else False + */ function update($app,$current,$version) { //echo "

etemplate.db_tools.update('$app',...,'$version')

\n"; @@ -864,6 +859,12 @@ return True; } + /** + * unsets all keys in an array which have a given value + * + * @param array &$arr + * @param mixed $val value to check against + */ function remove_from_array(&$arr,$value) { foreach($arr as $key => $val) @@ -875,6 +876,14 @@ } } + /** + * creates an update-script + * + * @param string $app app-name + * @param array $current new table-defintion + * @param string &$tables returns comma delimited list of new table-names + * @return string the update-script + */ function update_schema($app,$current,&$tables) { $this->read($app,$old); @@ -968,15 +977,13 @@ return $update; } - /*! - @function normalize_index - @abstract orders the single-colum-indices after the columns and the multicolunm ones bedind - @syntax normalize_index( $index,$cols ) - @param index array with indices - @param cols array with column-defs (col-name in key) - @author ralfbecker - @result the new array - */ + /** + * orders the single-colum-indices after the columns and the multicolunm ones behind + * + * @param array $index array with indices + * @param array $cols array with column-defs (col-name is the key) + * @return array the new array of indices + */ function normalize_index($index,$cols) { $normalized = array(); @@ -999,13 +1006,14 @@ return $normalized; } - /*! - @function normalize - @syntax normalize( $table ) - @author ralfbecker - @abstract sets all nullable properties to True or False - @result the new array - */ + /** + * normalices all properties in a table-definiton, eg. all nullable properties to True or False + * + * this is necessary to compare two table-defitions + * + * @param array $table table-definition + * @return array the normaliced defintion + */ function normalize($table) { $all_props = array('type','precision','nullable','default'); @@ -1029,13 +1037,14 @@ ); } - /*! - @function tables_identical - @syntax tables_identical( $old,$new ) - @author ralfbecker - @abstract compares two table-definitions - @result True if they are identical or False else - */ + /** + * compares two table-definitions, by comparing normaliced string-representations (serialize) + * + * @param array $a + * @param array $b + * @return boolean true if they are identical (would create an identical schema), false otherwise + * + */ function tables_identical($a,$b) { $a = serialize($this->normalize($a)); @@ -1047,6 +1056,3 @@ return $a == $b; } } - - - diff --git a/etemplate/inc/class.editor.inc.php b/etemplate/inc/class.editor.inc.php index 1dbab0bdbe..b8f80c6c7b 100644 --- a/etemplate/inc/class.editor.inc.php +++ b/etemplate/inc/class.editor.inc.php @@ -12,6 +12,13 @@ /* $Id$ */ + /** + * template editor of the eTemplate package + * + * @package etemplate + * @author RalfBecker-AT-outdoor-training.de + * @license GPL + */ class editor { var $debug; @@ -94,9 +101,7 @@ 'xml_label' => $xml_label, 'xml' => $xml ? '
'.$this->etemplate->html->htmlspecialchars($xml)."
\n" : '', ); - $options = explode(',',$this->etemplate->size); - reset($this->options); - while (list($n,$opt) = each($this->options)) + foreach(explode(',',$this->etemplate->size) as $n => $opt) { $content['options'][$opt] = $options[$n]; } @@ -783,6 +788,8 @@ } else { + // set onclick handler + $this->etemplate->onclick_handler = "alert('%p');"; $show->data[$show->rows]['A']['obj'] = &$this->etemplate; $vals = $post_vars['vals']; $olds = $post_vars['olds']; @@ -800,14 +807,13 @@ ),''); } - /*! - @function scan_for_extensions - @syntax scan_for_extensions( $app ) - @author ralfbecker - @abstract search the inc-dirs of etemplate and the app whichs template is edited for extensions / custom widgets - @discussion extensions are class-files in $app/inc/class.${name}_widget.inc.php - @result array with name => human_name of the extensions found - */ + /** + * search the inc-dirs of etemplate and the app whichs template is edited for extensions / custom widgets + * + * extensions are class-files in $app/inc/class.${name}_widget.inc.php + * + * @return array with name => human_name of the extensions found + */ function scan_for_extensions($app='etemplate') { $extensions = array(); diff --git a/etemplate/inc/class.so_sql.inc.php b/etemplate/inc/class.so_sql.inc.php index 9b394d7d3a..f3ac592851 100644 --- a/etemplate/inc/class.so_sql.inc.php +++ b/etemplate/inc/class.so_sql.inc.php @@ -12,25 +12,49 @@ /* $Id$ */ -/*! -@class so_sql -@author ralfbecker -@abstract generalized SQL Storage Object -@discussion the class can be used in following ways: -@discussion 1) by calling the constructor with an app and table-name or -@discussion 2) by setting the following class-vars in a class derifed from this one -@discussion Of cause can you derife the class and call the constructor with params. -@param $table_name need to be set in the derived class to the db-table-name -@param $autoinc_id db-col-name of autoincrement id or '' -@param $db_key_cols array of all primary-key-columns in form dbName => internalName -@discussion the save function does NOT touch any other cols in the table!!! -@param $db_data_cols array of all data-cols -@param $debug turns on debug-messages -@param $empty_on_write string to be written to db if a col-value is '', eg. "''" or 'NULL' (default) -@param $non_db_cols all cols in data which are not (direct)in the db, for data_merge -*/ +/** + * generalized SQL Storage Object + * + * the class can be used in following ways: + * 1) by calling the constructor with an app and table-name or + * 2) by setting the following documented class-vars in a class derifed from this one + * Of cause can you derife the class and call the constructor with params. + * + * @package etemplate + * @author RalfBecker-AT-outdoor-training.de + * @license GPL + */ class so_sql { + /** + * @var string $table_name need to be set in the derived class to the db-table-name + */ + var $table_name; + /** + * @var string $autoinc_id db-col-name of autoincrement id or '' + */ + var $autoinc_id = ''; + /** + * @var array $db_key_cols array of all primary-key-columns in form dbName => internalName + * the save function does NOT touch any other cols in the table!!! + */ + var $db_key_cols = array(); + /** + * @var array $db_data_cols array of all data-cols + */ + var $db_data_cols = array(); + /** + * @var array $non_db_cols all cols in data which are not (direct)in the db, for data_merge + */ + var $non_db_cols = array(); + /** + * @var int $debug turns on debug-messages + */ + var $debug = 0; + /** + * @var string $empty_on_write string to be written to db if a col-value is '', eg. "''" or 'NULL' (default) + */ + var $empty_on_write = 'NULL'; var $public_functions = array( 'init' => True, 'data_merge' => True, @@ -39,24 +63,19 @@ class so_sql 'delete' => True, 'search' => True, ); - var $db,$table_name; - var $autoinc_id = ''; - var $db_key_cols = array(),$db_data_cols = array(); // key_cols mean primary keys + var $db; var $db_uni_cols = array(); var $db_cols; // = $db_key_cols + $db_data_cols - var $non_db_cols = array(); var $data; // holds the content of all db_cols - var $debug = 0; - var $empty_on_write = 'NULL'; - /*! - @function so_sql - @syntax so_sql( $app='',$table='' ) - @author ralfbecker - @abstract constructor of the class - @discussion NEED to be called from the constructor of the derived class - @param $app, $table should be set if table-defs to be read from /setup/tables_current.inc.php - */ + /** + * constructor of the class + * + * NEED to be called from the constructor of the derived class !!! + * + * @param string $app should be set if table-defs to be read from /setup/tables_current.inc.php + * @param string $table should be set if table-defs to be read from /setup/tables_current.inc.php + */ function so_sql($app='',$table='') { $this->db = $GLOBALS['phpgw']->db; @@ -75,14 +94,12 @@ class so_sql } } - /*! - @function setup_table - @syntax setup_table( $app,$table ) - @author ralfbecker - @abstract reads table-definition from /setup/tables_current.inc.php - @discussion Does NOT set a different internal-data-name. If you want this, you have to do so - @discussion in a derifed class !!! - */ + /** + * reads table-definition from /setup/tables_current.inc.php + * + * Does NOT set a different internal-data-name. If you want this, you have to do so + * in a derifed class !!! + */ function setup_table($app,$table) { include(PHPGW_SERVER_ROOT . "/$app/setup/tables_current.inc.php"); @@ -120,13 +137,11 @@ class so_sql } } - /*! - @function so_data_merge - @syntax so_data_merge( $new ) - @author ralfbecker - @abstract merges in new values from the given new data-array - @param $new array in form col => new_value with values to set - */ + /** + * merges in new values from the given new data-array + * + * @param $new array in form col => new_value with values to set + */ function data_merge($new) { if (!is_array($new) || !count($new)) @@ -149,56 +164,49 @@ class so_sql } } - /*! - @function db2data - @abstract changes the data from the db-format to your work-format - @discussion it gets called everytime when data is read from the db - @discussion This function needs to be reimplemented in the derived class - @param $data if given works on that array and returns result, else works on internal data-array - */ - function db2data($data=0) + /** + * changes the data from the db-format to your work-format + * + * it gets called everytime when data is read from the db + * This function needs to be reimplemented in the derived class + * + * @param array $data if given works on that array and returns result, else works on internal data-array + */ + function db2data($data=null) { - if ($intern = !is_array($data)) + if (!is_array($data)) { - $data = $this->data; + $data = &$this->data; } // do the necessare changes here - if ($intern) - { - $this->data = $data; - } return $data; } - /*! - @function data2db - @abstract changes the data from your work-format to the db-format - @discussion It gets called everytime when data gets writen into db or on keys for db-searches - @discussion this needs to be reimplemented in the derived class - @param $data if given works on that array and returns result, else works on internal data-array - */ - function data2db($data=0) + /** + * changes the data from your work-format to the db-format + * + * It gets called everytime when data gets writen into db or on keys for db-searches + * this needs to be reimplemented in the derived class + * + * @param array $data if given works on that array and returns result, else works on internal data-array + */ + function data2db($data=null) { if ($intern = !is_array($data)) { - $data = $this->data; + $data = &$this->data; } // do the necessary changes here - if ($intern) - { - $this->data = $data; - } return $data; } - /*! - @function init - @abstract initializes data with the content of key - @param $keys array with keys in form internalName => value - @result void - */ + /** + * initializes data with the content of key + * + * @param array $keys array with keys in form internalName => value + */ function init($keys=array()) { $this->data = array(); @@ -208,11 +216,11 @@ class so_sql $this->data_merge($keys); } - /*! - @function read - @abstract reads row matched by key and puts all cols in the data array - @param $keys array with keys in form internalName => value, may be a scalar value if only one key - @result data array if row could be retrived else False and data = array() + /** + * reads row matched by key and puts all cols in the data array + * + * @param array $keys array with keys in form internalName => value, may be a scalar value if only one key + * @return array/boolean data if row could be retrived else False */ function read($keys) { @@ -279,15 +287,15 @@ class so_sql return $this->data; } - /*! - @function save - @abstracts saves the content of data to the db - @param $keys if given $keys are copied to data before saveing => allows a save as - @result 0 on success and errno != 0 else - */ - function save($keys='') + /** + * saves the content of data to the db + * + * @param array $keys if given $keys are copied to data before saveing => allows a save as + * @return int 0 on success and errno != 0 else + */ + function save($keys=null) { - $this->data_merge($keys); + if (is_array($keys) && count($keys)) $this->data_merge($keys); if (!$this->autoinc_id) // no autoincrement id, so we need to find out with read if key already in db { @@ -342,13 +350,13 @@ class so_sql return $this->db->errno; } - /*! - @function delete - @abstract deletes row representing keys in internal data or the supplied $keys if != '' - @param $keys if not '', array with col => value pairs to characterise the rows to delete - @result affected rows, should be 1 if ok, 0 if an error + /** + * deletes row representing keys in internal data or the supplied $keys if != null + * + * @param array $keys if given array with col => value pairs to characterise the rows to delete + * @return affected rows, should be 1 if ok, 0 if an error */ - function delete($keys='') + function delete($keys=null) { if (!is_array($keys) || !count($keys)) // use internal data { @@ -381,19 +389,20 @@ class so_sql return $this->db->affected_rows(); } - /*! - @function search - @abstract searches db for rows matching searchcriteria - @discussion '*' and '?' are replaced with sql-wildcards '%' and '_' - @param $criteria array of key and data cols, OR a SQL query (content for WHERE), fully quoted (!) - @param $only_keys True returns only keys, False returns all cols - @param $order_by fieldnames + {ASC|DESC} separated by colons ',' - @param $extra_cols string to be added to the SELECT, eg. (count(*) as num) - @param $wildcard string appended befor and after each criteria - @param $empty False=empty criteria are ignored in query, True=empty have to be empty in row - @param $op defaults to 'AND', can be set to 'OR' too, then criteria's are OR'ed together - @result array of matching rows (the row is an array of the cols) or False - */ + /** + * searches db for rows matching searchcriteria + * + * '*' and '?' are replaced with sql-wildcards '%' and '_' + * + * @param array/string $criteria array of key and data cols, OR a SQL query (content for WHERE), fully quoted (!) + * @param boolean $only_keys True returns only keys, False returns all cols + * @param string $order_by fieldnames + {ASC|DESC} separated by colons ',' + * @param string $extra_cols string to be added to the SELECT, eg. (count(*) as num) + * @param string $wildcard appended befor and after each criteria + * @param boolean $empty False=empty criteria are ignored in query, True=empty have to be empty in row + * @param string $op defaults to 'AND', can be set to 'OR' too, then criteria's are OR'ed together + * @return array of matching rows (the row is an array of the cols) or False + */ function search($criteria,$only_keys=True,$order_by='',$extra_cols='',$wildcard='',$empty=False,$op='AND') { if (!is_array($criteria)) @@ -444,15 +453,13 @@ class so_sql return $n ? $arr : False; } - /*! - @function not_unique - @syntax not_unique( $data='' ) - @author ralfbecker - @abstract Check if values for unique keys are unique - @param $data data-set to check, defaults to $this->data - @result 0: all keys are unique, 1: first key not unique, 2: ... - */ - function not_unique($data='') + /** + * Check if values for unique keys are unique + * + * @param array $data data-set to check, defaults to $this->data + * @return int 0: all keys are unique, 1: first key not unique, 2: ... + */ + function not_unique($data=null) { if (!is_array($data)) { @@ -479,4 +486,4 @@ class so_sql } return 0; } -}; +} diff --git a/etemplate/inc/class.uietemplate.inc.php b/etemplate/inc/class.uietemplate.inc.php index 354f943ddd..915b4197bd 100644 --- a/etemplate/inc/class.uietemplate.inc.php +++ b/etemplate/inc/class.uietemplate.inc.php @@ -45,8 +45,8 @@ /** * constructor of etemplate class, reads an eTemplate if $name is given * - * @param $name name of etemplate or array with name and other keys - * @param $load_via name/array with keys of other etemplate to load in order to get $name + * @param string $name of etemplate or array with name and other keys + * @param string/array $load_via with keys of other etemplate to load in order to get $name */ function etemplate($name='',$load_via='') { @@ -84,17 +84,17 @@ * form as submit-url to call process_show for the template before it * ExecuteMethod's the given $method of the caller. * - * @param $method Methode (e.g. 'etemplate.editor.edit') to be called if form is submitted - * @param $content array with content to fill the input-fields of template, eg. the text-field - * @param with name 'name' gets its content from $content['name'] + * @param string $method Methode (e.g. 'etemplate.editor.edit') to be called if form is submitted + * @param array $content with content to fill the input-fields of template, eg. the text-field + * with name 'name' gets its content from $content['name'] * @param $sel_options array or arrays with the options for each select-field, keys are the - * @param field-names, eg. array('name' => array(1 => 'one',2 => 'two')) set the - * @param options for field 'name'. ($content['options-name'] is possible too !!!) - * @param $readonlys array with field-names as keys for fields with should be readonly - * @param (eg. to implement ACL grants on field-level or to remove buttons not applicable) - * @param $preserv array with vars which should be transported to the $method-call (eg. an id) array('id' => $id) sets $_POST['id'] for the $method-call - * @param $output_mode int 0 = echo incl. navbar, 1 = return html, 2 = echo without navbar (eg. for popups) - * @param $changes array change made in the last call if looping, only used internaly by process_exec + * field-names, eg. array('name' => array(1 => 'one',2 => 'two')) set the + * options for field 'name'. ($content['options-name'] is possible too !!!) + * @param array $readonlys with field-names as keys for fields with should be readonly + * (eg. to implement ACL grants on field-level or to remove buttons not applicable) + * @param array $preserv with vars which should be transported to the $method-call (eg. an id) array('id' => $id) sets $_POST['id'] for the $method-call + * @param int $output_mode 0 = echo incl. navbar, 1 = return html, 2 = echo without navbar (eg. for popups) + * @param array $changes change made in the last call if looping, only used internaly by process_exec * @return string html for $output_mode == 1, else nothing */ function exec($method,$content,$sel_options='',$readonlys='',$preserv='',$output_mode=0,$changes='') @@ -294,14 +294,14 @@ * as it deals with HTML and is so UI-dependent, use exec instead. * * @internal - * @param $content array with content for the cells, keys are the names given in the cells/form elements - * @param $sel_options array with options for the selectboxes, keys are the name of the selectbox - * @param $readonlys array with names of cells/form-elements to be not allowed to change - * @param This is to facilitate complex ACL's which denies access on field-level !!! - * @param $cname string basename of names for form-elements, means index in $_POST - * eg. $cname='cont', element-name = 'name' returned content in $_POST['cont']['name'] - * @param $show_c string name/index for name expansion - * @param $show_row string name/index for name expansion + * @param array $content with content for the cells, keys are the names given in the cells/form elements + * @param array $sel_options with options for the selectboxes, keys are the name of the selectbox + * @param array $readonlys with names of cells/form-elements to be not allowed to change + * This is to facilitate complex ACL's which denies access on field-level !!! + * @param string $cname basename of names for form-elements, means index in $_POST + * eg. $cname='cont', element-name = 'name' returned content in $_POST['cont']['name'] + * @param string $show_c name/index for name expansion + * @param string $show_row name/index for name expansion * @return string the generated HTML */ function show($content,$sel_options='',$readonlys='',$cname='',$show_c=0,$show_row=0/*TEST-RB,$no_table_tr=False,$tr_class=''*/) @@ -345,15 +345,15 @@ * as it deals with HTML and is so UI-dependent, use exec instead. * * @internal - * @param $grid array representing a grid - * @param $content array with content for the cells, keys are the names given in the cells/form elements - * @param $sel_options array with options for the selectboxes, keys are the name of the selectbox - * @param $readonlys array with names of cells/form-elements to be not allowed to change - * @param This is to facilitate complex ACL's which denies access on field-level !!! - * @param $cname string basename of names for form-elements, means index in $_POST - * eg. $cname='cont', element-name = 'name' returned content in $_POST['cont']['name'] - * @param $show_c string name/index for name expansion - * @param $show_row string name/index for name expansion + * @param array $grid representing a grid + * @param array $content with content for the cells, keys are the names given in the cells/form elements + * @param array $sel_options with options for the selectboxes, keys are the name of the selectbox + * @param array $readonlys with names of cells/form-elements to be not allowed to change + * This is to facilitate complex ACL's which denies access on field-level !!! + * @param string $cname basename of names for form-elements, means index in $_POST + * eg. $cname='cont', element-name = 'name' returned content in $_POST['cont']['name'] + * @param string $show_c name/index for name expansion + * @param string $show_row name/index for name expansion * @return string the generated HTML */ function show_grid(&$grid,$content,$sel_options='',$readonlys='',$cname='',$show_c=0,$show_row=0/*TEST-RB,$no_table_tr=False,$tr_class=''*/) @@ -522,9 +522,18 @@ * calls show to generate included eTemplates. Again only an INTERMAL function. * * @internal - * @param $cell array with data of the cell: name, type, ... - * @param for rest see show - * @return the generated HTML + * @param array $cell with data of the cell: name, type, ... + * @param array $content with content for the cells, keys are the names given in the cells/form elements + * @param array $sel_options with options for the selectboxes, keys are the name of the selectbox + * @param array $readonlys with names of cells/form-elements to be not allowed to change + * This is to facilitate complex ACL's which denies access on field-level !!! + * @param string $cname basename of names for form-elements, means index in $_POST + * eg. $cname='cont', element-name = 'name' returned content in $_POST['cont']['name'] + * @param string $show_c name/index for name expansion + * @param string $show_row name/index for name expansion + * @param string &$span on return number of cells to span or 'all' for the rest (only used for grids) + * @param string &$class on return the css class of the cell, to be set in the tag + * @return string the generated HTML */ function show_cell($cell,$content,$sel_options,$readonlys,$cname,$show_c,$show_row,&$span,&$class) { @@ -1331,7 +1340,8 @@ /** * returns the javascript to be included by exec * - * @param $what &1 = returns the test, note: has to be included in the body, not the header, &2 = returns the common functions, best to be included in the header + * @param int $what &1 = returns the test, note: has to be included in the body, not the header, + * &2 = returns the common functions, best to be included in the header * @return string javascript */ function include_java_script($what = 3) diff --git a/etemplate/inc/class.xul_io.inc.php b/etemplate/inc/class.xul_io.inc.php index 6893084753..4c94c72dc4 100644 --- a/etemplate/inc/class.xul_io.inc.php +++ b/etemplate/inc/class.xul_io.inc.php @@ -41,7 +41,10 @@ function xul_io() { - $this->attr2xul = array( // how to translate attr, common to all widgets + /** + * @var array $attr2xul how to translate attr, common to all widgets + */ + $this->attr2xul = array( 'name' => 'id', 'help' => 'statustext', 'span' => 'span,class', @@ -50,7 +53,10 @@ 'readonly' => 'readonly=true', 'size' => 'options' ); - $this->widget2xul = array( // how to translate widget-names and widget-spec. attr. + /** + * @var array $widget2xul how to widget-names and widget-spec. attr., not set ones are identical + */ + $this->widget2xul = array( 'label' => array( '.name' => 'description', 'label' => 'value' @@ -100,6 +106,9 @@ 'size' => 'style,plugins', ), ); + /** + * @var array $xul2widget how to xul-widget names to our internal ones, not set ones are identical + */ $this->xul2widget = array( 'menulist' => 'select', 'listbox' => 'select', @@ -107,6 +116,13 @@ ); } + /** + * sets an attribute in the xml object representing a widget + * + * @param object &$widget widget to set the attribute in + * @param string $attr comma delimited attr = default-value pairs, eg. "type=int,min=0" + * @param array $val array with values to set + */ function set_attributes(&$widget,$attr,$val) { if ($attr != '') @@ -128,6 +144,14 @@ } } + /** + * add a widget to a parent + * + * @param object &$parent parten to add the widget + * @param array $cell widget to add + * @param array &$embeded_too already embeded eTemplates + * @return object reference (!) the the xml object representing the widget, so other children can be added + */ function &add_widget(&$parent,$cell,&$embeded_too) { $type = $cell['type']; @@ -276,6 +300,13 @@ $parent->add_node($widget); } + /** + * add a grid to $parent (xml object) + * + * @param object &$parent where to add the grid + * @param array $grid grid to add + * @param array &embeded_too array with already embeded eTemplates + */ function add_grid(&$parent,$grid,&$embeded_too) { $xul_grid = new xmlnode('grid'); @@ -317,6 +348,12 @@ $parent->add_node($xul_grid); } + /** + * add / embed an eTemplate into the global $xul_overlay object (used by export) + * + * @param object &$etempl eTemplate to embed + * @param array &embeded_too array with already embeded templates + */ function add_etempl(&$etempl,&$embeded_too) { if (is_array($embeded_too)) @@ -352,6 +389,12 @@ $this->xul_overlay->add_node($template); } + /** + * create an XML representation of an eTemplate + * + * @param object $etempl eTemplate object to export + * @return string the XML + */ function export($etempl) { if ($this->debug) @@ -377,6 +420,13 @@ return $xml; } + /** + * create an eTemplate from it's XML representation + * + * @param object &$etempl eTemplate object to set + * @param string $data the XML + * @param array/string array with names of imported templates or error-message + */ function import(&$etempl,$data) { if ($this->debug)