<?php
/**
 * api: php
 * title: PHP7 Templates
 * description: Output/Templating/Views utility code
 * version: 0.1
 * author: php7framwork team: Mario Salzer
 * type: output
 * category: library
 * 
 * 
 * Templating in P7F uses the simplest method that could possibly work:
 *
 *     include(template("index"));   // == template/default/index.en.htm
 *
 * Which gets executed in the current variable scope. It's recommended
 * to base templates upon PHPs short open tags:
 *
 *     <? include(template("defaults")); ?>
 *     <html><head>
 *       <title><?= $title ?></title>
 *     </head><body>
 *       <?= $body ?>
 * 
 * It's advisable to assemble templates with sub templates. The "defaults"
 * should be used in each, because it can instantiate default variables.
 * And it will also contain escaping code for any local output variables:
 *
 *     <? extract(html(get_defined_vars())); // filters local vars ?>
 *
 * Otherwise use above snippet in any template. It ensures that all output
 * is properly HTML-escaped to prevent XSS security exploits.
 *
 * Also:
 * - Utility functions can be defined within here, or in defaults.
 * - Sometimes you want a specific "functions" template also.
 * - template() looks for .php and .htm scripts, and localized variants
 * - $config["template"] usually redirects to "default" in ./template/
 * -
 * -
 *
 */



/**
 * HTML output escaping
 *
 * Is a shortcut around htmlspecialchars(), which simplifies escaping. It
 * specifically works on scalars AND arrays, but leaves for example PDO
 * result lists alone (to not waste memory).
 *
 * Usually filters everything in the "defaults" template snippet, but can
 * be called manually: <?= html($text) ?>.
 *
 * It leaves any $html_* and $raw_* variables untouched.
 *
 *
 * @param mixed  string/array raw
 * @return mixed  string/array escaped
 */
function html($var) {
    if (is_string($var)) {
        return(htmlspecialchars($var, ENT_QUOTES, "UTF-8", false));
    }
    elseif (is_array($var)) {
        // $var = array_map("html", $var);
        foreach ($var as $key=>$value) {
            if (($key[0] != "_") && strncmp($key, "html", 4)!=0 && strncmp($key, "raw", 3)!=0) {
                $var[$key] = html($value);
            }
        }
    }
    elseif (is_object($var)) {
        // leave alone; if it's a PDO list output needs manual html() calls
    }
    return($var);
}



/**
 * Template lookup.
 *
 *   include(template("index", $title="Home page"));
 *
 *
 */
function template($name) {
    // _partial template files are never wrapped
    if (is_string($name) && ($name[0] == "_"))  {
        return template_fn($name);
    }
    // might be rewritten
    else {
        
        // todo: parse "$name options caching etc."
        // todo: rewrite to "default" wrapper, which handles html() escaping
        // todo: caching handler should hook in here or in "default"

        return template_fn($name);
    }
}


/**
 * Returns the real template filename.
 *
 *
 */
function template_fn($name) {
    return "./template/default/$name.php";
}

?>