Source for file frames.php

Documentation is available at frames.php

  1. <?php
  2. /**
  3.  *  Base include file for SimpleTest
  4.  *  @package    SimpleTest
  5.  *  @subpackage WebTester
  6.  *  @version    $Id: frames.php 1672 2008-03-02 04:47:34Z edwardzyang $
  7.  */
  8.  
  9. /**#@+
  10.  *  include other SimpleTest class files
  11.  */
  12. require_once(dirname(__FILE__) . '/page.php');
  13. require_once(dirname(__FILE__) . '/user_agent.php');
  14. /**#@-*/
  15.  
  16.  *    A composite page. Wraps a frameset page and
  17.  *    adds subframes. The original page will be
  18.  *    mostly ignored. Implements the SimplePage
  19.  *    interface so as to be interchangeable.
  20.  *    @package SimpleTest
  21.  *    @subpackage WebTester
  22.  */
  23. class SimpleFrameset {
  24.     var $_frameset;
  25.     var $_frames;
  26.     var $_focus;
  27.     var $_names;
  28.  
  29.     /**
  30.      *    Stashes the frameset page. Will make use of the
  31.      *    browser to fetch the sub frames recursively.
  32.      *    @param SimplePage $page        Frameset page.
  33.      */
  34.     function SimpleFrameset(&$page) {
  35.         $this->_frameset = &$page;
  36.         $this->_frames = array();
  37.         $this->_focus = false;
  38.         $this->_names = array();
  39.     }
  40.  
  41.     /**
  42.      *    Adds a parsed page to the frameset.
  43.      *    @param SimplePage $page    Frame page.
  44.      *    @param string $name        Name of frame in frameset.
  45.      *    @access public
  46.      */
  47.     function addFrame(&$page, $name = false) {
  48.         $this->_frames[] = &$page;
  49.         if ($name) {
  50.             $this->_names[$name] = count($this->_frames) - 1;
  51.         }
  52.     }
  53.  
  54.     /**
  55.      *    Replaces existing frame with another. If the
  56.      *    frame is nested, then the call is passed down
  57.      *    one level.
  58.      *    @param array $path        Path of frame in frameset.
  59.      *    @param SimplePage $page   Frame source.
  60.      *    @access public
  61.      */
  62.     function setFrame($path, &$page) {
  63.         $name = array_shift($path);
  64.         if (isset($this->_names[$name])) {
  65.             $index = $this->_names[$name];
  66.         } else {
  67.             $index = $name - 1;
  68.         }
  69.         if (count($path) == 0) {
  70.             $this->_frames[$index] = &$page;
  71.             return;
  72.         }
  73.         $this->_frames[$index]->setFrame($path, $page);
  74.     }
  75.  
  76.     /**
  77.      *    Accessor for current frame focus. Will be
  78.      *    false if no frame has focus. Will have the nested
  79.      *    frame focus if any.
  80.      *    @return array     Labels or indexes of nested frames.
  81.      *    @access public
  82.      */
  83.     function getFrameFocus() {
  84.         if ($this->_focus === false) {
  85.             return array();
  86.         }
  87.         return array_merge(
  88.                 array($this->_getPublicNameFromIndex($this->_focus)),
  89.                 $this->_frames[$this->_focus]->getFrameFocus());
  90.     }
  91.  
  92.     /**
  93.      *    Turns an internal array index into the frames list
  94.      *    into a public name, or if none, then a one offset
  95.      *    index.
  96.      *    @param integer $subject    Internal index.
  97.      *    @return integer/string     Public name.
  98.      *    @access private
  99.      */
  100.     function _getPublicNameFromIndex($subject) {
  101.         foreach ($this->_names as $name => $index) {
  102.             if ($subject == $index) {
  103.                 return $name;
  104.             }
  105.         }
  106.         return $subject + 1;
  107.     }
  108.  
  109.     /**
  110.      *    Sets the focus by index. The integer index starts from 1.
  111.      *    If already focused and the target frame also has frames,
  112.      *    then the nested frame will be focused.
  113.      *    @param integer $choice    Chosen frame.
  114.      *    @return boolean           True if frame exists.
  115.      *    @access public
  116.      */
  117.     function setFrameFocusByIndex($choice) {
  118.         if (is_integer($this->_focus)) {
  119.             if ($this->_frames[$this->_focus]->hasFrames()) {
  120.                 return $this->_frames[$this->_focus]->setFrameFocusByIndex($choice);
  121.             }
  122.         }
  123.         if (($choice < 1) || ($choice > count($this->_frames))) {
  124.             return false;
  125.         }
  126.         $this->_focus = $choice - 1;
  127.         return true;
  128.     }
  129.  
  130.     /**
  131.      *    Sets the focus by name. If already focused and the
  132.      *    target frame also has frames, then the nested frame
  133.      *    will be focused.
  134.      *    @param string $name    Chosen frame.
  135.      *    @return boolean        True if frame exists.
  136.      *    @access public
  137.      */
  138.     function setFrameFocus($name) {
  139.         if (is_integer($this->_focus)) {
  140.             if ($this->_frames[$this->_focus]->hasFrames()) {
  141.                 return $this->_frames[$this->_focus]->setFrameFocus($name);
  142.             }
  143.         }
  144.         if (in_array($name, array_keys($this->_names))) {
  145.             $this->_focus = $this->_names[$name];
  146.             return true;
  147.         }
  148.         return false;
  149.     }
  150.  
  151.     /**
  152.      *    Clears the frame focus.
  153.      *    @access public
  154.      */
  155.     function clearFrameFocus() {
  156.         $this->_focus = false;
  157.         $this->_clearNestedFramesFocus();
  158.     }
  159.  
  160.     /**
  161.      *    Clears the frame focus for any nested frames.
  162.      *    @access private
  163.      */
  164.     function _clearNestedFramesFocus() {
  165.         for ($i = 0; $i < count($this->_frames); $i++) {
  166.             $this->_frames[$i]->clearFrameFocus();
  167.         }
  168.     }
  169.  
  170.     /**
  171.      *    Test for the presence of a frameset.
  172.      *    @return boolean        Always true.
  173.      *    @access public
  174.      */
  175.     function hasFrames() {
  176.         return true;
  177.     }
  178.  
  179.     /**
  180.      *    Accessor for frames information.
  181.      *    @return array/string      Recursive hash of frame URL strings.
  182.      *                               The key is either a numerical
  183.      *                               index or the name attribute.
  184.      *    @access public
  185.      */
  186.     function getFrames() {
  187.         $report = array();
  188.         for ($i = 0; $i < count($this->_frames); $i++) {
  189.             $report[$this->_getPublicNameFromIndex($i)] =
  190.                     $this->_frames[$i]->getFrames();
  191.         }
  192.         return $report;
  193.     }
  194.  
  195.     /**
  196.      *    Accessor for raw text of either all the pages or
  197.      *    the frame in focus.
  198.      *    @return string        Raw unparsed content.
  199.      *    @access public
  200.      */
  201.     function getRaw() {
  202.         if (is_integer($this->_focus)) {
  203.             return $this->_frames[$this->_focus]->getRaw();
  204.         }
  205.         $raw = '';
  206.         for ($i = 0; $i < count($this->_frames); $i++) {
  207.             $raw .= $this->_frames[$i]->getRaw();
  208.         }
  209.         return $raw;
  210.     }
  211.  
  212.     /**
  213.      *    Accessor for plain text of either all the pages or
  214.      *    the frame in focus.
  215.      *    @return string        Plain text content.
  216.      *    @access public
  217.      */
  218.     function getText() {
  219.         if (is_integer($this->_focus)) {
  220.             return $this->_frames[$this->_focus]->getText();
  221.         }
  222.         $raw = '';
  223.         for ($i = 0; $i < count($this->_frames); $i++) {
  224.             $raw .= ' ' . $this->_frames[$i]->getText();
  225.         }
  226.         return trim($raw);
  227.     }
  228.  
  229.     /**
  230.      *    Accessor for last error.
  231.      *    @return string        Error from last response.
  232.      *    @access public
  233.      */
  234.     function getTransportError() {
  235.         if (is_integer($this->_focus)) {
  236.             return $this->_frames[$this->_focus]->getTransportError();
  237.         }
  238.         return $this->_frameset->getTransportError();
  239.     }
  240.  
  241.     /**
  242.      *    Request method used to fetch this frame.
  243.      *    @return string      GET, POST or HEAD.
  244.      *    @access public
  245.      */
  246.     function getMethod() {
  247.         if (is_integer($this->_focus)) {
  248.             return $this->_frames[$this->_focus]->getMethod();
  249.         }
  250.         return $this->_frameset->getMethod();
  251.     }
  252.  
  253.     /**
  254.      *    Original resource name.
  255.      *    @return SimpleUrl        Current url.
  256.      *    @access public
  257.      */
  258.     function getUrl() {
  259.         if (is_integer($this->_focus)) {
  260.             $url = $this->_frames[$this->_focus]->getUrl();
  261.             $url->setTarget($this->_getPublicNameFromIndex($this->_focus));
  262.         } else {
  263.             $url = $this->_frameset->getUrl();
  264.         }
  265.         return $url;
  266.     }
  267.  
  268.     /**
  269.      *    Page base URL.
  270.      *    @return SimpleUrl        Current url.
  271.      *    @access public
  272.      */
  273.     function getBaseUrl() {
  274.         if (is_integer($this->_focus)) {
  275.             $url = $this->_frames[$this->_focus]->getBaseUrl();
  276.         } else {
  277.             $url = $this->_frameset->getBaseUrl();
  278.         }
  279.         return $url;
  280.     }
  281.  
  282.     /**
  283.      *    Expands expandomatic URLs into fully qualified
  284.      *    URLs for the frameset page.
  285.      *    @param SimpleUrl $url        Relative URL.
  286.      *    @return SimpleUrl            Absolute URL.
  287.      *    @access public
  288.      */
  289.     function expandUrl($url) {
  290.         return $this->_frameset->expandUrl($url);
  291.     }
  292.  
  293.     /**
  294.      *    Original request data.
  295.      *    @return mixed              Sent content.
  296.      *    @access public
  297.      */
  298.     function getRequestData() {
  299.         if (is_integer($this->_focus)) {
  300.             return $this->_frames[$this->_focus]->getRequestData();
  301.         }
  302.         return $this->_frameset->getRequestData();
  303.     }
  304.  
  305.     /**
  306.      *    Accessor for current MIME type.
  307.      *    @return string    MIME type as string; e.g. 'text/html'
  308.      *    @access public
  309.      */
  310.     function getMimeType() {
  311.         if (is_integer($this->_focus)) {
  312.             return $this->_frames[$this->_focus]->getMimeType();
  313.         }
  314.         return $this->_frameset->getMimeType();
  315.     }
  316.  
  317.     /**
  318.      *    Accessor for last response code.
  319.      *    @return integer    Last HTTP response code received.
  320.      *    @access public
  321.      */
  322.     function getResponseCode() {
  323.         if (is_integer($this->_focus)) {
  324.             return $this->_frames[$this->_focus]->getResponseCode();
  325.         }
  326.         return $this->_frameset->getResponseCode();
  327.     }
  328.  
  329.     /**
  330.      *    Accessor for last Authentication type. Only valid
  331.      *    straight after a challenge (401).
  332.      *    @return string    Description of challenge type.
  333.      *    @access public
  334.      */
  335.     function getAuthentication() {
  336.         if (is_integer($this->_focus)) {
  337.             return $this->_frames[$this->_focus]->getAuthentication();
  338.         }
  339.         return $this->_frameset->getAuthentication();
  340.     }
  341.  
  342.     /**
  343.      *    Accessor for last Authentication realm. Only valid
  344.      *    straight after a challenge (401).
  345.      *    @return string    Name of security realm.
  346.      *    @access public
  347.      */
  348.     function getRealm() {
  349.         if (is_integer($this->_focus)) {
  350.             return $this->_frames[$this->_focus]->getRealm();
  351.         }
  352.         return $this->_frameset->getRealm();
  353.     }
  354.  
  355.     /**
  356.      *    Accessor for outgoing header information.
  357.      *    @return string      Header block.
  358.      *    @access public
  359.      */
  360.     function getRequest() {
  361.         if (is_integer($this->_focus)) {
  362.             return $this->_frames[$this->_focus]->getRequest();
  363.         }
  364.         return $this->_frameset->getRequest();
  365.     }
  366.  
  367.     /**
  368.      *    Accessor for raw header information.
  369.      *    @return string      Header block.
  370.      *    @access public
  371.      */
  372.     function getHeaders() {
  373.         if (is_integer($this->_focus)) {
  374.             return $this->_frames[$this->_focus]->getHeaders();
  375.         }
  376.         return $this->_frameset->getHeaders();
  377.     }
  378.  
  379.     /**
  380.      *    Accessor for parsed title.
  381.      *    @return string     Title or false if no title is present.
  382.      *    @access public
  383.      */
  384.     function getTitle() {
  385.         return $this->_frameset->getTitle();
  386.     }
  387.  
  388.     /**
  389.      *    Accessor for a list of all fixed links.
  390.      *    @return array   List of urls as strings.
  391.      *    @access public
  392.      */
  393.     function getUrls() {
  394.         if (is_integer($this->_focus)) {
  395.             return $this->_frames[$this->_focus]->getUrls();
  396.         }
  397.         $urls = array();
  398.         foreach ($this->_frames as $frame) {
  399.             $urls = array_merge($urls, $frame->getUrls());
  400.         }
  401.         return array_values(array_unique($urls));
  402.     }
  403.  
  404.     /**
  405.      *    Accessor for URLs by the link label. Label will match
  406.      *    regardess of whitespace issues and case.
  407.      *    @param string $label    Text of link.
  408.      *    @return array           List of links with that label.
  409.      *    @access public
  410.      */
  411.     function getUrlsByLabel($label) {
  412.         if (is_integer($this->_focus)) {
  413.             return $this->_tagUrlsWithFrame(
  414.                     $this->_frames[$this->_focus]->getUrlsByLabel($label),
  415.                     $this->_focus);
  416.         }
  417.         $urls = array();
  418.         foreach ($this->_frames as $index => $frame) {
  419.             $urls = array_merge(
  420.                     $urls,
  421.                     $this->_tagUrlsWithFrame(
  422.                                 $frame->getUrlsByLabel($label),
  423.                                 $index));
  424.         }
  425.         return $urls;
  426.     }
  427.  
  428.     /**
  429.      *    Accessor for a URL by the id attribute. If in a frameset
  430.      *    then the first link found with that ID attribute is
  431.      *    returned only. Focus on a frame if you want one from
  432.      *    a specific part of the frameset.
  433.      *    @param string $id       Id attribute of link.
  434.      *    @return string          URL with that id.
  435.      *    @access public
  436.      */
  437.     function getUrlById($id) {
  438.         foreach ($this->_frames as $index => $frame) {
  439.             if ($url = $frame->getUrlById($id)) {
  440.                 if (! $url->gettarget()) {
  441.                     $url->setTarget($this->_getPublicNameFromIndex($index));
  442.                 }
  443.                 return $url;
  444.             }
  445.         }
  446.         return false;
  447.     }
  448.  
  449.     /**
  450.      *    Attaches the intended frame index to a list of URLs.
  451.      *    @param array $urls        List of SimpleUrls.
  452.      *    @param string $frame      Name of frame or index.
  453.      *    @return array             List of tagged URLs.
  454.      *    @access private
  455.      */
  456.     function _tagUrlsWithFrame($urls, $frame) {
  457.         $tagged = array();
  458.         foreach ($urls as $url) {
  459.             if (! $url->getTarget()) {
  460.                 $url->setTarget($this->_getPublicNameFromIndex($frame));
  461.             }
  462.             $tagged[] = $url;
  463.         }
  464.         return $tagged;
  465.     }
  466.  
  467.     /**
  468.      *    Finds a held form by button label. Will only
  469.      *    search correctly built forms.
  470.      *    @param SimpleSelector $selector       Button finder.
  471.      *    @return SimpleForm                    Form object containing
  472.      *                                           the button.
  473.      *    @access public
  474.      */
  475.     function &getFormBySubmit($selector) {
  476.         $form = &$this->_findForm('getFormBySubmit', $selector);
  477.         return $form;
  478.     }
  479.  
  480.     /**
  481.      *    Finds a held form by image using a selector.
  482.      *    Will only search correctly built forms. The first
  483.      *    form found either within the focused frame, or
  484.      *    across frames, will be the one returned.
  485.      *    @param SimpleSelector $selector  Image finder.
  486.      *    @return SimpleForm               Form object containing
  487.      *                                      the image.
  488.      *    @access public
  489.      */
  490.     function &getFormByImage($selector) {
  491.         $form = &$this->_findForm('getFormByImage', $selector);
  492.         return $form;
  493.     }
  494.  
  495.     /**
  496.      *    Finds a held form by the form ID. A way of
  497.      *    identifying a specific form when we have control
  498.      *    of the HTML code. The first form found
  499.      *    either within the focused frame, or across frames,
  500.      *    will be the one returned.
  501.      *    @param string $id     Form label.
  502.      *    @return SimpleForm    Form object containing the matching ID.
  503.      *    @access public
  504.      */
  505.     function &getFormById($id) {
  506.         $form = &$this->_findForm('getFormById', $id);
  507.         return $form;
  508.     }
  509.  
  510.     /**
  511.         *    General form finder. Will search all the frames or
  512.         *    just the one in focus.
  513.         *    @param string $method    Method to use to find in a page.
  514.         *    @param string $attribute Label, name or ID.
  515.         *    @return SimpleForm    Form object containing the matching ID.
  516.         *    @access private
  517.         */
  518.     function &_findForm($method, $attribute) {
  519.         if (is_integer($this->_focus)) {
  520.             $form = &$this->_findFormInFrame(
  521.                     $this->_frames[$this->_focus],
  522.                     $this->_focus,
  523.                     $method,
  524.                     $attribute);
  525.             return $form;
  526.         }
  527.         for ($i = 0; $i < count($this->_frames); $i++) {
  528.             $form = &$this->_findFormInFrame(
  529.                     $this->_frames[$i],
  530.                     $i,
  531.                     $method,
  532.                     $attribute);
  533.             if ($form) {
  534.                 return $form;
  535.             }
  536.         }
  537.         $null = null;
  538.         return $null;
  539.     }
  540.  
  541.     /**
  542.      *    Finds a form in a page using a form finding method. Will
  543.      *    also tag the form with the frame name it belongs in.
  544.      *    @param SimplePage $page  Page content of frame.
  545.      *    @param integer $index    Internal frame representation.
  546.      *    @param string $method    Method to use to find in a page.
  547.      *    @param string $attribute Label, name or ID.
  548.      *    @return SimpleForm       Form object containing the matching ID.
  549.      *    @access private
  550.      */
  551.     function &_findFormInFrame(&$page, $index, $method, $attribute) {
  552.         $form = &$this->_frames[$index]->$method($attribute);
  553.         if (isset($form)) {
  554.             $form->setDefaultTarget($this->_getPublicNameFromIndex($index));
  555.         }
  556.         return $form;
  557.     }
  558.  
  559.     /**
  560.      *    Sets a field on each form in which the field is
  561.      *    available.
  562.      *    @param SimpleSelector $selector    Field finder.
  563.      *    @param string $value               Value to set field to.
  564.      *    @return boolean                    True if value is valid.
  565.      *    @access public
  566.      */
  567.     function setField($selector, $value) {
  568.         if (is_integer($this->_focus)) {
  569.             $this->_frames[$this->_focus]->setField($selector, $value);
  570.         } else {
  571.             for ($i = 0; $i < count($this->_frames); $i++) {
  572.                 $this->_frames[$i]->setField($selector, $value);
  573.             }
  574.         }
  575.     }
  576.  
  577.     /**
  578.      *    Accessor for a form element value within a page.
  579.      *    @param SimpleSelector $selector    Field finder.
  580.      *    @return string/boolean             A string if the field is
  581.      *                                        present, false if unchecked
  582.      *                                        and null if missing.
  583.      *    @access public
  584.      */
  585.     function getField($selector) {
  586.         for ($i = 0; $i < count($this->_frames); $i++) {
  587.             $value = $this->_frames[$i]->getField($selector);
  588.             if (isset($value)) {
  589.                 return $value;
  590.             }
  591.         }
  592.         return null;
  593.     }
  594. }
  595. ?>

Documentation generated on Sun, 04 May 2008 09:21:39 -0500 by phpDocumentor 1.3.0