three types of pages:
show-page = bersichtsseite, where all entries are shown
edit-page = page where one can edit/add entries
view/spy-page = page where one can view a specific entry (more detailed than in digest-page)
implemented :
+ .. 100%
9 .. 99%
S .. in reference-script
name meaning default implemented example
PART A) variables in g_ptr
dbhandles list of cached dbhandles {} + user should not interfere with this variable
usercounter numer of users logged on at this childprocess 0 ? 0
identify random-number identifying the current childprocess. 'root' means unset. root + 94345
filehandles see dbhandles
configs cache for configfiles. see filehandles
rereadconfig cached values of ptr->{config}
test a testvalue
syslog full filename for the syslog /tmp/genericSQL2_syslog_'.getpwuid ($>) + /data/logs/genericSQL2/syslog
mod_perl if mod_perl is used. Automatically set. + + 0
initdebug if the first steps should also be logged. (steps before actually a logfile is opened or a configfile loaded . ..) 1 + 0
transactions set to 0 if the sql-server does not understand commands like "autocommit=0" 1 ? 0
default_config use this configfile if no other is defined ...
PART B) varibales in ptr
save_err an database-error occured while saving
ver_err an error occured while saving (reported by some funcs)
ver_allowerr save entry even if ->ver_err is set !!
webmaster emailadress specified by errormessages ? +
sql type of database : pg or mysql. It is very important to set because some queries look different in these different databases ? ?Pg
db databasehandle ? ? dbi:Pg:dbname=malmoe;host=127.0.0.1;port=11556
log logfile ? +
user username to logon at sql-database. see also ->loginname ? +
pass password ? +
loginname username that was entered when logging on. see also ->user ? +
uid uid of user in auth3-db
gid gid of user in auth3-db
h gate to content. mostly this is a hash where the fields of the current database-entry are stored. This hash can be queried and altered in almost any function (prefunc, postfuncs etc.) . +
legend if set to 1 print legend at the end of edit-page. Dont forget to set to 0 if using ->edit_template 1 +
edit_template dont use a generic edit-mask but use a template designed by an expensive designer instead ;) see seperate section. '' + see seperate section
tb name of the table to edit. look at ->tbrange ->authgroup . +
tbrange anon. list of tables that are valid to be edited withing this config ->authgroup. [$ptr->{tb}] + ['letters1','letters2']
auth authentication-level ? +
auth_db database-identifier for auth3-table.(see also note about table-definitions) ? + ['dbi:Pg:dbname=malmoe;host=127.0.0.1;port=11556','users','malmoe','pass','pguser,uid,gid','username','userpass','valid]
pg_db database-identifier for table that translates auth3-users into pg-users ? + ['dbi:Pg:dbname=malmoe;host=127.0.0.1;port=11556','pguser','malmoe','pass','pgpass','pguser]
entry_sess database-identifier for entryessesion-table ? +
entry_id level of entrysession 0,1,2 ? +
store_sess database-identifier for storage of session-related values [] + see entry_sess
store_sess_parameter which values should be stored in store_sess and the defaultvalues {javascript=>'no'} + .
store_sess_parameter_clone which values should be cloned if a new session is opened based on an old session {javascript=>1}
lock_db database-identifier for entrylock-table ? + ['dbi:Pg:dbname=malmoe;host=127.0.0.1;port=11556','lock_tb','malmoe','kummerl7','row,tbname,username,key','expire'];
lock_addon subroutine that returns values to be stored in ->lock_db ? + sub{return $_[0];}
nosticky all cgi's get no-sticky - used when intersave to avoid problems with multi-fields
htmlcache if set to 1 then each call of the ->html method does not print out the text immediately but its cached in $ptr->{html}. If set to 0 the next call of ->html will print out and clear all the cache. The wrapper-script should print the header and then change this value to ->htmlcacheall. at least at the end of the script this value must be set to 0 and ->html called to print out the output.
htmlcacheall ->htmlcache will be set to this value after the header is printed
lock_id level of entrylock 0,1,2 ? +
keepopen amount of internal databaseconnection-pooling. If set >0 this value specifies the number of connetions that are stored between several calls when using mod_perl. If set to 0 no connections are pooled. Set to 0 if using Apache::DBI and look at ->cacheintern and -> ? +
keepopen_fh amount of internal filehandle-pooling. If set >0 this value specifies the number of handles that are stored between several calls when using mod_perl. If set to 0 no connections are pooled. 1 ? +
cacheintern cache database-connections internally while one call if set to 1. If set to 0 keepopen has no effect. Set to 0 if using Apache::DBI and also look at ->keepopen 1 +
unbuffered_fh disable buffering on filehandles for better debugging 0 + 1
hires Log with High TimeResolution if set to 1. 0 +
log_debug anon. array that contains expressions that should be logged at each logit-call. only for debug-purpose
log2file bit0: log logevents to log-file bit1: log logevents to screen bit2: log messages to log-file ? 9
loglevel level of messages to log (1 .. basic tasks, 40 .. very detailed, 60 .. long logfiles ...) ? +
memlog should memoryusage be logged (experimental and ineffecient !!!)
rereadconfig reread config-file on each call when using mod_perl or used cached version ? +
global->initdebug if set to 1 also events before opening logfiles, db-handles are logged. note that changing this value in configfile will not log the first events until the configfile is read, cause the defaultvalue is set to 0. If you want to log *everything* you need to change this value in the sourcecode of the module 0 +
path_lead the full url of the application incuding override and config but not any command
path_lead_nc the full url of the application incuding override but not config and not any command
authgroup strings that describes the databases/tables that can be choosed in statusline. see also ->tbrange and section regarding cookies and sessionkeys. see technical description for format of this string
charset used charset for all html-pages and forms UTF-8 + UTF-8
html this string contains all the html-code created so far. all methods add their output to this variable and the programmer can change or output it at the end of the script or at any given stage of the program and reset it after printing out the content. This also allows to fetch and isolate the output of any sequence of methods by buffering the content before starting the sequence '' +
INSERT(file) a metacommand the reads definitions in mentioned file . +
order order of entries in digest-page. Take also very close looks at ->ext_ctr_ptr which will most likely overrule this value. . ~
showlength max. length (in chars/bytes) of an element in digest-page ? + 500
showwidth html-width for tablewidth in digest-page 100% + 500%
fieldnames->all all fields including dummies
fieldnames->sql all fields without dummies
fieldnames->show all fields that should be queried in showstuff ->showstuff
defaultaction action that is choosen if no other action was processed
button_ptr points to an hash containing all button-defintions see extra section +
private gate to your private datastructure that is used in your private subs. most likely this will be a reference to your private world. ? + $ptr->{private}->{croatia}="country";
private_funcs reference to hash where you store your private subfunctions. Note that you can also store your functions as part of the ->private-structure, but this hash is explicetly destroyed when closing a session which is very important due to heavy memleaking prior to perl 5.6.1 !!! {} + $ptr->{private_funcs}->{moon}=sub{return 'raise';};
debug if set to 1 additional debug-info is printed out to the screen. This is meant to be replaced with the extended loggin-features in the future. 0 +
debugs if set to 1 and ->log2file is set all CGI-values are dumped to the logfile 0 +
sysmaster defaultvalue for ->webmaster genericSQL@goldfisch.at +
unbuffered_fh if set to 1 all logdata will be written unbuffered. This allows more exact debugging but usage is not recommended in productional environment due to performance-loss 1 +
title html-title. If empty then script-configfile is used as default . +
global gate to global variables. see extra section and *never change* !!! $ptr->{global}=$g_ptr; +
start_html if set this value is used instead of $query->start_html;
oid value of submitted oid-variable (CGI)
todo value of submitted submit-variable (CGI)
initfunc_ptr anonymous array that contains all functions that are evaluated at the beginning of each call {} + see seperate section
initfunc0_ptr anonymous array that contains all functions that are evaluated at the beginning of each call {} + see seperate section
postfunc_ptr anonymous array containing anonymous subs that are executed before an entry is saved to the database (save, intersave ..). At this stage all internal checkings are already completed and $ptr->{h} contains all values {} + push(@{$ptr->{postfunc_ptr}},sub{$ptr->{h}->{'to_short'}=substr($ptr->{h}->{'to_'},0,20);});
postfunc0_ptr like postfunc_ptr, but this functions are executed *before* the internal processing is done. {} + see postfunc_ptr
postfunc1_ptr like postfunc_ptr, but this functions are executed *after* the entry was saved to the database. Nevertheless all dummy_parameters are accessible via $ptr->{h} and you can use this functions to perform some extra work like updating other databases. Note that $ptr->{h}->{oid} contains the new OID in every case at this stage. Even when a new entry was saved !! {} + see postfunc_ptr
extra_get additional to the elements specified this values should be fetched from the database when going to edit or spy mode. needed for prefunctions. Alwaysd need a leading ',' !!! . + ',val1,val2,val2'
ctr_ptr creates types for the elements listed in ->desc_ptr . + see technical description
edit_table html-addons for table-definition . + cellpadding=5
view_table like ->edit_table but used in view/spy-page . +
view_descr like ->edit_descr but used in view/spy-page <font color=#800000> +
view_sep like ->edit_dep but used in view/spy-page <hr> +
ext_table additional html-code for table-definition for extended head er . +
ext_sep seperator between lines in extended header . +
show_ptr order of elements in edit- and spy-page . + see technical description
edit_desc html-code for formatting the names of the elements in edit-mode <font color=#800000> + <font color=#008000>
edit_desc_nz like edit_desc but special format for nz-elements ? + <b><font color=#802000>
edit_desc_nz_end closing tags to ->edit_desc_nz_end ? + </b></font>
edit_sep seperator between lines in edit-page <hr> + <hr>
show_table table-definition in digest-page . + 'width=100% cellpadding=5 cellspacing=0 bordercolor=#e0e0e0'
show_desc like ->edit_desc but in digest-page ? +
show_lock no : a new html-table is shown for each entry in digest-mode, which maked the output more efficient. yes : all entries are shown within the same table which makes the output more human readable. ? +
showall_desc yes : the field-names are shown before each entry. no : the field-names are only shown at the beginning and the end of the digest ? +
show_sep seperator between lines in digest-page. better use ->show_sep2 cause this is a relict from ancient times and we dont know exactely what this was for ;) . +
show_sep2 seperator between lines in digest-page. also look at ->show_sep. <hr> +
caller scriptnames that are allowed to invoke this configfile. more than one scriptname can be specified using ; as seperator. note that in any case there must be a trailing ';'. setting this value to '*' means that *every* script can invoke this configfile. This is meant if you restrict access to scripts using auth-mechanism from your webserver and want to prevent clever users from accessing other customers configfiles using their own scripts. Note that it is strictly recommended to use the auth-mechanisms this module provided !!! . + customer1;
valid_user anonymous hash (new) containing all users-id's (uid) that are allowed to work with this configfile when using auth3. Note that '*' allows all users to logon that are stored in the ->auth3_db. Note that any user is allowed to logon that is specied here *or* is member of a group mentioned in ->valid_groups !!! [] + [100,101,102,103]
valid_groups anonymous hash (new) containing all group-id's (gid) that are allowed to work with this configfile when using auth3. Note that '*' allows all groups to logon that are referenced in the ->auth3_db. Note that any user is allowed to logon that is specified in ->valid_user *or* is member of a group mentioned here !!! [] + [100,101,102,103]
multiparamsep this value is used to seperate multiparameters in the database. look at ->multifilesep. Do not change this if there is already data stored !! - + #
multifilesep this value is used to seperate multifilevalues in the database. Do not change this if there is already data stored !! / + #
xfactor multiplier for all x-values defined in ->desc_ptr 1 + 0.8
yfactor multiplier for all y-values defined in ->desc_ptr 1 + 0.8
relogon_txt html-code displayed on logon-screen . + '<br><br>welcome you moron<br><br>'
sec_process passed select-parameters will be checked if they are inside the definition-range 0 + 1
-------------------------------------------------------------------------------------
button-defintions
default-button-defintions are:
$ptr->{button_htpr}->{name}=[-type=>,
-skin=>,
-return=>,
-class=>];
where type is
'button' ... always a button (use javascript-submit if javascript)
'auto' .... link with submit if javascript - button else
'link' .... always a link
skin is the text to appear in link/button or [source,alt] if a imagelink or imagebutton
class is optional and specifies the class of the element ...
return is the returnvalue delivered when pressing this button. In fact
each button will be named 'submit:returnvalue' and the script is then
scanning for such entries and delivering a keypair:
submit=returnvalue
returnvalue is supposed to have the following format:
action1-param-param
or
action1-param-param/action2-param
instead of returnvalue a function calculating the returnvalue can also be definded. This function takes $ptr as first parameter and optionally more parameters that are submitted via the call of the button-method. Note that this function can also alter the look of the button.
If the returnvalue (defined or returned via function) is undef then no
button is returned but '' !!!!
each button can optionally have a "are you sure"-question that is stored
$ptr->{button_sptr}->{name}='are you sure you want to delete this entry ?';
this value can be customized inside the button_fptr-subs as can be the
other values.
corresponding to each button we need to define actions that should be
performed when a button is pressed. If a button defines 'edit-234' as
returnvalue we need to define a function that handles the action
'edit'
$ptr->{action}->{edit}=['edit'];
$ptr->{func}->{def}->{edit}=sub{..};
as $ptr->{action}->{ACTION} is a array you can define more than one
subs for each action !!
several actions are predefined and can be altered. Note that very
often you want to have the following as your last statement in your
selfdefined action:
push(@{$ptr->{todo}},'reload');
$ptr->{defaultaction} defines an action that is processed if no other
action was processed.
$ptr->{defaultaction}='show';
-----------------------------------------------
supplying important parameters :
config=?
submit=?
sessionkey=?
override=?
i) the calling script can of course alter and supply any of this values
ii) supply via url - this is to be supposed the 'modern' way if javascript is available
iii) as known via parameters. This is used if javascript is not available and the value cannot by supplied via url.
format via url:
http://www.domain.com/sub/script.pl/aaa/bbb/ccc/ddd/eee
aaa, bbb, ccc is read and interpreteded as following:
if first term starts with 'ov' its supposed to be an override-term and can be followed by one or more of the following strings
fjs : ForceJavaScript
njs : NoJavaScript
fck : ForceCookies
nck : NoCookies
rd : RanDom - this will replaced by rd followed by a random number which might help with browsers that keep internal caches
the next term (first or second) is supposed to be the name of the
configfile. The configfile can consists of two parts. 'config-table'
if we want to access another table. The table must be defined in
->tbrange If config does not contain a . the '.conf.pl' is added to
get the full filename.
Note that is very important to have your configfile ended by .pl or
any other extension that is not handled by your webserver as text/html
or otherwise viewable format or all the passwords in this file can be
easily compromised.
then we continue with submit commands like edit-3234 or delete-3334-3 or whatever
if the last term starts with SK then this is the sessionkey which is provided that way if cookies are not used
-----------------------------------
switching of tables
->tb defines the table where we work on and is defined in the
configfile. If we want to access a different table within the same
configfile, we can define a list of allowed tables with ->tbrange and
submit one of these tables within the config-parameter (via url or via
cgi-param). Of course this only makes sense when all other definitions
stays the same and the table has the very same format.
the parameter for the configfile can therefore be extended to config-table
example : .../edit/myconfig-mytab2/reload
imho its better to use different configfiles, which can consist of a
few lines only that include a common def-file.
-----------------------------------
authgroup
->authgroup is if a user should be able to access more than one table
(or more than one configfile) without need to logon again. The
sessionkey is also valid for all other configs with the same
authgroup. The sessionkey is stored as cookie that has the name
'sessionkey-authgroup'
so authgroup does not do any auth on its own (use standard mechs for
this) but only let the CMS use a already existing session_key
Note that in the ->session_db you define a addon-function that will
calculate a id-string. a given sessionkey is only accepted if this
id-string is the same than stored in the database.
potential attack :
user has access to a certain table1 but not to a different table2,
which he knows the exact format. So the user can logon table1 and spy
the name of the authgroup from the stored cookies on his browser.
Then he could create a configfile for table2 that belongs to the same
authgroup and create a simple wrapping-script for genericSQL and
therefore could logon table2 without any need to auth. (A own script
is necessary cause configfiles need to be in the same folder than the
calling script and the sysadmin will be so smart the users * not* to
give writeaccess to this folders)
At this point the user would need to know the password for the
session-db, the auth-db and others to mention in its configfile. If
the user already knows this value we are doomed anyway, cause he could
easily create a script that reads all user/pass from the database
itself.
But its an important point to mention : usual apache-installations
allow users readaccess to all other apache-files on the machine. So
writing a script that simply scans the whole machine for configfiles
and passwords is not a very hard task. Its up the webadmin to use
suexec and proper filepermission to avoid such nasty things.
--------------------------------------------
sessionkey
the sessionkey is the unique id that leads through a whole
session. Each user that logs on gets assigned an unique sessionkey.
This key is stored along with the following parameters:
loginname,uid,gid,tablename,id-string,values
id-string is a unique string calculated via the addon-sub defined in
->session_db that identifies the session on the client machine. This
string should contain the ip-adress, the client-id .. as well as the
auth-group.
tablename is the name of the table the values are valid for. If you
switch to a different table or different config then the defaultvalues
are used and a new entry in the ->session_db is stored with the same
sessionkey, login,uid,gid,id and the new table and new values. This
assures that you can simultaneosly work on two tables with the same
sessionkey without inteferring. (see also ->callsession)
session_db
this is the table where the ->sessionkey is stored and is responsible
for userauth and sessionmanagment. see ->LOGON
the definition follows the standard ->table-definition:
$ptr->{session_db}={-db=>'dbi:Pg:dbname=peter;host=127.0.0.1', # database to connect to
-table=>'userdb', # name of the table
-user=>'itsme', # username to connect to the database
-pass=>'mypass', # password
-s_key=>'s_key', # the field holding the session_key
-query=>'tb,login,uid,gid,id,values', # the fields for table,loginname,uid,gid,idstring,values
-values=>'values', # must also be specified in query !!
-table_field=>'tb', # must also be specified in query !!
-entrydate=>'cdate', # the field when this session was created (DEFAULTVALUE IN DB NEEDED !!)
-udate=>'udate', # the field when this key was last altered (UPDATED BY THE SCRIPT !!)
-expire=>'0:30', # maximum age of a sessionkey before considered as expired
# -call_key=>'c_key', # optional field for ->callsessions
-addon=>'session_id'}; # name of the addon-sub that will calculate the id-string
====================
LOGON :
once a user logs on, his username and password are verified against
->auth_db and it is checked if this user is in ->valid_user *OR* the
group in ->valid_group.
If the user can be authenticated a ->sessionkey is generated and
stored along with its parameters (see ->sessionkey) in the
->session_db. The sessionkey is additionally stored as cookie on the
clients computer or will be passed as part of the url.
Each time the clients requests an action his sessionkey will be
processed by the server :
* does the sessionkey exist in the database and is not expired ?
* does the id-string match with a new created id-string ?
if this is true than the requested action will be processed. Otherwise
all entries that match the clients sessionkey will be deleted.
If there is a further match between the table the client is requested
and the table stored with a matching sessionkey than the values of
this entry are read and processed.
After a request is processed the potentially changed values are stored
to the disk again (or a new entry is created if the table was switched
or the user just logged in). The udate-field is then updated to the
current timestamp and this field will help us to determine if a key is
expired the next time a client requests an action for this sessionkey.
======================
session-values
there are couple of values that can be stored along with the
sessionkey. This are values like currentpage, extra_searchtext
... that needs to be passed between client-requests.
The values that are stored in the ->session_db are listed in
->store_sess_parameter as anonymous hash: key=>defaultvalue, where the
defaultvalue is used to initialize the values.
Only values listed in this hash are read from or written to the ->session_db
---------------------------------------------
store_sess
in this table all the important per-session parameters are stored
(like current page and so on). The values that are stored are defined
in ->store_sess_parameter, which is a hash defining the values and its
defaultvalues. The configfile can alter ->store_sess_parameter and
the module assigns the defaultvalues automatically after reading the
configfile.
The format of the store_sess-table :
key,login,tb,values
key is the first field in the db-definition and values the last field
note that if using ->call_sess you need an additional field 'callkey'
and add this field as second field in the db-definition.
--------------------------------------------------
call_sess
this is a very special feature. We want to allow users to open several
instances of the same session. This is to allow them to 'open link in
new tab/window'-operations. For this purpose we add a unique call_key
that is different for each call. The parameters stored in store_sess
use this key as second identifier and the key changes at each call.
So the process is like this:
get call_key
read parameters
create new call_key
...parameters are altered and all links use the new call_key
save parameters with new call_key
Note that this feature may be irritating for non-experienced users and
uses lot of dataspacespace ...
-----------------------------------------------
templates
Templates simply define how the data will be showed.
the module does not need any templates but creates very nice templates
on its own (->autotemplates). However you might like to use your own templates.
The following templates are waiting for your designers:
$ptr->{templates}->{start_html}
hier wird das form-element eingefgt
$ptr->{templates}->{head}
for the overview:
$ptr->{templates}->{show}->{pre}
$ptr->{templates}->{show}->{head}
$ptr->{templates}->{show}->{element}
$ptr->{templates}->{show}->{foot}
$ptr->{templates}->{show}->{post}
The element-template is repeated for each listed element.
for the edit:
$ptr->{templates}->{edit}->{pre}
$ptr->{templates}->{edit}->{element}
$ptr->{templates}->{edit}->{post}
$ptr->{templates}->{foot}
Each template can use the following variables:
[% button(name,privilege,param) %]
only name is mandatory
action is the redactional action like 'C' for Change ... (see
->redactional) and the button is only printed if the user helds
this privilege.
param are additional parameters passed to the button
[% class(classname) %]
returns the class-definition for this classname if CSS is
allowed. Mainly this queries the $ptr->{class}-structure.
[% link(shortlink,text,privilege) %]
transform the shortlink, which would mostly be an action like
'change-45664' to a full url including session-keys if needed,
overrides and so on...
text is the text to display (which can be an image or anything else
of course)
[% cgi(name) %]
This will print any cgi-element defined in $ptr->{cgis}
[% func(name) %]
This will print the result of a function defined in $ptr->{func}->{def}->{name}
$$variable
This will print the value of the mentioned parameter ($ptr->{h}->{name})
[% field(name) %]
This will present the cgi-field for the mentioned field and is only substituted in edit-templates.
-----------------------------------------------
autotemplates
if your designers did not do a good job, you can always rely on the
module to create templates on its own. It needs a bit Information from
you. The following parameters do not apply if you defined the
approptriate ->templates directly.
$ptr->{autotemplates}->{show}->{fields}=['field1','field2' ...]; the fields we want to see in the show (overview) defaults to OID
$ptr->{autotemplates}->{show}->{buttons}=['button1()$perm','button2()$perm' ...]; the buttons we want to see in the show for each line. The format is similar to the templatedefintion but without the leading $B defaults to ['showview()$V','showchange()$C','showdelete()$C'];
The template is created in the following way: one table-row per
entry. The buttons are on the left side. Between each field is a empty
column. Various css-styles are used that still needs to be
documentated. There is a header and a footer naming the columns and
offering links to change the order. The module is smart enough not to
offer order-change for dummy-fields :)
---------------------------------------------
the field var
$ptr->{fieldnames}->{show}=[field1,field2...] .. this fields are
fetched from database for overview-page defaults to ->
$ptr->{fieldsnames}->{sql}. oid is added automatically if not
specified
$ptr->{fieldnames}->{search}=[field1,field2 ..] .. this fields are
searched per default is $ptr->{store_sess}->{extra_defaultfield} is
not set. NOTE THAT YOU MUST MANUALLY SET THIS !!! ->search
$ptr->{fieldnames}->{all} .. all fields = keys $ptr->{fields}
$ptr->{fieldnames}->{sql} .. all fields = keys $ptr->{fields} except
the dummies + oid if not specified in $ptr->fields
-----------------------------------------------
table-definitions
to access a certain table (session, auth etc.) there is a socalled table-defintion-array, that consists of the following elements:
$ptr->{xxx}=[database,table,user,pass,values,addons];
database='dbi:Pg:dbname=peter;host=127.0.0.1;port=1111';
table=name of the table. If this is empty string then "values" needs to contain the whole select-string including the table-name
user,pass : needed to access this table
values : values to query from the table or the whole sql-command
addons : depends on which table
example:
$ptr->{auth3_db}=['dbi:Pg:dbname=peter;host=127.0.0.1','userdb','session','donttell','pguser,uid,gid','username','userpass','valid'];
$ptr->{auth3_db}=['dbi:Pg:dbname=peter;host=127.0.0.1','','session','donttell','select pguser,uid,gid from userdb where username=? and userpass=? and valid>current_date'];
--------------------------------------------------------------------
funcs
this makes the module most flexible by offering a complex range of
functions that are processed during one call.
For various events you can define functions that are executed if this
even takes place. This functions can be used to change values of your
configuration, change values of your datasource, fetch values from a
different datasource or do whatever you like. the functions are
programmed in perl and are defined the following way
$ptr->{func}->{def}->{name}=sub{my $ptr=shift; ..... };
The first parameter is the object
The second parameter is the name of the field (if related to a field)
Then the defined parameters are passed
In different configs you define when each function will be executed:
A) functions related to a field:
$ptr->{func}->{categorie}->{field}=[['func1',arguments],['func2',arguments]....];
with categorie:
show ... the function is called *before* an entry is shown in the overview
prepare ... the function is called *before* an entry is shown in edit-mode
view ... the function is called *before* an entry is shown in view-mode
verify ... the function is called *before* an entry is saved to the database.
delete .. the function is called *before* an entry is deleted
note that prepare and verify should most times go together. If you
change the values of a popup-field in prepare you should also change
it in verify. For most of these funcs will be defined in the
->fielddefs, its very easy simply to specify 'pv' when defining a
function.
B) functions related to an event:
$ptr->{func}->{categorie}=[['func1',arguments],['func2',arguments]....];
where categorie can be :
callinit ... called at beginning of each call after config was read and processed. This is a very heavy weapon and should be used with caution !!
init ... called at beginning of each call after auth was successful *AFTER* head is printed out already and after sessionparams are processed
exit ... called at the end of each call *BEFORE* the final html is printed
callexit ... called at end of each call (ususually before memleak)
where ... used for create the where_expression
preshow ... before the data is read from database
preshowloop ... before a line is shown (has already access to data)
predelete ... before an entry is deleted ...
preprepare->{page} .. before the prepare-funcs are called (has access to data)
preprepare->{all} .. before the prepare-funcs are called (has access to data)
preview->{page}
preview->{all}
preverify->{page} .. before the verify-funcs are called (has access to data) specific for a page
preverify->{all}
postverify->{page} .. after the verify-funcs are called (has access to data) specific for a page
postverify->{all}
note that all is called before page !!! If you dont like this you need to change the source or add the func to each ->page
note that per default each function can access all fields that were
defined in ->$ptr->{fields}. This is also true for show-function even
when not all fields will be displayed in the overview. This can make
overview really slow, so you can select only to query a subset, but
then you need to take care that your show-funcs only accesses elements
that are in this subset. It has also proven as very useful if this
subset at least contains the fields that should be displayed in the
overview.
a common statement in the config therefore is :
$ptr->{showsqlfieldnames}=$ptr->{autotemplates}->{show}->{fields};
C) extra funcs
this are the action-funcs, that are defined in a different branch.
And then we have
$ptr->{func}->{scheduler}->{task_id}='funcname';
$ptr->{func}->{def}->{funcname}=sub{ ...};
returnvalues of funcs:
fieldfuncs can change the value of fields and can check the value and
return errors if the value is not what it is expected to be. Checking
the value makes only sense in verify-functions before saving.
A function should always return 0 unless there was an error. In that
case it should return the error as
[error-id,parameters].
If an error relates to more than one field or the func itself is not
related to a field (ie. preverify->{all}) then the func should return
an anonymous hash like:
field1=>[error,params],
field2=>[error,params],
...
====================
defaultfuncs
func->preshow->_init_
setorderclass : change the class of the showloopheaderFIELD to
showloopheaderorder for all fields that appears in the ->order
======================
field-defs:
$ptr->{fields}->{name}={ ... }
-type : 'view'
'text'
'hide'
'file'
'sel-popup'
'sel-scroll'
'sel-multiscroll'
'sel-radiogroup'
'sel-checkboxgroup'
'sel-checkbox'
'multi'
-size_x
-size_y
-title
-dummy : if set then this field is not in the database
-value : its value :) (which is overrode by the module most certain with the real value)
-valuefunc : a func that returns the value (override with -value)
-name : its name - defaults to name
-default : its defaultvalue if creating a new entry
-values : for sel-types
-values=>[val1,val2 ...]
-labels : for sel-types
-labels=>{val1=>label1,val2=>label2 ...}
-multiparamsep : defaults to $ptr->{multiparamsep}
-url : for file-types : weblocation
-path : for file-types : absolute path
-subfields : for multitypes
-subfields=>[field1,field2,field3]
each of these fields must be a fully specified field and can have attributes and all. Note that this field of course needs to have set -dummy=>1
-empty : for multitypes : number of empty fields to display
-attributes=>[a1,a2...]
where attributes is merely a set of functions that will be processed
according to this fields (->funcs)
each attribute is an anonymous array with two or three
elelements.
[categories,function,arguments]
categories are spvir were s is for show, p for prepare, v for verify,
r for preview and i for the experimental integrity (for multipage
only). See ->funcs for details.
function is the name of the function to call and arguments are
potential arguements to this function.
If arguments are ommited then no arguments are passed and if you
specify a string than this is interpreted as ['v',string]
note that each type defines a defaultattribute ['v','type-$type'] that
is usually processed after all attributes. If you want to process it
at a different position, just add a attribute named '-' at the
position you like.
============================
fieldnames
each sql-valid name is allowed as fieldname
however there are some names that should be avoided cause they are used for internal purposes:
del-xxxxxx
multi-xxxx
session key
=============================
classes
the following text applies to autotemplates. It is wise to use the same classes in your own templates !!
the design is widely driven via css.
each element gets its own css-class assigned that the designer can
edit in its css-file. The names of the classes are of course defined
in the templates. One can use whatever names it likes. There is a
template-element "class" invoked as [% class(name) %] which is
replaced by a full class-statement and the actual style is taken from
ptr->class->name. This values can be changed in your funcs.
By now only on one occasion the CMS itself alters classes. If an error
occures during a verify-process, then the following statement is
executed:
$ptr->{class}->{'edit'.$fieldname}=$ptr->{templates}->{css}->{error};
where the latter is set to 'fielderror' by default. Note that this
hardcoded assignment should be replaced by some better solution in
later versions.
If using default-templates or templates based on defaulttemplates then
the following conventions are used:
two types of classes:
i) configuration-independet i.e. : showloopheader or showloopline
ii) configuration-dependent i.e. : showfield1
note that there is a possibility to change the class for a certain
element. so its possible to assign the class 'showloopheaderorder' to
the element 'showloopheader' if the current element determines the
order. you got the point. (see $ptr->{class})
the name of classes are concated parts:
part1:
show
view
edit
showlooptable ... the table table
showloopheader ... the names of a column tr td a
showloopline ... the current line tr
showloopfooter ... the names of a column tr
showlooplineempty ... empty rows tr td
showloopheader$FIELD$ ... the name of a column td
showloopline$FIELD$ ... the value of a field td
showloopfooter$FIELD$ ... the name of a column td
showloopspace ... the column that seperates two fields
showloopbutton ... the column where a button is printed
edittable ... the table table
editline ... the current line tr
edit$FIELD ... the current field td
edittitle$FIELD ... the current title span
==========================
tt-templates
[% val1 %] => val1
[% $val1 %] =>
[% "$val1" %] => val1
[% "val1" %] => 'val1'
[% '$val1' %] => '$val1'
[% 'val1' %] => 'val1'
==============================
field-lists:
the module handles several lists of fields for different purposes. You
dont need to take care about this fields (beside the searchlist), but if you do, you can
things speed up by significant factors:
$ptr->{fieldnames}->{NAME}
where NAME is
all : all fields - DO NOT CHANGE - calculated in ->process_descriptors
sql : all sql-fields (= all but not the dummies) - DO NOT CHANGE - calculated in ->process_descriptors. oid is added automagically if not defined as field
show : the fields that are fetched for overview.
default = $ptr->{fieldnames}->{sql}.
If you restrict this to the fields you want to
show and need in your showfuncs this can speed up the query even by
factor 10-100 if you can skip large fields here.
edit : the fields are processed per default when an entry is saved.
default = $ptr->{autotemplates}->{edit} without the oid
So this should be set even if you dont need autotemplates. If you dont set this you need to set the list by yourself.
search : list of fields that are searched if you perform a
standardsearch. From this fields a defaultfield
(coalesce(field1,'')||coalesce(field2,'')... ) is formed. You can
specify a more exotic defaultsearchfield by using
$ptr->{store_sess_parameter}->{extra_defaultfield} and ignore this
list. There is no defaultvalue for this list cause not all sql-fields
are compatible with coalesce and || :)
If all fields are, you can simply add a init-func that set search=sql if you want to search all fields (long list = slow speed !!)
============================
errormessages:
a errormessage is merely a template that can be filled with
parameters.
You can define several types of errormessages where each one has its
own template. (warning, usererror, systemerror ...)
Additionaly you can define a action for each errormessage, which can be:
0 .. continue
1 .. die
And finally you will set the errormessages itself. Each error has a unique id
$ptr->{errmsg}->{id}=[type,action,text];
$ptr->{errtemplate}->{type}=template;
Template contains the variable $$text where the text ist substituted.
The Template and the text can contain several other variables:
$a .. current authgroup
$c .. current config
$t .. current table
$u .. current user
$l .. current logfile
$f .. calling function
$m .. webmaster
additional parameters $1 - $9 can be supplied via the error-methode
error(id,params)
========================
configfile
the configfile is a perl-script that is loaded and processed. Note
that this is processed under eval to allow reread even under mod_perl.
If you want to insert other configs in your config, dont use the require or use-statement but use
INSERT file;
to avoid troubles under mod_perl. file must not contain any path but reside under the same path
when an error occures then the errormessage will specify the config
and the block and the line inside this block where the blocks are
seperated by the insert-statements. (Linecounting is just too expensive :)
========================
redactional-module
this module provides redactional functionality, which means that
certain users have different rights.
The module can be loaded in the configfile or the calling script
use goldfisch::genericSQL3::redactional;
and is activated by calling
goldfisch::genericSQL3::redactional::init_redactional($ptr);
It is fully controlled via $ptr->{redactional} and offers the new
action "perm_stat" to dump this structure.
Basically there are three additional fields in the table that are
necessary:
uid : uid of the creator of this entry
gid : gid of the creator of this entry
mod : flag that tells if this entry was modified by anyone different than the creator
This fields are defined as
$ptr->{redactional}={
entry_uid=>...
entry_gid=>...
entry_mod=>...
};
You can define this fields in your $ptr->{fields}-definition.
Otherwise these fields are defined automatically as view-types. If
not listed in fieldnames->{show} these fields are added automatically.
The permissions for a table are stored in a permissionstring which is described below and defined as
$ptr->{redactional}->{permission}=...
The module mainly defines a set of functions that will calculate the
needed values and apply them. Its only hard-coded connection to the
mainmodule is the method $ptr->is_allowed, which normally returns
1. The redactionalmodule defines a function
$ptr->{redactional}->{is_allowed} which is queried in $ptr->is_allowed
and its value is returned then.
---------
permissionstring:
privilege-target-allowed//action-target-allowed//...
R-A-523,567,987//A--87,987//R-623-987//R-O-A//C-Ou-A
You can define your own privileges, but per default the module knows
of the following:
R .. Read
A .. Add
C .. Change
D .. Delete
Re .. Release
target describes whose entries we are talking about. This can be a
group or one of the following. more entries are ,-seperated
A .. All
O .. Own
Ou .. Own if not modified yet
u:uid .. applies for special user
gid .. a gif
and allowed tells me what groups are allowed to perform this action on
entries created by target and is a group-list.
So the above example means:
Read - All - Groups 523,567,987
Members of Groups 523 and 567 and 987 are allowed to read all entries
Read - groups 623 - groups 987
Members of group 988 are allowed to read entries created by members of group 623
Add - ... - 87,987
Members of groups 87 and 987 are allowed to add new entries
Read - Own - All
Change - Own if not modified - All
kb/backend/raw.txt · Last modified: 2006/02/01 23:28