<?php
/**
 * api: php
 * title: template lookup
 * description: Output/Templating/Views utility code
 * version: 0.1
 * author: mario
 * type: output
 * category: library
 * state: abandoned
 * 
 * Note that this was a pretty crude version, no longer updated.
 *
 * 
 * Implements a extremely trivial templating concept:
 *
 *     include(template("index"));   // == template/default/index.en.htm
 *
 * Which is supposed to inherit the current local variable scope.
 * Therefore only advised for terminating output logic; not between control
 * logic sections.
 *
 * Templates themselves, obviously, should use baseline PHP. Short tags
 * are advised (and just `phptags -l` for portability/transition).
 *
 *     <? include(template("defaults")); ?>
 *     <html><head>
 *       <title><?= $title ?></title>
 *     </head><body>
 *       <?= $body ?>
 * 
 * The "defaults" chaining here is supposed to instantiate predefined
 * variables, predeclare utility functions, and notably contains baseline
 * output filtering of local vars:
 *
 *     <? extract(html(get_defined_vars())); ?>
 *
 * (A more clever approach skipping `$raw_*` or `$html_*` prefixed vars
 * is often needed though.)
 *
 * Notes:
 *
 * - Utility functions can be defined within here, or in `defaults`.
 *
 * - It's sensible to craft more targetted "functions.xy" templates still.
 *
 * - template() looks for .php and .htm scripts, and may switch between
 *   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";
}

?>