htdocs/TESTS/simpletest/page.php

   1 <?php
   2     /**
   3      *  Base include file for SimpleTest
   4      *  @package        SimpleTest
   5      *  @subpackage     WebTester
   6      *  @version        $Id: page.php,v 1.99 2004/08/18 23:10:19 lastcraft Exp $
   7      */
   8
   9     /**#@+
  10      *  include other SimpleTest class files
  11      */
  12     require_once(dirname(__FILE__) . '/http.php');
  13     require_once(dirname(__FILE__) . '/parser.php');
  14     require_once(dirname(__FILE__) . '/tag.php');
  15     require_once(dirname(__FILE__) . '/form.php');
  16     /**#@-*/
  17
  18     /**
  19      *    SAX event handler. Maintains a list of
  20      *    open tags and dispatches them as they close.
  21          *    @package SimpleTest
  22          *    @subpackage WebTester
  23      */
  24     class SimplePageBuilder extends SimpleSaxListener {
  25         var $_tags;
  26         var $_page;
  27
  28         /**
  29          *    Sets the builder up empty.
  30          *    @access public
  31          */
  32         function SimplePageBuilder() {
  33             $this->SimpleSaxListener();
  34         }
  35
  36         /**
  37          *    Reads the raw content and send events
  38          *    into the page to be built.
  39          *    @param $response SimpleHttpResponse  Fetched response.
  40          *    @return SimplePage                   Newly parsed page.
  41          *    @access public
  42          */
  43         function parse($response) {
  44             $this->_tags = array();
  45             $this->_page = &$this->_createPage($response);
  46             $parser = &$this->_createParser();
  47             $parser->parse($response->getContent());
  48             return $this->_page;
  49         }
  50
  51         /**
  52          *    Creates an empty page.
  53          *    @return SimplePage        New unparsed page.
  54          *    @access protected
  55          */
  56         function &_createPage($response) {
  57             return new SimplePage($response);
  58         }
  59
  60         /**
  61          *    Creates the parser used with the builder.
  62          *    @return SimpleSaxParser   Parser to generate events for
  63          *                              the builder.
  64          *    @access protected
  65          */
  66         function &_createParser() {
  67             return new SimpleSaxParser($this);
  68         }
  69
  70         /**
  71          *    Start of element event. Opens a new tag.
  72          *    @param string $name         Element name.
  73          *    @param hash $attributes     Attributes without content
  74          *                                are marked as true.
  75          *    @return boolean             False on parse error.
  76          *    @access public
  77          */
  78         function startElement($name, $attributes) {
  79             $tag = &$this->_createTag($name, $attributes);
  80             if ($name == 'form') {
  81                 $this->_page->acceptFormStart($tag);
  82                 return true;
  83             }
  84             if ($name == 'frameset') {
  85                 $this->_page->acceptFramesetStart($tag);
  86                 return true;
  87             }
  88             if ($name == 'frame') {
  89                 $this->_page->acceptFrame($tag);
  90                 return true;
  91             }
  92             if ($tag->expectEndTag()) {
  93                 $this->_openTag($tag);
  94                 return true;
  95             }
  96             $this->_page->acceptTag($tag);
  97             return true;
  98         }
  99
 100         /**
 101          *    End of element event.
 102          *    @param string $name        Element name.
 103          *    @return boolean            False on parse error.
 104          *    @access public
 105          */
 106         function endElement($name) {
 107             if ($name == 'form') {
 108                 $this->_page->acceptFormEnd();
 109                 return true;
 110             }
 111             if ($name == 'frameset') {
 112                 $this->_page->acceptFramesetEnd();
 113                 return true;
 114             }
 115             if (isset($this->_tags[$name]) && (count($this->_tags[$name]) > 0)) {
 116                 $tag = array_pop($this->_tags[$name]);
 117                 $this->_addContentTagToOpenTags($tag);
 118                 $this->_page->acceptTag($tag);
 119                 return true;
 120             }
 121             return true;
 122         }
 123
 124         /**
 125          *    Unparsed, but relevant data. The data is added
 126          *    to every open tag.
 127          *    @param string $text        May include unparsed tags.
 128          *    @return boolean            False on parse error.
 129          *    @access public
 130          */
 131         function addContent($text) {
 132             foreach (array_keys($this->_tags) as $name) {
 133                 for ($i = 0; $i < count($this->_tags[$name]); $i++) {
 134                     $this->_tags[$name][$i]->addContent($text);
 135                 }
 136             }
 137             return true;
 138         }
 139
 140         /**
 141          *    Parsed relevant data. The parsed tag is added
 142          *    to every open tag.
 143          *    @param SimpleTag $tag        May include unparsed tags.
 144          *    @access private
 145          */
 146         function _addContentTagToOpenTags(&$tag) {
 147             if (! in_array($tag->getTagName(), array('option'))) {
 148                 return;
 149             }
 150             foreach (array_keys($this->_tags) as $name) {
 151                 for ($i = 0; $i < count($this->_tags[$name]); $i++) {
 152                     $this->_tags[$name][$i]->addTag($tag);
 153                 }
 154             }
 155         }
 156
 157         /**
 158          *    Opens a tag for receiving content. Multiple tags
 159          *    will be receiving input at the same time.
 160          *    @param SimpleTag $tag        New content tag.
 161          *    @access private
 162          */
 163         function _openTag(&$tag) {
 164             $name = $tag->getTagName();
 165             if (! in_array($name, array_keys($this->_tags))) {
 166                 $this->_tags[$name] = array();
 167             }
 168             array_push($this->_tags[$name], $tag);
 169         }
 170
 171         /**
 172          *    Factory for the tag objects. Creates the
 173          *    appropriate tag object for the incoming tag name.
 174          *    @param string $name        HTML tag name.
 175          *    @param hash $attributes    Element attributes.
 176          *    @return SimpleTag          Tag object.
 177          *    @access protected
 178          */
 179         function &_createTag($name, $attributes) {
 180             if ($name == 'a') {
 181                 return new SimpleAnchorTag($attributes);
 182             } elseif ($name == 'title') {
 183                 return new SimpleTitleTag($attributes);
 184             } elseif ($name == 'input') {
 185                 return $this->_createInputTag($attributes);
 186             } elseif ($name == 'button') {
 187                 return new SimpleButtonTag($attributes);
 188             } elseif ($name == 'textarea') {
 189                 return new SimpleTextAreaTag($attributes);
 190             } elseif ($name == 'select') {
 191                 return $this->_createSelectionTag($attributes);
 192             } elseif ($name == 'option') {
 193                 return new SimpleOptionTag($attributes);
 194             } elseif ($name == 'form') {
 195                 return new SimpleFormTag($attributes);
 196             } elseif ($name == 'frame') {
 197                 return new SimpleFrameTag($attributes);
 198             }
 199             return new SimpleTag($name, $attributes);
 200         }
 201
 202         /**
 203          *    Factory for selection fields.
 204          *    @param hash $attributes    Element attributes.
 205          *    @return SimpleTag          Tag object.
 206          *    @access protected
 207          */
 208         function &_createSelectionTag($attributes) {
 209             if (isset($attributes['multiple'])) {
 210                 return new MultipleSelectionTag($attributes);
 211             }
 212             return new SimpleSelectionTag($attributes);
 213         }
 214
 215         /**
 216          *    Factory for input tags.
 217          *    @param hash $attributes    Element attributes.
 218          *    @return SimpleTag          Tag object.
 219          *    @access protected
 220          */
 221         function &_createInputTag($attributes) {
 222             if (! isset($attributes['type'])) {
 223                 return new SimpleTextTag($attributes);
 224             }
 225             if ($attributes['type'] == 'submit') {
 226                 return new SimpleSubmitTag($attributes);
 227             } elseif ($attributes['type'] == 'image') {
 228                 return new SimpleImageSubmitTag($attributes);
 229             } elseif ($attributes['type'] == 'checkbox') {
 230                 return new SimpleCheckboxTag($attributes);
 231             } elseif ($attributes['type'] == 'radio') {
 232                 return new SimpleRadioButtonTag($attributes);
 233             } else {
 234                 return new SimpleTextTag($attributes);
 235             }
 236         }
 237     }
 238
 239     /**
 240      *    A wrapper for a web page.
 241          *    @package SimpleTest
 242          *    @subpackage WebTester
 243      */
 244     class SimplePage {
 245         var $_links;
 246         var $_title;
 247         var $_open_forms;
 248         var $_complete_forms;
 249         var $_frameset;
 250         var $_frames;
 251         var $_frameset_nesting_level;
 252         var $_transport_error;
 253         var $_raw;
 254         var $_sent;
 255         var $_headers;
 256         var $_method;
 257         var $_url;
 258         var $_request_data;
 259
 260         /**
 261          *    Parses a page ready to access it's contents.
 262          *    @param SimpleHttpResponse $response     Result of HTTP fetch.
 263          *    @access public
 264          */
 265         function SimplePage($response = false) {
 266             $this->_links = array();
 267             $this->_title = false;
 268             $this->_open_forms = array();
 269             $this->_complete_forms = array();
 270             $this->_frameset = false;
 271             $this->_frames = array();
 272             $this->_frameset_nesting_level = 0;
 273             if ($response) {
 274                 $this->_extractResponse($response);
 275             } else {
 276                 $this->_noResponse();
 277             }
 278         }
 279
 280         /**
 281          *    Extracts all of the response information.
 282          *    @param SimpleHttpResponse $response    Response being parsed.
 283          *    @access private
 284          */
 285         function _extractResponse($response) {
 286             $this->_transport_error = $response->getError();
 287             $this->_raw = $response->getContent();
 288             $this->_sent = $response->getSent();
 289             $this->_headers = $response->getHeaders();
 290             $this->_method = $response->getMethod();
 291             $this->_url = $response->getUrl();
 292             $this->_request_data = $response->getRequestData();
 293         }
 294
 295         /**
 296          *    Sets up a missng response.
 297          *    @access private
 298          */
 299         function _noResponse() {
 300             $this->_transport_error = 'No page fetched yet';
 301             $this->_raw = false;
 302             $this->_sent = false;
 303             $this->_headers = false;
 304             $this->_method = 'GET';
 305             $this->_url = false;
 306             $this->_request_data = false;
 307         }
 308
 309         /**
 310          *    Original request as bytes sent down the wire.
 311          *    @return mixed              Sent content.
 312          *    @access public
 313          */
 314         function getRequest() {
 315             return $this->_sent;
 316         }
 317
 318         /**
 319          *    Accessor for raw text of page.
 320          *    @return string        Raw unparsed content.
 321          *    @access public
 322          */
 323         function getRaw() {
 324             return $this->_raw;
 325         }
 326
 327         /**
 328          *    Accessor for raw headers of page.
 329          *    @return string       Header block as text.
 330          *    @access public
 331          */
 332         function getHeaders() {
 333             if ($this->_headers) {
 334                 return $this->_headers->getRaw();
 335             }
 336             return false;
 337         }
 338
 339         /**
 340          *    Original request method.
 341          *    @return string        GET, POST or HEAD.
 342          *    @access public
 343          */
 344         function getMethod() {
 345             return $this->_method;
 346         }
 347
 348         /**
 349          *    Original resource name.
 350          *    @return SimpleUrl        Current url.
 351          *    @access public
 352          */
 353         function getUrl() {
 354             return $this->_url;
 355         }
 356
 357         /**
 358          *    Original request data.
 359          *    @return mixed              Sent content.
 360          *    @access public
 361          */
 362         function getRequestData() {
 363             return $this->_request_data;
 364         }
 365
 366         /**
 367          *    Accessor for last error.
 368          *    @return string        Error from last response.
 369          *    @access public
 370          */
 371         function getTransportError() {
 372             return $this->_transport_error;
 373         }
 374
 375         /**
 376          *    Accessor for current MIME type.
 377          *    @return string    MIME type as string; e.g. 'text/html'
 378          *    @access public
 379          */
 380         function getMimeType() {
 381             if ($this->_headers) {
 382                 return $this->_headers->getMimeType();
 383             }
 384             return false;
 385         }
 386
 387         /**
 388          *    Accessor for HTTP response code.
 389          *    @return integer    HTTP response code received.
 390          *    @access public
 391          */
 392         function getResponseCode() {
 393             if ($this->_headers) {
 394                 return $this->_headers->getResponseCode();
 395             }
 396             return false;
 397         }
 398
 399         /**
 400          *    Accessor for last Authentication type. Only valid
 401          *    straight after a challenge (401).
 402          *    @return string    Description of challenge type.
 403          *    @access public
 404          */
 405         function getAuthentication() {
 406             if ($this->_headers) {
 407                 return $this->_headers->getAuthentication();
 408             }
 409             return false;
 410         }
 411
 412         /**
 413          *    Accessor for last Authentication realm. Only valid
 414          *    straight after a challenge (401).
 415          *    @return string    Name of security realm.
 416          *    @access public
 417          */
 418         function getRealm() {
 419             if ($this->_headers) {
 420                 return $this->_headers->getRealm();
 421             }
 422             return false;
 423         }
 424
 425         /**
 426          *    Accessor for current frame focus. Will be
 427          *    false as no frames.
 428          *    @return array    Always empty.
 429          *    @access public
 430          */
 431         function getFrameFocus() {
 432             return array();
 433         }
 434
 435         /**
 436          *    Sets the focus by index. The integer index starts from 1.
 437          *    @param integer $choice    Chosen frame.
 438          *    @return boolean           Always false.
 439          *    @access public
 440          */
 441         function setFrameFocusByIndex($choice) {
 442             return false;
 443         }
 444
 445         /**
 446          *    Sets the focus by name. Always fails for a leaf page.
 447          *    @param string $name    Chosen frame.
 448          *    @return boolean        False as no frames.
 449          *    @access public
 450          */
 451         function setFrameFocus($name) {
 452             return false;
 453         }
 454
 455         /**
 456          *    Clears the frame focus. Does nothing for a leaf page.
 457          *    @access public
 458          */
 459         function clearFrameFocus() {
 460         }
 461
 462         /**
 463          *    Adds a tag to the page.
 464          *    @param SimpleTag $tag        Tag to accept.
 465          *    @access public
 466          */
 467         function acceptTag(&$tag) {
 468             if ($tag->getTagName() == "a") {
 469                 $this->_addLink($tag);
 470             } elseif ($tag->getTagName() == "title") {
 471                 $this->_setTitle($tag);
 472             } elseif ($this->_isFormElement($tag->getTagName())) {
 473                 for ($i = 0; $i < count($this->_open_forms); $i++) {
 474                     $this->_open_forms[$i]->addWidget($tag);
 475                 }
 476             }
 477         }
 478
 479         /**
 480          *    Tests to see if a tag is a possible form
 481          *    element.
 482          *    @param string $name     HTML element name.
 483          *    @return boolean         True if form element.
 484          *    @access private
 485          */
 486         function _isFormElement($name) {
 487             return in_array($name, array('input', 'button', 'textarea', 'select'));
 488         }
 489
 490         /**
 491          *    Opens a form. New widgets go here.
 492          *    @param SimpleFormTag $tag      Tag to accept.
 493          *    @access public
 494          */
 495         function acceptFormStart(&$tag) {
 496             $this->_open_forms[] = &new SimpleForm($tag, $this->getUrl());
 497         }
 498
 499         /**
 500          *    Closes the most recently opened form.
 501          *    @access public
 502          */
 503         function acceptFormEnd() {
 504             if (count($this->_open_forms)) {
 505                 $this->_complete_forms[] = array_pop($this->_open_forms);
 506             }
 507         }
 508
 509         /**
 510          *    Opens a frameset. A frameset may contain nested
 511          *    frameset tags.
 512          *    @param SimpleFramesetTag $tag      Tag to accept.
 513          *    @access public
 514          */
 515         function acceptFramesetStart(&$tag) {
 516             if (! $this->_isLoadingFrames()) {
 517                 $this->_frameset = &$tag;
 518             }
 519             $this->_frameset_nesting_level++;
 520         }
 521
 522         /**
 523          *    Closes the most recently opened frameset.
 524          *    @access public
 525          */
 526         function acceptFramesetEnd() {
 527             if ($this->_isLoadingFrames()) {
 528                 $this->_frameset_nesting_level--;
 529             }
 530         }
 531
 532         /**
 533          *    Takes a single frame tag and stashes it in
 534          *    the current frame set.
 535          *    @param SimpleFrameTag $tag      Tag to accept.
 536          *    @access public
 537          */
 538         function acceptFrame(&$tag) {
 539             if ($this->_isLoadingFrames()) {
 540                 if ($tag->getAttribute('src')) {
 541                     $this->_frames[] = &$tag;
 542                 }
 543             }
 544         }
 545
 546         /**
 547          *    Test to see if in the middle of reading
 548          *    a frameset.
 549          *    @return boolean        True if inframeset.
 550          *    @access private
 551          */
 552         function _isLoadingFrames() {
 553             if (! $this->_frameset) {
 554                 return false;
 555             }
 556             return ($this->_frameset_nesting_level > 0);
 557         }
 558
 559         /**
 560          *    Test to see if link is an absolute one.
 561          *    @param string $url     Url to test.
 562          *    @return boolean        True if absolute.
 563          *    @access protected
 564          */
 565         function _linkIsAbsolute($url) {
 566             $parsed = new SimpleUrl($url);
 567             return (boolean)($parsed->getScheme() && $parsed->getHost());
 568         }
 569
 570         /**
 571          *    Adds a link to the page.
 572          *    @param SimpleAnchorTag $tag      Link to accept.
 573          *    @access protected
 574          */
 575         function _addLink($tag) {
 576             $this->_links[] = $tag;
 577         }
 578
 579         /**
 580          *    Test for the presence of a frameset.
 581          *    @return boolean        True if frameset.
 582          *    @access public
 583          */
 584         function hasFrames() {
 585             return (boolean)$this->_frameset;
 586         }
 587
 588         /**
 589          *    Accessor for frame name and source URL for every frame that
 590          *    will need to be loaded. Immediate children only.
 591          *    @return boolean/array     False if no frameset or
 592          *                              otherwise a hash of frame URLs.
 593          *                              The key is either a numerical
 594          *                              base one index or the name attribute.
 595          *    @access public
 596          */
 597         function getFrameset() {
 598             if (! $this->_frameset) {
 599                 return false;
 600             }
 601             $urls = array();
 602             for ($i = 0; $i < count($this->_frames); $i++) {
 603                 $name = $this->_frames[$i]->getAttribute('name');
 604                 $url = new SimpleUrl($this->_frames[$i]->getAttribute('src'));
 605                 $urls[$name ? $name : $i + 1] = $url->makeAbsolute($this->getUrl());
 606             }
 607             return $urls;
 608         }
 609
 610         /**
 611          *    Fetches a list of loaded frames.
 612          *    @return array/string    Just the URL for a single
 613          *                            page.
 614          *    @access public
 615          */
 616         function getFrames() {
 617             $url = $this->getUrl();
 618             return $url->asString();
 619         }
 620
 621         /**
 622          *    Accessor for a list of all fixed links.
 623          *    @return array   List of urls with scheme of
 624          *                    http or https and hostname.
 625          *    @access public
 626          */
 627         function getAbsoluteUrls() {
 628             $all = array();
 629             foreach ($this->_links as $link) {
 630                 if ($this->_linkIsAbsolute($link->getHref())) {
 631                     $all[] = $link->getHref();
 632                 }
 633             }
 634             return $all;
 635         }
 636
 637         /**
 638          *    Accessor for a list of all relative links.
 639          *    @return array      List of urls without hostname.
 640          *    @access public
 641          */
 642         function getRelativeUrls() {
 643             $all = array();
 644             foreach ($this->_links as $link) {
 645                 if (! $this->_linkIsAbsolute($link->getHref())) {
 646                     $all[] = $link->getHref();
 647                 }
 648             }
 649             return $all;
 650         }
 651
 652         /**
 653          *    Space at the ends will be stripped and space in
 654          *    between is reduced to one space.
 655          *    @param string $html  Typical HTML code.
 656          *    @return string       Content as big string.
 657          *    @access private
 658          */
 659         function _normalise($html) {
 660             return preg_replace('/\S\s+\S/', ' ', strtolower(trim($html)));
 661         }
 662
 663         /**
 664          *    Matches strings regardles of varying whitespace.
 665          *    @param string $first    First to match with.
 666          *    @param string $second   Second to match against.
 667          *    @return boolean         True if matches even with
 668          *                            whitespace differences.
 669          *    @access private
 670          */
 671         function _isNormalMatch($first, $second) {
 672             return ($this->_normalise($first) == $this->_normalise($second));
 673         }
 674
 675         /**
 676          *    Accessor for URLs by the link label. Label will match
 677          *    regardess of whitespace issues and case.
 678          *    @param string $label    Text of link.
 679          *    @return array           List of links with that label.
 680          *    @access public
 681          */
 682         function getUrlsByLabel($label) {
 683             $matches = array();
 684             foreach ($this->_links as $link) {
 685                 if ($this->_isNormalMatch($link->getContent(), $label)) {
 686                     $matches[] = $this->_getUrlFromLink($link);
 687                 }
 688             }
 689             return $matches;
 690         }
 691
 692         /**
 693          *    Accessor for a URL by the id attribute.
 694          *    @param string $id       Id attribute of link.
 695          *    @return SimpleUrl       URL with that id of false if none.
 696          *    @access public
 697          */
 698         function getUrlById($id) {
 699             foreach ($this->_links as $link) {
 700                 if ($link->getAttribute('id') === (string)$id) {
 701                     return $this->_getUrlFromLink($link);
 702                 }
 703             }
 704             return false;
 705         }
 706
 707         /**
 708          *    Converts a link into a target URL.
 709          *    @param SimpleAnchor $link    Parsed link.
 710          *    @return SimpleUrl            URL with frame target if any.
 711          *    @access private
 712          */
 713         function _getUrlFromLink($link) {
 714             $url = $this->_makeAbsolute($link->getHref());
 715             if ($link->getAttribute('target')) {
 716                 $url->setTarget($link->getAttribute('target'));
 717             }
 718             return $url;
 719         }
 720
 721         /**
 722          *    Expands expandomatic URLs into fully qualified
 723          *    URLs.
 724          *    @param SimpleUrl $url        Relative URL.
 725          *    @return SimpleUrl            Absolute URL.
 726          *    @access protected
 727          */
 728         function _makeAbsolute($url) {
 729             if (! is_object($url)) {
 730                 $url = new SimpleUrl($url);
 731             }
 732             return $url->makeAbsolute($this->getUrl());
 733         }
 734
 735         /**
 736          *    Sets the title tag contents.
 737          *    @param SimpleTitleTag $tag    Title of page.
 738          *    @access protected
 739          */
 740         function _setTitle(&$tag) {
 741             $this->_title = &$tag;
 742         }
 743
 744         /**
 745          *    Accessor for parsed title.
 746          *    @return string     Title or false if no title is present.
 747          *    @access public
 748          */
 749         function getTitle() {
 750             if ($this->_title) {
 751                 return $this->_title->getContent();
 752             }
 753             return false;
 754         }
 755
 756         /**
 757          *    Finds a held form by button label. Will only
 758          *    search correctly built forms.
 759          *    @param string $label       Button label, default 'Submit'.
 760          *    @return SimpleForm         Form object containing the button.
 761          *    @access public
 762          */
 763         function &getFormBySubmitLabel($label) {
 764             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 765                 if ($this->_complete_forms[$i]->hasSubmitLabel($label)) {
 766                     return $this->_complete_forms[$i];
 767                 }
 768             }
 769             return null;
 770         }
 771
 772         /**
 773          *    Finds a held form by button label. Will only
 774          *    search correctly built forms.
 775          *    @param string $name        Button name attribute.
 776          *    @return SimpleForm         Form object containing the button.
 777          *    @access public
 778          */
 779         function &getFormBySubmitName($name) {
 780             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 781                 if ($this->_complete_forms[$i]->hasSubmitName($name)) {
 782                     return $this->_complete_forms[$i];
 783                 }
 784             }
 785             return null;
 786         }
 787
 788         /**
 789          *    Finds a held form by button id. Will only
 790          *    search correctly built forms.
 791          *    @param string $id          Button ID attribute.
 792          *    @return SimpleForm         Form object containing the button.
 793          *    @access public
 794          */
 795         function &getFormBySubmitId($id) {
 796             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 797                 if ($this->_complete_forms[$i]->hasSubmitId($id)) {
 798                     return $this->_complete_forms[$i];
 799                 }
 800             }
 801             return null;
 802         }
 803
 804         /**
 805          *    Finds a held form by image label. Will only
 806          *    search correctly built forms.
 807          *    @param string $label       Usually the alt attribute.
 808          *    @return SimpleForm         Form object containing the image.
 809          *    @access public
 810          */
 811         function &getFormByImageLabel($label) {
 812             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 813                 if ($this->_complete_forms[$i]->hasImageLabel($label)) {
 814                     return $this->_complete_forms[$i];
 815                 }
 816             }
 817             return null;
 818         }
 819
 820         /**
 821          *    Finds a held form by image button id. Will only
 822          *    search correctly built forms.
 823          *    @param string $name        Image name.
 824          *    @return SimpleForm         Form object containing the image.
 825          *    @access public
 826          */
 827         function &getFormByImageName($name) {
 828             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 829                 if ($this->_complete_forms[$i]->hasImageName($name)) {
 830                     return $this->_complete_forms[$i];
 831                 }
 832             }
 833             return null;
 834         }
 835
 836         /**
 837          *    Finds a held form by image button id. Will only
 838          *    search correctly built forms.
 839          *    @param string $id          Image ID attribute.
 840          *    @return SimpleForm         Form object containing the image.
 841          *    @access public
 842          */
 843         function &getFormByImageId($id) {
 844             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 845                 if ($this->_complete_forms[$i]->hasImageId($id)) {
 846                     return $this->_complete_forms[$i];
 847                 }
 848             }
 849             return null;
 850         }
 851
 852         /**
 853          *    Finds a held form by the form ID. A way of
 854          *    identifying a specific form when we have control
 855          *    of the HTML code.
 856          *    @param string $id     Form label.
 857          *    @return SimpleForm    Form object containing the matching ID.
 858          *    @access public
 859          */
 860         function &getFormById($id) {
 861             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 862                 if ($this->_complete_forms[$i]->getId() == $id) {
 863                     return $this->_complete_forms[$i];
 864                 }
 865             }
 866             return null;
 867         }
 868
 869         /**
 870          *    Sets a field on each form in which the field is
 871          *    available.
 872          *    @param string $name        Field name.
 873          *    @param string $value       Value to set field to.
 874          *    @return boolean            True if value is valid.
 875          *    @access public
 876          */
 877         function setField($name, $value) {
 878             $is_set = false;
 879             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 880                 if ($this->_complete_forms[$i]->setField($name, $value)) {
 881                     $is_set = true;
 882                 }
 883             }
 884             return $is_set;
 885         }
 886
 887         /**
 888          *    Sets a field on the form in which the unique field is
 889          *    available.
 890          *    @param string/integer $id  Field ID attribute.
 891          *    @param string $value       Value to set field to.
 892          *    @return boolean            True if value is valid.
 893          *    @access public
 894          */
 895         function setFieldById($id, $value) {
 896             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 897                 if ($this->_complete_forms[$i]->setFieldById($id, $value)) {
 898                     return true;
 899                 }
 900             }
 901             return false;
 902         }
 903
 904         /**
 905          *    Accessor for a form element value within a page.
 906          *    Finds the first match.
 907          *    @param string $name        Field name.
 908          *    @return string/boolean     A string if the field is
 909          *                               present, false if unchecked
 910          *                               and null if missing.
 911          *    @access public
 912          */
 913         function getField($name) {
 914             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 915                 $value = $this->_complete_forms[$i]->getValue($name);
 916                 if (isset($value)) {
 917                     return $value;
 918                 }
 919             }
 920             return null;
 921         }
 922
 923         /**
 924          *    Accessor for a form element value within a page.
 925          *    Finds the first match.
 926          *    @param string/integer $id  Field ID attribute.
 927          *    @return string/boolean     A string if the field is
 928          *                               present, false if unchecked
 929          *                               and null if missing.
 930          *    @access public
 931          */
 932         function getFieldById($id) {
 933             for ($i = 0; $i < count($this->_complete_forms); $i++) {
 934                 $value = $this->_complete_forms[$i]->getValueById($id);
 935                 if (isset($value)) {
 936                     return $value;
 937                 }
 938             }
 939             return null;
 940         }
 941     }
 942 ?>