<?php
/**
 * PHPTAL templating engine
 *
 * PHP Version 5
 *
 * @category HTML
 * @package  PHPTAL
 * @author   Kornel Lesiński <hide@address.com>
 * @license  http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License
 * @version  SVN: $Id: $
 * @link     http://phptal.org/
 */

/**
 * Base class for prefilters.
 *
 * You should extend this class and override methods you're interested in.
 *
 * Order of calls is undefined and may change.
 *
 * @package PHPTAL
 */
abstract class PHPTAL_PreFilter implements PHPTAL_Filter
{
    /**
     * @see getPHPTAL()
     */
    private $phptal;

    /**
     * Receives root PHPTAL DOM node of parsed file and should edit it in place.
     * Prefilters are called only once before template is compiled, so they can be slow.
     *
     * Default implementation does nothing. Override it.
     *
     * @see PHPTAL_Dom_Element class for methods and fields available.
     *
     * @param PHPTAL_Dom_Element $root PHPTAL's DOM node to modify in place
     *
     * @return void
     */
    public function filterDOM(PHPTAL_Dom_Element $root)
    {
    }

    /**
     * Receives DOM node that had phptal:filter attribute calling this filter.
     * Should modify node in place.
     * Prefilters are called only once before template is compiled, so they can be slow.
     *
     * Default implementation calls filterDOM(). Override it.
     *
     * @param PHPTAL_Dom_Element $node PHPTAL's DOM node to modify in place
     *
     * @return void
     */
    public function filterDOMFragment(PHPTAL_Dom_Element $node)
    {
        $this->filterDOM($node);
    }

    /**
     * Receives template source code and is expected to return new source.
     * Prefilters are called only once before template is compiled, so they can be slow.
     *
     * Default implementation does nothing. Override it.
     *
     * @param string $src markup to filter
     *
     * @return string
     */
    public function filter($src)
    {
        return $src;
    }

    /**
     * Returns (any) string that uniquely identifies this filter and its settings,
     * which is used to (in)validate template cache.
     *
     * Unlike other filter methods, this one is called on every execution.
     *
     * Override this method if result of the filter depends on its configuration.
     *
     * @return string
     */
    public function getCacheId()
    {
        return get_class($this);
    }

    /**
     * Returns PHPTAL class instance that is currently using this prefilter.
     * May return NULL if PHPTAL didn't start filtering yet.
     *
     * @return PHPTAL or NULL
     */
    final protected function getPHPTAL()
    {
        return $this->phptal;
    }

    /**
     * Set which instance of PHPTAL is using this filter.
     * Must be done before calling any filter* methods.
     *
     * @param PHPTAL $phptal instance
     */
    final function setPHPTAL(PHPTAL $phptal)
    {
        $this->phptal = $phptal;
    }
}