XmlDoc @ WWW - generation III ----------------------------- Vychazi ze sigiho dokumentace, s minimem uprav. Prakticky se bude kompletnie rusit sigiho PHP vrstva a tedy u generovani. Sigiho PHP se stane NEFUNKCNIM, takze pripadne generovani PDF/CHM se bude muset dopsat, az bude potreba. Rekaputulace stavu u sigiho --------------------------- Existuji 2 zakaldni druhy XML souboru. Struktura je definovana pomoci elemetu . Kazdy soubor obsahujici tento root element je jedna struktura. Na jejich umisteni nezalezi. Tento soubor obsahuje logicky 'strom' - tedy co do dokumentace patri. Cesty jsou pak vyhledavany od 'rootu' dokumentace (pravdepodobne tento soubor - neovereno). Zde se rucne pridavaji soubry, urciji se parent/prev/next a podobne. Soubory, zacinajici element jsou brany jako 'dokument'. Jine XML sepravdepodobne nijak nezpracovavaji. Jakekoliv jine XML soubory jsou brany jako 'externi' soubory a nejsou NIJAK zpracovany. Soubory jine nez XML jsou take zarazeny do 'externich' a nejsou zpracovavany. Odkazy funguje na zakladne 'xlink' elementu, ktery ma 2 typy. Bud definuje atribut pageid nebo refid. Kazdy element mzue obsahovat 'id' atribut a pak se odkazuje pomoci 'refid' v ramci dane stanky. Pomoci pageid se delaji mezi-page linky. Vychazeji ze jmena souboru a pozice v adresarove strukture. Existuji 2 zkratokove zapisy - @ a @@. @ je novy radek a @@ odstavec. Neco je kodovano v UTF, nece ve WIN codepage. Generovani statickych veci je na zaklade konfiguracnich souboru. Zmeny (tedy uz by zde mel byt cas minuly, neb probehly) ===== @@ bude prevedeno na element (paragraph) @ bude prevedno na element. Expandovat se muzou do cehokoliv. Nedaval bych sem umyslne 'br' z HTML, protoze mame '2' ruzne deleni. Jmena elementu nech pripadne navhne axl. Musi jit o elementy 'bez' tela. Sigi povoluje nicmene pouzivat i 'br' takze predpokladam, ze si axl rekne o konverzi tech 3 elementu na 2. Linky se budou funknce menit. Kazdy element bude moci mit 'id' - vcetne docpage. Defaultne to bude jmeno souboru pro 'docpage', elementy pak budou bez sveho ID. se zmeni tak, ze bude jeden atribut - 'target'. Jesli odkazuje na stejnou stranku, nebo jen na jiny element je jedno. Pri konverzi element 'id' bude vygenerovan z jmena souboru. Jinak bude vyzadovat pro docapge. Nebude se nicmene jednat o atribut, ale element na urovni docpage. Jinde se bude jednat o atribut. Jedna z velkych zmen bude zmena docpage. Struktua bude nasledujici: ... ... ... .. std sigiho elementy Poradi je zavazne, nektere elementy budou vyzadovany - zejmena id/owner. Duvod je jednoduchy - daji se pridavat elementy, ktere budou vice popisovat stranku (docpage), jinak by nebyla kontrola. Napriklad zde muze byt cbs-user-name tedy clovek zodpovedny za stranku build,buil2,build3 automaticke vlozeni do buildu 123 priorita pri generovani stromu (cislo, first, last, ...) odkazove_jmeno jmeno pro odkazovani Dokumenty budou prevedeny automaticky - a to vlozenim patricneho elementu a childu. je obecny element a da se pozit i jinde. Owner je vlastnik daneho dokuemntu, tedy odpovedna osoba za jeho zpravu, proto bude vyzdovana. 'id' v zasade vyzadovano byt nemusi, nicmene bych ho vyzadoval, aby bylo jasne z hlediska odkazovani. Muze se pripadne presunout do 'docpage' jako atribut, ale protoze u docpage se jedna o dost specialni vec, nechal bych ji 'as-is'. rozdilnost 'id' of filename se da vyuzit pro jazykove mutace, dke se mzue vyskutovat "neco.xml" a dale "neco.lang.xml" a podobne. System muze kontrolovat konzistenci techto elementu v pripadne jazykovych mutaci, pripadne pomoci parametru a specialniho parametru v ramci DTD pak nepovolit prekaldatelum tyto elementy vubec vkladat. Priapdne preklad mzue zacinat jinym root tages - docpageslave a pod. Soubory s jak jsou ted se zrusi a udela se nahrada, kde se bude moci definovat strutkura automatizovane - pridavat stranky na zaklade pravidel - napriklad adresar s podradresarema, stranky, jez budou mit u v sobe prislusny element "include" s jmenem buildu a podobne. Viz vlasnosti 'docpage'. Na pozici souboru nezalezi a vzdy se pridava v ramci struktury stromu dokuemntu (ne layoutu). Pribyde generalni element pro praci s ACL . Pomoci atributu pujde definovat, jakou uroven musi mit clovek aby videl dany odstavec. 'docpage' muze obsahovat rank v ramci sve hlavicky. Potom cela docpage ve strukture bude schazet. Jinak se budou vyhazovat jen child elementy. Atributy jsou mozne tyto: level - generalni level: public, private, secret a topsecret (opravte mne) group - prislusnost ke skupine v ramci CBS acl - pritomnost konkretniho ACL Uvest se muze pouze jeden z nich, zakladni budit 'level' dle vojaku. Nazvy je mozne zmenit. Dalsi duelzita zmena je to, ze filesystem jako takovy prestava byt dulezity. Odkazy NEBUDOU dale fungovat na urovni filesystemu. Adresar, umisteni a jemno souboru (ani externich !) uz nebude dulezite. To co popisu je jak k tomu bude pristupovat system a s 'defaultnich' chovanim. Veskere dokumenty tvori stromovou strukturu. Jednotlive node budou odeleny '/'. Zapis znamena 'cil'. Jedna stranka muze mit vice 'cilovych' bodu - napriklad pojmenovane casti. Tedy i stranka muze mit sve 'childy'. Pokdu ma stranka 'popis' pojmenovane odstavce 'hlavni' a 'featury' potom ve strome odkazu bude vystupovat jako .... popis hlavni featury Samotne odkazy na strance se nevnoruji, byt je tak ucineno v XML, aby odkazovani bylo jednodussi. Cil je urcen 'path' (/) konvenci - napriklad huhu. Pri vyhledani cile se postupuje nasledovne: 1. vyhleda se cil na urovni 'childu' daneho objektu 2. vyhleda se child an stejen urovni 3. byhleda se o uroven vyse - a pak postupne (dle priorit) v obsahu parenta 4. dokud nebude 'root' prechazi se na [3] Vzdy se porovnava 'cela' odkazovana cast. Cesta je tedy vzdy relativni, dokud se explicitne pomoci / na zacatku neurci absolutne. Dokuemtnacni strom JE JEDEN A JE ZDILEN vsemi. Nicmene na vyslednou funkcni nema pozice dokuemntu vliv (krome pozic a podobne). Role adresaru. Jak jsem rekl - adreare NEHRAJI vice zadnou roli a jsou KOSMETICKE. Pro dobrou organizaci. Soubor se mzue v ramci struktury presouvat jak chce - dokud 'id' bude unikatni zcela bez omezeni. Po udpatu dokuemtnace, se toto musi ujednotit a ve strukture oznacit, jake adresare maji byt, a jake ne, soucasti stromu dokumentu. Pokud 'id' neni unikatni (napriklad 'featury' z vise uvedeneho prikladu mzue byt na 100 strankach) tak se vyhleda cil nejblizsi. Ve vetsine priapdu je toto zadouci chovani (index, ...) a pokud ne, tak se muze pouzit path konvence na specifikaci 'parentu'. Ta muze obsahovat zastupne znaky (jako v XML XPATH). TO znamena, ze muzu mit link ve stylu popis/*/neco A tak podobne. Fatury se mohou pridat dle pozadavku. Cil muze byt ruzny na ruzne urovni ACL. Pokud napriklad mam 'detajly' jako cil, tak dle ACL mohu ukazovat na detajly '2' ruznych stranek - 'detajly' nebo 'detajly_private'. Neda se odkazovat na konkretni elementy - vzdy se odkazuje na id. Elementy se pri tranformaci mohou dost menit, proto nema vyznam na ne odkazovat. Protoze adresar nehraje roli, standardne se vsechny soubory davaji do 'rootu'. Jejich jmeno je odvozeno z 'id'. Pokud soubor nema (XML) nebo neumoznuje id zadat (pdf, png) tak se generuje AUTOMATICKY ze sveho nazvu. Kazdy objekt muze mit vice 'cilovych' nazvu. Tyto dalsi nazvy (sekundarni) slouzi pro pripad, ze neni jina s danym cilem primarni. Jedinou vyjimku z teto nezavilsoti tvori pozice adresare - pokud neni exlicitne urcena jeho pozive ve stromu dokuemntu, pouzije se pozice nadrazene (pripadne nadrazeneho (pripadne nadrazeneho ... :))) adresare. Pokud chci souboru umistnit ve strukture jinde, je nutne udelat specialni soubor 'metadata.xml' jehoz ukolem je urcit, kde se jaky soubor nazyva, pripadne jaky ma 'dst id' name (pro pdf/png/...) Jde tak obsah celeho adresare dat do konkretni casti struktury. Zaroven jde 'prelinkovat' fyzicke umisteni souboru. Pokud se jedna o externi soubury, tak defaultne se do jmena linku NEPRIDAVA pripona. Zaroven je mozno definova ACL i na PDF/... - tedy primo na fyzicke soubory. Pouze pomoci 'metadata.xml'. Zde je take mozno, pokud bude nutne, pro celou skupinu souboru, pridavat i propony. Pokud mam strukturu ala: neco.xml images/obrazek.png tak se na nej odkazu pomoci . System 'sam' dohleda, jesli se jedan o XML, nebo o externi souboru. Jeslize by zde existovalo lokalni id 'obrazek' (takto oznaceny odstavec), tak se ukazalo na nej. Pokud by takovy konflikt nastal, je mozno presunout obrazek do struktury jinam, nebo mu rposte mzenit jmeno - bud fyzicky nebo jen logicky pomoci metadata.xml. Konkretne zde by tento problem nenastal, protoze v prioritach hraje roly primarni typ odkazu - a to je u 'image' externi soubor. Cili, pokud existuje externi soubor a lokalni stejneho id, dostava zde prednost externi. Tyto priority plati pouze v ramci stejne vetve dokumentacniho stromu. Pokud by adresar 'images' obsahoval direktivu, ze nazev adresare tvori cast stromu, potom se na obrazek ukazuje Pripona se std nepridava z toho duvodu, ze std widle nezobrazuji pripony a user musi explictne zjistit priponu. Navic je problem ve velikosti pismen. Zaroven se timto 'rusi' TXT co jsme si udelali, protoze budou soucasti 'strukturalnich' XML (jmena bookmarku a pod). Zustanou pouze 'bookmarks.txt' - jen z toho bude XML. V ramci struktury bude lepsim zpusobem umozneno zobrazovani stranek v ruznych kontextech. Nicmene - soucasti 'aliasu' pro odkazovani pripona *JE* --> to tedy znamena, ze se MUZE uvadet a je mozny mit jeden soubor s 50ti priponama. Pokud Xdoc nedokaze dohledat jediny cil (napriklad odkaz je "obrazek" a existuje "obrazek.jpg" a "obrazek.png" -> error). Co se tyce ranku (obecne seciruty) tak muze byt jak na urovni stromu, tak layoutu nebo dokumentu. Vysledne pak musi dokument projit 'vsim' aby se zobrazil. A pak v ramci kazdeho dokumentu se muze jeste menit obsah v zavislosti na ranku. Obecne se doheldava v aktualni sestave/layoutu, ne ve strukture. Pokud si tedy do layouty (ne)pridate vsechno, pak se odkazy 'gumove' predelaji na patricna mista. Vzdy se ale muze pozuit 'plna' cesta, je-li libo. Pokud existuej nejaky soubor, co nemuze obsahovat popois (napriklad obrazek), pak je mozno udelat k nemu explicitni popisny fajlik. Ted se dela pomoc "filename-control.xml" kde filename je originalni nazev VCETNE pripony. Tento fajl pak obsahuje pouze element. Detajlni popis elementu a pod. jindy, uz toho mam plny zuby, zase jako jedinej neco psat.... (z developeru :) Uvedomujete si vubec, ze tenhle fajl je velky jako 38% x-doc jako celku ? huh TPL --- Na urovni TPL bude existovat sada funkci pro praci. Ty upresnim po schaleni teto casti (a to uz je spise domena mne+axla). Na externi soubory se odkazuej jako na jakykoliv jiny DATA file a to vcetne moznosti cachovani (extfiles, wf.html a pod). Vazba na axlikovo veci je soucasti layoutu, ne struktury. Do layoutu se automaticky pridavaji ne-XML soubory pri referenci (takze pozor na tajne matrose -> a to i pokud je dany odkaz v utajenem elementu !!!) kdezto XML se pridavaji 'rucne' v ramci layoutu. Jeslize nejake sobory jsou tajne, tak je vhodne pouzit 'control.xml' na prislusnou sliozku kde jsou a pro celou slozku nastavit ACL. Tento problem se tyka hlavne offline verzi, kde se muze tajny soubor timto zpusobem 'dostat' do vystupu - sice nebude nikde odkazovan, nicmene... Pokud se ejdna o build typu CHM (tedy non-online), pak system do vystupu nepridava casti XML, ktere neprosli prez ACL takze se vyradi i tyto soubory. Pokud ale foramt je live - soubory se PRIDAJI. System v ten okamzik nevi, zda-li tyto soubory budou posleze potreba pri prohlizeni. Tedy - tajde matrose VZDY explicitne acelkovat - treba celou slozku nebo cast stromu. Struktura --------- Rekapitulace struktury: XML a externi fajly tvori dohromady DOKUMENTACNI STRUKTURU - doc tree. Ta je dana, globalni a zdilena. Pomoci teto struktur probiha odkazovani. Je odelena od struktury soubou - tedy pozice souboru a jeho jemno neni v prime souvislosti s touto dokumentani strukturou. Obecne se to nazyva 'struktura' Logicka sttruktura - layout - tvori dokumentacni strom pro konkretni 'pouziti' nebo popis. Oebcne se mluvi o 'layoutu'. Layoutu muze byt cela rada. Build je konkretni vystup (chm/pdf) konkretniho layoutu za pomoci konkretni tranformace a externich programu (chm compiler, PDF generator, ...). Buildu muze existovat nekolik. Struktura se drzi v ramci SVN. Layouty v ramci XML souboru. Buildy taktez v ramci XML a pripadne dodatecnych skriptu. Tranformace elementu -------------------- DOC page muze obsahovat libovolne mnozstvi urovni tranformaci. Ty se definuji v ramci DTD. Jako primarni se urcti dane DTD, napr: DTD 'XdocFormatEntities.dtd' pak ROZSIRUJE moznosti 'docpage' o dalsi elementy. V tomto pripade vypada zapis takto: Jak je vidno, rozsiruje docpage o element 'toc'. System prohledava XML soubory a pokud najde XML kde je definovat element zapamatuje si danou tranformaci a pokud XML referencuje prislusne DTD, tak tranformaci pusti. Generalni format je nasledujci: urcuje v ramci jakeho DTD se ma XLT spustit obsah elementu je cele jemno souboru s referencovanym DTD dodatecne definovane LNG ID (tranformace je muze vyuzit ve svem tele) atribut 'ref' odkazuje na jmeno XML souboru, kde se nachazi 'lngpharses' jakozto root telo XLT, kde telo obsahuje samotnou tranformaci. rozpoznavaji se tyto atributy: kind druh, aktualne jsou podporovane: simple a tplxlt serial seriove cislo, ktere by se mel zvedat pri kazde zmene element element, pro ktery se dana XLT spusti Tranformace se provadi VZDY pri VIEW stranky ONLINE takze pripadne vazby na ostatni casti systemu (acl, prihlaseny uzivatel, ... cokoliv) jsou PLNE funknci !!!! Priklad tranformace, ktera umozni pouzivat element v jednoduche podobne a tranformuje ho do eleemntu . Proc vlastne ? V podstate jde o 'makro' aby slo pouzivat zjednodusenou formu misto rozsahleho elementu ktery definuje Xdoc jako takova. Tranformace: System\Custom\FormatEntities\XdocFormatEntities.xml Fraze: System\Custom\FormatEntities\XdocFormatEntities_txt.xml (soubor XdocFormatEntities_txt je referencovan primo v tranforamci) Pokud do XLT vstoupi nalsedujici element: (SVN vise uvedene XLT v revizi 3083) bude vystupem teto tranformace toto (pro cestinu) Anyplication ! Dokument Strucny popis Tento element je jiz dale zpracovat Xdoc. Muze taktez dojit ke zretezeni zpracovani. Podobne funguje napriklad 'XdocProdigma.dtd' nicmene elementy zde pridane (iface struct dobj change) jsou zpracovany primo redererem (Whiskey: Tools\Server\Cbs\HtDocs\data\xdoc\original\render.tpl) samozrejmne je idelani, aby tyto elementy byli zakodovany v XLT zde a ne v rendereru. Tranformace - simple -------------------- Simple transformace je urcena pro pozuivani beznou masou. Jedna ze o velice jednoduchou XLT kde telo tvori normalni TPL kod, kde se veskere elementy zdroje nauci to tempalty jako variables. A to nasledobne (viz priklad): text nekde text jinde text v cecku text na konci a_attr_a1 => xxx b_attr_b1 => yyy c => text v cecku K textum 'text...' tedy neni pristup, ani k poradi elementu. Posleze se spusti TPL kod, kde je toto vse nauceno, takze typicky se pouziva {:exists}. Jednoduche :) Tranformace - tplxlt -------------------- Plna tranformace. Telo tranformace tvori data, dle kterych se nauci 'TPL' tranformace a ta se pak proste pusti na dany element se vsim vsudy. Ucelem tela transformace je tedy naucit templatu onu trnaformaci a je to tedy to same, jako volat sadu prikazu: {:xml.transformRuleAdd ...} a dalsi. Jen se to zapisuje v trochu citelenjsi forme. Format obsahu tranfromace: [[element elem]] [[condition cond]] [[flags flagy] [[open]] kod pro open [[close]] kod pro close [[element... dalsi element "elem" - jmenu elementu pro tranformace "cond" - podminka (kompletni expression) "flagy" - flagy (own_childs_exec,pass_unmatched,....) "kod pro open" - TPL kod provedeny pro open elementu "kod pro close" - TPL kod provedeny pro close elementu Pokud NENI uvedent element 'close' ani 'open' je TPL kod pred [[close]] povazovat za 'kod pro open'. Jak funguji TPL XLT je popsano v TPL dokumentaci. Priklad: [[element jobdescription]] [[flags own_childs_exec]] ...... [[close]] ... Tato XLT by se spustil na , ridila by spousteni child elementu a jako celek by generovala ......obsah..... vysledek. Zde je opet videt, jak se 'datovy' element 'jobdescription' preklada na vizualni 'explain' Language pharses ---------------- Xdoc muze vyuzit prekladatelne fraze. Ty se definuji pomoci root elementu 'lngpharses' a maji strukturu tvorenou elementem 'pharse' kde atribut 'lid' obsahuje language ID a telo pak preklad. Tyto fraze jsou samozrejmne plne prekaldatelne. Priklad: Dokument Stručný popis Společnost Oddělení Funknce X-doc pro TPL --------------------- Xdoc jako takova ma sadu funknci, ktere funguje i mimo WWW kontext, typicky v tranformacich. Samozrejmne funguje i v kontextu WWW. Automaticky se napojuji na 'aktualni' Xdoc. V tento okamzik nelze mit otevrene 2 nezavisle Xdoc instance. Lze nicmene rendrovat 2 stranky postupne. To jest prvni a pak druha. Pripadne druha a pak prvni :) Jedna se i tyto funknce: xdoc.linkPrepare (origin link) ------------------------------ Pripravy veskera data potrebna pro 'link'. Origin je treba zadat z nasledujicich: bin - binarni soubor docpage - odkaz na stranku dokumentace any - jakykoliv odkaz Pri vyhledavani cile se bere potaz jeho 'puvod' - tedy binarka, nebo docpage. Pokud existuji 2 stejne cile, lze je rozlisit podle typu - typicky nebo mohou vybrat spravny cil, ikdyz ma stejne jmeno. Pouziva se v XLT. Kazdy 'prepare' nastavi data pro volani 'xdoc.linkQuery'. Nelze mit pripravene dva nebo vice linku 'naraz' (ani k tomu neni duvod). Typicka XLT udela preapre + query (na to co ji ohledne linku zajima). xdoc.linkQuery(name[:param] flags?) ----------------------------------- po provedeni linkPrepare prozkouma vysledky odkaz. 'param' je nepovinny za zavisi na to, co chceme prozkoumat na linku. Flagy jsou taktez nepovinne. Vse vracene je tedy vysledek prechoziho volani linkPrepare. name tedy muze byt: status - vraci 0/1 podle toho, jesli je link OK nebo neni ref - vrati fyzickou referenci na dany objekt (ta se generuje prez callback, ktery zpracovava WWW knihovna x-docu). pokud linky zpracovava WWW modul, tak pri 'ref' jsou validni tyto flagy: href - pokud existuje 'cil na strance' generuje se #anchor inner - vraci odkaz v ramci dokumentu (ID/jmeno objektu, typicky se pouzije pro #anchor) pokud cil neobsahuje inner cast, vraci se prazdny vesmir niceurl - vrati nice url cestu na dany objekt (v ramci dokumentace !!!) meta - vraci hodnotu meta property pro cil. 'param' je v tomto pripade seznam metas, ktere se maji najit. pri nalezeni prvni se konci, jinak se pokracuje v hledani dalsi. Jako prvni se hleda 'meta' pro dany objekt, pokud existuje 'vnitrni' cil (objekt v ramci DOCu - pojmenovany odstravec, ....) a existuje meta pro dany vnitrni cil pouzije se tato priklad: xdoc.linkQuery(metas:lname,chapter) -> pokusi se najit v ramci linku 'lname' pokud neexistuje bude hledat 'chapter'. To znamena, ze pokud definuji strance 'lname' (link name) meta propertu, tak kdyz se na mne nekdo odkaze, bude mit link tento nazev. Pokud ne, pouzije se 'chapter' (nazev kapitoly). vnitrni cile. Mejme stranku 'stranka' se 4ma odstavcema, ktere se jmenuji (odstavce) a b c d. Pokud 'cil' bude 'stranka#a' tak jako prvni se proheldaji meta vlastnosti daneho odstavce a pak cele stranky. Odstavec 'a' ma definovano lname jako meta vlasnost 'ja_jsem_a'. Ostatni nemaji. Samotna stranka nema lname nicmene chapter je na 'kapitolaX'. Pri zavolani 'lname' dostaneme vysledky: stranka -> 'kapitolaX' stranka.b -> 'kapitolaX' stranka.a -> 'ja_jsem_a' Timto zpusobem lze kontrolovat, pokud by nekdo chtel, jmeno pri okazovani na dany objekt. Meta property jsou nastavovat automaticky, takze lze vyuzit i lokalni nadpis. Napriklad: .... Detajl fetury hurvajz .... Pokud odkazu na 'detajl' (resp. klidne stranka.detajl, XDoc dohleda sam nejblizsi cil, viz nekde nahore) dostanu na pro 'lname' 'Detajl featury hurvajz' tim padem kdyz nekd napisu: .... viz tak se mi vygeneruje Detajl featury hurvajz a nemusim vsude vypisovat jmeno linku nebo jako debil psat: viz tady Podotykam, ze Xdoc nerozlisuje 'inner' - tj. vzdy se pise / a zbytek je na sytemu. Typicka XLT u xlink rozslisuje, jesli ma 'xlink' dany jemno linku nebo ne. Pokud ne dohelda ho. A k tomu slouzi prave (mimo dalsich moznost) meta vlasnosti. Meta muze byt zaroven X/Y obrazku, cokoliv. Metas jsou pomerne mocne az caromocne :) Jdou take psat/definvoat rucne. xdoc.getId(id_elementu?) ------------------------ Prevadi ID daneho elementu na textove. Pokud neni 'id_elementu' zadano, ziska se volanim {:xml.elemId this}. Jinak ID zustava v 'ciselne' podobne. Pri 'auto elementu' se predpoklada se tedy beh v ramci tranformace. Jinymi slovy, pokud se nekde tak se jako jeho id bude pouzivat 'jmeno' jinak systemem 'vygenerovane' cislo. xdoc.getSearchLink(cislo_stranky?) DEPRECATED ---------------------------------- Pri pouziti 'searchu' v ramci render stranky (xdoc.search) vraci odkaz na 'search' stranku (viz parametry xdoc.search xdoc.getControlCode ------------------- Vraci obsah systemoveho souboru CbsTpl_xdoc_page_control.tpl v ramci CBS generovani dokumentace. Neni duvod ji pouzivat jindy :) xdoc.generateContents(dst type xml_params) ------------------------------------------ Generuje 'obsah'. Aktualne generuje 'childs' dane cesty (muze se pridavt dalsi forma, treba o cely substromecek) Parametry 'type' je nevyuzit, predavat prazny retezec. 'xml_params' jsou XML definvoane volby: vyzadovano titul volitelne volitelne + opakujici se co volitelne dle_ceho volitelne + opakujici se typy volitelne Typicky se predava primo to co je v souboru - cely element atribut 'root' obsahuje zacatek generovani obsahu. Specialni hodnota 'this' hleda vlastni childy pokud cesta zacina '.' bere se od aktualniho dokumentu, jinak se vyhledava nejblizsi cil, ktery splni obsahu atributu root. To jest najde se v ceste vse co obsahuje 'root' a pak se vysledek setridi dle delky 'pred' a 'po' vyskytu. Prvni se pak bere jakozto vysledna cesta (tj. neblizsi k zadane) obsah elementu aktualne nevyuzit <display> atribut data obsahuje meta-propertu, ktera se ma 'posbirat' (a pozdeji asi i zobrazit :) systemove meta vlasnosti jsou (popsane jsou/budou v ramci Xdocu): user,chapter,overview,width height,lname,nupath <search> omezeni vyslednych dokumentu: 'where' musi byt 'co'. Where muze nabyvat: metaprop:jmeno_metaproperty -> metaproperta musi mit zadany obsah. pokud je prazdny tak dana metaproperta musi existovat typicke pouziti je filtrovani 'content' podle ruznych 'tagu' (napr. stranky tykajici se 'nastaveni' mohou mit prislusnou metapropertu a pak se mzue seznam generovat pekne dynamicky) <sort> srovna vysledek dle parametru type typ rovnani: nic=text num=ciselne by type trideni: metaprop dle metaproeperty svnmtime modifikace na SVN order desc=sestupne, jinak vzestupne dle_ceho na zaklade by: metaprop jmeno metaproperty <types> carkama oddeleny seznam objektu, co se maji vygenerovat. je to obecny alias pro Xdoc typ objektu, nicmene smysl zde ma pouze: docpage stranka bin binarni soubor (jpg, ...) nodeinfo dir info pokud neni uvedeno, hleda se vse co ma pozici ve strukture layoutu Vysledek samzorejmen respektuje SVN/XDOC prava a aktualni Layout. Na konci se nauci tabulka jmenem 'dst'. Ta obsahuje tytpe sloupce: id reference objektu [sys.meta] systemove meta-property (vyzadane) - viz <display> link link na objekt - musi se predat do linkPrepare -> neni tedy konecny a jeho format je systemovy type Xdoc typ objektu - textove (nodeinfo,docpage,...) svnmtime modifikace SVN xdoc.metaPropVal(name) ---------------------- Vraci meta propertu pro aktualni stranku. Ty si definuje user. Krome user-defined meta propert je zde i par systemovych: sys.name jmeno stranky - link name sys.file jmeno SVN zdroje stranky sys.path cesta SVN zdroje stranky sys.lang aktualni jazyk stranky (fyzicky, ten co je zobrazen) Xdoc<->WWW ----------- X-doc uz se umi zobrazit na webu. Proto ma nekolik prikazu, v ramci knihovny 'xdoc'. Jeden ze zakladnich problemu, ktere Xdoc musi resit, je predavani 'stavu'. Jedna se zejmena o: - layout ID - zobrazovanou stranku - otevrene nody ve stromecku - vysviceni hledaneho terminu Xdoc nektere linky generuje 'sama' v ramci generovani vystupu. Jedna se o: - link v ramci textu (jine tranky) - odkazy na obrazky a jine externi soubory Aby Xdoc mohla generovat linky jak ma, tak nektere prikazy umoznuji nastavit toto tvoreni linku. Kdyby to tak nebylo, musel by existovat nejaky 'callback' ktery by na zaklade parametru generoval, coz by bylo slozite (ve skutecnosti Xdoc na urovni LIBu takovy callback ma a o jeho provedeni se stara www lib xdoc, na zaklade predanych nastaveni) Naopak, Xdoc negeneruje linky na nasledujici (nestara se o vystup) - navigacniho stromecku Proto Xdoc umoznuje nastavit template variable, ktere k temto ucelum pouziva. Ty samozrejmne muzou byt NiceUrl a tim padem slouzit k peknym odkazum. Pokud neni pouzito NU, tak si Xdoc v parametry predava Par poznamek: - otevrene nody si lze uchovavat v session (viz moznosti CBS) - nemusi se vybec posilat klientovy - stejne jak vysvicena klicova slova - vysviceni klicovych slov lze provadet jak pri searchu tak i klidne ad-hoc a zapinat/vypinat dle prani usera - jdou samozrejmne prenased i prez klasicke TPL itemu (ssid nebo req) xdoc.init (data_id) ------------------- inicializace Xdocu, jako parametr je potreba zadat ID dat, na ktere se ma Xdoc pripojit xdoc.setParam (name value) -------------------------- nastavi parametr 'name' na 'value'. Vyznam parametru: variable, fungujici v ramci vytvareni linku: linkvar.nodes - otevrene nody navigacniho stromecku linkvar.highlight - hledany term pro vysviceni (zadany text se zvyrazni - je to seznam ID do klicovych slov) linkvar.page_niceurl - odkaz na stranku predavany jako 'nice URL' (nelze kombinovat s linkvar.page) linkvar.link - parametry linku xdoc.result (name) ------------------ nauci variablu 'name' vystupem z posledniho prikazu, ktery vraci nejaky 'text' xdoc.status ----------- vraci 'status' Xdocu (prazdno) - ok noinit - neni inicializovano access - access denied chyba notfound - stranka/layout nenalezen params - chyba v parametrech xdoc.layoutsGet (name) ---------------------- nauci tabulku 'name' vsemi dostupny layouty xdoc.pagePrepare (layout page?) ------------------------------- pripravi stranku v ramci layoutu (pokud je page=0 tak pripravy vychozi) naucit hodne promenych, jejichz seznam upresnim casem, {:dump} je kamarad uci se veskera navitagce, TOC stromecek, prev/next, meta props (vcetne prev/next/up) a tak dale result v tomto bode je ORIGINALNI xml v ramci Xdocu layout muze byt ciselne id nebo name, ktere je definovano v layoutu page muze byt ciselne id nice-url cesta (pokdu Xdoc ma nice URL) xdoc.pageXltBegin ----------------- priprava na tranformaci a prikazu TPL pouzivanych v ramci tranformace xdoc.pageXltEnd --------------- opak k begin, uzavira.. je mozno volat vice XLT najednou (postupne) xdoc.pageXltBuiltIn (text) -------------------------- prozene 'text' interni XLT (jako ma CBS) a vraci ho v ramci resultu. Tato XLT je zde vicemene na tstovani, realna XLT bude udelana normalne v ramci WWW modulu a jejich XLT. Neni moznost z WWW ovlivnit interni XLT, daji se jen udelat vlastni. Defaultni XLT se nachazi ve whiskey, na adrese Tools\Server\Cbs\HtDocs\data\xdoc\original\render.tpl (pro predstavu... je to malinkata XLT) Vrele nedoporucuji tuto funknce POZIVAT !!!! Misto toho vyuzit vlastni XLT. xdoc.search (var_pharse search_opts var_results_page) ----------------------------------------------- provede search pharse - nacte si je z promene 'var_pharse'. 'var_results_page' se pouziva pri generovani linku. Tato funknce vyhledava zpusobem, ktery je identicky se zobrazenim stranky, pouze misto vystupu stranky nauci vysledek hledani. 'ex' verze je nicmene na pouziti primejsi a je doporucena pro pozuivani. Vysledek je identicky jako u xdoc.searchEx funkce. Podporovane search_opts - ve forme 'volba volba2' - viz EX verze: nat -> usenational or -> defaultor Pro beh teto funkce musi probehnout xdoc.pagePrepare O ACL a dalsi veci se stara Xdoc a je vuci userovy transparetni. xdoc.searchEx (layout pharse options) ------------------------------------- Zcela necekane tato funkce hleda 'pharse'. Narozdil od ne-ex verze bezi mimo pagePrare a staci obligatni init. 'options' jsou v link formne (option&option2=value)... Plati pro ni to same jako pro ne-EX verzi (ACL, ...) Pokud neni definovan typ, jedna se o true/false -> pritomnost je true Volby: usenational - pouzit 'nacionalni' verzi, jinak se vyhledava konvertovane ANSI (ignoruji se hacky/carky -> dlouhe 'a' je to same jako 'a') vysviceni se pak provede ve vsech formach, takze pokud hledam 'neco' tak to se muze vyhledavat nekolik klicovych slov: neco ne~co a pod. defaultor - slova se spojuji 'OR' a ne 'AND' page - cislo stranky v resultech - kolikatou stranku zobrazit (pocita se od 0) mnoho voleb neni exportovano - velikost stranky (25 default) a dalsi, dle pozadavku pridam Vysledkem je rada naucenych vars. Jmenovite: xResults tabulka vysledku, majici tyto sloupce: id ID objektu (content ID) lcid layout content ID order relevance relevance (pdole toho kde se naleza - text, jmeno kapitoly, ...) words pocet slov ktere se nalezly ze searchu occurrence kolikrat se slova vyskytli type typ objekty (viz vise) - akorat je zde numericka forma, musim zmenit na TXT alias niceurl NU cesta k dokumentu, pokud existuje link vytvoreny link (prioritne NU) a pozadovane meta property, tedy napr: chapter, overview a dalsi xNav prefix pro standardni CBS 'strankovani' - viz Architecture.txt : cbsSearchPreparePaging jmena jsou ucena s prvni pismenem velky, tedy xNavNeco xNavNeco2 etc. xMatches celkovy pocet nalezenych vysledku xTotalDocs pocet proheldanych dokumentu xEmpty 1 pokud neco nalezeno, 0 pokud ne xlLayoutName layout, ve kterem se heldalo Pokud se nic nenalezne, existuje pouze xEmpty, ostatni nejsou nauceny. DB struktura ------------ Nekdy rekne vic nez 1000 slov :) Struktura se generuje z XML, nicmene, zpracovava se kompletne runtime. Vyjimu tvori 'build', ktere se updatuji rucne/dle potreb. Build nejsou soucasti (vysledek) SVN. Zaroven se nedrzi historie buildu, nicmene, diky SVN se muze generovat verze v ramci jakehokoliv data. To plati pro celou dokumentaci - cela dokuemtnace je synchonizovana se 'SVN' reizi - takze je mozno delat releasy, vetveni a podobne. V konfiguraci modulu se zadava 'cesta' a 'revize' v ramci SVN. Tak pak ovlivni VSE. Protoze DOC bude 'mini modul' na bazi DTD, je mozne provozovat nekolik nezavislych instanci dokumetnace najednou (s ruznymi nastavenimi). XDOCS side tabulka k 'datum' int id data instance ID txt d_svnbase SVN cesta ke stahovani patricke DOC txt d_svnrev revize (HEAD: aktualni) date d_update datum posledniho 'udpate' tabulek txt d_update_base SVN base pri update txt d_update_rev SVN base pri update int d_opts options 1 - auto update 'texts' from SVN BUILDS offline buildy dokumentace (generovano z XML) seq id id buildu txt b_name jmeno txt b_comment komentar txt b_format typ vystupu (chm/pdf/...) bin b_result aktualni 'obsah' (tedy fyzicky CHM/PDF/...) txt b_result aktualni delka obsahu txt b_mime MIME typ pro download (muze byt jen 'pripona') date b_gentime datum generovani txt b_genrevision reize SVN ve std SVN tvaru key:layouts.id b_layout pouzity layout LAYOUTS layouty dokumentace (logicke stromy) seq id id txt l_name jmeno key:layoutcontents l_default 'index' v ramci layoutu (default stranka) key:layoutcontents l_accessdenied access 'denied' stranka (sem se odkaze v priapdne odepreni pristupu na dokument) key:layoutcontents l_missing -//- stranka neni v danem layoutu dispozici txt l_tocdisplay tabulka, sloupce 'kind' a 'display' (tvorena {row} a {val}) aktualni kindy navigation - co ukazat v navigaci tree - co ukacat v tree (jmeno,komentar) je mozno pouzit atribut (ala 'id') nebo meta - meta:jmeno LAYOUTSCONTENTS obsah layoutu, tabulka generovana na zaklade pravidel uvedenych v XML,nezavisle na LNG (vyuziva default) seq id id radku key:layouts.id bc_layout relevatni layout key:contents.id bc_doc reference na dokument jako takovy key:struct.id bc_srcstruct reference na strukturu, pokdu je dokument pridat skrze strukturu key:contents.id bc_srcdoc reference na dokument, jez pridava polozku key:id bc_next dalsi v ramci nody layoutu (pouze DOC pages) key:id bc_prev predchozi v ramci nody layoutu (pouze DOC pages) key:id bc_next2 dalsi v ramci celeho layoutu (pouze DOC pages) key:id bc_prev2 predchozi v ramci celeho layoutu (pouze DOC pages) key:id bc_parent rodic v ramci layoutu (pouze DOC pages) key:id bc_firstchild prvni detatko v ramci layoutu - 'index' je preskocen (pouze DOC pages) key:id bc_index pokud ma noda index, odkaz na ni (pouze DOC pages) int bc_innerpos nested zaznam, index v ramci zdrojoveho dokumentu (NULL pokud neni inner) txt bc_path kompletni path vcetne aliasu txt bc_constraints omezeni, aplikovana pri generovani, format: omezeni[=value];omezeni2[=value]... txt bc_rank rank daneho zaznamu (ACL, security status, ..) txt bc_bookmark web bookmark (odkaz na axlovo bookmark) - vzdy platny, dogenerovany z 'XML' zdroju int bc_isindex 1 pokud je dany DOC indexem v ramci nody int bc_type typ zaznamu, pokud bc_doc neni NULL potom kopie c_type, jinak NULL STRUCT fyzicka struktura dokumentace - pouze strom (generovani z XML na zaklade metadata.xml a FS) seq id id txt s_name jmeno (pouzito pri odkazovani) txt s_path cesta v ramci stromu (plna) key:id s_parent rodic dokumentu key:contents s_content pokud strukturu definuje nejaky dokument, je to link na nej txt s_rank rank dane casti struktury (ACL, security status, ..) Je nutno si uvedomit, ze STRUCT vnika 'mimo' strukturu adresaru, jmen souboru a zaroven, ze rada casti stromu muze byt pridavana 'automaticky' - napriklad stranka s anchorem se sem prida. CONTENTS fyzicky obsah (generovani z XML + auomaticky) seq id cislo (nema nic spolecneho s odkazovanim) bin c_ctx fyzicky obsah (XML, PDF, ...) v konvenci data modulu (tj. atributy na zacatku: mime/fname) txt c_ctxmd5 MD5 sum of contents txt c_path cesta k souboru (v ramci SVN) txt c_pathinner cesta v ramci source objektu - muze to byt napriklad cesta/poradi elementu (u XML virtual-anchor) int c_type typ obsahu XDOC_CONTENT_TYPE_* 0: XML docpage 1: externi binarni soubor 2: 'virtualni' cil (napriklad cil v ramci jineho objektu ala anchor) 3: systemovy/konfiguracni soubor (pridavano automaticky) 4: jazykvoa mutace (c_source je original) 5: layout deklarace key:id c_source zdrojovy obsah (napriklad XML stranka pro anchor, u jazkobvych mutaci original a pod) txt c_name jmeno (pozuivane pro okazovani) txt c_namefull plna cesta v ramci struktury, pocet koncovich '@' urcuje hloubku inner cesty key:struct.id c_struct pozice ve strukture int:users.id c_owner vlasnik int c_prior prioria (0:neutralni) cim vissi tim vice 'top' bude dokument int c_indexprior priorita indexu. NULL opkud nema byt index txt c_include pravidla pro autoamticke vkladani do buildu txt c_rank rank dokumentu (ACL, security status, ..) txt c_lang lang id (CZ,EN,...) NULL pokud nema vyznam key:xlt.id c_customxlt custom XLT reference, pokud je znama int c_order priorita pri razeni txt c_svnmtime SVN modification time v SVN formatu METAS meta hodnoty - nazvy stranek, user veci, ... seq id cislo (nema nic spolecneho s odkazovanim) key:contents.id cm_content relevantni content key:layouts.id cm_layout relevantni layout (pokud META definuje layout) txt cm_name jmeno meta hodnoty (pokud se jedna o ssytemovu, pak systemove jmeno) int cm_kind systemove cislo druhu (typu) - NULL='user' txt cm_value hodnota int cm_offset index od zacatku, jemuz properta nalezi, NULL pokud se jedna o globalni *typicky index elementu) LINKS linky seq id cislo (nema nic spolecneho s odkazovanim) key:contents.id x_src zdrojovy content key:contents.id x_dst cilovy content - vzdy defalt jazykova mutace key:contents.id x_dstctx cilovy content - zakladni source, bez inner cile int x_dsttype dst type copy int x_dstoffset dst offset - pokud ma vyznam (typicky element index) cile linku int x_origin puvod linku 0:bin odkaz 1:docpage odkaz (rucni) txt x_lname kompletni 'linkname', vcetne inners int x_innertrail konec 'inner' linku - cast, kde se dokazuji pouze 'inner' dokumenty XLT transformace seq id seq id txt x_reference DTD name ref key:contents.id x_pharses pharse to load XLTBODIES samotne tranformace seq id seq id key:xlt.id xb_xlt XLT txt xb_element element kde zacit int xb_kind druh tela (0: simple TPL) int xb_serial serial number (cim vetsi tim novejsi) txt xb_body telo jako takove FTWORDS full text fraze (pro kazde slovo o dane relevanci samostatny zaznam) int id seq id txt:32 fw_word word txt:32 fw_word_base word, bez nacionalnich znaku int fw_relevance relevance 300 titulek 200 nadpis 100 telo FTINDEX full text index - pokud je slovo v dokumentu ve vice relevancich, ukazuje se na jeden zaznam s nejvetsi relevanci seq id seq id key:contents.id fi_ctx related content key:ftwords.id fi_word referenced word int fi_cnt celkovy pocet slov v dokumentu (nehelde na relevance) text:4 fi_lang ISO jazyka