_____ _________ ________ ___ ___ _________ ________
/ __/ \_ ____/ \ ) | | | | \_ ____/ \ )
\__ \ | _)_ | __ _/ | | | | | _)_ | __ _/
___\ \ | \ | | \ \ \ \_/ / | \ | | \ \ solutions
\____/ /_____ / /_/ \ \ \ / /_____ / /_/ \ \
\/ \/ \_/ \/ \/
(c) Lada 'Ray' Lostak (c) Orcave (c) 2002-2005
Content:
Central Boozing System architecture
History:
05/18/2002 Ray - initial version
12/18/2004 Ray - glued together with PHP part of STLC
1.0 PHP Requies (dependicies)
-----------------------------
CBS required for work configured/running Text PHP extension. Required PHP settings:
short_open_tag=on
magic_quotes_gpc=off
magic_quotes_runtime=off
recomended:
variables_order="GPCS"
register_globals=off
1.0.1 Sessions
--------------
At client side stores 'cookie' or 'url variable' -> 'client session id'. Both form uses string form. Session ID
(in context without table it refers to client one) consists of following parts:
1. random number (generated for every request - unimportant number - just to send cipher in some random way)
2. "stlc" (sign)
3. SessionID (see down)
4. Request ID
5. related URL hash
6. params
Parts 1,3,4,5 are stored in 'binary' (chars 00-ff)
4+5+6 ciphered by per request cipher private key
1+2+3+4+(4+5+6) ciphered by private server cipher key
Parts are stored as 'text', delimited by '@' char. Parts can't include '@' char. Because of it, in params,
'%' char is special. After this char follow 'real' one. So, %@ mean 'real @' not delimiting @. Ofcourse, any
% char is encoded to %%. Params doesn't need to be URL encoded (% char) itselfs.
Whole 'parameter' consits of 6 parts is converted to 6 bit hex form.
Server protects IP address (optionally), client, etc. It also detects connection hijacking, by request
ID change. It allows only request ID "+1" (next one) or "-3" (previous), but not other jumps. Also, time
of generate session/request ID need to be earlier than 'time limit'.
1.1 Database
------------
1.1.0 SESSIONS database tabl
------------------------------
Table holding all openned connections (=sessions) and informations about them.
Columns:
[int] id - unique session ID
[int] address - client IP address
[string] addressdns - clinet DNS address
[string] browser - exact browser version
[string] cipherkey - text form of random cipher key (hex)
[string] clprotocol - client protocol: http/https/terminal
[string] cllocale - client locale name
[string] cllocalediff - clinet locale differences - table
[time] cllogintime - clinet login time (GMT)
[int] cltimezone - client time zone
[int] userid - physical system user ID, when logged
[int] flags - connection state flags
STLC_CONN_FLG_LOGGED user sucesfully logged (if this bit is clear, session is not fully 'valid' !)
STLC_CONN_FLG_WATCH connection is watched
STLC_CONN_FLG_AUTH_IN_PROGRESS autentification is in the proccess
[string] sauthtype - session autentification type (if auth requires more requets)
[string] sauthstate - session authentification state
[timestamp] screation - session creation time
[int] srandom - session random number
[timestamp] lastreqtime - last request time
[int] lastreqid - last request ID
[string] lastreq - last request - in encoded form (last 'different')
[string] pernvars - pernament variables (URL form)
1.1.2 system USERS table
------------------------
While logging into system STLC have to access 'USERS' table to verify access.
Columns:
[int] id - system unique user id
[int] flags - user account state
STLC_USER_FLG_LOGIN_STATIC user uses static login
[string] loginplaces - comma delimited login places
[int] treenode - tree node
[string] alias - alias
[string] aliasfull - alias including tree path
[string] comment - user coment
[string] passwd - MD5 password hash
1.1.4 GROUPS table
------------------
Table containing information about groups.
Columns:
[int] id - physical group ID
[int] treenode - tree node
[string] alias - alias
[string] aliasfull - alias including tree path
[string] comment - user coment
1.1.4 GROUPSASSIGN table
------------------------
Physical group assign
Columns:
[int] userid - related user
[int] groupid - member group
[int] origingid - if group is assigned throw nesting to user, then this is origin grroup
1.1.4.2 GROUPSNESTING table
---------------------------
Groups nesting
Columns:
[int] groupid - group id
[int] nestgroupid - nested group (nested inside ^)
1.1.5 LOGINPROTECT table
------------------------
Login dictionary attack protection table.
Columns:
[string] NameId - related user name (ID not used because we don't want to allow guessing
real UserId -> on bad UserId will not be displayed 'timeout error')
[timestamp] LastTime - last guess time
[int] Delay - current delay
[int] Count - guess count
[int] Address - first reques client IP
1.1.6. ACL table
----------------
Table contain ryles for controlling access. Every rule can be asigned to one or mroe users/groups. Every
rule can contains zero or more constraints. Rules are always test across physical user. So, in other words,
it always reply question: "What access have user XX for action YY" ?
Columns:
[int] id - unique rule Id
[int] treenode - tree node
[string] alias - alias
[string] aliasfull - alias including tree path
[string] comment - user coment
[int] flags - flags
global - valid for all users
1.1.7 ACLRULES
---------------
Physical ACL rules assigned to 'acl' groups.
[int] id - unique rule ID
[string] alias - rule alias
[string] comment - rule comment
[int] aclid - acl group reference
[int] acltypeid - acl type id ref
[string] val - rule 'values' - comma delimited list
[int] flags - rule flags CBS_ACL_RULE_FLG_*
[int] groupflags - group flags (copy of ACL.flags)
[int] result - result
[string] aclinfomod - acl module origin
[string] aclinfoalias - acl module alias
[string] aclinfoaliasfull - acl full alias in form module@rule_alias
[int] aclinfoflags - acl flags
[int] aclinforesult - acl result type (higher number, higher prior by default)
da - denided/allowed
drw - denied/read/write
drwa - denied/read/write/admin
[int] aclinfoobject - related object type
user - user ID
group - group ID
modules - system modules
...
[int] aclinfoval - value type (copy from objectinfo)
int - related values are integers (id's)
string - related values are strings (alaises)
mask - related values are strings masks (tree.path.item,tree.path.* ...)
...
1.1.7b ACLUSERTYPES
---------------
Holds user & system ACL rules (system generated form module info and hidden while edditing)
[seq] id
[int] treenode - tree node
[string] alias - rule alias
[string] aliasfull - rule full alias
[string] comment - rule comment
[string] description - rule description
[string] origin - rule origin moule@rule
[string] i_alias - full valid rule alias in form origin@alias - user rules origin: '$user'
[string] i_results - table of results, columns: value,alias
[string] i_objecttype - object type in form origin@object
[int] i_objectvaltype - object value type CBS_ACL_OBJECT_VAL_TYPE_*
1.1.8 ACLASSIGN table
---------------------
Physical ACL assign
Columns:
[int] aclgroup - ACL rule reference
[int] scope - scope type (user/group ID)
[int] scopeparam - parameter
[string] scopeparamtxt - parameter (text based)
Scopes:
group - access related to group, scoppParam is group ID
user - access related to user, scopeparam is user ID
1.1.9 Login places - PLACES
---------------------------
IP's addresses dictionary
columns:
[int] id serial
[int] treenode tree node
[int] userid user id, if record is user-specific (-1 if non-specific)
[string] alias alias
[string] aliasfull alias including path
[string] comment user comment
1.1.10 Login place's addresses - PLACESADDR
-------------------------------------------
IP's addresses
columns:
[int] id ip serial
[int] place related place
[char.8] type place type
IPv4 - IP version 4 address
[char.64] ip IP address itselfs with mask
[string] dns DNS name
[int] flags ip flags:
active - record is 'active'
reverse - reverse is required
matchrev - reverse and forward have to match
matchdns - DNS have to match (* ? can be used)
matchip - IP address with mask have to match
[string] comment comment
1.1.11 SESSIONSWATCH database table
-----------------------------------
Table used to online session watch (not used for logging)
Columns:
[int] sessionid - session ID
[txt] reqprofile - request profile timing
[txt] reqsql - request SQL commands
[txt] reqparams - request parametres
[txt] reqpost - request post parametres
[timestamp] reqstart - start request time (absolute)
1.1.12 CBS user profile - PROFILES
----------------------------------
CBS user profile contains CBS related information about user.
columns:
[int] userid STLC user ID
[string] nametitle Title before name
[string] namefirst First name
[string] namemiddle Middle name
[string] namelast Last name
1.1.13 Photos - PHOTOS
-----------------------
Separate table with user photos
columns:
[int] userid STLC user ID
[string] type MIME type
[bin] photo User photo :)
1.1.14 Companies - COMPANIES
----------------------------
Base info about companies
colums:
[int] id unique company ID
[int] treenode tree node
[string] alias alias
[string] aliasfull alias including tree path
[string] comment user coment
[string] name simple company name
[string] namefull full company name
[string] addresspost post address
[string] address official address
1.1.15 Tree structures
-----------------------
Common tree structures
TREES table holds tree skeletons
[int] id tree node
[string] tree related tree name (table name)
[string] alias node alias
[int] parent parent tree node (-1:root)
[string] comment node comment
1.1.16 Long prorgesses
----------------------
Long action reports to users its progress
PRORGESSES table holds relevant progresses
[seq] id record ID
[int] progress current progress 0-100
[txt] name 'name' of progress
[txt] comment 'comment' of progress
[txt] pernvars additional variable for template in form name=value&name2=value..
[txt] dstlink destination address
[txt] logdetails log details ('new' text only which need to be send to client)
[timestamp] timestart progress start time
1.1.17 SESSIONSMSGS session messages
-------------------------------------
Table for sending messages between sessions
Columns:
[int] id - msg ID
[int] srcid - source session ID
[int] dstid - destination session ID
[string] msgtype - message type - module.msgtype.subtype....
[string] msgparams - message params
1.2 Autorizace
--------------
Autorizace muze probihar radou zpusobu. Nejzakladnejsi (tzv. static login) pouziva staticke heslo.
-> uzivatel (program) zasila
<- odpoved server
Samotna autentifikace probiha na urovni nejakeho protoholu (HTTP, SAUTH, ... ) takze fyzicka implementace a prenosy
mohou byt rozdilne protokol od protokolu. Veskere znaznorneni komuknace nize je pseudokod. Fyzky muze probihat prez
formular, XML, ...
Vysledek autorizace je vytvoreni prislusne session ID.
1.2.0 Klice & certifikaty
--------------------------
CBS obsahuje samostatnou cast, kde se defunuji klice - at jiz simetrycke, nebo asymetircke a pod. Klic se
odkazuje aliasem, platny v modulu. Specialni jmena klicu zacinaji '$'
Aktualne se rozpoznavaji tyto specilani klice:
$pass_md5 - md5 ze statickeho logovaciho hesla.
Pokud referencovany klic/certifikat neumoznuje pozadouvanou akci (podpis, ...) pripadne neni validni, server
generuje chybu.
1.2.1 Code book [code_book]
----------------------------
-> 'code book identifikator' (jez je sprazen s jeho user ID)
'heslo' pro svoji kodovou knizku
pokud dana kodova knizka existuje a heslo je spravne, vznika 'session' (ve fazy auth)
<- server zazada o konkretni kod na radku/sloupci
-> kod
<- error/vytvoreni session
O kazdy kod se zada pouze jednou, po pouziti vsech kodu prestava byt code book platna. Code book ma take
omezenou platnost datumem. Neni dobre si psat heslo na code book :)
Uzivatel zlvadne cely proces 'sam', komunikace probiha na urovni HTTP formulare.
1.2.2. Kryptovani pomoci symetrickeho klice [skey_sign]
-------------------------------------------------------
Tento typ logovani neni urcen jako 'secure' - ale jako automatizovana nahrada logovani pomoci programu
v nezabezpecenem kanalu (typicky telnet, http, ...)
KNAME - jemno klice, pomoci ktereho se chce klient autentifikovat (viz 1.2.0)
UNAME - user name
DIGEST - nahodny klic (server)
RND - nahodne cislo
[..] - kryptovano pomoci
ALG - sifrovaci algoritmus name.keylen (blowfish.128)
Delka klice a pouziteho cipher algoritmu se musi shodovat.
-> UNAME KNAME
<- DIGEST ALG
-> RND DIGEST [DIGEST+klic]
<- error/vytvoreni session
Session vnika az uspesne prokazani identity uzivatele.
XML definice autorizace
->
reb909
$pass_md5
<-
BASE64 encoded data
blowfish.128
->
[signed data]
<- status (v ramci auth)
'Signed data' je v tomto pripade mysleno encodovani pomoci zvoleneho algoritmu a tajneho klice.
1.3. Terminal
-------------
CBS umoznuje pristup ke svym funkncim pomoci 'terminalu' coz je plne negraficke prostredi. Ne vsechny funkce
vsech modulu jsem prez terminal dostupne. Veskera komunikace probiha na urovni XML, server-client stylu.
Predpoklada se probehla autentifikace uzivatele a pripadne zbudovani sifrovaneho kanalu, at jiz pomoci
SSL vrstvy, ci vhodne vymeny klicu.
Transportnim protokolem muze byt napr. protokol HTTP - kvuly pruchodnosti PROXY/firewallu a pod. Nasledujici
popis se zabiba 'dotazem' a 'odpovedi'. Jakym zpusoben je predan, je vec druha. Server muze klientovy zasilat
notifikace.
Jako protokol se pocita 'XML' predavany v klasicke textove podobne (odelovac radku muze byt DOS/UNIX/WIN).
1.3.0. Komunikace na urovni terminalu
-------------------------------------
Po navazani konexe je klient neautentifikovan. Nektere akce vyazduji autentifikaci, jine ne. Typicky priklad
akce, jez nevyzaduje autentifikaci je autoentifikace samotna :) Komunikace muze byt sifrovana na urovni
terminalu (symetrickymi klicemy) nebo na urovni SSL HTTPS ci pod. Server muze odmitnout splnit pozadavky
klienta, pokud komunikace nebude sifrovana. Komuniace je plne asynchonni, za klienta se povazuje ten, kdo
zasila pozadavek. Server je pak zpracujici. Fyzicky muze byt server jak server tak klient (pokud je server
inicializacni clen)
Obecny format odpovedi je
kde "ok" je minen stav 'v poradku'. Tento zakladni tag je suocasti KAZDE odpovedi
Obecny format requestu je
V nasledujim textu nebudou tyto root elementy uvadeny.
Autentifikace
-> navrh autentizacniho protokolu
skey_sign
<- status
Nasleduje kompletni dialog nutny pro autorizaci klienta. Klient veskere sve pozadavky
vklada to elementu
vice viz 1.2.2.
auth se ukoncue ze strany serveru
->
welcome
ci
denied
Zasifrovani komunikace
-> navrh sfrovaciho algoritmu a klicu
encryopting algo
key alias
Klice viz 1.2.0. Typ klice zavisi na algoritmu, parametr neni povinny.
<-
nahodny klic v BASE64 formatu
---> veskera dalsi komunikace je jiz kryuptovana dohodnutym algoritmem
fyzicky klic vnika kombinace digestu a klice, dohodnuteho prve
na zacatku kazde komunikace se zasila 32-bit radom cislo
->
ok
CBS gateway
->
...
...
xxx
value BASE64 encoded
...
<-
data_block_name
BASE64 encoded result
...
Terminalove akce viz CBS.
Uzavreni konexe
->
<- uzavreni spojeni
Notifikace klienta
<-
...
->
ok
Keeping alive - klient musi pravidelne davat serveru na vedomy svou existenci
->
<-
Server muze kdykoliv klienta pozadat o overeni trvalosti spojeni
<-
->
Zmena klicu
jak klient tak server mohou kdykoliv zmenit aktualni klice. Server klice meni standardne jednou za
30 minut.
nahodny klic v BASE64 formatu
Vypocet realneho klice je stejny jako pri prvotni sifrovani komunikace.
Druha strana odpovida
ok
1.3.1. Bugger
-------------
Bugger pouziva ke sve komunikaci vyhradne XML. Bugger (mineno protokol) je v zasade pouze 'cesta' k CBS
terminalu.
Pred samotnym XML telem dotazu/odpovedi Bugger zasila/prijma dodatecne hlavicky. Obecny format hlavicek
je
jmeno-parametru: value
Na kazdem radku je prave jeden parametr. Konec hlavicek se znaci samotnout 'teckou' na radku. Pote jiz
nasleduji fyzicka data. Pro prenos dat je _NUTNE_ znat jejich delku. Za ":" pred hodnout parametru muze
byt zadna a vice mezer.
Server nemuze poslat request klientovy asynchonie. Pokud server zada po klientovy request (napr. zasila
zadost o vymenu klicu, event, ...) musi si na protokolove vrstve sjednat 'notify'. Notify se sjednava
ve hlavicce jakehokoliv request. Klient musi byt shcopen noptify rozpoznat v jakemkoliv okamziku. Server
niktera neceka na odpoved ci potvrzeni. V hlavice chodi notify dokud si klient 'nevyzvedne' veskere
requesty jemu urcene. Vyzvednuti hlavicky je v zasade reqeust klienta. Jediny rozdil je v tom, ze
server po zasladni 'odpovedi' na tento request (jez ma telo praznde, pouzivaji se havicky) ocekama
plnohodnoutnout odpoved.
Hlavicky zacinaji 'server' pokud jsou urceny pouze pro server, 'client' pokud hlavicka ma vyznam jen pro
klienta. Pokud nezacina nia jednim, je to oebcna hlavicka.
Aktualne zname hlavicky obecne:
contents-length: XXX
kompletni dela predavanych 'dat' (v bajtech)
request-status: XX YYY
chyba na urovni GG protokolu XX je decimlani cislo chyby, YYY pak textove vyjadreni. YYY je
nepovinne. Server vzdy zasila status. OK znaci 'v poradku'.
Aktualne zname hlavicky zasilane klientem:
server-draw-queue: TYPE
klient si preje vyzvednout svou frontu pozadavky. TYPE:
all - vsechny zaznamy
server-client-version: V
client zasila svou verzi GG protokolu serveru
vyznam ma jen pri navazovani konexe
Aktualne zname hlavicky zasilane servrem:
client-queue-notify: length
server zasila notofikaci klientu o delce fornty requestu, urcene pro klienta. Delka
je decimalni cislo.
client-timed-out: XX
timeout clienta XX je cas v ms, za ktery server resetue konexy. Po teto hlavicce
server ukamzite uzavira spojeni.
Server prizpusobuje sve CR/LF klientovy, ktery urci z prvniho requestu.
Pokud radek hlavicky zacina cislem - je tento radek IGNOROVAN (jak server tak klientem). Slouzi k zasilani
nahodneho cisla pro zvyseni bezpesnoti (horsi predikce klice).
Po pripojeni klienta k serveru klient zasila 'server-client-version' hlavicku. Data nejsou zasilana zadna.
Server pak odpovida pomoci request-status. Opet se nezasilaji zadna data. Pokud zde server zasle stav 'OK' je
prirpaven splnit kientovy kazde pravni, napr. 'rm -rf /'
Pokud nejsou prenasena data, musi se ukoncit 'header'. contents-length se mzue zaslat s delkou 0
Dodatecne hlavicky u GG existuji proto, aby se lehce dal prenast XML obsah bez nutnosti dopredne parsovani
pred prenesenim a pod. Je nutno podotknout, ze GG protokolovou vrstvu ovlivnuji i terminalove akce (napr.
zmena klicu). Terminal je uzce spjat s GG protokolovou vrstvou. Na GG protokol se lzde divat pouze jako
na transportni vrtvu.
To ze server vrati 'request-status' OK znamena, ze akce byla provedena - nepredukuje ale vysledek akce,
ktery bude dodan jako XML obsah. Na to pozor...
1.4. Data types
---------------
Various modules uses various types, but 'data types' are shared acros whole CBS. Not all datatypes are
support in all parts of CBS. Data types may be added by modules, so, real list of supported data types
depends on installed modules. 'core' module origin mean data type comming directly from 'data' module.
Core
Type/attrib | Comment | Addon | Type val | Type comment | User editable value
------------------+---------------------------------+-----------+-----------+---------------------------+-------------------------------------
id | text alias | | - | | alias
int | integer value | | - | | value
text | single line text | | - | | text
len | average text length | | int | | -
maxlen | max text length | | int | | -
textblock | block of text | | text | | text
rows | | | int | | -
cols | | | int | | -
link | link | | - | | var=value&var2=value2...
file | file reference | | - | | binary data
maxsize | | | int | | -
set | set of 'values' | | list | alias,col,col2...|... | 'set of'
select | select from 'values' | | list | alias,col,col2...|... | 'combobox'
ref_data | data reference | | list | dataid|filters|sort | data selection, filer/sort customization
dtd | referenced dtd | | int | | -
refs | resolve references | | list | itemid,itemid2,....... | -
customizable | customizable | | int | | -
ref_data_rec | data record reference | | list | dataid|recorid | data record selection
dtd | referenced dtd | | int | | -
refs | resolve references | | list | itemid,itemid2,....... | -
customizable | customizable | | int | | -
filters | filters | | list | filter1,filter2 | -
key | key reference | | list | dtd,cluster,col | table row selector
name | link name | | text | simple tpl | -
keysoft | soft key reference (Db layer) | | list | dtd,cluster,col | table row selector
name | link name | | text | simple tpl | -
float | soft key reference | | - | | float number
precision | | | int | | -
fraction | | | int | | -
momentary | momentary | | - | | momentary value
name | | | text | | -
symbol | | | text | | -
seq | auto increment | 2 | - | | -
folder | user 'folder' | 1 | - | | folder
fork | data fork | 1 | - | | fork
forkfolder | folder created by parent fork | 1 | - | | fork folder
WWW module
link | www link | | - | var1=val&var2=val2.... | 'link' editor (for CBS, external link just edit)
[1] supported only by 'tree data cluster'
[2] not avilable directly to user
Additonal infos
---------------
ref_data - value 'dataid|filters|sort'
dataid - integer
filters - , based list of: item_alias:value
sort - , based list of: item_alias
1.4.1. Type implementation callbacks
------------------------------------
All types have roots in some 'module'. Every module exporting types should export few functions. Naming convention:
[handler][operation]
Where handler is 'type' handler (info block). If handler not defined by type(s), standard form 'modPub_[modalias]_data'
is used.
Known operations and parametres:
item - ony physical item
items - items array
in - unput data (table)
out - output data (table)
attribs - item(s) attributes
addonpar - additional parametres (depending on caller module, various types expect various addonpars)
currec - current record
edit - 'edit' flags
add - 'add' flag
bad - 'error' output identifier
Operation over DTD
TypeCheck &$st $datatypeinfo &$attribs &$addonpar
TypeView &$st $datatypeinfo &$attribs &$addonpar
Operationes over physical TABLE (record set)
DataLearn &$st &$items &$addonpar
DataView &$st $items &$out &$in $addonpar $attribs
Operation over physical RECORD content
DataValView &$st &$items $edit $add $currec &$addonpar
DataValCheck &$st &$items &$addonpar &$val &$bad
Details
TypeCheck
check 'posted' DTD attributes edit
TypeView
prepare 'view' DTD attributes
DataLearn
learn data for template
DataView
view physical table rows
DataValView
prepare physical record view
DataValCheck
check posted 'values' of record edit
before this fn is called DataValView (for preparing value selectes/...)
2. Modules
----------
CBS is divided into module. Every module export set of function. All functions starts with prefix
followed by _ and module alias - for example: modInfo_admin. Basic module exported function:
modInfo - returns module information
modEvent - global CBS event handler
modGo - module 'main'
modGo_xxx - module 'action' where xxx is action alias.
All of these functions ofcourse includes also module alias - like modGo_admin_users.
Every module consists of few files. These files are lcoated at CBS home in directory with the name
by module alias. Inside this directory should be placed all files required by module, except templates
and otehr user editable/costomizable files. Folder contains these files:
CbsMod_x.php
CbsMod_x_y.php (more files)
x means module alias, y action (see down). There should be more files with action. Only first action
is used to build 'file name'. If action is equal to 'index' it is ommited out.
Info contains static info about module - alias, table names, ACL rules and similar. Main file
should define shared procedures, infos and events handlers.
2.0. WWW module
---------------
Www module cosists of few indepenend parts:
1. Pages tree
2. Templates tree
3. Macros tree
4. External files tree
Tables:
WWW main web properties (side table for DATA)
[int] id side-reference to DATA
[int] cachetype general caching policy
none
template
output
[int] extfaccess external file access - bit oriented
local_fs
local_fs_wrap
local_fs_http
[string] extflfsstorage external file local fs storage path
[string] extflfswraper HTML wraper @ physical web tree
[string] extflfsfolder physical web folder access URL
[string] extflfs
WWWHOSTS
[int] id host id
[int] www WWW reference
[string] host full host name
[string] hostbase host base URI
[string] birth start page
[string] runuser running user (alias)
[string] runuserpass running man password (plain text)
[string] logpath log path
WWWEXTFILESGROUPS external files groups (tree based)
[int] id id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[int] flags flags
public - file avialable 'directly' without CBS login
WWWEXTFILESCONTENTS
[int] id id
[int] extfgroup extern files group reference
[int] extfdedicated copy of EXTFILESFOLDERS.dedicated
[int] extgroupflags copy of EXTFILESGROUPS.flags
[string] alias file 'alias'
[string] aliasfull full file 'alias' (including 'extfilesgroup' full alias)
[string] comment user comment
[data] content file contents
[int] contentsize file size
[string] contentmd5 file MD5 hash
[string] contentmime mime type (empty: original, $std -> system standard for given extension)
[string] origfilename original file name
[string] origmime original mime type
[string] attribs file attributes in form "attrib=val&attrib2=val2"... where val is url encoded.
Www DTD contents:
PAGESTREE extending std folder members
[string] navcaption navigation bar caption
[string] navlink navigation bar link
[string] brcaption default browser caption
[string] expcetionxlt expcetion translation table
[int] cachetype cache type
default
none
template
output
PAGES physical pages (tree based)
[int] id id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[string] navbase navigation base (generated from parent folders) in form caption|link|caption|link....
[int] template root template
[string] caption browser caption (empty=>default)
[int] cachetype cache type
default
none
template
output
PAGESITEMS pages template variables/data sources
[int] id id
[int] page related page
[int] template related template
[int] templateitem related template itemid
[int] templateancestor related ancestor template id
[int] parent parent item (at PAGESITEMS)
[int] class item class
private - do not allow link change this value
public - link is abble to change value
publicreq - link us abble and have to fill value
[string] val property value
[string] path item 'path' (empty for root items)
[int] valuser nonzero if 'user' value, otherwise template 'default'
[int] itemparent parent template item (if structure from TEMPLATEITEMS have 'tree') - only 1 level
[int] itemancestor item ancestor
[int] itemtype item value type
[string] itemattribs item value attributes in form item:value,item2:value2,.... value is urlencoded
[string] itemalias item alias
[string] itempath item path
[string] itemname item name
[int] itemclass item class
[string] itemcomment item comment
[string] itempreparerl item preapre runlevel
All item* are copy of relevant TEMPLATESITEMS/TEMPLATESITEMSVALS records
PAGESCACHE pages caching
[int] id id
[int] page related page ID
[int] cachetype cache contens type
output
template
[timestamp] creationtime cache record creation time
[string] paramshash parameter hash (params in raw form, alphabetically sorted)
[string] params parametres for page itselfs INCLUDING stlc/cbs itselfs (alphabetical order)
[string] contents cache contents
TEMPLATES physical templates (tree based)
[int] id id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[string] body template body
[string] macros coma based list of reuqired macros ID's
[string] morigin module origin in form module@alias
[string] itemsrelations item relations - table: source, destination, sub-destination, type
special sources: $( $) $OR $AND
TEMPLATESITEMS template properties
[int] id id
[string] alias template alias (also TPL 'learn' base)
[string] name name
[string] comment comment
[int] template related template
[int] parent parent item (at this table)
[int] ancestor 'real' item (root item points to themselves !)
[int[ type data type
[int] class item class
private - avilable only within template
public - avilable at pages/layouts
publicreq - avilable at pages/layouts and require to be filled
publicstat - public, but not available for changing
[int] flags item flags
render - item comes form render
nested - item is nested by some other template inclusion
[string] val value (default/user)
[string] valuser value is user
[string] preparerl prepare run level - empty: never, * default
This table holds 'tree' structure of items. Primar items (root), always 'root' ones (parent=0) have coresponding
records in TEMPLATESITEMSVALS. Child (nests) doesn't have attributes. There are 2 kinds of childs:
render - created by template renderer. Ancestor not used.
nested - physical 'tree' nested items. All columns are COPY of 'orginal' (root) items. Ancestor points
to root item directly from all levels. For other parts nested items are 'normal items'
TEMPLATESITEMSVALS template item values (attributes)
[int] id id
[int] item property reference
[int] attrib related attribute
[string] val value
MACROS (tree based)
[int] id id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[int] mtype macro type
single
multiline
multibody
[string] body macro body
for multibody macro parts START END BODY delimited by {~!~}
[string] bodystart macro pre-body
[string] bodyend macro post-body
[string] name template name
EXTFILESGROUPS external files groups (tree based)
like WWWEXTFILESGROUPS (but for private using)
EXTFILESCONTENTS
like WWWEXTFILESCONTENTS (but for private using)
BOOKMARKS bookmarks groups (tree based)
[int] id id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
BOOKMARKSLINKS physical bookmarks links
[int] id id
[int] bookmark bookmark group (tree node)
[string] alias alias
[int] btype bookmark type
external (http, ftp, ....)
www (internal WWW module)
cbs (CBS valid link)
[string] body bookmark body
EXCEPTIONS exceptions
[int] id id
[string] ealias exception alias
[string] ehandler exception handler
[string] comment user comment
DRAFTLAYOUTS drafting layouts tree
[int] id id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[string] explains layout legend - delimited list {~!~} and {~$~} : name and contents
[string] items editable items for this layout similar list : name,x,y
DRAFTSTRUCTURE drafting structure and texts
[int] id id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[int] layout layout reference (0->none)
[string] explains layout legend - similar to DRAFTLAYOUTS.explains (local)
[string] items item contents - contents {~!~} list of DRAFTLAYOUTS.items
RUNLEVELS holds all available template runlevels
[int] id id
[string] alias run level alias
[string] comment run level comment
[int] execprior priority [0..smallest]
[int] execdata non-zero means 'prepare' data BEFORE runlevel is executed
[int] execoutput non-zero means runlevels vomit 'output'
[int] defrunlevel non-zero means 'default runlevel' (when template do not specify some)
[int] autochilds auto call child tempaltes
XMLTRANSFORMS
[int] id tranform ID
[int] treenode tree node
[int] tplcontext template context run
[string] alias tranform aliaas
[string] aliasfull type alias including path
[string] comment user comment
[string] body all transformation - delimited by {#@#} and {#!#} order: elements,condition,flags,body
XMLTRANSFORMSRULES
[int] id rule ID
[int] rtransform rule tranform group
[string] rcomment rule comment
[string] relements comma delimited realted tags
[string] rcondition rule condition
[string] rflags comma delimited flags
own child process : rule process its element child by hand
[string] rbody transformation body
[string] rbodyclose transformation body closing
2.1. Data storage
-----------------
Data storage module manages 'dynamic format' datas. Both parts - data type deffinition and datas itselfs.
"dtd" table holds physical data types.
[int] id data type id
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[string] morigin module origin alias
[string] malias module - type alias
[string] mname module - type name
[string] mcomment module - type comment
[int] mflags module - flags
dynamic - user is allowed to add new items
private - do nto allow 'edit' any fields directly
"dtdclusters" table holds tables and trees
[int] id table id
[int] dtd data type id
[string] alias item alias
[string] name item caption
[string] comment item comment
[int] flags item flags
private - module private - modifing allowed, but all edit disabled
fixed - fixed, items can't be deleted/changed, edit allowed
user - user table
customrecs - user allowed to add new records
[string] iinfodst cluster origin in form module@alias
[string] ciinfo cluster intem info destination: data_id.cluster
[int] type cluster type
table - table
tree - tree based structure
"dtditems" table holds data 'items' (columns/nodes)
[int] id item id
[int] cluster data cluster reference
[int] parent parent item (0 -> root)
[string] alias item alias
[string] name item caption
[string] comment item comment
[int] type item data type (see data types)
[int] typeflags item type flags
req - required
[int] flags item flags
private - module private (do not allow edit)
fixed - fixed item, can't be deleted
user - user columns
system - system column
[int] viewprior view priority (higher -> more to left)
"dtdattribs" holds specific data item values
[int] id attrib id
[int] item related item id
[int] attrib attribute
text_max_len
textblock_rows
textblock_cols
table_ref
file_max_size
set_default
select_default
[string] val 'value' (valid only for some atribs)
"data" table holds assigned physical datas to dtd
[int] id data type id
[int] dtd DTD refeence
[int] treenode tree node
[string] alias type alias
[string] aliasfull type alias including path
[string] comment user comment
[string] keys foreign keys in form src_table:src_col:dst_table:dst_col,....
[string] dtdcontents dtd contents while creating in form
cluster_alias:type:flags,item_alias:type:flags:typeflags:parent,item2:type:flags:parent|cluster2...
DATA_X where X is in cluster ID holds physical datas
2.2. Languages
--------------
Multi language support. Uses 'TREES' for storing 'visual' groups
Static tables:
LNGLANGUAGES avilabel language list (global)
[tree members]
[text] name Language name visible to user ('common')
[text] namenat Language name (natural)
[text] isocode ISO language code
LNGS connection to DTD's
[item members from DTD - alias,aliasfull,comment]
[int] id DTD connection
[text] fileorigin Origin LNG file (related to CBS root)
[timestamp] filecnvtime Last LNG file conversion
[text] langs List of all involved languages
[int] langdef Default language
LNGTREE - sets trees
[standard tree deffinitions members]
[txt] aliasfull Full alias
core DTD:
STRINGS holds language 'identifiers'
[seq] id String Id
[int] groupid Text group reference
[time] modtime Modification time
[int] flags Flags
[text] alias String alias
[text] comment Comment
[text] commentparts Parts comment
[text] body Default body
STRINGSTRANS holds phsyical translations
[seq] id String Id
[int] stringid Text reference
[int] langid Language reference
[time] modtime Modification time
[uid] moduser Last modification user reference
[text] body Translation body
2.3. XML data type
------------------
XML data typ je datovy typ, ktery ma v sobe XML dokument presne definvoane struktury.
"dtdxml" main DTD XML storage
[seq] id XML id
[key] xml_treenode tree node (-> trees.id)
[string] xml_alias alias
[string] xml_aliasfull full alias
[string] xml_comment comment
[string] xml_vcontents XML DTD contents (for native this is generated column)
[int] xml_vtype vontents type: DTD_XML_TYPE_*
none (valid xml) => 0
xsd (XML schema) => 1
native structure => 2
"dtdxmlelements" XML elements
[seq] id element ID
[key] elem_xml owner XML (-> dtdxml.id)
[string] elem_name element name
[string] elem_model element model in standard DTD form (depends on modeltype), eg: (elem | elem2+)*
[int] elem_modeltype element (model)type, DTD_XML_ELEM_TYPE_* constant
normal (full model) => 1 PCDATA only
PCDATA => 0 normal element with model (except mixed)
mixed => 2 mixed (#PCDATA | elem | elem | ...)* - stored only elements
PCDATA with content type => 3 PCDATA includes valid CBS type
empty => 4 no contents
any => 5 any
[int] elem_valtype type id DTD_ITEM_TYPE_* if used [3] (note: this is not std DTD XML compatible, this is CBS enhancement)
[int] elem_flags flags, DTD_XML_ELEM_FLG_* (not yet used)
[string] elem_roles comma delimited roles of element (not used)
[string] elem_comment some cool text
"dtdxmlelementsvattr" value attributes of elements
[seq] id id
[key] item related item -> dtdxmlelements.id
[int] attrib attribute id (DTD_ITEM_TYPE_ATTR_*)
[string] val value of attribute
"dtdxmlattribs" XML attributes
[seq] id id
[key] attr_element related element -> dtdxmlelements.id
[string] attr_name attribute name
[int] attr_flags atribute flags DTD_XML_ATTR_FLG_* (not yet used)
[int] attr_valtype attribute value type (note: not all types are supported by std XML DTD)
[int] attr_type attribyte type DTD_XML_ATTR_TYPE_*
optional => 0 value is optional
required => 1 value required
implied => 2 value is optional, if missing use 'default' value
fixed => 3 value fixed in 'default' value
[string] attr_valdef default value
[string] attr_roles roles of attibute in system
[string] attr_comment some words
"dtdxmlattribsvattr" value attributes of XML element's attribs
[seq] id id
[key] item related attribute ->dtdxmlattribs
[int] attrib attribute id (DTD_ITEM_TYPE_ATTR_*)
[string] val value of attribute
"dtdxmlentitiesgrp" XML entities groups
[seq] id id
[int] entg_treenode tree folder
[string] entg_alias alias
[string] entg_aliasfull alias full
[string] entg_comment comment
[int] entg_global nonzero, if group is global
"dtdxmlentities" DTD entities
[seq] id id
[key] ent_group related entity group -> dtdxmlentitiesgrp.id
[string] ent_name name
[string] ent_comment comment
[key] ent_vtype user type -> key:dtdxmlentitiesvt
[string] ent_vcontents contents of entity
"dtdxmlentitiesvt" entities value types
[seq] id id
[string] entvt_name entity value type name (user type)
[string] entvt_comment arf arf
[int] entvt_vtype CBS data type id
"dtdxmlentitiesvtattr" value type attributes of entities
[seq] id id
[key] item related type -> dtdxmlentitiesvt.id
[int] attrib attribute id (DTD_ITEM_TYPE_ATTR_*)
[string] val value of attribute
"dtdxmlentitiesass" entities assigement (relation to XML)
[seq] id id
[key] enta_xml XML which uses given group ->dtdxml.id
[key] enta_ent entities group -> dtdxmlentitiesgrp.id
3. Software developer kit
-------------------------
Next par is jsut fast technical document about how to use CBS and how to write modules.
CBS is based on 'modules'. Every module have 'actions', which can be executed during every requests. Every
action includes module name and module specific action nodes. All these parts are separated by dot ('.') and
stored as CBS 'action'.
CBS library uses for its own function these link variables (they are permited to be used by modules on their
own):
module - identifies active module
action - current module action
reqErr - request error
reqErrSrc - source where to be redirected if 'error' occurs
reqFormItem_x - request form items (x is alias of item)
reqDoneRedir - source where to be redirected when request is processed
See down for details.
Every unit of time cbs is present at some 'state'. State 'module' (or normal, no state) is normal state, where
module is executing request. Module or CBS core itselfs can change 'state'. These states can be:
- normal state
request_error - some erorr occurs during processing request
Note: request_error is general error. It is not handled by module but separate template 'CbsTpl_Error.tpl'
This erorr should occurs, when module gets unexpected/bad parametres, databse errors and similar.
Entering invalid value in form (such as 'name') is not threated as 'error'.
CBS includes 'address' line which is created from used module and its actions. Module can improve address
by its interbal state.
In following text, we will use word 'link' or 'request state'. Link represent full request state. And request
state is represented by its link. 'request variables' means all variables inside link.
CBS calls templates to render page. Details about rendering see at 'modules' section.
3.0. Standard template enhancement
----------------------------------
CBS by default learns many tempalte variable definitions. These deffinitons depends on state.
Variables avilable in ERROR state:
type - error type
- no group
db - database error
access - access level error
param - parameter troubles
id - session ID problem
err - error message
Variable available allways:
sysTitle - page title
sysAddressLine - current CBS address line
sysRoot - root inside web server - such as '/'
sysBase - root inside web server, including page - '/cbs.html'
sysBaseFull - sysBase including server - 'www.company.com/cbs.html'
sysCursorPtr - 'pointer' cursotr name ('hand' for IE, 'pointer' (stadnard) for others)
sysDate - date in form 'month/day Year'
sysTime - current 24hour time in form 'hh:mm'
sysUserName - full user name
sysUserId - user id (-1 if not yet loged)
sysMod - current module
sysModAction1 - 1st module action
sysModAction2 - 2st module action
sysModAction3 - 3st module action
reqState - request 'state' (see CBS status)
reqErr - request 'error'
reqForm_x - request form item (if known), where x is item alias
CBS also allow using additional template functions:
link - create 'link'
linke - create 'link' and include 'reqErr' points to current request
linka - modify (or add) current 'link'
access - test access rights
All link function can generate only link body or whole tag. If you with to getenrate full tag, use
following form of parametres:
{*link module=some_paramatres|Link name} -> Link name
3.1. CBS state
--------------
CBS uses 'state' for its work. This state is derived from 'stlc' state. Additional memebrs, avaibale to modules:
[R] - read only (or execute)
[W] - read/write
[P] - private (do not access)
* - array in form ['item_alias']=$value
tpl - [R] template
formItemsDef - [W] default form item values *
formItemsLearn - [W] form items which should be learned allways *
reqErr - [W] request 'error' (errors separated by \n character - always use $st->reqErr.="error\n" !)
reqErrSrcDef - [W] default request 'source' if not given by state
reqState - [W] request 'state' (CBS only learn reqState variable, no more meaning)
pgLine - [W] address line
pgTitle - [W] page title
OutputDone - [W] module allready outputs results (do not call template)
OutputNoStd - [W] do not process standard things like address, title, ...
OutputTpl - [W] force different output template (this is path)
module - [R] module
action - [R] module action array
formItems - [P] form items
formPostVars - [P] form items which become a par of form error and previously posted at _POST
formDatas - [P] form items related directly to datas
prevReqErr - [P] request 'error' (from previous request)
prevFormItems - [P] form items (from previous request)
trackvars - [P] track request variable to next request
cursorptr - [P] cursor - pointer/link
STLC state members:
dbid - [P] database connection ID
dbtransaction - [P] transaction in progress
dberror - [P] database error
dberrord - [P] database error details
dbdebug - [P] do not process SQL, only display
sessionid - [P] current session ID
cipherkey - [P] current cipher key
reqid - [P] current request ID
userid - [P] current user ID
reqparams - [P] current request parametres
lastreq - [P] last request parametres
lastreqid - [P] last request ID
timeout - [P] login timeout
3.2. Request live (forms, redirecting, variable tracking, ...)
--------------------------------------------------------------
When CBS process requests, it take care of few things:
access control - control general access (enabled modules, active module, ....)
variable tracking - auto add given variables to links
forms - form administrating (remeber values)
error handling - redirect to 'error handlers' when some error occurs
render output - rendering output
calling module - calling module functions
events - event administrating/executing
3.2.1. Access control
---------------------
CBS includes static list of enabled modules. It also take care of valid session ID, auto log anonymous
users (and redirect to valid module which hanled anonymous connections), controlling general user access
to module and similar startup things. If occur any erorrs, CBS exected 'request error state'
3.2.2. Variable tracking
------------------------
CBS allow auth 'tracking' variables. It means, CBS will automaticly add selected varibles to *EVERY* link
which is created. This is very useful feature. Track variable will be added only, if:
1. current and 'link' modules match
2. current and 'link' actions are not different in more than 1 node
so, of current request is module 'test' and action 'tree.node' and we are tracking variable 'hell':
module=test&action=tree.node.sub YES
module=sex&action=tree.node NO
module=test&action=tree.node.sub.sub2 NO
module=test&action=tree YES
Variable value is readed from 'request variables'.
3.2.3. Forms
------------
Everything, what is identified as 'post' variable become a part of form. Variable become part of form,
when executed cbsRequestvarGet with proper parameter flags.
If module fills 'formItemsDef' array, CBS automaticly get this value, if related item is not posted.
This is used to fill 'default' form values.
CBS automaticly learns teplate variables 'reqForm_' for all known form items.
If form, is posted, and module fills 'request error' with some error, CBS automaticly gets ALL known
form items and REDIRECT to error handler (reqErrSrc). And standard cbs error handling occurs.
Form example:
Template:
Template uses reqForm_beername to fill default value.
Module - variable read:
cbsRequestVarGet($st,"beername","f","id",$beername);
Module - set default form item
$st->formItemsDef['beername']=read_from_db_some_value;
Module - error report
$st->reqErr.="Sorry, beername is not valid !\n";
Module ussualy set default module if form wan't entered (module test one of required form items, or
adds variabel to form link). If filling default value is time expensive, module can test form items
for presence 'item value' and skip it if necessary. reqErr is usually filed after process form datas.
3.2.4. Error handling
---------------------
CBS error occurs when reqErr is not empty. If error handler is not known, it tries to use request var
'reqErrSec'. If it is empty, it tires to use 'reqErrDef' state variable. If no error handler is known,
it normally executes module. In this case, it is up to module to recognize error (reqErr) and process it.
For redirecting errors is used 'redir' HTTP header.
3.2.5. Render output
--------------------
After module is called, and eror handler (e.g. redir if necessary) CBS calls 'template' to render output.
Template is executed by following scheme:
[data_path]/module/CbsTpl_action1[_action2[_action3]].tpl
If action is exual to 'index' and there is no next action, it is ommited from filename template.
(for cbs_dpath see 4.2.)
When module sets state var 'OutputTpl' it is used instead of previous one.
When module sets 'OutputDone' to true, CBS doesn't execute any TPL call. If module sets 'OutputNoStd'
then CBS omites learning template thing like:
address
page_title
...and others
It is necessary, when generating page doesn't include valid address/... language deffinitions
(see modules for details)
3.2.6. Calling module
---------------------
CBS have to call module-specific function ever requests. See 3.3. for details.
3.2.7. Events
-------------
Events are global and shared across all modules. See 3.7. for details.
3.3. Modules & its templates
-------------------------
Every module is a indepenend part of CBS. It consists of 4 things:
1. Info files
2. Info sources
3. Source itselfs
4. Templates
Every module have 'alias'. All module file are stored at CBS tree root, in directory, named by module
alias. Module alias need to bue unique across all modules. 'x' will refer in following text module
alias. All files are realted to 'module root' (cbs_root/x)
3.3.1. Info file
----------------
File 'CbsMod_x.info' is 'offline' module information file. It allows CBS to collect base info about
modules without including physical source. This file is standard INI/conf file. It means, it have
[sections] and every section contains 'property=value'. If value contains spaces or other wierd
characters, it have to include quotes.
Sections:
[info] - general info about modules
name - module name
comment - module comment
alias - alias (need to match with x and module directory)
[access] - exported access lists
acl1
acl2
...
aclN
where every ACL are values, separated by commas in form:
acl_alias,acl_data_ref_type,X,acl_rule_name
acl_alias - acl alias (unique in module contents)
acl_data_ref_type - data reference type
X -
acl_rule_name - full acl rule
(for more info about ACL see 3.4.)
Info file can contain also other sections, which are depenend on other modules. See modules tech doc
for details.
3.3.2. Source files
-------------------
Module source are divided into '2' cathegories:
global - CbsMod_x.php
local - CbsMod_x_action1.php
Global file is included always. It HAVE TO include at least 'Info' function (see down). Local files
are derived from *FIRST* module action. Module doesn't need to include local source files and use
only global ones. CBS 'includes' them separate, so, it is up to module, where functions will be placed.
Module functions:
modInfo_x - module info, returns reference to 'info'
modStatus_x - returns module status
modEventPre_x - pre-event handler
modEvent_x - event handler
modEventPost_x - post-event handler
modGo_x - module 'execution' point (global, executed every time)
modGo_x_action1 - module local execution point
modOperation_... - module operation
modGo_navLink_x - check naviation link line
*ALL* module function includes at first parameter REFERENCE to '$st' - CBS state. Do not change unlees
you know what are you doing.
Every module contains 'operations'. Operations can be user defined or system. Syste, operations:
create - create 'static' table structure
test - test if 'static' table structure is OK
3.3.3. Module info - function &modInfo_x(&$st,$full)
------------------
$full - full info required ('single' info requires only "actions" member)
return - array of infos
actions - action tree. Every member of array includes ["action_alias"]=>"flags"
where flags can be also sub-array (in this case, first item of this array is "."
which holds real flags for item).
Known flags:
d - default (if no 'item' at current tree level given, use this one - typically index)
n - no address (do not include in address line)
Example:
$i=>array(); // later returned by function)
$i["actions"]=array("."=>"",
"index"=> "dn",
"test" => array("." =>"", // real flags for 'test'
"tree" =>array("."=>"dn",
"view" =>"dn",
"itemact" =>"n" ),
"types" =>array("."=>"",
"index" =>"nd",
"view" =>"",
"update" =>""
)
)
)
tables - static tables - array of tables and its columns in form
"table_name"=>array("col1","col2",..."colN");
Every column have following syntax:
col_name type flags
col_name - column name/alias - be aware of reserved words
type - databaze type (see STLC doc)
flags - flags (see STLC doc)
"test_table"=>array(
"id seq primary",
"dtd int req",
"alias char.64 req",
"name txt",
"comment txt",
"flags int"),
operations - static operations executed by 'modules administrating' - form:
"alias"=>array("action_name",flags);
Operations are usually executed by admin. These operations are dedicated to
data storage, managing and others.
Function which handles operation have following prototype:
modOperation_(action_name)_x(&$st);
System actions:
create - 'static tables were created' - return value: proper error code
test - check data structures - return value: proper error code (empty: 'default' check)
trees - defining user tree records for automatized tree functions (e.g. check coherency etc.)
defines rows (arrays) with these members:
"tables" => "table1" or "table1,table2"
"flags" => "flag1,flag2,..."
Tables depends on used flags.
If no flag is given, standard tree is assumed. It means:
table1 = tree table
table2 = data table
if flag 'stdtree' is given, then table1 means datatable and tree are stored in
system more-tree 'tree' table
if flag 'dtd:xxx' (where xxx id 'dtd' alias) then data table is placed in 'data'
if flag 'multitree:table,tree_name' is placed in given 'table' and 'tree_name' is used as
tree name. It can include {dataid} for data reference - only in combination with dtd
3.3.4. Module status - function modStatus_x(&$st)
--------------------
Return module status (emty string: ready)
Before module status is queired, 'test' action is also executed for data consistency
3.3.5. Module executing
-----------------------
CBS executes every request 2 functions of module:
modGo_x(&$st)
modGo_(action1)_x(&$st)
There is nothing to add.
3.3.6. Checking address link - function modGo_navLink_x(&$st,&$lnk,&$name);
----------------------------
CBS calls this fucntion for EVERY link on navigation bar and module have chance to chage
link and its name. Link is in RAW form (var=value)
3.4. Access control lists
-------------------------
ACL controls 'access' to modules, its functions and more. Ale ted se mi to nechce psat.
cbsAclGetUserList(&$st,$name,&$dst,$result=CBS_ACL_RULE_RESULT_FULL_ACCEESS);
$name - aclrule full alias: mail@mailbox.access
$dst - returned array of users
$result - condition on rules
return list of all users with acl rule's result
3.5. CBS core functions
-----------------------
db_error_format(&$st,$err,$details,$origin) - format error message
$err - error code/text
$details - error details
$origin - error origin
this function format error message in depenency of user 'error view' settings. Normal user should see
only $err no more. Advanced user also $details and administrators also $origin. $origin is often SQL
source.
cbsRequestError(&$st,$err="",$type="")
$err - error code/text
$type - error kind (see 3.0. and ERROR state)
this function handles fatal 'ERROR' - it never returns.
cbsFatalExit($err)
$err - error code/text
display error and quit
cbsDebug(&$st)
send $st t obrowser
cbsSendEvent - see 3.7.
cbsModsInfoGet($includeall=false)
$includeall - include all modules/include only modules 'alowed' by general config
function return asociative array (cahced) which infomactions about modules.
array[mod_index][alias] - modules alias
array[mod_index][source] - module main file source
array[mod_index] - fill module ini info file (parsed) - see stlcIniParse
cbsTablesCreate(&$st,$tables)
$tables - array of tables to create
function creates set of table (if not yet exists) using db_table_create function (see for $tables params)
cbsCoreCreate(&$st)
creaes CBS DB core
cbsAccessGet(&$st,$name,$param="",$auto_fail=false)
$name - ACL name
$param - ACL param
$autho_fail - if denied, go to 'error state' (fn never returns)
returns true/false (access granted/denied)
cbsLinkCreateAdd(&$st,$par="")
par - tedt parameter (URL form) or array, text can include | and generate also links tags
Function modifies current 'link' - add new params or change current
cbsLinkCreate(&$st,$par="",$includeerrsource=false,$lname="")
$par - link parametres (array or text)
$includeerrsource - include reqErrSrc with current lik
$lname - if give, full tags are generated
create CBS links, add tracks vars, current module (if not given) and check for '@this@' as variable
parameter, which is replaced by current page link. It also adds form items if necesary.
cbsRequestFileTest(&$st,$name)
$name - file name to test
test posted files for $fname presence
cbsRequestFileGet(&$st,$name,$flags,&$allowed,&$dst,$errmsg)
$name - file name
$flags - flags:
* - go to error state on error (fn never returns)
r - automaticly read file as 'contents' info $dst
h - togetehr with 'r' stores 'hex' contents instead of binary ones
$allowed - allowed
mime - full mime tags (empty=all)
maxsize - max file size (reuired)
$dst - destination array
contents - file contents
type - mime type
file - path to uplaoded file (caller have to call unlink($dst['file']) when processed !
cbsRequestVarReuse(&$st,$name,$flags,$newtype,$type,&$dst,$param=0)
$name - variable name
$flags - cbsRequestVarGet flags
$newtype - returned 'var' type
flags - param is 'array' of flags, function converts text form to numerical
$type - cbsRequestVarGet type
$dst - destination
$param - optional parametres (depends on type)
function 'reuse' variable if possible (return true on sucesfull reuse). Variable is reused from
previous item (reqFormItem_* vars)
cbsRequestVarTest($st,$name,$flags="")
$name - var name
$flags - flags
p - post alowed
g - get alowed
function test (returns ture/false) if request variable is present
cbsRequestVarGet(&$st,$name,$flags,$type,&$dst,$defaultval="",$error="")
$name - var name
$flags - flags
p - post alowed
g - get alowed
! - empty value not alowed
f - store variable as 'form item'
F - variable is form item, but posted from previous 'form' (required for error handlers)
s - prepare dst as 'sql' parameter
S - similar to s but also add '
l - learn template current variable (if array, comma delimited string is learned)
L - learn as 'form variable' at template (reqForm_...)
t - 'track' variable (add automaticly to links - see 3.2.2.
d - variabel is directly related to 'data' (optionally used to autoamticly fill DB datas)
* - on error go to 'request error' state (fn never returns)
v - set value allways (fill with 'type' default)
k - king size - do not test 'max' length (depending on type - alias by default 32 chars, etc.)
K - KING size - do not test global 'max' lnegth (default 2K)
t - request variable will be automatically tracked across requests
$type - variable type to check (convert)
general syntax
"type[:optional_list]" if not say different, optional_list is unused
list - comma delimited list (a,b,c) - dst stored as numerical array, chars not limited
listkeep - like list, except dst keeps original list format
if optional_list given, then it includes 'list' of possible values
like: "list:,one,two" - empty/one/two are possible
special 'optional_list' values - need to be given first
*id - list of ID's (words)
*id. - list of ID's (words) and dots
* - list of numbers
idi - integer identifier
idip - integer positive identifier (0+)
id@ - word@words_with_dots
id. - words with dots [note: all dost need to be palced inside words]
id - word
mask - any combination of characters except ; " ' %
bool - 0/1 true/false on/off (dst is stored as true/false)
bool1 - 0/1 true/false on/off (dst is stored as 1/0)
hexnum - hex number
email - email address
$dst - destination
$defaultval - default value, if var not present
$error - related error
function read request variable, test/conert/store to dst, and if 'error' given, it stores error to
$st->reqErr. If erorr occurs, 'error' is empty (and flags doesn't include *) function returns error
code. If variable not present and default value not defined, function doesn't 'touch' on $dst
cbsRedir(&$st,$redir,$addreqerr);
$redir - destination link (raw form)
$addreqerr - add 'reqErr' to link (if $st->reqErr not empty)
cbsTrackReqVar(&$st,$varname)
start tracking request variable
3.6. Trees
----------
CBS includes support for Trees. Trees can be manual, semi-automatical and automatical, depends on use.
It means, tree can be generated automaticly from database or by hand. Tree support includes few public
function. Before we will start, let's explain how tree works.
Tree and 'tree structure'. Runtime is tree represented as simple array (table rather). Every 'item'
includes:
node - current 'node' ID (usually current index)
parent - parent node
(so, $tree[0]['parent'] and similar)
This is unprepared tree, RAW state. After structure is 'generated', tree is being prepared. It means,
new columns are added:
Tdepth - numerical 'depth' of node
Tchilds - 1 if node have some child nodes
Ticons - set of 'icons' (string list, 0 first icon) which creates 'tree' structure on the screen
it includes empty 'spaces', line drawing, +- to open/close subnodes and also item icon itselfs
first icons are resevred for tree use (drawings, ...)
Raw data may include only openned items or all. At least it have to include one 'sublevel' of openned nodes
to determine, if childs are presents or not.
Database in tree is stored separate from datas. Tree structures can be glued into one table. Tree used
in this case followgin colums (to store folders)
id - autoincrement [seq]
tree - tree name [char]
alias - folder alias [char]
parent - folder parent [int]
comment - folder comment [txt]
[any next fileds]
Tree doesn't store data by itselfs, but data should include following columns:
treenode - owner folder, 0 for root level [int]
alias - item alias [char]
aliasfull - item full alias (=alais including folder path) [txt]
comment - comment [txt]
[any next fileds]
Tree routines automaticly take care about *all* these database columns.
cbsTreePrepare(&$data,&$openned,$flags="")
$data - data to prepare
$openned - openned structure
$flags - not used yet
function prepares tree (add Tdepth, Tchilds, Ticons) and take care on 'openned' nodes
cbsTreePath_get(&$st,$tbname,$tbtree,$folderid,$folder,$folderalias=-1,$folderparent=-1,$addon="")
$tbname - tree name
$tbtree - tree table name
$folderid - folder id (or owning folder ID for data path)
$folder - true/false - true: folder path false: item path
$folderalias - folder alias (-1: function will determine)
$folderparent - parent item (-1: function will determine)
$addon - 'path addon' (usually empty, internally ignored for item paths)
return full path for folder/item.
cbsTreeCreate(&$st,&$p)
$p - params
tbtree - tree table name (if empty, global CBS TREE will be used)
tbname - data table name
openned - list or array of openned nodes (optional)
autovars - read automaticly request vars to determine [request var]:
openned items [treenodes]
datafilter - filter data table (valid SQL)
create 'tree' from database and return full result
cbsTreeBrowse(&$st,&$p)
$p - params - all cbsTreeCreate valid parametres and additional:
addrbase - base action
function shows 'browse tree' (usually used as IFRAME). This tree doesn't include anythign around,
jsut tree. It process '2' request variablees:
onlclick - what javascript to execute when user clicks on some item
allowfolder - allow selecting folders (if not true, then only items)
This functiosn redirects template to 'CbsTpl_TreeBrowse.tpl'
cbsTreePrepareData(&$st,&$p,&$data,$flags)
$p - params
res - item result (see cbsTreeAction)
$data - destination data
$flags - flags
d - automtaicly use 'form data' and store to destination (see F at cbsRequestVarGet)
t - include tree related data (treenode,alias,aliasfull,comment)
function prepares $data for database insert/udpate, and adds/sets requested columns
cbsTreeLearnDataFromOut(&$st,&$p,$flags='?')
$p - params
out - realted data 'output' (see cbsTreeAction)
data which should be processed by this functions
$flags - flags
? - auto decide if flag d or f should be used (editd action -> d)
l - learn variable
d - set 'formItemsDef' array
function learns template or set formItemsDef array from all items of $p['out'] array. It excludes
following system tree variables: treenode,alias,aliasfull,comment
cbsTreeProcessDefAction(&$st,&$p,$act,&$actpar)
$p - params (standard tree ones - see cbsTreeAction)
$act - action name
$actpar - action parametres (dpenend on $act) [array]
deld: eventname - name of event to raise
function process 'default' item tree action:
newd - it inserts database item into data table (cbsTreePrepareData used for preparing datas)
deld - function setup event and raise
cbsTreeAction(&$st,&$p) - general function to execute action over some tree
cbsTreeProcessPost(&$st,&$p)
$p - parametres
tbname - data table name
tbtree - tree table name (if empty, glboal CBS TREE will be used)
tbmixed - tree and folder structure is ONE table - true/false
tbnamecp - column name for tree structure parent... default: parent (tbmixed) or treenode (normal)
res - output 'result' (forms, ....)
out - while edit/property datas, function select * from 'data' (result stored to out)
formsrcdef - set default form error source ($st->reqErrSrcDef)
state - tree state (itemact, browse, ...) , by default determined automaticly from CBS action (next action after 'tree')
autovars - automaticly 'reads' variables:
itemact - item action. fills action
itemid - item ID (>0=item, <0=folder), fills itemido
treenodes - current openned treenodes, fills openned
reqDoneRedir - redir when 'done'
allowact - allowed standard actions (if not given, all are enabled)
addon - additional actions
addonview - actions which 'view' datas
addonedit - actions which 'edits' datas
addoncolsf - additional columns for folder (passed from data into TPL tree)
addoncolsd - -//- for data
addonaddr - lng base for 'addon' actions
nopgline - do not add line item for 'items' (comma based list)
defaultact - default action parametres
action - tree item action (dot delimited list)
actionx - untranslated action
actionxlt - action translation table in form "action"=>"newaction"
actions - array of 'actions'
itemido - original itemid (before translation folder/item)
itemid - item ID (-1 on folder)
folderid - like itemid but related to folder (unset on item)
addrbase - based link (action) address
datafilter - generla data filter for data part of tree (see cbsTreeCreate)
aliasglobal - normally, data alias is unique within 'tree' of node. Trueing this parameter
will change this behaviour to 'data alas unique across whole tree'
redirlink - parametres (array: key->value) automaticly added when tree is redirecting
(child tree can automaticly track parent vars)
treeid - suffix for tree vars - itemAlias, itemComment, ... EVERYTHING about tree
(default: '')
customdata - do not access DB and get these datas as tree structure
openned - list of openned 'folders' (array or , based list)
nodata - folder based tree only
outputtpl - tpl executed (if tree executes tpl, like browsing)
move - move parametres: src,dst,srcfolder,srcinfo,dstinfo
structev - structure changes event name
nodefact - do not process default action - apply datbase changes for items, etc.
form - tree form 'posted'
parametres used in 'post' process (see down, how redir works)
returnonerr - 'return' if erorr occurs ($st->reqErr ofcourse)
return - return alwyas (same as done=true and ignorereqerr=true)
done - action done (return to caller of NO error)
redir - default 'redir'
rediredit - default redir for 'edit' actions
DTD related
dtdfilter - filter tree view for DTD - value in form 'moduleorigin@dtdalias' where dtd alias is optional
dtddataref - reference to DATA, if empty, $p['itemid'] used as data reference
dtdparent - parent DTD, automaticly sets dtdfilter, activates DTD 'extensions', redirects edit/prop/del actions
to DTD contents tree, automaticly sets 'structev'
dtdsidetbl - name of 'side' tbl for data instance
outDataInfo - * from 'data info' (dtddata, filled if dtddataref or dtdparent used)
outData - * from 'data' (physical data table, fillsed if dtdsidetbl used)
function learns template (always) by these variables:
itemact - item action (original)
itemid - item ID (original)
function executes high-level action over tree. It support 'reqDoneRedir' - it will automaticly redirects
to specified page, after tree node operation is done. This function recognized few item actions and
preparre/process them:
del - delete item/folder
newd - add new data
newf - add new folder to current level
newf2 - add new folder as child node
prop - property
edit - edit
In the process, tree renamed 'original action' to new ones, which includes 'data' (d) or 'folder' (f)
suffix. Deleting data (action del on data) will end as 'deld' and similar. Possible tranforms:
del -> deld / delf
prop -> propd / propf
edit -> editd / editf
Module using tree dones't need to handle any 'folder' actions. Module should react on 'tranformed' actions.
But don't remeber, while creating link, original actions need to be used.
This function work in pair. Before processing tree, module should call cbsTreeProcess and after
processing action (or doesn't do nothing on error for example) module should call cbsTreeProcessPost
which handled additional operations (such as redirects, ....)
If some actions requires 'form' to enter some datas, tree adds 'ask' to 'action'. So, we can have
deldask or newdask and others.
'Pre process' actions:
newd - new item
1. retrive parent folder (if itemid is 'data')
2. take care of 'new data form' (newdask action)
3. prepares $p['res'] (if form entered)
folderid,alias,aliasfull,comment
It is up to user to 'done' this action
newdask - ask for 'new data properties' (originally newd)
learn template variable 'folderPath' (full parent folder path)
newf, newf2 - new folder
1. checking parent folders/presence
2. take care of 'new folder form' (newfask action)
3. physically inserts folder
This action is automaticly 'done' on no-error
newfask,newf2ask - ask for new folder properties (originally newf/newf2)
deld - delete data (originally del)
delf - del folder (originally del)
3.7. Events
-----------
Every module can 'raise' event. In this case, CBS walk throw all modules and call *EVERY* module
to hanle events. Every event have name in form 'module.event.name'. By defauls, CBS send events
only to modules, which are interested in retreiving them (see 3.3.1.). Exception are events from
module 'admin' which are sent always to all modules.
Modules are sent by CBS function
cbsSendEvent(&$st,$event_name,$params,$errmsg="",$fnflags="")
$event_name - event name in form module.event.name
$params - event parameter array
$errmsg - error message, on event failure
$fnflags - function flags
$params - array of parametres ["param_name"]=value
this pamareters are pased to every module
params are event-depenend, but some of parameter names are global
itemId - related item ID [e.g. 123]
itemAlias - related item alias [e.g. root]
itemAliasfull - realted item alais full [e.g. admins.root]
If item 'datas' should be moved to different 'item'
itemDstId - destination item ID
itemDstAlias - destination item alias
itemDstAliasFull - destination item full alias
If related item is referenced, then:
tableColName - table column reference name [e.g. UserId]
tableColVal - table column related value [e.g. 123]
table is used for speedup deleting records
$errmsg - error text if event failures
by default "Error occurs during processing event ..."
$fnflags - function flags (text string)
r learn reqErr if error occurs
When CBS execute event in module contents, it executes following order:
modEvent_x(&$st,$event,$params,&$actions)
Event handler - info. This handler shold NOT execute any SQL statement and to any actions !
It should process valid checks, or setup 'actions' array (executed later). Action is array,
list of following texts:
"NAME;param1=val1;param2=val2:body"
NAME - name of action which CBS shoudl process
param - action depenend parameters [optional]
body - action depenend body
Known actions:
T - delete from 'table', column name get from tableColName and equal test with tableColVal
param: col - change 'column' to abc
filter - add 'AND xxx' to SQL statement (where xxx is parameter ofcourse)
body: table name
This action automaticky construct SQL like:
DELETE FROM TABLE_NAME WHERE tableColName=tableColVal [AND filter]
SQL - standard SQL statement
param: none
body: sql statement itselfs
Actions are not EXECUTED after functin returns to CBS. All actions are collected together and
executed AFTER pre exec but before exec itselfs.
modEventPre_x(&$st,$event,$params)
$event - event name
$params - parametres
function should execute own SQL statements, work over datas, whatever, BEFORE event is 'processed'.
[here are processed actions from into handler]
modEventExec_x(&$st,$event,$params,&$actions)
execution itselfs (remeber, event action may by 'canceled' in POST actions !!!)
modEventPost_x(&$st,$event,$params,&$actions)
similar to pre event, excpet this is executed after all event handlers
modEventDone_x(&$st,$event,$params,&$actions)
send after event was sucefully processed. Event can't be canceled while processing this
handler. There is no 'error' return value at all.
3.7.1 Known events
------------------
Known events, their sources and parametrs. Event is always in form:
module.name[.name2[.name3...]]
Commonly used event properties:
itemId - related item ID (tree structures)
itemData - full item data
recId - related record ID (pure tables)
recData - full record data
dtd - CBS dtd info
dtdCluster - cluster info
dtdItems - dtd items
dtdId - dtd id
data - CBS data info
dataId - data id
dataTable - data name (e.g. 'DATA_3_ALIAS')
dataTableBase - data table base (e.g. 'DATA_3_')
Parametres marked by ? are sets only if known (if required, handler have to check for presence
and get proper value on its own respectively)
Not all events should be send by other modules than origins. It is because many internal parametres
which events may require to do 'real' work. These parametres should be never used (or sets !!!) by
other modules.
Followinng events should be NOT send by custom modules:
data.contents.rec.edit - database record is udpated
recId,recData,dtdId,dataIt,dataTable
data.contents.rec.delete - database record is going to be deleted
recId,recData,dtdId,dataIt,dataTable
data.contents.rec.insert - new database record is going to be inserted
recId,recData,dtdId,dataIt,dataTable
Following events are global - any module can send these events to others:
not yet used... Ale budou :) A hodne....
3.8, CBS Lib
------------
CBS function library includes few usefull functions
cbsTableMakeInOut($all,$vals_in,&$in,&$out,$colname)
cbsTableEraseDuplicates($datas,&$data_out,$colname)
cbsArrayToTable(&$out,$array_in,$colname,$type="")
cbsTableCompleteFromInList(&$out,$recsin,$tablecol,$table,$addcol,$type)
cbsTableCheckvals($st,&$testtable,$tablecol,$table)
cbsTableCheckvalsList($st,$testlist,$tablecol,$table)
cbsTableFromList($l,$colname)
cbsFlagsTranslate($val,$table)
cbsFlagsTranslateRev($val,$table)
cbsSearchPreparePaging(&$page,$rows,$pagelen,&$out)
prepare navigation for visualisation and checks page to be valid within range.
Params:
page actual page
rows total rows in result
pagelen length of page
out resulting array:
page actual page (starts at 0)
current actual page - current for user (start at 1 so page+1)
pagescount total pages
prev 1 when previous page available (2nd and next pages)
prevpage previous page
next 1 when next page available
nextpage next page
list table of 'pages' (created to be user friendly)
page ID of page (start at 0)
number visual number of page (start at 1)
current 1 when current page equals
pagelen page length
ready always 1
Typical usage is to create link like: <- next ... [5] [6] *7* [8] ... next ->
cbsSearchProcess($st,$par)
functions process 'search' (optional) and paging over tables. It's parametres:
searching:
p_mask - mask for 'search'
p_match - list of columns to match
p_matchtype - macth type: sub (substring) exact (exact phase)
p_matchglue - glueing more experessions: OR/AND
p_reverse - boolean, if true, sorting in reverse order
p_order - list of columns - ordering result
p_page - actual page (counter from 0)
p_pagelen - page length
processing (generating) SQL:
resultcols - array of columns in resulng data/sql
tables - array of tables in SQL
cols - array cols avilable for searching (matching):
1. only column (integer index, simple array) cols=array('col1','col2')
matchname is equal to column
2. indexed columns cols=array(index=>'col1,col2,col2')
matchname is 'index' and matching more columns - ORed
(usefull for searching over more colums - like alias / aliasfull)
value to match is autoamticallu readed from request variables: mask_XX where XX is matchname
It is possible to search more expressions at once, in this case p_matchglue is used
to combine expressions
defmatchall - if there are no expressions/masks, return FULL table (else empty result)
deforder - default columns to sort. if not given, first column is used
nodeforder - do not use auto first column to order result
sqladdon - add SQL to result (with AND)
sql - OUT: returned SQL
navprocess - nonzero means process 'navigation' - fills 'nav' with:
page - actual page
pagescount - pages count
prev - previous page (counted from 0)
prevpage - previous page (counted from 1) - visual page
next - like prev but for next
nextpage - -//-
list - table of 'list' pages: page - page
number - page number from 1
current - 0 or 1
list may 'miss' some number - e.g. ... 4 5 6 7 ...
if there is too much options
pagelen - actual page length
ready - 1 on sucessfull
navlearn - auto learn 'nav' things
navlearnbase - base for learning nav (first letter is uppercased)
execsql - exec SQL (return as 'res')
learnresult - also learn table called 'results'
autovars - override searchin p_* variables by auto getting 'request' variables (mask/match/...)
ps: this etxt was added 05/11 2004 on Sigi's demand. In 3 days after request. Let see, when he will notice,
that there is explained search library function.
4. CBS config
-------------
CBS configure options
4.1. CbsOptions.php
-------------------
This file contains stats CBS options:
CBS_BENCHMARK - 0/1 - show benchamrking
cbs_active_modules - comma separated list of generally enabled modules (security reasons)
4.2. Runtime options
--------------------
CBS require (before its general call) to se few variables. Namelly they are:
$cbs_path - full path to CBS source tree root
$cbs_dpath - full path to CBS related data (templates)
$cbs_options - array in form of
['option']=value
this options override any of 4.1. options (if more instances of CBS is running)
5. WWW renderer
---------------
WWW renderer extends TPL engine about many powerfull commands. Templated in WWW renderer consists of 'items'
and they are included together. Templates are used in pages. Which template is included into another template
can be set by end-page or by template iteself.
All items have standard properties like name/alias/comment/type/typeflags/attributes/...
Additional properties:
scope - says, if item is available only for 'template' or also can be changed by 'page' (and links)
prepare - data preparation runlevel or auto preparation disabling
While rendering, tempaltes are processed lineary, from 'root' teplate, which is set in every page. Template
can include 'child' templates on specified place by command.
WWW render canm also use enhanced 'runlevels'. It means, temapltes are NOT processed once, by in few passes.
See 5.2. for more details about runlevels. In runlevels are not used, WWW renderer runs in single mode, were
all datas are prepared before template bodies are executed. All output if executing templates is sent to
browser.
Item value can be sets from tempalte by using
{*set item value}
Only own items can be sets. Setting value will update related 'template' variables/tables, but will NOT
force data to be re-preared. If you need to change 'data' you have to call {*set} before 'data' are
being prepared.
If value is not given, value is 'reseted' to default (0, empty string, no selection, ....)
{*setdef item)
Sets item value to 'default' (template one) - it overrides possible 'link' value - everything else is
identical to {*set}
By default, data are prepared before template render starts. If runlevels are used, and 'prepare' item field
is set to runlevel, datas are prepare before selected runlevel is executed. This auto-prepare can be fully
disabled. In all cases, data can be prepared by hand. Allready prepared datas can't be re-prepared
{*prepare item}
Immediatelly prepare (execute all required SQL/conversions, ....) datas
Preparing on non-data fields (e.g. text/int/....) is not alowed and have no meaning.
5.0. Links
----------
WWW links works a bit different from 'normal' CBS or standards ones.
To create 'www' link use
{*www params}
Where params are standard pairs of
param=value¶m2=value2
'param' is referencing 'item' of template. Value should corespond to related item type. If value not matchs
type, default value is used and parameter is ignored. Passing inexising item parameters are also ignored.
All referenced items are LOCAL. It means, by default, every template references OWN items. While creating link,
_ALL_ items which are diferent from default value are added to link. There is no important if item was changed
by link or in TPL by {*set} command. Local means, that every template has own 'namespace' for items. So,
referencing item 'x' of template A and B (both have same item) always set right one - A or B one. It is because
items are passed as 'template.item', so, if template 'A' includes {*www x=10} it means 'A.x=10'. Similar for B.
When item passed in link is not used for reference item (e.g. template is no more included in the page), it is
not longer automaticly added to new links.
If one template exists at more instances, stadnard link will set relevant item of ALL templates. This behaviour
can be changed, but let's look on it later.
Sometimes it is necessary to set item value of another template. Normal link can't be used, because it references
only 'current' template.
There are 2 pretty different ways how to set item of another tempate. It is called 'cross template link'
1. Referencing throw template alias
2. Referencing throw alas of template inlude item
What's the difference ? Referencing by template alias is usefull, if you have one template in the page ans you
do not care where the template on page is really included. On the other side, referencing by alis of template
incude item care about position in page. Referencing by template alias is commonly recomended, because it is
lees depenend on page structure. Referencing by template include item alias is recomended, when one template
exists in more isntances at page tree.
Referencing by template alias:
#template:item=value
Template can be full template alias or just alias of template. If you will use only alias, take care about
passing values to right template ! First are searched full aliases and then aliases only. If this cross link
match some full alias, search and performing link on aliases only are not executed. After setting item value,
link is converted to normal one. It means:
1. you create link by template.item=value
2. when link is perfomed (user clicks), engine finds 'template' and set 'item' to 'value'
3. next time is item value passed as normal link (like writing 'item=value' in template
Cross template link, dependnd on structure is usefull, where one template is included more times at page. Its form:
$templateitem.item=value
Template alias is not important right now, it is important its 'parent' item - template type. Can be also used
more parents - e.g. parent1.parent2.item=value. Be carefull while passing links, because you can set item of
more templates ! This form of links 'keeps' it form, so, it is not converted to normal page link. It can be used
in purpose, where more included templates on page are swapped across another templates - as long parent will
machs link, value will be set.
Now back to 'normal' behaviour links. By default, links works as expalied above. When template is included in
another template, you have to use 'template' included item. This item can change link passing: you can tell
system to NOT use normal link form and use cross-tempalte links, based on template includes aliases. It allow
you having on one page more same templates and keep primar template working normally and other working throw
cross template links together.
You think it is complicated ? No, it isn't ;) It is required, because you never know, what templates will
run with your 'current'. So, link have to be template independed as possible. That's also why, you can't
simple use 'normal' form.
If you need to 'redirect' to new location, tyou can use command
{*wwwredir link}
This command is identical to {*www} and clicking on the link, except it is done automatically by browser
without asking user (if not redirecting to another domain, then user may be asked in depending on
security settings)
ity is recomended to redirect after psoted forms etc. because if your willl do 'refresh' you can get data
more times.
Co se tyce WWW linku, tak je ted moznost 'cbs:' a udela CBS link.
Jako DEFAULT (tedy bez niceho) by se melo v menu pouzit CBS link, ve WWW
modulu WWW link. Format klasickej.
5.0.1 bookmarky pro WWW
------------------------
Bookmarky ve WWW slouzi pro organizaci 'casto' pozuivanych linku. Typove je
to neco jako external files, tedy jsou stromove orientovane 'skupiny'
(bookmark groups), ve kterych se nachazeji 'links'.
Bookmarky existuji z nekolika duvodu. Jednim z nich je zprava 'externich'
linku na site pozuivane na vicero strankach a u internich zprehldneni. Linky
jsou 'nad' databazi, takze zmena v bookmarks vyvola okazite zmenu na vsech
prislusnych strankach.
Kazdy link ma (zatim, uvazoval jsem o pridani naprikald stylu, 'name' a
dalsich, ale nejdrive se k tomu musi vyjadrit mr. Axl) 'typ' a 'body'. V
body je 'telo' linku, typ urcije 'typ' linku (prekvapive :)
Linky jsou techto typu:
1. external
------------
Obycejny link na nejakou sajtu. Obecna forma URL: protokol://cesta Pokud
chyby :// (protokol) CBS automaticky pridava HTTP na zacatek. Priklas linku:
www.fufme.com - link se bere 'as is' je tedy mozne pouzit klasickou URL pro
predavani parametru.
2. WWW
---------
WWW link v ramci WWW modulu (aktialniho virtualniho webu samozrejmne).
Parametry jsou stejne jako v template. Vyzadovany parametr je _page
(stranka). Tento link automaticky preatahava 'vsechny' parametry z aktualni
stranky, jsou-li zapotreby. Je to obdoba napsani linky v TPL 'aktualni'
stranky - 1:1
WWW link bude pdlehat 'substituci' parametru stejne jako telo WWW (cisla <->
full aliasy).
3. CBS
-------
Link do CBS systemu. Stejne jako v TPL u CBS. Vyzadovany parametr je
'module'. Podotykam, ze odskok se provadi v ramci aktualniho uzivatele, pod
kterym WWW bezi. Nepredavaji se z WWW modulu ABSOLUTNE zadnne dalsi
aprametry (form source, form itemy, ... proste nic)
Tolik 'teorite' k administraci. A jeste krapek okolo TPL.
V TPL se link pouziva velice slozite. Obecna forma prikazu v TPL je
{*bookmark ID} pripadne {*bookmark ID parametry}
ID je ______CISELNE_____ ID bookmarku. Nahrazeni za alias nastane zaroven s
nahrazenim parametru pro _page a dalsich (az toho axlik bude mit vic, zatim
at si trebuje pamet :) Parametry jsou klasicke TPL parametry, ktere
rozsiruji/prepisuji parametry linku z bookmarku. Parametry pro 'externi'
link musi splnovat URL pozadavky, nejsou provadeny zadne konverze a link jde
'as-is'.
Doporucuji pretezovani/rozsirovani parametru pouzivat jen kdyz je opravdu
potreba, napriklad predani ID stranky externimu pocitadlu a tak podobne.
Vysledny linky pak tedy muze vypadat takto (predpoklad: mame zavedenou
bookmarku 'externi sajty' a v ni je link 'unreal' a link unreal ma ID 13 -
umisteni neni dulezite):
Unreal home
V nasem pripade se link prekope na http://www.unreal64.net
Vysledna podoba zalezi samozrejmne na TYPU. Pokud se jedna o WWW, vzdy se
pujde prez AKTUALNI VIRTUALNI WEB, na to bacha. Takze je-li fyzicky potreba
'prepnout' i virtualni web (domenu) v ramci jednho WWW site, pak je treba
pouzit 'external WWW link'. CBS vzdy smeruje na 'cbs' domenu, externi je v
tomto pripade zcela jasne a nepotrebuje zadny komentar (pro mene chapave:
externi link ma vzdy u sebe domenu :)
Muzeme linky doplnit obecne o atributy - ala 'name', 'class' a podobne, ale
myslim, ze to neni moc dobry napad, protoze bookmarky budou existovat v
ramci ruznych 'virtualnich webu' - ale v ramci JEDNOHO 'www' webu, takze
class nebude pozuitelna. Podobne je na tom 'name' (ac retezec muze byt
multilanguage) - vystavujeme se nebezpeci (zejmena pri zmene) spatnemu
kontextu. Proto tak zatim tyto (ani dalsi) atrbuty nejsou, ale technicky je
mozne je celkem snadno doplnit.
5.1. Data items related to WWW renderer only
--------------------------------------------
WWW renderer adds some data types, which have meaning only in WWW related enviroment.
5.1.1. template
---------------
Data item, referencing another 'template'. Template can be filled by owning template or by end page. It can't
be set runtime. Referenced value is 'template'.
Child template is 'executed' by
{*template alias}
where alias is template item. Whole command is expanded into 'child' template body. if template
is not assigned, nothing is generated.
If template is NOT referenced, is NOT included by default. But when runlevels are used, may be possible,
child template will be executed in the end automatically. See 5.2. for more details.
5.1.2. templaterenderer
-----------------------
Tempalte renderer is basically 'library' for TPL engine, which extends TPL about new functions, or it prepares
(learns) datas. Template renderer is 'text' with alias of renderer (which is system unique)
5.2. Runlevels
--------------
If runlevels are used, tempalte body is divided into more 'parts' - every part coresponds to some runlevel.
----- template start ------
TPL out of runlevels
{*runlevel name1}
TPL belongs to runelvel named name1
{*runlevel name2}
TPL belongs to runelvel named name2
------ template end -------
In dependency on settings, 'TPL out of runlevels' can be IGNORED or assigned to some (default) runlevel.
All texts in TPL (so, non-directives) is taken as 'text' and stored. This text (TPL result) can be accessed.
In dependency on settings, this text can be ignored or send to browser. Usualy, one runlevel is called
'render' and this runlevel is send to browser. But this behavious can be fully customized.
Access to runlevel result
{*runleveloutput name}
Every runlevel runs 'standalone' - it means, if template X learns at runlevel A variable 'var', the
same template in later runlevel B can reference it. But template Y in runlevel B (processing order
let's say is X.a Y.a X.b Y.b) can't access 'var' even it is running later. It is because of separate
TPL enviroments. If you need to 'export' variables, you have to use command
{*export name}
where name is table or variable. var/table is moved into 'global' scope (shared)
After exporting var/table, all _LATER_ tempaltes in _ALL_ runlevel can export the variable. Changing
variable value without {*export} doesn't change global scoped value.
The reason to separate variable is clean - you (again) never know, what all templated will be runned
together, so, be carefull with {*export}
Runlevels..... Musim to nekdy dopsat... Ale ted nemam naladu.
5.3. Request static variables
------------------------------
Sometimes is handy to 'store' variables/tables accross requests. Stadnard way is to use cookies, but not
all clients will enable storing / sending cookies. Also, it is not much secure and you rely on client side.
Better way is to use special WWW feature called 'request static variables'.
You can create 'groups' of tables and variables, which will be stored for you accross requests. If you want to
store some var/table, just 'register' it. They will be automatically stored. If you need them, just tell the
system you 'require' them. Groups are created for performance.
Every 'user' is loged into system (usually as 'www' user) and all these statics are related to its session.
They are valid throw session, so, if user go to e-shop, then run away to another part of site and back
to the shop, e-shop statics will be restored. All these statics are deleted when session is ended.
Registering variables/tables
{*staticvar group var_name}
{*statictable group table_name}
register variable/table as 'static'. System takes their CURRENT value. If their value will be changed
later, it will not change static ones. If var/table is allready registered. its value is overwritten.
Deleting static var/table
{*staticdel group}
{*staticdel group var_or_table}
Deletes variable or table from given static group or deletes whole static group. When you delete static
group, all remembered valies are forgotten. If you will use 'require' next time, given gorup will not
exists
Reading statics
{*staticrequire group}
By requiring static group, you force system to try read stored values and learn all var/tables present
in the group
Querying static
{*staticexists group}
{*staticexists group name}
Query (after staticrequire) if given group or var/table exists. Commands expands into:
[empty] group was not restored (doesn't exists yet) or item doesn't exists
group group was readed and 'name' weren't requested
var given group is readed and name is variable
table given group is readed and name is table
!!! When using static variables, *ALWAYS* use {:www.staticrequire} *BEFORE* {:www.staticvar} for the same group.
5.4. Forms
----------
formitemname
formitemval
formitemvalraw
formitemvalif
formitemstate
formitemorigin
formitemread
formitemtest
formitemdel
formerrcount
formexists
formread
formwrite
formrollback
5.5. Miscellaneous
------------------
Bookmark access
{*bookmark fullalias}
reference bookmark - replaced by full 'bookmark' result - e.g. if 'link' was used, do not use {*www} or do
not add prefixes like http:// etc.
5.6. External files
-------------------
External files are access by links or by its bodies. Access to external files can be speedup by system. For
speedup, they need to be maker as 'public'.
Details about speedup - undocumented yet, but transpared for WWW creator.
Instead of full alias in all file* commands can be used file ID (number).
Including efile contents
{*fileInc fullalias}
Command is replaced by body if referenced external file
Referencing exteral file attribute
{*fileAttr fullalias attrib_name}
Replaced by value of file attribute.
Referecing file
{*file fullalias}
Creates link which references 'file'. Form of link depends on external file settings (public) and web
settings. In all cases, this command is tanslated into full and valid URL which can be used on client
side. URL may be different every template run if no optimalization are used.
{*fileNoPub}
Like previous, but force 'public' flag to be ignored (false)
5.7. Data connection
--------------------
Referencing 'data' binary
Pristup je resen kompletne v ramci WWW modulu, aby uzivatel 'www' nemusel
mit pristup do data contents. Reseni je (jak jinak :) genitalne jednoduche.
Pokud si user vyznaci v DTD (na webu) 'file', potom (defaultne, chovani lzde
zmenit) 'value' dane column v tabulce _NENI_ obsah celu, ale je to string ve
forme 'data_id.cluster_alias.colum_alias.record_id'. Tento retezec, ktery
lze zadar i rucne, se potom preda do funknce 'dataFileRef' ktera z nej udela
validni link. Jinymi slovy, pokud mam item 'obrazek', kteryzto v DTD je
file, potom zcela jednoduse 'udelam' link pomoci
{*dataFileRef data_id cluser_name data_column row_id}
creates valid URL to access binary cell in specified data/cluster/row.
Bude-li treba vlozit FYZICKY obsah souboru do HTML, pridela se command
dataFileContents.
5.8 WWW data source filters
---------------------------
Filtry fungujou tak, ze v data_set e zvoli seznam 'sloupcu' se kterymy pujde
operovat v ramci filtrovani. U item relations (v dat_refu) pak pribide
relation na kazdy INTEGER nebo TEXT item. Pokud se tento item vybere, pak se
muze testovat na kalsicke operatory ala = > < <= >= a v pripade textu jeste
navic substring a tak.
Pozor - je treba 'vydeditovat' stavajici item relations a dat u nich update
!
Priklad:
Pro zorbazeni jednoho produktu si pridat item 'int' 'productid'. V dat_refu
si zvolim aby se dalo pouzit k diltrovani 'id', v pages potom u patrivneho
data_refu dam relations na 'productid' a zvolim realtion type ' ='. Jde to
pouzit i k jednoduchemu vyhledavani (ale bez moznosti strankvoani).
Prikladu linku:
{*www _page=3&product=4|Ukaz info o SAMSONOVY}
(4ka je muj produkt samson)
{*www _page=4&productname=m|Najit piva s M v nazvu}
productname je 'text'
product je 'int'