|
KWeb
6.4
|
Data Structures | |
| class | KWebTemplate |
Inc files are one of the main building blocks of KWeb system. They are standard PHP files used in different contexts. Their key advantage is extensive file discovery algorithm, wchich allows for overriding, inheritance and configurability.
Those files are used in different roles, to leverage this advantage, and make things more consistent.
The contexts are:
Templates are bits of HTML or text, printed out to the output. Any action, or another template can print them, and pass them any additional information through parameters.
KWeb::$inst->printInc('_bricks/header/head', array('title' => '...'));
Will print /kweb/template/_bricks/header/head.inc (if not overriden)
As templates can be overriden, overriding templates can print parent templates like this:
KWeb::$inst->printInc('_bricks/header/head', KWeb::$inst->getCurrentIncVariables(), false, true, __FILE__);
Or simply require parent template (allowing it access to all local variables):
require KWeb::$inst->getIncPath('_bricks/header/head', true, __FILE__);
Views are the same as templates, however they are printed in the context of an KWebObject object. Template has access to $item variable, and the template discovery process takes object's type, printer, and active section into account.
KWebCache::$inst->getItem('some_image')->printMe('view/full');
Assuming that "some_image" is and KWebItem_Image item in the CMS, this code will print /kweb/template/view/full/__image.inc
As views can be overriden in a much more complicated way, every overriding view can print parent view like this:
$item->printMeNext();
Sometimes it's convenient (and faster) to include other inc files directly, allowing them access to local variables.
require KWeb::$inst->getIncPath('_config/boxes'); require_once KWeb::$inst->getIncPath('_bricks/init/jquery');
There are many code snippets in KWeb, wchich not necesseraly print HTML output.
Actions are typical to CMFs with front controller, however they are absent in KWeb. Instead, views are used directly, and accessed through predefined URL routes, without the need to configure the controller. Actions are standard views (inc files), however they also contain action's logic, and print out other templates and views if needed.
These views are defined in URL, along with object's id, on which the actions should be taken. The default view is "view/full".
Typical examples of URL to view translations are:
These urls translate to something like this:
KWebCache::$inst->getItem('something')->printMe($view);
Sometimes it's way faster and logical to use a "static" file, instead of adding it to CMS, or prepare a special Controller handling. Such files are called pages, and again, they are the same old .inc files found in /template/ directories.
These pages are accessed directly through URLs, without any setup necessery. URLs translate to inc filenames like this:
These urls translate to something like this:
KWeb::$inst->printInc($page);
KWeb uses *.inc files stored in /template/ directory. Requested files are found using discovery algorithm, which takes many variables into account, like current view, object type, active section, and configuration. Therefore the same identifier, can yeld different results under different circumstances.
Files are requested by their filename, without the extension (eg. "view/full", "user/login"). Depending on context, the filename is decorated with different suffixes and prefixes in a loop, and the first existing file is returned. File structure is cached, therefore discovery process is pretty fast, although complicated.
As mentioned before, inc files aren't unique. The actual file used depends on context. To allow more control, the inc name may be prepended with single '/' to skip any prefixes, and only to look for files in directory sets (eg. "/view/full"). Additional '/' will restrict discovery only to KWeb's directory tree, ignoring all overrides (eg. "//view/full").
Before traversing, variables are first populated.
$printers is fetched from KWebObject::getPrinter(), so it depends on the item being printed. Normally it is a list of type names in class inheritance order. The list is reversed, and an empty prefix is added at the end.
$prefixList is a merge of several prefix lists.
At first it contains only one empty prefix. If the object being printed uses sections (KWebSection, KWebObject::getSection()), then the section prefixes are added through KWebSection::getPrefixList(). Otherwise, $globalPrefixes are added. Whole list is reversed afterwards.
$sectionPrefixes is a list of prefixes used by a section. If a section has parent sections, then the prefixes will also contain parent section's prefixes.
$globalPrefixes is a list of prefixes used globally. It's stored in the KSetting tmpl/global_prefix, and mainly used in conjuction with domains.
It's important to note, that section prefixes returned by KWebSection::getPrefixList() are itself a merge of $sectionPrefixes and $globalPrefixes in the order:
Traversing is done by two nested loops. The outer loop traverses $printers, and the inner loop the $prefixList. This way for every $printer in $printers and every $prefixItem in $prefixList the following is applied:
$incPath = $prefixItem . $view . '/' . $prefix . $printer;
$incPath = $view . '/' . $prefixItem . $prefix . $printer;
The best way to explain is by example.
Let's assume these input variables:
After initialization they'll look like these:
During traversing following paths will be checked for existence:
1.7.5.1