/*
 *  SPL - The SPL Programming Language
 *  Copyright (C) 2004, 2005  Clifford Wolf <clifford@clifford.at>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *  mod_wsf_switch.spl: A WSF Component for switching between other components
 */

/**
 * This module implements a WSF Component for switching between 
 * components. Usually this is used for navigating between different
 * dialogs.
 */

load "wsf";

/**
 * This WSF Component provides an easy infrastructure for switching between
 * components. In most cases, one will derive another object from this
 * one and use that instead.
 *
 * The children["content"] (see [[wsf:WsfComponent.children]]) contains the
 * current content of this component. Additional children may be defined and
 * are not handled specially by this component.
 *
 * An example:
 *
 *	object Foobar WsfSwitch
 *	{
 *		var cases = [
 *			[	'title' => 'Goto Demo A',
 *				'code' => function()
 *					{ return new WsfDisplay("Demo A"); }
 *			],
 *			[	'title' => 'Goto Demo B',
 *				'code' => function()
 *					{ return new WsfDisplay("Demo B"); }
 *			]
 *		];
 *
 *		method get_html() {
 *			switch_reset();
 *			return
 *			<>
 *				<div id="$id">
 *				<spl:foreach var="i" list="cases">
 *					<a ${switch_href(i)}>${cases[i].title}</a>
 *				</spl:foreach>
 *				$( if (declared children["content"])
 *					return children["content"].get_html_cached(); )
 *				</div>
 *			</>;
 *		}
 *	}
 *
 * This Object is derived from [[wsf:WsfComponent]].
 */
object WsfSwitch WsfComponent
{
	/**
	 * This variable is a hash or array of the possible choices.
	 *
	 * Each element is a hash and has an element with the key 'code' which
	 * is a function pointer. This function must return the new component
	 * which should replace the current children["content"].
	 *
	 * Additional keys might be defined in addition to the 'code' key.
	 * Usually keys such as 'title' or 'admin_only' are added.
	 *
	 * This object creates the key 'isactive' to store information about
	 * a choice beeing given the user and later only allows the user
	 * entering those choices.
	 */
	var cases;

	/**
	 * Overloaded [[wsf:WsfComponent.main()]].
	 */
	method main() {
		while (1) {
			task_co_return();
			if (declared cgi.param.switch and declared cases.[cgi.param.switch].isactive)
				switch_code(cases.[cgi.param.switch].code);
		}
	}

	/**
	 * This method is executed when one of the choices are selected. But
	 * it is also possible to call this method from outside and so forcing
	 * a switch to another component (possibly not in the choices given
	 * by the elements of the [[.cases]] variable).
	 */
	method switch_code(code)
	{
		var destory_function;

		if (declared children.["content"].destroy)
			destory_function = children.["content"].destroy;

		delete children.["content"];
		children.["content"] = code();
		dirty = 1;

		// this could kill the running task. so we need to do it
		// as last thing...
		if (defined destory_function)
			destory_function();
	}

	/**
	 * Used to add the href attriuted in a link to one of the choices.
	 * See the generic description of this object [[WsfSwitch]] for a
	 * usage example.
	 */
	method switch_href(i) {
		var cases.[i].isactive = 1;
		return add_href("${cgi.url}?sid=${sid}&switch=$i");
	}

	/**
	 * Reset the 'isactive' flags (see [[.cases]]).
	 *
	 * This should be called by the get_html() method in derived
	 * objects. (see [[wsf:WsfComponent.get_html()]])
	 */
	method switch_reset() {
		foreach i (cases)
			delete cases.[i].isactive;
	}
}