Uvod u STRIX engine

Svaka web stranica koju engine generira i koja ima svoj URL se strogo veže uz jednu kategoriju (kategorija). Za svaku stranicu, tj. kategoriju engine učitava iz baze njen izgled i sadržaj. Izgled stranice je određen pre-definiranim glavnim templateom (template) i rasporedom modula unutar nje. Moduli (modules) su funkcionalno neovisni dijelovi web stranice koji generiraju konačan sadržaj. Za svaku kategoriju, moduli se po želji odabiru i raspoređuju unutar nje (layout).

Više uređenih kategorija čini jedan site (site). Site služi za zgodno grupiranje npr. prava pristupa ili dizajna.

Engine podržava do 3 uređene (poredane) liste modula (npr. za lijevi, srednji i desni stupac).

Podržana je i jedna ne-uređena (slobodna) lista modula, čija pozicija prikaza je definirana unutar glavnog templatea (npr. glavna navigacija, baneri, footer, breadcrumbs, datum i vrijeme i slične). Ovi moduli će se prikazivati na svim stranicama koje imaju isti template.

 Module je moguće definirati i za cijeli site, u kojem slučaju se oni prikazuju iznad ili ispod modula definiranih za pojedinu stranicu (pre_layout).

 Prilikom generiranja stranice, engine dohvati sve instance modula za trenutnu kategoriju, izvrši ih, a njihove generirane sadržaje posloži u glavni template.

Opisi glavnih relacija

kategorija

 Foreign-key constraints:
    "$3" FOREIGN KEY (site_id) REFERENCES site(id) ON UPDATE CASCADE ON DELETE     
 CASCADE
    "$2" FOREIGN KEY (lang) REFERENCES lang(id) ON UPDATE CASCADE ON DELETE CASCADE
    "$1" FOREIGN KEY (template_id) REFERENCES "template"(id) ON UPDATE CASCADE ON   
 DELETE CASCADE

site

template

 Foreign-key constraints:
    "$1" FOREIGN KEY (design_id) REFERENCES design(id)

Glavni template (tfilename) je html/smarty file, koji se svaki put koristi prilikom generiranje konačne stranice. U fileu su definirane pozicije za prikaz uređenih i slobodih modula, kao i includeovi za CSS i JS.

design

layout

 Foreign-key constraints:
    "$3" FOREIGN KEY (module_id) REFERENCES modules(id) ON UPDATE CASCADE ON DELETE CASCADE
    "$2" FOREIGN KEY (kategorija_id) REFERENCES kategorija(id) ON UPDATE CASCADE ON DELETE CASCADE
    "$1" FOREIGN KEY (user_id) REFERENCES users(id) ON UPDATE CASCADE ON DELETE CASCADE

pre_layout

 Foreign-key constraints:
    "$2" FOREIGN KEY (module_id) REFERENCES modules(id) ON UPDATE CASCADE ON DELETE CASCADE
    "$1" FOREIGN KEY (template_id) REFERENCES "template"(id) ON UPDATE CASCADE ON DELETE CASCADE

modules

Klase

Ovdje se nalazi opisi korisnih klasa koje postoje unutar Strix engina.

Dokumentacija klasa koje su napisane tako da se dotična može iz njih automatski izgenerirati pomoću phpDocumentora nalazi se dostupna na http://plivaweb.pliva.hr/phpdoc/

phpDocumentator se pokreće sa:

$ phpdoc -o HTML:frames:phpedit -f class.foo.php -t /data/phpdoc

Opcije su:

 -o : definira izlaz u obliku output:converter:templatedir

 -f : datoteka koja sadrži klasu za koju generiramo dokumentaciju

 -t : path do direktorija gdje će se zapisati generirana dokumentacija

Više o opcijama koje nudi phpDocumentator može se saznati sa:

$ phpdoc -h

Dobar Quickstart manual nalazi se ovdje.

Dvije funkcije koje se mogu koristi bilo gdje u kodu:

• _time_start('name_of_timer')
• _time_stop('name_of_timer')

Stranice pozvane sa profiling url-om oblika

http://www.example.com/?_do_profile=1

koristiti će ove timer-e.

Timeri se mogu u ugnježđivati. To se koristi u STRIX-u za mjerenje
ukupnog vremena potrošenog na Smarty, layout i cijelu stranicu.

Ako je profile uključen, postaviti će se i cookie _do_profile, tako da možete dalje surfati po site-u i gledati profile informacije svake stranice.

Modifikacije u datotekama:

index.php
sysinc/dbinit.php
sysinc/time_profile.php
sysinc/MemCachedClient.inc.php
mod_admin_qlinks.php
templates/admin_qlinks.tpl
app/profile/*

Logiranje rada programa i grešaka

Logging for fun and profit!

Kako logirati pogreške?

jednostavno:

<?php
_debug("...");
_info("...");
_error("boink, error: "._var($foo));
?>

Level logiranja definira se u konfiguracijskoj datoteci ili u enviromentu servera. Defaultne vrijednosti su:

<?php
$_LOG_ERROR = 1;
$_LOG_INFO = 0;
$_LOG_DEBUG = 0;
?>

Oprez! Info level se po defaultu ne zapisuje u log.

Log datoteke

Lokacija log file-a definirana je u php.ini datoteci (obično u /etc/php4/apache/php.ini) kao:

 ; Log errors to specified file.
 error_log = /var/log/php.log

Vlasnik log datoteke mora biti korisnik pod kojim se izvršava web server (na Debianu www-data) da bi se išta zapisivalo u nju osim PHP Warninga.

Što se trenutno logira?

U server details admin quick links postoji ispis koji je trenutan log level, npr:

  Logging: errors, debug, info

Strix Document Management s naglaskom na import dokumenata

O dokumentu

Nove verzije ovog dokumenta bi se mogle naci na strix wikiju.

Verzija 1: Matko Anđelinić, Srpanj 2005., Inicijalna verzija

Opis tablica

Tablica "document"

Glavna tablica. Zapisi i za dokumente i foldere.

PRIMARY KEY (id)

Tablica "document_revision"

Tablica koja veze verziju dokumenta s filenameom na filesystemu servera. Filename
je samo filename i ne ukljucuje path (ni relativni ni apsolutni).

PRIMARY KEY (document_id, version_num)

Napomena 1: Verzioniranje ide redom 1, 2, ....

Napomena 2: Iako folderi ne mogu imati verzije, za njih je svejedno potrebno
imati zapis u ovoj tablici s version_num=0, te proizvoljnim vrijednostima u
ostalim poljima.

Napomena 3: Lokacija dokumenta na disku se racuna ovako:

$docman_dir/$document_id/$version_num/$filename

gdje je

• $docman_dir - konfiguracijska varijabla iz etc/.conf.php
• $document_id - id dokumenta (public.document.id ili public.document_revision.id)
• $version_num - redni broj verzije dokumenta (public.document_revision.version_num)
• $filename - vrijednost u polju public.document_revision.filename

Tablica "document_author"

Vise zapisa po dokumentu. Informacija o autorima dokumenta koja se moze unositi
i mijenjati preko sucelja. Po defaultu bi trebao biti barem jedan zapis s npr.
osobom koja je uploadala dokument.

PRIMARY KEY (document_id, version_num, author_id)
FOREIGN KEY (document_id, version_num) referencira "document_revision"

Ostale tablice

atributi
komentari

Dozvole

Koristi se STRIX-ov sustav dozvola - ACL. Oznaka za dokumente u ACL-u je 'file'.

Tablice acl_user i acl_group

Opis ACL-a nije u scopeu ovog dokumenta pa se nece opisivati. Vazno je da postoje
te tablice, te zgodna plpgsql funkcija:

acl_userObjectAddPerm(user_id, 'file', document_id, perm)

Za dokumente perm moze biti:

• 'PERM_READ' ili integer vrijednost 1
• 'PERM_SUGGEST' ili integer vrijednost 2
• 'PERM_AUTHOR' ili integer vrijednost 4
• 'PERM_OWN' ili integer vrijednost -1 ili 8

Automatska, defaultna dodjela dozvola

Uploaderu se, na razini baze (triggerom) automatski dodjeljuje OWN pravo. Bez
obzira na sučelje kojim je zapis zavrsio u bazi. Uploader je osoba upisana
u polju author_id prilikom inserta recorda u tablicu document.

Za one koji zele znati vise, za to je zaduzen sljedeci zapis u tablici
acl_users_default:

 acl_id |                              default_sql
--------+-----------------------------------------------------------------------
 file   | SELECT 'file', NEW.id, author_id, -1 FROM document WHERE id = NEW.id

Dodatno, preporuka je da se OWN pravo dodijeli i svim osobama navedenim kao autori
dokumenta u tablici document_author.

SELECT acl_userObjectAddPerm($user_id, 'file', $document_id, 'PERM_OWN');

Mali primjer importa dokumenta koristenjem PHP libraryja

Zamislimo slucaj da imamo na filesystemu dokument /data/tmp/dokument.doc kojeg
zelimo importati u novi folder "Novi folder" koji bi se nalazio ispod postojeceg
foldera XXXX sa id-jem 9.

Stanje sadrzaja foldera XXXX prije pokretanja skripte za import:

	plivaweb=# select id, title, folder, depth, ord from getDocumentTree(9);
	 id |   title   | folder | depth | ord
	----+-----------+--------+-------+-----
	 12 | Bayer.zip | f      |     0 |   1
	 13 | Lilly.zip | f      |     0 |   2
	(2 rows)

Skripta za import: docman-import.php

	<?php
	
		include_once("sysinc/stdlib.php");
		include_once "docman.php";
		
		// globalna varijabla koja (ako je true) libraryju govori da 
		// pobrise OWN dozvole koje su automatski dodijeljene uploaderu (author_id)
		// preko triggera u bazi
		$PD_no_automatic_perms = false; 
		
		$parent_folder = 9; 
		$document_path = "/data/tmp/dokument.doc";
		
		$in = array (
		     "title" => "Novi folder"
		   , "description" => ""
		   , "creation_time" => strftime("%Y-%m-%d")
		   , "lang_id" => "1"
		   , "allow_discussion" => "t"
		   , "author_id" => "4"
		   , "approved" => "t"
		   , "keywords" => "testni folder, document import"
		   , "edit_time" => ""
		   , "edit_user" => ""
		   , "source" => ""
		   , "folder" => "t"
		);
		$folder = PlivawebDocuments::createFolder($parent_folder, $in);
		
		if (PlivawebDocumentsError::isError($folder)) die ($folder->text);
		
		//ako smo ovdje u varijabli $folder imamo id novokreiranog foldera
		
		$in = array (
		     "title" => "Moj dokument"
		   , "description" => "Dokument koji sam uploadao"
		   , "creation_time" => strftime("%Y-%m-%d")
		   , "lang_id" => 1 
		   , "allow_discussion" => "t"
		   , "author_id" => 3 
		   , "approved" => "t"
		   , "keywords" => ""
		   , "edit_time" => strftime("%Y-%m-%d")
		   , "edit_user" => 3
		   , "source" => ""
		
		   , "attributes" => array()
		
		   , "local_file_name" => $document_path
		
		);
		
		$did = PlivawebDocuments::addDocument($folder, $in);
		if (PlivawebDocumentsError::isError($did)) die ($did->text);
		
		echo "Document created";

	?>

Pokrenuta skripta:

$ php4 docmanimport-example.php plivaweb

Stanje sadrzaja foldera XXXX poslije pokretanja skripte za import:

	plivaweb=# select id, title, folder, depth, ord from getDocumentTree(9);
	  id  |    title     | folder | depth | ord
	------+--------------+--------+-------+-----
	 4949 | Novi folder  | t      |     0 |   3
	 4950 | Moj dokument | f      |     1 |   4
	   12 | Bayer.zip    | f      |     0 |   6
	   13 | Lilly.zip    | f      |     0 |   7
	(4 rows)

Napomena 1: PHP library u inc/docman.php nije ni blizu kompletan i 100% fail safe,
ali je dobar start za nekoga tko zeli importati dokumente kroz skriptu.

Napomena 2: Nema razloga da se ne napise skripta u nekom drugom jeziku koja
bi direktno pisala po document* tablicama pridrzavajuci se gore opisanih pravila.

Dodatak: Funkcije za dohvat podataka

Postoji niz funkcija za rukovanje (dohvacanje podataka). One su mahom rekurzivne.
Popis tih plpgsql funkcija, zajedno s implementacijom moze se naci u
tables2/docman.sql.

Najcesce koristena takva funkcija je getDocumentTree(folder_id integer) koja
vraca popis zapisa iz document tablicom skupa s dvije dodatne kolone depth (dubina,
razina) te ord (redoslijed po kriteriju folder, title)

Npr.

plivaweb=# select id, title, folder, depth, ord from getDocumentTree(26);
 id  |               title                | folder | depth | ord
-----+------------------------------------+--------+-------+-----
  27 | forms                              | t      |     0 |   1
  28 | AC form                            | f      |     1 |   2
 426 | ChemClient Izjava                  | f      |     1 |   3
 427 | Formular za publikacije            | f      |     1 |   4
 417 | HTS_form.pdf                       | f      |     1 |   5
 418 | New_PL_form.pdf                    | f      |     1 |   6
 419 | New_PL_form.xls                    | f      |     1 |   7
 422 | PK&M form                          | f      |     1 |   8
  29 | Publications Form                  | f      |     1 |   9
 428 | Rjesenje GO                        | f      |     1 |  10
 429 | Zahtjev za nabavu                  | f      |     1 |  11
  33 | instructions                       | t      |     0 |  12
  35 | LabNotebooks law.pdf               | f      |     1 |  13
 421 | Pravilnik za pisanje lab. dnevnika | f      |     1 |  14
 420 | Upute o kretanju NII.pdf           | f      |     1 |  15
  30 | instruments                        | t      |     0 |  16
  31 | instruments_development.xls        | f      |     1 |  17
  32 | instruments_research.xls           | f      |     1 |  18
  37 | presentations                      | t      |     0 |  19
(19 rows)

Preporuka je, ne koristiti ovu funkciju bas za svaku moguci dohvat dokumenata,
jer dodavanje WHERE uvjeta nad ovakav upit nece nimalo ubrzati dohvat podataka.
Ako bi se dodao Where uvjet, svejedno bi se za svaki upit izgenerirao kompletan
result set nakon cega se tek radi filtriranje. Bolje rjesenje je da se za svaku
specificnu upotrebu pri kojoj je bitna efikasnost pise svoja rekurzivna funkcija.

Napomena: Iako to nije slucaj sa funkcijama u tables2/docman.sql, zgodno je
dodati STABLE u definiciji takve funkcije sto bi moglo bitno ubrzati te funkcije
u nekim slucajevima. (Npr. u sucajevima kada se u jednom upitu radi visestruko
pozivanje iste funkcije s istim parametrima).