<?php
/**
 *  Base include file for SimpleTest
 *  @package    SimpleTest
 *  @subpackage WebTester
 *  @version    $Id: frames.php 1672 2008-03-02 04:47:34Z edwardzyang $
 */

/**#@+
 *  include other SimpleTest class files
 */
require_once(dirname(__FILE__) . '/page.php');
require_once(dirname(__FILE__) . '/user_agent.php');
/**#@-*/

/**
 *    A composite page. Wraps a frameset page and
 *    adds subframes. The original page will be
 *    mostly ignored. Implements the SimplePage
 *    interface so as to be interchangeable.
 *    @package SimpleTest
 *    @subpackage WebTester
 */
class SimpleFrameset {
    var $_frameset;
    var $_frames;
    var $_focus;
    var $_names;

    /**
     *    Stashes the frameset page. Will make use of the
     *    browser to fetch the sub frames recursively.
     *    @param SimplePage $page        Frameset page.
     */
    function SimpleFrameset(&$page) {
        $this->_frameset = &$page;
        $this->_frames = array();
        $this->_focus = false;
        $this->_names = array();
    }

    /**
     *    Adds a parsed page to the frameset.
     *    @param SimplePage $page    Frame page.
     *    @param string $name        Name of frame in frameset.
     *    @access public
     */
    function addFrame(&$page, $name = false) {
        $this->_frames[] = &$page;
        if ($name) {
            $this->_names[$name] = count($this->_frames) - 1;
        }
    }

    /**
     *    Replaces existing frame with another. If the
     *    frame is nested, then the call is passed down
     *    one level.
     *    @param array $path        Path of frame in frameset.
     *    @param SimplePage $page   Frame source.
     *    @access public
     */
    function setFrame($path, &$page) {
        $name = array_shift($path);
        if (isset($this->_names[$name])) {
            $index = $this->_names[$name];
        } else {
            $index = $name - 1;
        }
        if (count($path) == 0) {
            $this->_frames[$index] = &$page;
            return;
        }
        $this->_frames[$index]->setFrame($path, $page);
    }

    /**
     *    Accessor for current frame focus. Will be
     *    false if no frame has focus. Will have the nested
     *    frame focus if any.
     *    @return array     Labels or indexes of nested frames.
     *    @access public
     */
    function getFrameFocus() {
        if ($this->_focus === false) {
            return array();
        }
        return array_merge(
                array($this->_getPublicNameFromIndex($this->_focus)),
                $this->_frames[$this->_focus]->getFrameFocus());
    }

    /**
     *    Turns an internal array index into the frames list
     *    into a public name, or if none, then a one offset
     *    index.
     *    @param integer $subject    Internal index.
     *    @return integer/string     Public name.
     *    @access private
     */
    function _getPublicNameFromIndex($subject) {
        foreach ($this->_names as $name => $index) {
            if ($subject == $index) {
                return $name;
            }
        }
        return $subject + 1;
    }

    /**
     *    Sets the focus by index. The integer index starts from 1.
     *    If already focused and the target frame also has frames,
     *    then the nested frame will be focused.
     *    @param integer $choice    Chosen frame.
     *    @return boolean           True if frame exists.
     *    @access public
     */
    function setFrameFocusByIndex($choice) {
        if (is_integer($this->_focus)) {
            if ($this->_frames[$this->_focus]->hasFrames()) {
                return $this->_frames[$this->_focus]->setFrameFocusByIndex($choice);
            }
        }
        if (($choice < 1) || ($choice > count($this->_frames))) {
            return false;
        }
        $this->_focus = $choice - 1;
        return true;
    }

    /**
     *    Sets the focus by name. If already focused and the
     *    target frame also has frames, then the nested frame
     *    will be focused.
     *    @param string $name    Chosen frame.
     *    @return boolean        True if frame exists.
     *    @access public
     */
    function setFrameFocus($name) {
        if (is_integer($this->_focus)) {
            if ($this->_frames[$this->_focus]->hasFrames()) {
                return $this->_frames[$this->_focus]->setFrameFocus($name);
            }
        }
        if (in_array($name, array_keys($this->_names))) {
            $this->_focus = $this->_names[$name];
            return true;
        }
        return false;
    }

    /**
     *    Clears the frame focus.
     *    @access public
     */
    function clearFrameFocus() {
        $this->_focus = false;
        $this->_clearNestedFramesFocus();
    }

    /**
     *    Clears the frame focus for any nested frames.
     *    @access private
     */
    function _clearNestedFramesFocus() {
        for ($i = 0; $i < count($this->_frames); $i++) {
            $this->_frames[$i]->clearFrameFocus();
        }
    }

    /**
     *    Test for the presence of a frameset.
     *    @return boolean        Always true.
     *    @access public
     */
    function hasFrames() {
        return true;
    }

    /**
     *    Accessor for frames information.
     *    @return array/string      Recursive hash of frame URL strings.
     *                              The key is either a numerical
     *                              index or the name attribute.
     *    @access public
     */
    function getFrames() {
        $report = array();
        for ($i = 0; $i < count($this->_frames); $i++) {
            $report[$this->_getPublicNameFromIndex($i)] =
                    $this->_frames[$i]->getFrames();
        }
        return $report;
    }

    /**
     *    Accessor for raw text of either all the pages or
     *    the frame in focus.
     *    @return string        Raw unparsed content.
     *    @access public
     */
    function getRaw() {
        if (is_integer($this->_focus)) {
            return $this->_frames[$this->_focus]->getRaw();
        }
        $raw = '';
        for ($i = 0; $i < count($this->_frames); $i++) {
            $raw .= $this->_frames[$i]->getRaw();
        }
        return $raw;
    }

    /**
     *    Accessor for plain text of either all the pages or
     *    the frame in focus.
     *    @return string        Plain text content.
     *    @access public
     */
    function getText() {
        if (is_integer($this->_focus)) {
            return $this->_frames[$this->_focus]->getText();
        }
        $raw = '';
        for ($i = 0; $i < count($this->_frames); $i++) {
            $raw .= ' ' . $this->_frames[$i]->getText();
        }
        return trim($raw);
    }

    /**
     *    Accessor for last error.
     *    @return string        Error from last response.
     *    @access public
     */
    function getTransportError() {
        if (is_integer($this->_focus)) {
            return $this->_frames[$this->_focus]->getTransportError();
        }
        return $this->_frameset->getTransportError();
    }

    /**
     *    Request method used to fetch this frame.
     *    @return string      GET, POST or HEAD.
     *    @access public
     */
    function getMethod() {
        if (is_integer($this->_focus)) {
            return $this->_frames[$this->_focus]->getMethod();
        }
        return $this->_frameset->getMethod();
    }

    /**
     *    Original resource name.
     *    @return SimpleUrl        Current url.
     *    @access public
     */
    function getUrl() {
        if (is_integer($this->_focus)) {
            $url = $this->_frames[$this->_focus]->getUrl();
            $url->setTarget($this->_getPublicNameFromIndex($this->_focus));
        } else {
            $url = $this->_frameset->getUrl();
        }
        return $url;
    }

    /**
     *    Page base URL.
     *    @return SimpleUrl        Current url.
     *    @access public
     */
    function getBaseUrl() {
        if (is_integer($this->_focus)) {
            $url = $this->_frames[$this->_focus]->getBaseUrl();
        } else {
            $url = $this->_frameset->getBaseUrl();
        }
        return $url;
    }

    /**
     *    Expands expandomatic URLs into fully qualified
     *    URLs for the frameset page.
     *    @param SimpleUrl $url        Relative URL.
     *    @return SimpleUrl            Absolute URL.
     *    @access public
     */
    function expandUrl($url) {
        return $this->_frameset->expandUrl($url);
    }

    /**
     *    Original request data.
     *    @return mixed              Sent content.
     *    @access public
     */