Na nabídku

Programátorská část aneb trocha dokumentace


Celý systém stojí a padá se soubory a stromem složek. Uspořádání stromu má svou logiku v oddělení jednotlivých částí modulů a možnosti jejich úprav pomocí centrálních funkcí.

Zadání

  • Webové stránky se správou
  • Nahrávání obrázků, dokumentů, videí
  • Vice možných uživatelů
  • Výrazná modulárnost
  • Žádná databáze
  • Definované vstupy a výstupy - rozumně rozdělené zpracování a odpověď

Elementární modul

Elementární modul je soubor obsahující třídu, který leží v patřičném místě - složce s moduly. Třída v něm implementuje rozhraní pro danou část KWCMS. Zpravidla jde o parametry v __construct() a výstup v out(). Třída s modulem je též napojená na zbytek systému, ať už ve výpisu modulů nebo v menu.

#ELEMENTARY modul pro prezentaci
# modules/elementarytest/base/module.php

class elementarytest extends modules {
 private $par = array();
 const module = 'elementarytest'; # nekde jako promenna, pak lze rychle zmenit sablony

 public function __construct($params=array()) {
  global $conf;
//  if (!$conf->load(self::module)) throw new Exception ('cannot load config');
//  if (!$conf->lang(self::module)) throw new Exception ('cannot load langs');
  if (count($params) > 0)
   $this->par = $params;
 }

 public function out() { # vypust
  $r = 'Ahoj, jsem Elementary module.';
  $t = new template(self::module, 'elementary');
  $t->change('{-GET-}', $r);
  if (count($this->par) > 0)
   $t->change('{-PARAM-}', key($this->par).':'.current($this->par));
  $t->change('{-PARAM-}', 'Nothing.');
  $r = $t->out();
  return $r;
 }
}
#ELEMENTARY sablona v prezentaci
# modules/elementarytest/style/elementary.htm
 <-div class="elementary"->{-GET-}: {-PARAM-} <-/div->

Dále stačí nahlédnout do dalších, již provozních modulů.

Více možností mají knihovny. Ty sice nic neimplementují, avšak jsou cílené na 5 operací - přidání, úpravu, mazání, vyhledání a detaily. Protože nemusí obsahovat všechny operace, nelze (zatím) sestavit jejich rozhraní nebo abstraktní třídu. Nastavení detailů probíhá opět přes __construct().

#ELEMENTARY knihovna pro administraci
# lib/libelementary.php

class libelementary {
 private $par = array();
 private $cont = array();

 public function __construct($params=array()) {
  if (count($params) > 0)
   $this->par = $params;
 }

 public function __destruct() { # uklid
  foreach (array_keys(get_object_vars($this)) as $val)
    unset($this->$val);
 }

 public function add($line) { # vloz
  $this->cont[] = $line;
  return true;
 }

 public function update($id, $line) { # uprav
  if (isset($this->cont[$id])) {
   $this->cont[$id] = $line;
   return true;
  };
  return false;
 }

 public function remove($id) { # smaz
  if (isset($this->cont[$id])) {
   unset($this->cont[$id]);
   return true;
  };
  return false;
 }

 public function entry($id) { # prvek
  if (isset($this->cont[$id]))
   return $this->cont[$id];
  return null;
 }

 public function out() { # vypust
  return $this->cont;
 }
}

Moduly pro zobrazení

V modules/ se nachází složka pojmenovaná jako modul. V ní pak minimálně složka base/ , ve které je soubor module.php , obsahující samotný kód modulu. Podle potřeby ještě přibývají složky conf/ (nastavení), style/ (šablony součástí) a lang/ (jazyky).

Třída tvořící modul se jmenuje stejně jako modul sám. Musí implementovat rozhraní třídy.

Parametry ze stránek dostává vstupní funkce __construct() jako pole jmenných hodnot. Samotný modul vrací obsah podle stupňování - tedy že vypíše to, co tam patří a co má práva. Je to vidět třeba u RSS nebo LANGS.

Přidání modulu do prezentace se provádí (zatím) přes výpis /modules/module.X.conf přidáním řádku s modulem do výpisu. "X" je úroveň.

Přidání modulu do administrace se provádí (zatím) přes šablonu /style/main.htm přidáním řádku s modulem do menu.

Zvláštní moduly

Nachází se v složkách /base/modules , /admin/base/lib a /admin/comp . Jde o moduly nutné pro rozsáhlejší možnosti systému - práve zde se ukrývá spojení s databázemi a (v administraci) správa uživatelu. Jejich usporádání je pokud možno shodné s ostatními moduly, avšak mohou mít více výstupních funkcí (právě databáze).

Upozorňuji, že vzhled veškerých modulu si navíc může uživatel upravit tím, že si přidá patřičné cesty a soubory do svých složek.

Pokud hodláte tvořit další moduly, tak doporučuji se kouknout na kód těch již vytvořených a hlavně na jejich uspořádání vůči systému. Zpravidla to funguje tak, že modul dostává od systému minimum informací a co si nese, to má. Se závislostmi je to také neslavné, pokud autor nebyl hodný a nenapsal o ní, tak se to dozvíte až studiem kódu.

Třídy, které systém používá k zobrazování

BASE - Jádro systému, má na svědomí zobrazování stránek a rozhoduje, zda-li se bude obsah šperkovat dalšími součástmi nebo ne. Nelze využít k běžnému psaní modulu.

CACHE - Keš. Ukládá data, která se téměř nemění, jako jakousi šablonu.

CONFS - Nastavení. Načítá nastavení.

HEADERS - Hlavičky. Určují rozhraní jednotlivým částem.

MODULES - Načítá a zobrazuje moduly. Jinými slovy, tahle třída stojí přesně na druhé straně, než použitelné třídy neb je volá, a proto je zajímavá až při testování funkčnosti v rámci systému.

PATHS - Cesty. Má tři úkoly: Za prvé vůbec cesty nastavit. Za druhé umožnit pracovat s jmény souborů. A za třetí podle nastavení přepisovat cesty na "hezká" URL. Jeho rozhraní je jedno z nejpoužitelnějších.

RECODE - Přepis. Má opět jednoduchý úkol - překopnou veškeré národní znaky do UTF8 entit. Text k překódování se posílá jako řetězec do out() .

TEMPLATE - Šablony. Nejdůležitější třída pro tvorbu modulů - zajišťuje vzhledy pomocí šablon. Její nejčastěji používané funkce jsou Change(zčeho, na_co)_ a Out() . Do Template lze vložit i vlastní šablonu, uloženou mimo určená místa, avšak tím se potlačí schopnost změn uživatelem a odpovědnost za modul spadne na programátora.

TEXTFILE - Další zvláštní verze Template (souborem v něm). Navíc hledá moduly, které jsou na stránce. A opět slouží pouze pro potřeby třídy Base .

Třídy, které systém používá ke správě

AUTH - Poměrně zásadní třída ověřující uživatele vůči systému. Neměla by být volána mimo Base a ani by neměla být užívána její globální proměnná $auth.

BASE - Jádro systému, vybírá modul k načtení a ověřuje uživatelovu totožnost. Modul potřebuje vědět akorát to, jak ji zavolat, aby se spustil.

CAPTCHA - Trochu divná třída, která ale nutí uživatele ověřit, že je člověk. Nutná jen k přihlášení, ale ne pro moduly.

HEADERS - Hlavičky tříd. Nutná pro moduly, definuje jejich rozhraní a použitelné konstanty.

INCL - Třída, která vkládá další součásti. Moduly ji též využívají.

LANGS - Kódování do různých jazyků. Z každé části, kterou systém má, dostane pole jazyků a provede překódování. Moduly ji využívají jen pokud jedou sólo. Zpracovávající funkce je atypicky Chg() , out() provádí úplný přepis podle všech jazyků.

MODULE - Tak tato třída volá obsah externího modulu a řeší, jestli je třeba ho ocukrovat. Jinak nepoužitelná.

MODULES - Až na podobu jména má zcela jiný účinek - zpracovává poslaná data pro moduly a brání podhození závadných řetězců. Dále připravuje řádek s odpovědí pro některé moduly.

TEMPLATE - Nejdůležitější třída pro tvorbu modulů - zajišťuje vzhledy pomocí šablon. Její nejčastěji používané funkce jsou Change(zčeho, na_co)_ a Out() . Opět neexistuje možnost vložit do Template vlastní šablonu, uloženou mimo určená místa, (právě kvůli možnosti uživatelů je měnit).

Knihovny administrace

BANNED - Ovocná smršť pro nezvané hosty. Zamezuje přístup z blokovaných IP (zatím teda starším režimem). Modul ji nepotřebuje.

DISK_SPACE - Třída, která vypisuje množství místa na disku, které vám pro hrátky se soubory zbývá. Výstup klasicky out() .

CGROUPS - Správa uživatelských skupin. Příliš specifická a tedy správně nepoužitelná.

CCLASSES - Správa uživatelských tříd. Příliš specifická a tedy správně nepoužitelná.

LOGS - Zaznamenávání problémových operací. Logování systém běžně používá pouze na zaznamenávání manipulací s účty.

META - Práce s metadaty. Ono nejde o jiná data, než ta upravující menu. V budoucnu asi půjde přímo do složky modulu TREE. Moduly je mohou použít.

MIMETYPE - Práce s mime souborů. Je třeba jakmile zjistíte, že poskytovatel nevede funkce mime_content_type() a finfo , což u souborově zaměřené správy nepotěší. Moduly ji mohou použít, výstup se volá přes mime(složka,soubor) .

PASSWD - Pracuje přímo se soubory s jmény a hesly uživatelů. Neměla by se volat ničím, protože hrozí reálné riziko průseru.

RECODE - Má jednoduchý úkol - překopnou veškeré národní znaky do UTF8 entit. Text k překódování se posílá jako řetězec přes out() .

USRDIR - Uživatelské složky. Neměla by se volat ničím, protože hrozí reálné riziko průseru.

Komponenty administrace

CSCRIPTS - Vkládá do stránky skripty modulů. Volá ji Base a jinak je nepoužitelná.

CSTYLES - Totéž, akorát se styly.

MAIN - Poněkud divná třída. Na jednu stranu cukruje výpis Module , na druhou zase doplňuje dynamicky generované menu.

CHOSEDIR - Parťačka Paths . Tahle vypisuje formulář pro výměnu složky, který pak Paths zpracovává.

LOCATIONS - Zásadní třída, bez které se systém a ani některé moduly nehnou ( Chosedir ). Má na svědomí pročesávání stromu webu a jeho následné zpracovávání. Taktéž je proto tou nejpomalejší ze všech. Naštěstí ji zpravidla stačí zavolat 1x. Je závislá na Mimetype .

Zvláštní příznaky

ONLY_CONTENT - O obsah se stará jenom modul, tedy i takové věci jako překódování či jazyky jsou na jeho triku. Je potřeba ho nastavit ještě před voláním Base .

Moduly zobrazení, bez kterých by to šlo, ale nebylo by to ono

a:LOGIN - Vlastně modul, který vypisuje formulář k přihlášení. Jinak nepoužitelná.

a:LOGOUT - Taky vlastně modul, který ale odhlašuje. Nebezpečná.

a:USERS - Správa uživatelských účtů. Nebezpečná, Vyřazená.

a:GROUPS - Správa uživatelských skupin. Nebezpečná, Vyřazená.

a:CHSETT - Správa nastavení. Nebezpečná.

p:ERRORS - Chybové hlášky. Potřebují ještě nastavit .htaccess, aby se zobrazily.

p:LANGS - Jazyky. Pokud je nastaveno více jazyku, tak tyhle moduly zobrazují vlaječky výběru jazyků. Langs je do stránky, Langselect někam na bok.

p:MENU - Nabídka. Ke svému využití potřebují ještě zvláštní soubory, které nabídku popíší. Navíc je možno použít i Cache.

p:LOGO - Logo. To je ten obrázek, který je (zpravidla) nahoře v koutě.

p:SHORTM - Krátké zprávy. Je zpravidla určený pro informování o aktualitách. A stránka, kde se nic neobjevuje, je mrtvá stránka.

p:THEME - Témata a styly. Třída slouží jako výběr stylů a jejich témat podle nastavení.

Uživatelské složky

Každý uživatel někde začíná. A to s prázdnou složkou. Zde je na rovinu potřeba rozlišit případy, kdy je uživatelů v systému více - a spravují jeden strom - a kdy má každý strom svůj. Toto je ovlivněno nastavením settings[page][more_users]. Samotné umístění uživatelů se řeší přímo v administraci.

První myšlenka byla, že umisťování je podřízeno uživateli Root (Správce systému) a jeho / (lomítku). Takže lomítko na začátku cesty značí, že se začíná v kořenové složce s prezentací. Lomítko na konci znamená, že nezná složky s nastavením. Jinak to interpretuje jako domovskou složku všech uživatelů "user/" a podle závěrečného v uživateli pak složka "data/". Prázdný řetězec tak paradoxně znamená, že cesta míří do "user/data/" (to není chyba, ale účel).

Správce systému se o složky s nastavením starat nemusí, ten má automatický přístup k úpravám základních nastavení. Pro Správce stránek platí totéž. V případě podwebů je vhodné, aby jeden z upravujících účtů měl taktéž práva Správce stránek, což ale též znamená, že může všem měnit nastavení administrace.

Přátelské varování

Jsem si vědom, že instalátor zatím složky moc nepobral. Takže je potřeba mít připravené FTP a kdyžtak trochu laborovat. Nebo to jde (s omezeními platnými pro moduly) i z účtu Správce systému.

kwcms{mailchar}kalanys.com