holm/egroupware
1
1
Fork 0
forked from extern/egroupware
Code Issues Pull Requests Packages Projects Releases Wiki Activity

changed documentation to phpdoc standard

Browse Source
This commit is contained in:
Ralf Becker 2004-10-07 21:53:10 +00:00
parent b7d77a8588
commit cff0ca3801
3 changed files with 457 additions and 468 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

564
etemplate/inc/class.boetemplate.inc.php
View File

@ -1,6 +1,6 @@
<?php
/**************************************************************************\
* eGroupWare - EditableTemplates - Buiseness Objects *
* eGroupWare - EditableTemplates - Business Objects *
* http://www.eGroupWare.org *
* Written by Ralf Becker <RalfBecker@outdoor-training.de> *
* -------------------------------------------- *
@ -14,13 +14,15 @@
include_once(PHPGW_INCLUDE_ROOT . '/etemplate/inc/class.soetemplate.inc.php');
/*!
@class boetemplate
@author ralfbecker
@abstract Buiseness Objects for eTemplates
@discussion Not so much so far, as the most logic is still in the UI-class
@param $types,$alings converts internal names/values to (more) human readible ones
*/
/**
* Business Object for eTemplates, extending the Storage Object
*
* Not so much so far, as the most logic is still in the UI-class
*
* @package etemplate
* @author RalfBecker-AT-outdoor-training.de
* @license GPL
*/
class boetemplate extends soetemplate
{
var $extensions = array();
@ -47,27 +49,16 @@
'hbox' => 'HBox', // a (horizontal) box to contain widgets in cols, size = # of cols
'deck' => 'Deck' // a container of elements where only one is visible, size = # of elem.
);
/*!
@function boetemplate
@abstract constructor of class
@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
@discussion Calls the constructor of soetemplate
*/
/**
* constructor of class
*
* Calls the constructor of soetemplate
*
* @param $name string/array name of etemplate or array with name and other keys
* @param $load_via string/array name or array with keys of other etemplate to load in order to get $name
*/
function boetemplate($name='',$load_via='')
{
$this->public_functions += array(
'set_row_attribute' => True,
'disable_row' => True,
'set_column_attribute' => True,
'disable_column' => True,
'disable_cells' => True,
'set_cell_attribute' => True,
'get_cell_attribute' => True,
'get_array' => True,
'set_array' => True,
'unset_array' => True
);
$this->soetemplate();
$tname = &$name;
@ -84,32 +75,32 @@
}
}
/*!
@function expand_name
@syntax expand_name( $name,$c,$row,$c_='',$row_='',$cont='' )
@author ralfbecker
@abstract allows a few variables (eg. row-number) to be used in field-names
@discussion This is mainly used for autorepeat, but other use is possible.
@discussion You need to be aware of the rules PHP uses to expand vars in strings, a name
@discussion of "Row$row[length]" will expand to 'Row' as $row is scalar, you need to use
@discussion "Row${row}[length]" instead. Only one indirection is allowd in a string by php !!!
@discussion Out of that reason we have now the variable $row_cont, which is $cont[$row] too.
@discussion Attention !!!
@discussion Using only number as index in field-names causes a lot trouble, as depending
@discussion on the variable type (which php determines itself) you used filling and later
@discussion accessing the array it can by the index or the key of an array element.
@discussion To make it short and clear, use "Row$row" or "$col$row" not "$row" or "$row$col" !!!
@param $name the name to expand
@param $c is the column index starting with 0 (if you have row-headers, data-cells start at 1)
@param $row is the row number starting with 0 (if you have col-headers, data-cells start at 1)
@param $c_, $row_ are the respective values of the previous template-inclusion,
@param eg. the column-headers in the eTemplate-editor are templates itself,
@param to show the column-name in the header you can not use $col as it will
@param be constant as it is always the same col in the header-template,
@param what you want is the value of the previous template-inclusion.
@param $cont content array of the template, you might use it to generate button-names with
@param id values in it: "del[$cont[id]]" expands to "del[123]" if $cont = array('id' => 123)
*/
/**
* allows a few variables (eg. row-number) to be used in field-names
*
* This is mainly used for autorepeat, but other use is possible.
* You need to be aware of the rules PHP uses to expand vars in strings, a name
* of "Row$row[length]" will expand to 'Row' as $row is scalar, you need to use
* "Row${row}[length]" instead. Only one indirection is allowd in a string by php !!!
* Out of that reason we have now the variable $row_cont, which is $cont[$row] too.
* Attention !!!
* Using only number as index in field-names causes a lot trouble, as depending
* on the variable type (which php determines itself) you used filling and later
* accessing the array it can by the index or the key of an array element.
* To make it short and clear, use "Row$row" or "$col$row" not "$row" or "$row$col" !!!
*
* @param $name sring the name to expand
* @param $c int is the column index starting with 0 (if you have row-headers, data-cells start at 1)
* @param $row int is the row number starting with 0 (if you have col-headers, data-cells start at 1)
* @param $c_, $row_ int are the respective values of the previous template-inclusion,
* eg. the column-headers in the eTemplate-editor are templates itself,
* to show the column-name in the header you can not use $col as it will
* be constant as it is always the same col in the header-template,
* what you want is the value of the previous template-inclusion.
* @param $cont array content of the template, you might use it to generate button-names with id values in it:
* "del[$cont[id]]" expands to "del[123]" if $cont = array('id' => 123)
* @return string the expanded name
*/
function expand_name($name,$c,$row,$c_='',$row_='',$cont='')
{
$is_index_in_content = $name[0] == '@';
@ -133,29 +124,29 @@
return $name;
}
/*!
@function autorepeat_idx
@abstract Checks if we have an row- or column autorepeat and sets the indexes for $content, etc.
@discussion Autorepeat is important to allow a variable numer of rows or cols, eg. for a list.
@discussion The eTemplate has only one (have to be the last) row or column, which gets
@discussion automaticaly repeated as long as content is availible. To check this the content
@discussion has to be in an sub-array of content. The index / subscript into content is
@discussion determined by the content of size for templates or name for regular fields.
@discussion An autorepeat is defined by an index which contains variables to expand.
@discussion (vor variable expansion in names see expand_names). Usually I use the keys
@discussion $row: 0, 1, 2, 3, ... for only rows, $col: '@', 'A', 'B', 'C', ... for only cols or
@discussion $col$row: '@0','A0',... '@1','A1','B1',... '@2','A2','B2',... for both rows and cells.
@discussion In general everything expand_names can generate is ok - see there.
@discussion As you usually have col- and row-headers, data-cells start with '1' or 'A' !!!
@syntax autorepeat_idx($cell,$c,$r,&$idx,&$idx_cname,$check_col=False)
@param $cell array with data of cell: name, type, size, ...
@param $c,$r col/row index starting from 0
@param &$idx returns the index in $content and $readonlys (NOT $sel_options !!!)
@param &$idx_cname returns the basename for the form-name: is $idx if only one value
@param (no ',') is given in size (name (not template-fields) are always only one value)
@param $check_col boolean to check for col- or row-autorepeat
@result true if cell is autorepeat (has index with vars / '$') or false otherwise
*/
/**
* Checks if we have an row- or column autorepeat and sets the indexes for $content, etc.
*
* Autorepeat is important to allow a variable numer of rows or cols, eg. for a list.
* The eTemplate has only one (have to be the last) row or column, which gets
* automaticaly repeated as long as content is availible. To check this the content
* has to be in an sub-array of content. The index / subscript into content is
* determined by the content of size for templates or name for regular fields.
* An autorepeat is defined by an index which contains variables to expand.
* (vor variable expansion in names see expand_names). Usually I use the keys
* $row: 0, 1, 2, 3, ... for only rows, $col: '@', 'A', 'B', 'C', ... for only cols or
* $col$row: '@0','A0',... '@1','A1','B1',... '@2','A2','B2',... for both rows and cells.
* In general everything expand_names can generate is ok - see there.
* As you usually have col- and row-headers, data-cells start with '1' or 'A' !!!
*
* @param $cell array with data of cell: name, type, size, ...
* @param $c,$r int col/row index starting from 0
* @param &$idx string returns the index in $content and $readonlys (NOT $sel_options !!!)
* @param &$idx_cname string returns the basename for the form-name: is $idx if only one value
* @param (no ',') is given in size (name (not template-fields) are always only one value)
* @param $check_col boolean to check for col- or row-autorepeat
* @return boolean true if cell is autorepeat (has index with vars / '$') or false otherwise
*/
function autorepeat_idx($cell,$c,$r,&$idx,&$idx_cname,$check_col=False)
{
$org_idx = $idx = $cell[ $cell['type'] == 'template' ? 'size' : 'name' ];
@ -194,12 +185,9 @@
return $Ok;
}
/*!
@function appsession_id
@syntax appsession_id( )
@author ralfbecker
@abstract creates a new appsession-id via microtime()
*/
/**
* creates a new appsession-id via microtime()
*/
function appsession_id()
{
list($msec,$sec) = explode(' ',microtime());
@ -208,12 +196,12 @@
return $id;
}
/*!
@functin appsession
@syntax appsession($location = 'default', $appname = '', $data = '##NOTHING##')
@abstract db-sessions appsession function
@note It is used to overcome the problem with overflowing php4-sessions
*/
/**
* db-sessions appsession function, not longer used !!!
*
* It was used to overcome the problem with overflowing php4-sessions, which seems to not exist any more !!!
* @depricated
*/
function appsession($location = 'default', $appname = '', $data = '##NOTHING##')
{
// use the version from the sessions-class if we use db-sessions
@ -289,19 +277,18 @@
return $data;
}
/*!
@function save_appsession
@syntax save_appsession( $data,$id='' )
@author ralfbecker
@abstract saves content,readonlys,template-keys, ... via the appsession function
@discussion As a user may open several windows with the same content/template wie generate a location-id from microtime
@discussion which is used as location for appsession to descriminate between the different windows. This location-id
@discussion is then saved as a hidden-var in the form. The above mentions session-id has nothing to do / is different
@discussion from the session-id which is constant for all windows opened in one session.
@param $data the data to save
@param $id the id to use or '' to generate a new id
@result the location-id
*/
/**
* saves content,readonlys,template-keys, ... via the appsession function
*
* As a user may open several windows with the same content/template wie generate a location-id from microtime
* which is used as location for appsession to descriminate between the different windows. This location-id
* is then saved as a hidden-var in the form. The above mentions session-id has nothing to do / is different
* from the session-id which is constant for all windows opened in one session.
*
* @param $data array the data to save
* @param $id string the id to use or '' to generate a new id
* @return string location-id
*/
function save_appsession($data,$id='')
{
if (!$id)
@ -313,14 +300,12 @@
return $id;
}
/*!
@function get_appsession
@syntax get_appsession( $id )
@author ralfbecker
@abstract gets content,readonlys,template-keys, ... back from the appsession function
@param $id the location-id
@result the session-data
*/
/**
* gets content,readonlys,template-keys, ... back from the appsession function
*
* @param $id the location-id
* @return array with session-data
*/
function get_appsession($id)
{
$data = $GLOBALS['phpgw']->session->appsession($id,'etemplate');
@ -334,28 +319,26 @@
return $data;
}
/*!
@function get_cell_attribute
@syntax get_cell_attribute( $name,$attr )
@author ralfbecker
@abstract gets an attribute in a named cell
@result the attribute or False if named cell not found
*/
/**
* gets an attribute in a named cell
*
* @param $name string cell-name
* @param $attr string attribute-name
* @return mixed the attribute or False if named cell not found
*/
function get_cell_attribute($name,$attr)
{
return $this->set_cell_attribute($name,$attr,NULL);
}
/*!
@function set_cell_attribute
@syntax set_cell_attribute( $name,$attr,$val )
@author ralfbecker
@abstract set an attribute in a named cell if val is not NULL else return the attribute
@param $name sting name of the cell
@param $attr attribute-name
@param $val if not NULL sets attribute else returns it
@result the number of changed cells or False, if none changed
*/
/**
* set an attribute in a named cell if val is not NULL else return the attribute
*
* @param $name sting cell-name
* @param $attr attribute-name
* @param $val mixed if not NULL sets attribute else returns it
* @return mixed number of changed cells or False, if none changed
*/
function set_cell_attribute($name,$attr,$val)
{
//echo "<p>set_cell_attribute(tpl->name=$this->name, name='$name', attr='$attr',val='$val')</p>\n";
@ -415,29 +398,26 @@
return $n;
}
/*!
@function disable_cells
@syntax disable_cells( $name )
@author ralfbecker
@abstract disables all cells with name == $name
*/
/**
* disables all cells with name == $name
*
* @param $name sting cell-name
* @return mixed number of changed cells or False, if none changed
*/
function disable_cells($name)
{
return $this->set_cell_attribute($name,'disabled',True);
}
/*!
@function set_row_attributes
@syntax set_row_attibutes( $n,$height=0,$class=0,$valign=0,$disabled=0 )
@author ralfbecker
@abstract set one or more attibutes for row $n
@param $n is numerical row-number starting with 1 (!)
@param $height in percent or pixel or '' for no height
@param $class name of css class (without the leading '.') or '' for no class
@param $valign alignment (top,middle,bottom) or '' for none
@param $disabled True or expression or False to disable or enable the row
@param Only the number 0 means dont change the attribute !!!
*/
/**
* set one or more attibutes for row $n
*
* @param $n int numerical row-number starting with 1 (!)
* @param $height string percent or pixel or '' for no height
* @param $class string name of css class (without the leading '.') or '' for no class
* @param $valign string alignment (top,middle,bottom) or '' for none
* @param $disabled boolean True or expression or False to disable or enable the row (Only the number 0 means dont change the attribute !!!)
*/
function set_row_attributes($n,$height=0,$class=0,$valign=0,$disabled=0)
{
list($old_height,$old_disabled) = explode(',',$this->data[0]["h$n"]);
@ -450,29 +430,24 @@
($valign ? ','.$valign : '');
}
/*!
@function disable_row
@syntax disable_row( $n,$enable=False )
@author ralfbecker
@abstract disables row $n
@param $n is numerical row-number starting with 1 (!)
@param $enable can be used to re-enable a row if set to True
*/
/**
* disables row $n
*
* @param $n int numerical row-number starting with 1 (!)
* @param $enable boolean can be used to re-enable a row if set to True
*/
function disable_row($n,$enable=False)
{
$this->set_row_attributes($n,0,0,0,!$enable);
}
/*!
@function set_column_attributes
@syntax set_column_attibutes( $n,$width=0,$disabled=0 )
@author ralfbecker
@abstract set one or more attibutes for column $c
@param $c is numerical column-number starting with 0 (!), or the char-code starting with 'A'
@param $width in percent or pixel or '' for no height
@param $disabled True or expression or False to disable or enable the column
@param Only the number 0 means dont change the attribute !!!
*/
/**
* set one or more attibutes for column $c
*
* @param $c int/string numerical column-number starting with 0 (!), or the char-code starting with 'A'
* @param $width string percent or pixel or '' for no height
* @param $disabled boolean True or expression or False to disable or enable the column (Only the number 0 means dont change the attribute !!!)
*/
function set_column_attributes($c,$width=0,$disabled=0)
{
if (is_numeric($c))
@ -485,27 +460,23 @@
($disabled ? ','.$disabled : '');
}
/*!
@function disable_column
@syntax disable_column( $c,$enable=False )
@author ralfbecker
@abstract disables column $c
@param $c is numerical column-number starting with 0 (!), or the char-code starting with 'A'
@param $enable can be used to re-enable a column if set to True
/**
* disables column $c
* @param $c int/string numerical column-number starting with 0 (!), or the char-code starting with 'A'
* @param $enable can be used to re-enable a column if set to True
*/
function disable_column($c,$enable=False)
{
$this->set_column_attributes($c,0,!$enable);
}
/*!
@function loadExtension
@syntax loadExtension( $type )
@author ralfbecker
@abstact trys to load the Extension / Widget-class from the app or etemplate
@param $name name of the extension, the classname should be class.${name}_widget.inc.php
@discussion the $name might be "$name.$app" to give a app-name (default is the current app,or template-name)
*/
/**
* trys to load the Extension / Widget-class from the app or etemplate
*
* @param $name string name of the extension, the classname should be class.${name}_widget.inc.php
* the $name might be "$name.$app" to give a app-name (default is the current app,or template-name)
* @return string/boolean human readable name or false if not found/loadable
*/
function loadExtension($type)
{
list($class,$app) = explode('.',$type);
@ -534,11 +505,10 @@
function haveExtension($type,$function='')
/*
@function haveExtension
@syntax haveExtension($type)
@author ralfbecker
@abstract checks if extension is loaded and load it if it isnt
*/
* checks if extension is loaded and load it if it isnt
*
* @return boolean
*/
{
return ($GLOBALS['phpgw_info']['etemplate']['extension'][$type] || $this->loadExtension($type,$ui)) &&
($function == '' || $GLOBALS['phpgw_info']['etemplate']['extension'][$type]->public_functions[$function]);
@ -546,16 +516,15 @@
function extensionPreProcess($type,$name,&$value,&$cell,&$readonlys)
/*
@function extensionPreProcess
@syntax extensionPreProcess(&$cell,&$value,&$readonlys)
@param $type of the extension
@param $name form-name of this widget/field (used as a unique index into extension_data)
@param &$cell table-cell on which the extension operates
@param &$value value of the extensions content(-array)
@param &$readonlys value of the extensions readonly-setting(-array)
@abstract executes the pre_process-function of the extension $cell[]type]
@author ralfbecker
*/
* executes the pre_process-function of the extension $cell[]type]
*
* @param $type string type of the extension
* @param $name string form-name of this widget/field (used as a unique index into extension_data)
* @param &$cell array table-cell on which the extension operates
* @param &$value mixed value of the extensions content(-array)
* @param &$readonlys array value of the extensions readonly-setting(-array)
* @return mixed the return-value of the extensions preprocess function
*/
{
if (!$this->haveExtension($type))
{
@ -567,15 +536,13 @@
function extensionPostProcess($type,$name,&$value,$value_in)
/*
@function extensionPostProcess
@syntax extensionPostProcess(&$cell,&$value)
@param $type of the extension
@param $name form-name of this widget/field (used as a unique index into extension_data)
@param &$value value of the extensions content(-array)
@abstract executes the post_process-function of the extension $cell[type]
@returns True if a value should be returned (default for no postprocess fkt.), else False
@author ralfbecker
*/
* executes the post_process-function of the extension $cell[type]
*
* @param $type string name of the extension
* @param $name string form-name of this widget/field (used as a unique index into extension_data)
* @param &$value mixed value of the extensions content(-array)
* @return boolean True if a value should be returned (default for no postprocess fkt.), else False
*/
{
if (!$this->haveExtension($type,'post_process'))
{
@ -588,11 +555,9 @@
function extensionRender($type,$name,&$value,&$cell,$readonly)
/*
@function extensionRender
@syntax extensionRender(&$cell,$form_name,&$value,$readonly)
@abstract executes the render-function of the extension $cell[type]
@author ralfbecker
*/
* executes the render-function of the extension $cell[type]
* @return mixed return-value of the render function
*/
{
if (!$this->haveExtension($type,'render'))
{
@ -602,13 +567,13 @@
$GLOBALS['phpgw_info']['etemplate']['extension_data'][$name],$this);
}
/*!
@function isset_array
@syntax isset_array( $arr,$idx )
@author ralfbecker
@abstract checks if idx, which may contain multiple subindex (eg.'x[y][z]'), is set in array
@author ralfbecker
*/
/**
* checks if $idx is set in array $arr
*
* @param $arr array
* @param $idx string may contain multiple subindex (eg.'x[y][z]')
* @return boolean
*/
function isset_array($arr,$idx)
{
$idxs = explode('[',str_replace(']','',$idx));
@ -625,21 +590,20 @@
return isset($pos[$last_idx]);
}
/*!
@function set_array
@abstract sets $arr[$idx] = $val
@author ralfbecker
@syntax set_array( &$arr,$idx,$val )
@param $arr array the array to search, referenz as a referenz gets returned
@param $idx string the index, may contain sub-indices like a[b], see example below
@discussion This works for non-trival indexes like 'a[b][c]' too: $arr['a']['b']['c'] = $val;
@author ralfbecker
*/
/**
* sets $arr[$idx] = $val
*
* This works for non-trival indexes like 'a[b][c]' too: $arr['a']['b']['c'] = $val;
*
* @param &$arr array the array to search
* @param $idx string the index, may contain sub-indices like a[b], see example below
* @param $val mixed
*/
function set_array(&$arr,$idx,$val)
{
if (!is_array($arr))
{
die('set_array() $arr is no array');
die('set_array() $arr is no array<br>'.function_backtrace());
}
$idxs = explode('[',str_replace(']','',$idx));
$pos = &$arr;
@ -650,22 +614,22 @@
$pos = $val;
}
/*!
@function get_array
@abstract return a var-param to $arr[$idx]
@author ralfbecker
@syntax get_array( &$arr,$idx,$referenz_into=False )
@param $arr array the array to search, referenz as a referenz gets returned
@param $idx string the index, may contain sub-indices like a[b], see example below
@param $referenz_into boolean default False, if True none-existing sub-arrays/-indices get created to be returned as referenz, else False is returned
@example $sub = get_array($arr,'a[b]'); $sub = 'c'; is equivalent to $arr['a']['b'] = 'c';
@discussion This works for non-trival indexes like 'a[b][c]' too: it returns &$arr[a][b][c]
*/
function &get_array(&$arr,$idx,$referenz_into=False)
/**
* return a reference to $arr[$idx]
*
* This works for non-trival indexes like 'a[b][c]' too: it returns &$arr[a][b][c]
* $sub = get_array($arr,'a[b]'); $sub = 'c'; is equivalent to $arr['a']['b'] = 'c';
*
* @param $arr array the array to search, referenz as a referenz gets returned
* @param $idx string the index, may contain sub-indices like a[b], see example below
* @param $reference_into boolean default False, if True none-existing sub-arrays/-indices get created to be returned as referenz, else False is returned
* @return mixed reference to $arr[$idx] or false if $idx is not set and not $reference_into
*/
function &get_array(&$arr,$idx,$reference_into=False)
{
if (!is_array($arr))
{
die('set_array() $arr is no array');
die('set_array() $arr is no array<br>'.function_backtrace());
}
$idxs = explode('[',str_replace(']','',$idx));
$pos = &$arr;
@ -680,21 +644,20 @@
return $pos;
}
/*!
@function unset_array
@abstract unsets $arr[$idx]
@author ralfbecker
@syntax unset_array( &$arr,$idx )
@param $arr array the array to search, referenz as a referenz gets returned
@param $idx string the index, may contain sub-indices like a[b], see example below
@example unset_array($arr,'a[b]'); is equivalent to unset($arr['a']['b']);
@discussion This works for non-trival indexes like 'a[b][c]' too
*/
/**
* unsets $arr[$idx]
*
* This works for non-trival indexes like 'a[b][c]' too
* unset_array($arr,'a[b]'); is equivalent to unset($arr['a']['b']);
*
* @param $arr array the array to search, referenz as a referenz gets returned
* @param $idx string the index, may contain sub-indices like a[b], see example below
*/
function unset_array(&$arr,$idx)
{
if (!is_array($arr))
{
die('set_array() $arr is no array');
die('set_array() $arr is no array<br>'.function_backtrace());
}
$idxs = explode('[',str_replace(']','',$idx));
$last_idx = array_pop($idxs);
@ -706,31 +669,42 @@
unset($pos[$last_idx]);
}
/*!
@function complete_array_merge
@syntax complete_array_merge( $old,$new )
@author ralfbecker
@abstract merges $old and $new, content of $new has precedence over $old
@discussion THIS IS NOT THE SAME AS PHP4: array_merge (as it calls itself recursive for values which are arrays.
*/
/**
* merges $old and $new, content of $new has precedence over $old
*
* THIS IS NOT THE SAME AS PHP4's functions:
* - array_merge, as it calls itself recursive for values which are arrays.
* - array_merge_recursive accumulates values with the same index and $new does NOT overwrite $old
*
* @param $old array
* @param $new array
* @return array the merged array
*/
function complete_array_merge($old,$new)
{
@reset($new);
while (list($k,$v) = @each($new))
if (is_array($new))
{
if (!is_array($v) || !isset($old[$k]))
foreach($new as $k => $v)
{
$old[$k] = $v;
}
else
{
$old[$k] = $this->complete_array_merge($old[$k],$v);
if (!is_array($v) || !isset($old[$k]))
{
$old[$k] = $v;
}
else
{
$old[$k] = $this->complete_array_merge($old[$k],$v);
}
}
}
return $old;
}
/**
* generated a file-name from an eTemplates, name, template(-set) and lang
*
* @return string
*/
function cache_name($name='',$template='default',$lang='default')
{
if (empty($name))
@ -755,16 +729,20 @@
return $cname;
}
/*!
@function store_in_cache()
@abstract stores the etemplate in the cache in phpgw_info
*/
/**
* stores the etemplate in the cache in phpgw_info
*/
function store_in_cache()
{
//echo "<p>store_in_cache('$this->name','$this->template','$this->lang','$this->version')</p>\n";
$GLOBALS['phpgw_info']['etemplate']['cache'][$this->cache_name()] = $this->as_array(1);
}
/*
* returns true if a given eTemplate is in the cache
*
* @return boolean
*/
function in_cache($name,$template='default',$lang='default',$group=0,$version='')
{
$cname = $this->cache_name($name,$template,$lang);
@ -783,6 +761,13 @@
return $cname;
}
/*
* reads the content of an eTemplate from the cache into the current object
*
* same as read but only via the cache
*
* @return boolean true if the eTemplate was found in the cache
*/
function read_from_cache($name,$template='default',$lang='default',$group=0,$version='')
{
//if (is_array($name)) $version = $name['version']; echo "<p>read_from_cache(,,,version='$version'): ";
@ -795,13 +780,19 @@
return False;
}
/*!
@function read
@abstract Reads an eTemplate from the cache or database / filesystem (and updates the cache)
@param as discripted in soetemplate::read
@param $load_via name/array of keys of etemplate to load in order to get $name (only as second try!)
@result True if a fitting template is found, else False
*/
/**
* reads an eTemplate from the cache or database / filesystem (and updates the cache)
*
* reimplementation of soetemplate::read to use and/or update the cache
*
* @param $name string name of the eTemplate or array with the values for all keys
* @param $template string template-set, '' loads the prefered template of the user, 'default' loads the default one '' in the db
* @param $lang string language, '' loads the pref. lang of the user, 'default' loads the default one '' in the db
* @param $group int id of the (primary) group of the user or 0 for none, not used at the moment !!!
* @param $version string version of the eTemplate
* @param $load_via mixed name/array of keys of etemplate to load in order to get $name (only as second try!)
* @return boolean True if a fitting template is found, else False
*/
function read($name,$template='default',$lang='default',$group=0,$version='',$load_via='')
{
if (is_array($name)) {
@ -816,7 +807,8 @@
return False;
}
$parent = is_array($load_via) ? $load_via['name'] : $load_via;
if (strstr($pname,'.') === False && !empty($parent))
if (strstr($pname,'.') === False && !empty($parent))
{
$pname = $parent . '.' . $pname;
}
@ -837,13 +829,19 @@
return True;
}
/*!
@function save
@abstract saves eTemplate-object to db and update the cache
@params keys see soetemplate::save
@result the number of affected rows, 1 should be ok, 0 somethings wrong
*/
function save($name='',$template='.',$lang='.',$group='',$version='.')
/**
* saves eTemplate-object to db and update the cache
*
* reimplementation of soetemplate::save to update the cache
*
* @param $name string name of the eTemplate or array with the values for all keys
* @param $template string template-set or '' for the default one
* @param $lang string language or '' for the default one
* @param $group int id of the (primary) group of the user or 0 for none, not used at the moment !!!
* @param $version string version of the eTemplate
* @return the number of affected rows, 1 should be ok, 0 somethings wrong
*/
function save($name='',$template='.',$lang='.',$group=0,$version='.')
{
if ($result = soetemplate::save($name,$template,$lang,$group,$version))
{
@ -851,4 +849,4 @@
}
return $result;
}
};
}

349
etemplate/inc/class.soetemplate.inc.php
View File

@ -12,38 +12,29 @@
/* $Id$ */
/*!
@class soetemplate
@author ralfbecker
@abstract Storage Objects: Everything to store and retrive the eTemplates.
@discussion eTemplates are stored in the db in table 'phpgw_etemplate' and gets distributed
@discussion through the file 'etemplates.inc.php' in the setup dir of each app. That file gets
@discussion automatically imported in the db, whenever you show a eTemplate of the app. For
@discussion performace reasons the timestamp of the file is stored in the db, so 'new'
@discussion eTemplates need to have a newer file. The distribution-file is generated with the
@discussion function dump, usually by pressing a button in the editor.
@discussion writeLangFile writes an lang-file with all Labels, incorporating an existing one.
@discussion Beside a name eTemplates use the following keys to find the most suitable template
@discussion for an user (in order of precedence):
@discussion 1) User-/Group-Id (not yet implemented)
@discussion 2) preferd languages of the user (templates for all langs have $lang='')
@discussion 3) selected template: verdilak, ... (the default is called '' in the db, not default)
@discussion 4) a version-number of the form, eg: '0.9.13.001' (filled up with 0 same size)
*/
/**
* Storage Objects: Everything to store and retrive and eTemplate.
*
* eTemplates are stored in the db in table 'phpgw_etemplate' and gets distributed
* through the file 'etemplates.inc.php' in the setup dir of each app. That file gets
* automatically imported in the db, whenever you show a eTemplate of the app. For
* performace reasons the timestamp of the file is stored in the db, so 'new'
* eTemplates need to have a newer file. The distribution-file is generated with the
* function dump, usually by pressing a button in the editor.
* writeLangFile writes an lang-file with all Labels, incorporating an existing one.
* Beside a name eTemplates use the following keys to find the most suitable template
* for an user (in order of precedence):
* 1) User-/Group-Id (not yet implemented)
* 2) preferd languages of the user (templates for all langs have $lang='')
* 3) selected template: verdilak, ... (the default is called '' in the db, not default)
* 4) a version-number of the form, eg: '0.9.13.001' (filled up with 0 same size)
*
* @package etemplate
* @author RalfBecker-AT-outdoor-training.de
* @license GPL
*/
class soetemplate
{
var $public_functions = array(
'init' => True,
'empty_cell' => True,
'new_cell' => True,
'read' => True,
'search' => True,
'save' => True,
'delete' => True,
'dump2setup' => True,
'import_dump' => True,
'writeLangFile' => True
);
var $debug; // =1 show some debug-messages, = 'app.name' show messages only for eTemplate 'app.name'
var $name; // name of the template, e.g. 'infolog.edit'
var $template; // '' = default (not 'default')
@ -68,13 +59,20 @@
);
var $db_cols;
/*!
@function soetemplate
@abstract constructor of the class
@syntax soetemplate($name='',$template='',$lang='',$group=0,$version='',$rows=2,$cols=2)
@param as read
*/
function soetemplate($name='',$template='',$lang='',$group=0,$version='',$rows=2,$cols=2)
/**
* constructor of the class
*
* calls init or read depending on a name for the template is given
*
* @param $name string name of the eTemplate or array with the values for all keys
* @param $template string template-set, '' loads the prefered template of the user, 'default' loads the default one '' in the db
* @param $lang string language, '' loads the pref. lang of the user, 'default' loads the default one '' in the db
* @param $group int id of the (primary) group of the user or 0 for none, not used at the moment !!!
* @param $version string version of the eTemplate
* @param $rows int initial size of the template, default 1, only used if no name given !!!
* @param $cols int initial size of the template, default 1, only used if no name given !!!
*/
function soetemplate($name='',$template='',$lang='',$group=0,$version='',$rows=1,$cols=1)
{
$this->db = $GLOBALS['phpgw']->db;
$this->db_cols = $this->db_key_cols + $this->db_data_cols;
@ -85,17 +83,16 @@
}
else
{
$this->read($name,$template,$lang,$group,$version,$rows,$cols);
$this->read($name,$template,$lang,$group,$version);
}
}
/*!
@function num2chrs
@abstract generates column-names from index: 'A', 'B', ..., 'AA', 'AB', ..., 'ZZ' (not more!)
@syntax num2chrs($num)
@param $num index to generate name from 1 => 'A'
@result the name
*/
/**
* generates column-names from index: 'A', 'B', ..., 'AA', 'AB', ..., 'ZZ' (not more!)
*
* @param $num int numerical index to generate name from 1 => 'A'
* @return string the name
*/
function num2chrs($num)
{
$min = ord('A');
@ -109,12 +106,13 @@
return $chrs;
}
/*!
@function empty_cell
@abstracts constructor for a new / empty cell (nothing fancy so far)
@syntax empty_cell()
@result the cell
*/
/**
* constructor for a new / empty cell
*
* nothing fancy so far
*
* @return array the cell
*/
function empty_cell($type='label',$name='')
{
return array(
@ -123,16 +121,15 @@
);
}
/*!
@function new_cell
@abstract constructs a new cell in a give row or the last row, not existing rows will be created
@syntax new_cell( $row=False )
@param int $row row-number starting with 1 (!)
@param string $type type of the cell
@param string $label label for the cell
@param string $name name of the cell (index in the content-array)
@param array $attributes other attributes for the cell
@returns a reference to the new cell, use $new_cell = &$tpl->new_cell(); (!)
/**
* constructs a new cell in a give row or the last row, not existing rows will be created
*
* @param int $row row-number starting with 1 (!)
* @param string $type type of the cell
* @param string $label label for the cell
* @param string $name name of the cell (index in the content-array)
* @param array $attributes other attributes for the cell
* @return a reference to the new cell, use $new_cell = &$tpl->new_cell(); (!)
*/
function &new_cell($row=False,$type='label',$label='',$name='',$attributes=False)
{
@ -169,11 +166,9 @@
return $cell;
}
/*!
@function set_rows_cols()
@abstract initialises rows & cols from the size of the data-array
@syntax set_rows_cols()
*/
/**
* initialises internal vars rows & cols from the size of the data-array
*/
function set_rows_cols()
{
$this->rows = count($this->data) - 1;
@ -188,14 +183,17 @@
}
}
/*!
@function init
@abstract initialises all internal data-structures of the eTemplate and sets the keys
@syntax init($name='',$template='',$lang='',$group=0,$version='',$rows=1,$cols=1)
@param $name name of the eTemplate or array with the keys or all data
@param $template,$lang,$group,$version see class
@param $rows,$cols initial size of the template
*/
/**
* initialises all internal data-structures of the eTemplate and sets the keys
*
* @param $name string name of the eTemplate or array with the values for all keys
* @param $template string template-set or '' for the default one
* @param $lang string language or '' for the default one
* @param $group int id of the (primary) group of the user or 0 for none, not used at the moment !!!
* @param $version string version of the eTemplate
* @param $rows int initial size of the template, default 1
* @param $cols int initial size of the template, default 1
*/
function init($name='',$template='',$lang='',$group=0,$version='',$rows=1,$cols=1)
{
reset($this->db_cols);
@ -231,16 +229,16 @@
}
}
/*!
@function read
@abstract Reads an eTemplate from the database
@syntax read($name,$template='default',$lang='default',$group=0,$version='')
@param as discripted with the class, with the following exeptions
@param $template as '' loads the prefered template 'default' loads the default one '' in the db
@param $lang as '' loads the pref. lang 'default' loads the default one '' in the db
@param $group is NOT used / implemented yet
@result True if a fitting template is found, else False
*/
/**
* reads an eTemplate from the database
*
* @param $name string name of the eTemplate or array with the values for all keys
* @param $template string template-set, '' loads the prefered template of the user, 'default' loads the default one '' in the db
* @param $lang string language, '' loads the pref. lang of the user, 'default' loads the default one '' in the db
* @param $group int id of the (primary) group of the user or 0 for none, not used at the moment !!!
* @param $version string version of the eTemplate
* @return boolean True if a fitting template is found, else False
*/
function read($name,$template='default',$lang='default',$group=0,$version='')
{
$this->init($name,$template,$lang,$group,$version);
@ -307,12 +305,10 @@
return True;
}
/*!
@function readfile
@abstract Reads an eTemplate from the filesystem, the keys are already set by init in read
@syntax readfile()
@result True if a template is found, else False
*/
/**
* Reads an eTemplate from the filesystem, the keys are already set by init in read
* @return boolean True if a template was found, else False
*/
function readfile()
{
list($app,$name) = split("\.",$this->name,2);
@ -383,17 +379,16 @@
return True;
}
/*!
@function search
@syntax search($name,$template='default',$lang='default',$group=0,$version='')
@author ralfbecker
@abstract Lists the eTemplates matching the given criteria
@param as discripted with the class, with the following exeptions
@param $template as '' loads the prefered template 'default' loads the default one '' in the db
@param $lang as '' loads the pref. lang 'default' loads the default one '' in the db
@param $group is NOT used / implemented yet
@result array of arrays with the template-params
*/
/**
* Lists the eTemplates matching the given criteria
*
* @param $name string name of the eTemplate or array with the values for all keys
* @param $template string template-set, '' loads the prefered template of the user, 'default' loads the default one '' in the db
* @param $lang string language, '' loads the pref. lang of the user, 'default' loads the default one '' in the db
* @param $group int id of the (primary) group of the user or 0 for none, not used at the moment !!!
* @param $version string version of the eTemplate
* @return array of arrays with the template-params
*/
function search($name,$template='default',$lang='default',$group=0,$version='')
{
if ($this->name)
@ -448,11 +443,9 @@
return $result;
}
/*!
@function db2obj
@abstract copies all cols into the obj and unserializes the data-array
@syntax db2obj()
*/
/**
* copies all cols into the obj and unserializes the data-array
*/
function db2obj()
{
for (reset($this->db_cols); list($db_col,$name) = each($this->db_cols); )
@ -485,16 +478,15 @@
$this->set_rows_cols();
}
/*!
@function compress_array
@syntax compress_array( $arr )
@author ralfbecker
@abstract to save space in the db all empty values in the array got unset
@discussion The never-'' type field ensures a cell does not disapear completely.
@discussion Calls it self recursivly for arrays / the rows
@param $arr the array to compress
@result the compressed array
*/
/**
* to save space in the db all empty values in the array got unset
*
* The never empty type field ensures a cell does not disapear completely.
* Calls it self recursivly for arrays / the rows
*
* @param $arr the array to compress
* @return array
*/
function compress_array($arr)
{
if (!is_array($arr))
@ -515,13 +507,12 @@
return $arr;
}
/*!
@function as_array
@abstract returns obj-data as array
@syntax as_array($data_too=0)
@param $data_too 0 = no data array, 1 = data array too, 2 = serialize data array
@result the array
*/
/**
* returns obj-data/-vars as array
*
* @param $data_too int 0 = no data array, 1 = data array too, 2 = serialize data array
* @return array
*/
function as_array($data_too=0)
{
$arr = array();
@ -543,13 +534,11 @@
return $arr;
}
/*!
@function save
@abstract saves eTemplate-object to db, can be used as saveAs by giving keys as params
@syntax save($name='',$template='.',$lang='.',$group='',$version='.')
@params keys see class
@result the number of affected rows, 1 should be ok, 0 somethings wrong
*/
/**
* saves eTemplate-object to db, can be used as saveAs by giving keys as params
*
* @return int number of affected rows, 1 should be ok, 0 somethings wrong
*/
function save($name='',$template='.',$lang='.',$group='',$version='.')
{
if (is_array($name))
@ -630,12 +619,11 @@
return $this->db->affected_rows();
}
/*!
@function delete
@abstract Deletes the eTemplate from the db, object itself is unchanged
@syntax delete()
@result the number of affected rows, 1 should be ok, 0 somethings wrong
*/
/**
* Deletes the eTemplate from the db, object itself is unchanged
*
* @return int number of affected rows, 1 should be ok, 0 somethings wrong
*/
function delete()
{
foreach ($this->db_key_cols as $db_col => $col)
@ -647,13 +635,12 @@
return $this->db->affected_rows();
}
/*!
@function dump2setup
@abstract dumps all eTemplates to <app>/setup/etemplates.inc.php for distribution
@syntax dump2setup($app)
@param $app app- or template-name
@result the number of templates dumped as message
*/
/**
* dumps all eTemplates to <app>/setup/etemplates.inc.php for distribution
*
* @param $app string app- or template-name contain app
* @return string translated message with number of dumped templates or error-message (webserver has no write access)
*/
function dump2setup($app)
{
list($app) = explode('.',$app);
@ -724,13 +711,13 @@
}
}
/*!
@function getToTranslate
@abstract extracts all texts: labels and helptexts from an eTemplate-object
@discussion some extensions use a '|' to squezze multiple texts in a label or help field
@syntax getToTranslate()
@result array with messages as key AND value
*/
/**
* extracts all texts: labels and helptexts from an eTemplate-object
*
* some extensions use a '|' to squezze multiple texts in a label or help field
*
* @return array with messages as key AND value
*/
function getToTranslate()
{
$to_trans = array();
@ -754,13 +741,12 @@
return $to_trans;
}
/*!
@function getToTranslateApp
@abstract Read all eTemplates of an app an extracts the texts to an array
@syntax getToTranslateApp($app)
@param $app name of the app
@result the array with texts
*/
/**
* Read all eTemplates of an app an extracts the texts to an array
*
* @param $app string name of the app
* @return array with texts
*/
function getToTranslateApp($app)
{
$to_trans = array();
@ -783,16 +769,15 @@
return $to_trans;
}
/*!
@function writeLangFile
@abstract Write new lang-file using the existing one and all text from the eTemplates
@syntax writeLangFile($app,$lang='en',$additional='')
@param $app app- or template-name
@param $lang language the messages in the template are, defaults to 'en'
@param $additional extra texts to translate, if you pass here an array with all messages and
@param select-options they get writen too (form is <unique key> => <message>)
@result message with number of messages written (total and new)
*/
/**
* Write new lang-file using the existing one and all text from the eTemplates
*
* @param $app string app- or template-name
* @param $lang string language the messages in the template are, defaults to 'en'
* @param $additional array extra texts to translate, if you pass here an array with all messages and
* select-options they get writen too (form is <unique key> => <message>)
* @return string translated message with number of messages written (total and new), or error-message
*/
function writeLangFile($app,$lang='en',$additional='')
{
if (!$additional)
@ -866,13 +851,12 @@
return lang("%1 (%2 new) Messages writen for Application '%3' and Languages '%4'",$n,$new,$app,$lang);
}
/*!
@function import_dump
@abstract Imports the dump-file /$app/setup/etempplates.inc.php unconditional (!)
@syntax import_dump($app)
@param $app app name
@result message with number of templates imported
*/
/**
* Imports the dump-file /$app/setup/etempplates.inc.php unconditional (!)
*
* @param $app string app name
* @return string translated message with number of templates imported
*/
function import_dump($app)
{
include($path = PHPGW_SERVER_ROOT."/$app/setup/etemplates.inc.php");
@ -894,14 +878,15 @@
return lang("%1 new eTemplates imported for Application '%2'",$n,$app);
}
/*!
@function test_import
@abstract test if new template-import necessary for app and does the import
@discussion Get called on every read of a eTemplate, caches the result in phpgw_info.
@discussion The timestamp of the last import for app gets written into the db.
@syntax test_import($app)
@param $app app- or template-name
*/
/**
* test if new template-import necessary for app and does the import
*
* Get called on every read of a eTemplate, caches the result in phpgw_info.
* The timestamp of the last import for app gets written into the db.
*
* @param $app string app- or template-name
* @return string translated message with number of templates imported
*/
function test_import($app) // should be done from the setup-App
{
list($app) = explode('.',$app);

12
etemplate/inc/class.xul_io.inc.php
View File

@ -12,7 +12,6 @@
/* $Id$ */
if (!function_exists('var2xml'))
{
if (file_exists(PHPGW_API_INC.'class.xmltool.inc.php'))
@ -25,6 +24,15 @@
}
}
/**
* XUL/XML Import & Export for eTemplates
*
* used only internaly
*
* @package etemplate
* @author RalfBecker-AT-outdoor-training.de
* @license GPL
*/
class xul_io
{
var $widget2xul;
@ -616,5 +624,3 @@
return $imported;
}
}
?>