From 1a737be2b408135177a9e94dcffd0f68c0aca90b Mon Sep 17 00:00:00 2001 From: Klaus Weidenbach Date: Tue, 5 Sep 2017 00:23:42 +0200 Subject: :bulb: Improving Doxygen documentation. Fix some Doxygen parsing errors. Improve hooks documentation. --- Zotlabs/Render/Comanche.php | 179 +++++++++++++++++++++++++++++--------------- 1 file changed, 119 insertions(+), 60 deletions(-) (limited to 'Zotlabs/Render') diff --git a/Zotlabs/Render/Comanche.php b/Zotlabs/Render/Comanche.php index 78ca870a7..cd06e11a8 100644 --- a/Zotlabs/Render/Comanche.php +++ b/Zotlabs/Render/Comanche.php @@ -5,10 +5,20 @@ namespace Zotlabs\Render; require_once('include/security.php'); require_once('include/menu.php'); - +/** + * @brief Comanche Page Description Language. + * + * Comanche is a markup language similar to bbcode with which to create elaborate + * and complex web pages by assembling them from a series of components - some of + * which are pre-built and others which can be defined on the fly. Comanche uses + * a Page Decription Language to create these pages. + * + * Comanche primarily chooses what content will appear in various regions of the + * page. The various regions have names and these names can change depending on + * what layout template you choose. + */ class Comanche { - function parse($s, $pass = 0) { $matches = array(); @@ -18,13 +28,13 @@ class Comanche { $s = str_replace($mtch[0], '', $s); } } - + /* - * This section supports the "switch" statement of the form given by the following - * example. The [default][/default] block must be the last in the arbitrary + * This section supports the "switch" statement of the form given by the following + * example. The [default][/default] block must be the last in the arbitrary * list of cases. The first case that matches the switch variable is used * and the rest are not evaluated. - * + * * [switch observer.language] * [case de] * [block]german-content[/block] @@ -37,7 +47,7 @@ class Comanche { * [/default] * [/switch] */ - + $cnt = preg_match_all("/\[switch (.*?)\](.*?)\[default\](.*?)\[\/default\]\s*\[\/switch\]/ism", $s, $matches, PREG_SET_ORDER); if($cnt) { foreach($matches as $mtch) { @@ -60,7 +70,7 @@ class Comanche { } } } - + $cnt = preg_match_all("/\[if (.*?)\](.*?)\[else\](.*?)\[\/if\]/ism", $s, $matches, PREG_SET_ORDER); if($cnt) { foreach($matches as $mtch) { @@ -89,7 +99,6 @@ class Comanche { $this->parse_pass0($s); else $this->parse_pass1($s); - } function parse_pass0($s) { @@ -103,7 +112,7 @@ class Comanche { $cnt = preg_match("/\[template=(.*?)\](.*?)\[\/template\]/ism", $s, $matches); if($cnt) { \App::$page['template'] = trim($matches[2]); - \App::$page['template_style'] = trim($matches[2]) . '_' . $matches[1]; + \App::$page['template_style'] = trim($matches[2]) . '_' . $matches[1]; } $cnt = preg_match("/\[template\](.*?)\[\/template\]/ism", $s, $matches); @@ -145,20 +154,23 @@ class Comanche { } /** + * @brief Replace conditional variables with real values. + * * Currently supported condition variables: + * * $config.xxx.yyy - get_config with cat = xxx and k = yyy + * * $request - request uri for this page + * * $observer.language - viewer's preferred language (closest match) + * * $observer.address - xchan_addr or false + * * $observer.name - xchan_name or false + * * $observer - xchan_hash of observer or empty string + * * $local_channel - logged in channel_id or false * - * $config.xxx.yyy - get_config with cat = xxx and k = yyy - * $request - request uri for this page - * $observer.language - viewer's preferred language (closest match) - * $observer.address - xchan_addr or false - * $observer.name - xchan_name or false - * $observer - xchan_hash of observer or empty string - * $local_channel - logged in channel_id or false + * @param string $v The conditional variable name + * @return string|boolean */ - function get_condition_var($v) { if($v) { - $x = explode('.',$v); + $x = explode('.', $v); if($x[0] == 'config') return get_config($x[1],$x[2]); elseif($x[0] === 'request') @@ -179,6 +191,7 @@ class Comanche { return $y['xchan_name']; elseif($x[1] == 'webname') return substr($y['xchan_addr'],0,strpos($y['xchan_addr'],'@')); + return false; } return get_observer_hash(); @@ -186,30 +199,39 @@ class Comanche { else return false; } + return false; } + /** + * @brief Test for Conditional Execution conditions. + * + * This is extensible. The first version of variable testing supports tests of the forms: + * + * - [if $config.system.foo ~= baz] which will check if get_config('system','foo') contains the string 'baz'; + * - [if $config.system.foo == baz] which will check if get_config('system','foo') is the string 'baz'; + * - [if $config.system.foo != baz] which will check if get_config('system','foo') is not the string 'baz'; + * - [if $config.system.foo >= 3] which will check if get_config('system','foo') is greater than or equal to 3; + * - [if $config.system.foo > 3] which will check if get_config('system','foo') is greater than 3; + * - [if $config.system.foo <= 3] which will check if get_config('system','foo') is less than or equal to 3; + * - [if $config.system.foo < 3] which will check if get_config('system','foo') is less than 3; + * + * - [if $config.system.foo {} baz] which will check if 'baz' is an array element in get_config('system','foo') + * - [if $config.system.foo {*} baz] which will check if 'baz' is an array key in get_config('system','foo') + * - [if $config.system.foo] which will check for a return of a true condition for get_config('system','foo'); + * + * The values 0, '', an empty array, and an unset value will all evaluate to false. + * + * @param int|string $s + * @return boolean + */ function test_condition($s) { - // This is extensible. The first version of variable testing supports tests of the forms: - - // [if $config.system.foo ~= baz] which will check if get_config('system','foo') contains the string 'baz'; - // [if $config.system.foo == baz] which will check if get_config('system','foo') is the string 'baz'; - // [if $config.system.foo != baz] which will check if get_config('system','foo') is not the string 'baz'; - // [if $config.system.foo >= 3] which will check if get_config('system','foo') is greater than or equal to 3; - // [if $config.system.foo > 3] which will check if get_config('system','foo') is greater than 3; - - // [if $config.system.foo <= 3] which will check if get_config('system','foo') is less than or equal to 3; - // [if $config.system.foo < 3] which will check if get_config('system','foo') is less than 3; - - // [if $config.system.foo {} baz] which will check if 'baz' is an array element in get_config('system','foo') - // [if $config.system.foo {*} baz] which will check if 'baz' is an array key in get_config('system','foo') - // [if $config.system.foo] which will check for a return of a true condition for get_config('system','foo'); - // The values 0, '', an empty array, and an unset value will all evaluate to false. if(preg_match('/[\$](.*?)\s\~\=\s(.*?)$/',$s,$matches)) { $x = $this->get_condition_var($matches[1]); if(stripos($x,trim($matches[2])) !== false) return true; + return false; } @@ -217,6 +239,7 @@ class Comanche { $x = $this->get_condition_var($matches[1]); if($x == trim($matches[2])) return true; + return false; } @@ -224,6 +247,7 @@ class Comanche { $x = $this->get_condition_var($matches[1]); if($x != trim($matches[2])) return true; + return false; } @@ -231,24 +255,31 @@ class Comanche { $x = $this->get_condition_var($matches[1]); if($x >= trim($matches[2])) return true; + return false; } + if(preg_match('/[\$](.*?)\s\<\=\s(.*?)$/',$s,$matches)) { $x = $this->get_condition_var($matches[1]); if($x <= trim($matches[2])) return true; + return false; } + if(preg_match('/[\$](.*?)\s\>\s(.*?)$/',$s,$matches)) { $x = $this->get_condition_var($matches[1]); if($x > trim($matches[2])) return true; + return false; } + if(preg_match('/[\$](.*?)\s\>\s(.*?)$/',$s,$matches)) { $x = $this->get_condition_var($matches[1]); if($x < trim($matches[2])) return true; + return false; } @@ -256,6 +287,7 @@ class Comanche { $x = $this->get_condition_var($matches[1]); if(is_array($x) && in_array(trim($matches[2]),$x)) return true; + return false; } @@ -263,6 +295,7 @@ class Comanche { $x = $this->get_condition_var($matches[1]); if(is_array($x) && array_key_exists(trim($matches[2]),$x)) return true; + return false; } @@ -270,13 +303,21 @@ class Comanche { $x = $this->get_condition_var($matches[1]); if($x) return true; + return false; } - return false; + return false; } - + /** + * @brief Return rendered menu for current channel_id. + * + * @see menu_render() + * @param string $s + * @param string $class (optional) default empty + * @return string + */ function menu($s, $class = '') { $channel_id = $this->get_channel_id(); @@ -291,7 +332,7 @@ class Comanche { } if($channel_id) { - $m = menu_fetch($name,$channel_id, get_observer_hash()); + $m = menu_fetch($name, $channel_id, get_observer_hash()); return menu_render($m, $class, $edit = false, $var); } } @@ -309,9 +350,8 @@ class Comanche { * Returns the channel_id of the profile owner of the page, or the local_channel * if there is no profile owner. Otherwise returns 0. * - * @return channel_id + * @return int channel_id */ - function get_channel_id() { $channel_id = ((is_array(\App::$profile)) ? \App::$profile['profile_uid'] : 0); @@ -321,6 +361,13 @@ class Comanche { return $channel_id; } + /** + * @brief Returns a parsed block. + * + * @param string $s + * @param string $class (optional) default empty + * @return string parsed HTML of block + */ function block($s, $class = '') { $var = array(); $matches = array(); @@ -339,7 +386,7 @@ class Comanche { $channel_id = $this->get_channel_id(); if($channel_id) { - $r = q("select * from item inner join iconfig on iconfig.iid = item.id and item.uid = %d + $r = q("select * from item inner join iconfig on iconfig.iid = item.id and item.uid = %d and iconfig.cat = 'system' and iconfig.k = 'BUILDBLOCK' and iconfig.v = '%s' limit 1", intval($channel_id), dbesc($name) @@ -381,6 +428,12 @@ class Comanche { return $o; } + /** + * @brief Include JS depending on framework. + * + * @param string $s + * @return string + */ function js($s) { switch($s) { @@ -401,9 +454,14 @@ class Comanche { $ret .= $init; return $ret; - } + /** + * @brief Include CSS depending on framework. + * + * @param string $s + * @return string + */ function css($s) { switch($s) { @@ -418,17 +476,22 @@ class Comanche { $ret = ''; return $ret; - } - // This doesn't really belong in Comanche, but it could also be argued that it is the perfect place. - // We need to be able to select what kind of template and decoration to use for the webpage at the heart of our content. - // For now we'll allow an '[authored]' element which defaults to name and date, or 'none' to remove these, and perhaps - // 'full' to provide a social network style profile photo. - // But leave it open to have richer templating options and perhaps ultimately discard this one, once we have a better idea - // of what template and webpage options we might desire. - - function webpage(&$a,$s) { + /** + * This doesn't really belong in Comanche, but it could also be argued that it is the perfect place. + * We need to be able to select what kind of template and decoration to use for the webpage at the heart of our content. + * For now we'll allow an '[authored]' element which defaults to name and date, or 'none' to remove these, and perhaps + * 'full' to provide a social network style profile photo. + * + * But leave it open to have richer templating options and perhaps ultimately discard this one, once we have a better idea + * of what template and webpage options we might desire. + * + * @param[in,out] array $a + * @param string $s + * @return array + */ + function webpage(&$a, $s) { $ret = array(); $matches = array(); @@ -438,22 +501,20 @@ class Comanche { $ret['authored'] = $mtch[1]; } } + return $ret; } - /** - * Render a widget + * @brief Render a widget. * * @param string $name * @param string $text */ - function widget($name, $text) { $vars = array(); $matches = array(); - $cnt = preg_match_all("/\[var=(.*?)\](.*?)\[\/var\]/ism", $text, $matches, PREG_SET_ORDER); if ($cnt) { foreach ($matches as $mtch) { @@ -480,7 +541,7 @@ class Comanche { if(method_exists($x,$f)) { return $x->$f($vars); } - } + } $func = 'widget_' . trim($name); @@ -563,9 +624,9 @@ class Comanche { } - /* - * @function register_page_template($arr) - * Registers a page template/variant for use by Comanche selectors + /** + * @brief Registers a page template/variant for use by Comanche selectors. + * * @param array $arr * 'template' => template name * 'variant' => array( @@ -577,8 +638,6 @@ class Comanche { * ) * ) */ - - function register_page_template($arr) { \App::$page_layouts[$arr['template']] = array($arr['variant']); return; -- cgit v1.2.3