Up to [Platon] / phpMyEdit / doc

minor changes

by Michal Palenik

about future changes I plan to implement

MOTIVATION
there are several limitations of current phpMyEdit design:
- lack of template system
- no possibility of implementation new visual differences (like image upload field, search of dates 
    within an interval, twined fields, ...), to implement such, it is neccessary to hack the core class 
    or build an extention (which sums to the same thing)
- lack of pages management (e.g. similar fields have to be defined again, no themes)
- no possibility to search within fields not displayed on F page
- sql fields are very tied to displayed fields
- numeric notations are sometimes used (sql), sometimes sql field names are used (html), 
    which makes it hard to link with other pages
- qfn (values of variables from cgi) is stored as string, it should be an array to be easy to reference 
- no possibility for validation of user input at php level, no possibility to correctly display error (eg unique key)
- whole design uses many long methods, which make extentions hard to build and maintain
- it is hard to tell which mode the page is in 


IMPLEMENTATION
for each field, not a mixture of configuration variables will be present, but rather a list of functions/methods 
which are to be called within some situations :

view:
- view_html : function which will return value to be displayed (return $this->value; )
- view_pre : preparation of the value (e.g. values2)
- view_name : will return name of the field (return $this->field['name'];)
- view_sql : sql code to be executed to retrieve the value (return $this->sd.$this->name.$this->ed.' as '.$this->name; )
- view_sql_join : sql code from the join part ( return 'left outer join ...';)
- view_help : returns help for the field ( return $this->help; )
- view_row : echo row
- view_page : echo complete page
- view_js : return js code
- couple more view_* see detailed notes below

similar: change, add, delete, list, filter, search (later)

next some special elements for each field:
filter :
- display - string to be displayed (eg  return 'id desc';)


search if F mode : 
- html - dropdown box, input, ...
- sql - sql code
- display - string to be displayed (eg colname > 2, date last week, ...)

cgi/sql variable names: (prefixes also available)
how to handle col_names with spaces ? these produce html related errors.
- filter : filter_colname / _idx / _comp
- sort : order_1=-colname
- add/change: data_colname
- sql: colname (colname_idx) retreived from $this->row by get_from_row(colname) 
    there is no neccessity to prefix col_names, if all joining is done by table reference as well

create several modes:
add_save, add_display
change_save, change_display,
...
so it will behave: add_display|reload|add_save,list_display|reload|...


NOTES
it is intendent for advanced usage only
basic usage by standard configuration, backward compatibility will be achieved
extentions will break, however it will be a lot easier to build new extentions


DETAILED NOTES

= view_html 

this function will return a html code to be displayed (e.g. textarea, text, ...)
return: value to be displayed
available and recomended variables:
$this->row
$this->field ( =$opts['fdd']['colname'] )
$this->name (colname)
$this->value (value = $this->row[$this->name] )
$this->rec ( =$this->row[$this->key] )
$this->key


= view_pre 

this function prepares data in $this->row, mainly values2 implementation. 
these modified values are available to view_html functions
variables: same variables as view_html
return: value for $this->row (update additional $this->row elements if neccessary)


= view_name 

name of the field to be returned ($this->field['name'])
in case of LF modes, return links to sort variables
variables: $this->field, $this->name, $this->key, $this->fdd
return: name to be displayed


= view_sql 

return sql code to be executed to retrieve the value from db, 
default: return $this->sd.$this->name.$this->ed.' as '.$this->name;
note: if this function is not defined, no value will be fetched from db
variables: $this->field, $this->name, ($this->join = string for join table name = $this->name.'_join')
return: sql code to be executed


= view_sql_join

sql code from the join part ( return 'left outer join ...';)
variables: $this->join, $this->field (mainly 'values' part)
return: complete sql join clause


= view_help 

returns help for the field ( return $this->field['help']; )
variables: $this->field, $this->name
return: string help


= view_js

javascript code for validation
eg: required, ...
variables: $this->field, $this->name
return: js code


= view_search_sql ?

return sql code with search options into filters (where clause)


= view_search_variables ?

return cgi variables to be passed if filter/search is valid yet not visible
eg in V mode, it should be passed via hidden
in L mode with link to V it should be in url


= view_row

method that echo a row of view page (without header and footer)
to be used with smarty
variables: a lot (array $data, array $name, array $help)
returns: nothing
echo: page using td, tr, 
not to echo: table, buttons, 


= view_page

method that will echo view page using view_row
to be used with smarty
variables: a lot($row by view_row, $buttons_top, $buttons_botton, $js, $header, $footer, ...)
return: nothing
echo: whole html page


SCHEDULE

prepare list_table(), remove some stuff into separate methods
recreate_fdd will have mode like add_save or add_display, it will create $this->fdd['colname']['advanced'] if not present
merge  display_add_record() and display_copy_change_delete_record()
change "for ($k = 0; $k < $this->num_fds; $k++)" to a foreach looping through 'advanced' when ready