<?php

namespace {
    /**
     * Class representing a page of a multipage form
     *
     * PHP version 5
     *
     * LICENSE:
     *
     * Copyright (c) 2006-2010, Alexey Borzov <avb@php.net>,
     *                          Bertrand Mansion <golgote@mamasam.com>
     * All rights reserved.
     *
     * Redistribution and use in source and binary forms, with or without
     * modification, are permitted provided that the following conditions
     * are met:
     *
     *    * Redistributions of source code must retain the above copyright
     *      notice, this list of conditions and the following disclaimer.
     *    * Redistributions in binary form must reproduce the above copyright
     *      notice, this list of conditions and the following disclaimer in the
     *      documentation and/or other materials provided with the distribution.
     *    * The names of the authors may not be used to endorse or promote products
     *      derived from this software without specific prior written permission.
     *
     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
     * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
     * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     *
     * @category   HTML
     * @package    HTML_QuickForm2
     * @author     Alexey Borzov <avb@php.net>
     * @author     Bertrand Mansion <golgote@mamasam.com>
     * @license    http://opensource.org/licenses/bsd-license.php New BSD License
     * @version    SVN: $Id: Page.php 295963 2010-03-08 14:33:43Z avb $
     * @link       http://pear.php.net/package/HTML_QuickForm2
     */
    /**
     * Class representing a page of a multipage form
     *
     * Unlike old HTML_QuickForm_Controller, this does not extend HTML_QuickForm2
     * but accepts an instance of that in the constructor. You need to create a
     * subclass of this class and implement its populateForm() method.
     *
     * @category   HTML
     * @package    HTML_QuickForm2
     * @author     Alexey Borzov <avb@php.net>
     * @author     Bertrand Mansion <golgote@mamasam.com>
     * @version    Release: @package_version@
     */
    abstract class HTML_QuickForm2_Controller_Page
    {
        /**
         * Button name template (needs form ID and action name substituted by sprintf())
         */
        const KEY_NAME = '_qf_%s_%s';
        /**
         * Whether populateForm() was already called
         * @var  boolean
         */
        private $_formPopulated = \false;
        /**
         * The form wrapped by this page
         * @var  HTML_QuickForm2
         */
        protected $form = null;
        /**
         * Controller this page belongs to
         * @var  HTML_QuickForm2_Controller
         */
        protected $controller = null;
        /**
         * Contains the mapping of action names to handlers (objects implementing HTML_QuickForm2_Controller_Action)
         * @var  array
         */
        protected $handlers = array();
        /**
         * Class constructor, accepts the form to wrap around
         *
         * @param    HTML_QuickForm2
         */
        public function __construct(\HTML_QuickForm2 $form)
        {
            $this->form = $form;
        }
        /**
         * Returns the form this page wraps around
         *
         * @return   HTML_QuickForm2
         */
        public function getForm()
        {
            return $this->form;
        }
        /**
         * Sets the controller owning the page
         *
         * @param    HTML_QuickForm2_Controller  controller the page belongs to
         */
        public function setController(\HTML_QuickForm2_Controller $controller)
        {
            $this->controller = $controller;
        }
        /**
         * Returns the controller owning this page
         *
         * @return   HTML_QuickForm2_Controller
         */
        public function getController()
        {
            return $this->controller;
        }
        /**
         * Adds a handler for a specific action
         *
         * @param  string                            action name
         * @param  HTML_QuickForm2_Controller_Action the handler for the action
         */
        public function addHandler($actionName, \HTML_QuickForm2_Controller_Action $action)
        {
            $this->handlers[$actionName] = $action;
        }
        /**
         * Handles an action
         *
         * If the page does not contain a handler for this action, controller's
         * handle() method will be called.
         *
         * @param    string      Name of the action
         * @throws   HTML_QuickForm2_NotFoundException   if handler for an action is missing
         */
        public function handle($actionName)
        {
            if (isset($this->handlers[$actionName])) {
                return $this->handlers[$actionName]->perform($this, $actionName);
            } else {
                return $this->getController()->handle($this, $actionName);
            }
        }
        /**
         * Returns a name for a submit button that will invoke a specific action
         *
         * @param  string  Name of the action
         * @return string  "name" attribute for a submit button
         */
        public function getButtonName($actionName)
        {
            return \sprintf(self::KEY_NAME, $this->getForm()->getId(), $actionName);
        }
        /**
         * Sets the default action invoked on page-form submit
         *
         * This is necessary as the user may just press Enter instead of
         * clicking one of the named submit buttons and then no action name will
         * be passed to the script.
         *
         * @param  string    Default action name
         * @param  string    Path to a 1x1 transparent GIF image
         * @return object    Returns the image input used for default action
         */
        public function setDefaultAction($actionName, $imageSrc = '')
        {
            // require_once 'HTML/QuickForm2/Controller/DefaultAction.php';
            if (0 == \count($this->form)) {
                $image = $this->form->appendChild(new \HTML_QuickForm2_Controller_DefaultAction($this->getButtonName($actionName), array('src' => $imageSrc)));
                // replace the existing DefaultAction
            } elseif ($image = $this->form->getElementById('_qf_default')) {
                $image->setName($this->getButtonName($actionName))->setAttribute('src', $imageSrc);
                // Inject the element to the first position to improve chances that
                // it ends up on top in the output
            } else {
                $it = $this->form->getIterator();
                $it->rewind();
                $image = $this->form->insertBefore(new \HTML_QuickForm2_Controller_DefaultAction($this->getButtonName($actionName), array('src' => $imageSrc)), $it->current());
            }
            return $image;
        }
        /**
         * Wrapper around populateForm() ensuring that it is only called once
         */
        public final function populateFormOnce()
        {
            if (!$this->_formPopulated) {
                if (!empty($this->controller) && $this->controller->propagateId()) {
                    $this->form->addElement('hidden', \HTML_QuickForm2_Controller::KEY_ID, array('id' => \HTML_QuickForm2_Controller::KEY_ID))->setValue($this->controller->getId());
                }
                $this->populateForm();
                $this->_formPopulated = \true;
            }
        }
        /**
         * Populates the form with the elements
         *
         * The implementation of this method in your subclass of
         * HTML_QuickForm2_Controller_Page should contain all the necessary
         * addElement(), addRule() etc. calls. The method will only be called if
         * needed to prevent wasting resources on the forms that aren't going to
         * be seen by the user.
         */
        protected abstract function populateForm();
        /**
         * Stores the form values (and validation status) is session container
         *
         * @param    bool    Whether to store validation status
         */
        public function storeValues($validate = \true)
        {
            $this->populateFormOnce();
            $container = $this->getController()->getSessionContainer();
            $id = $this->form->getId();
            $container->storeValues($id, (array) $this->form->getValue());
            if ($validate) {
                $container->storeValidationStatus($id, $this->form->validate());
            }
            return $container->getValidationStatus($id);
        }
    }
}
