Home / Section index

 PHPLint - Web tools - Bt form

Last updated: 2018-04-16

Good news: if you had the patience to read up here all about sticky forms and bt_, bt forms are really simple to understand because they can be used just like sticky forms. There are only few differences we list below and some important new features specific of the bt_ support.



Creating a bt form

A bt form is a class extending the it\icosaedro\web\bt_\Form class. A bt form only works in the user session environment created by bt_ because it relies on UserSession in order to set forward calls, backward calls and to save its state on the bt stack. Being a session now available, bt form does not need to save anything on the user's page: all is saved on the server. Bt forms so created are regular library classes that should be saved under the standard library directory, just like any other library class. So, say we have to build our web site www.acme.com: the first thing to do is to create the usual directory hierarchy under the standard library directory, in this case stdlib/com/acme/www, and that directory will hold all the classes related to the com\acme\www namespace. Lets finally see how a bt form may look like:

namespace com\acme\www;

require_once __DIR__ . "/../../../all.php";

use it\icosaedro\web\bt_\UserSession;
use it\icosaedro\web\bt_\Form;
use it\icosaedro\web\controls\Line;

class MyBtForm extends Form {

	/** @var Line */
	private $line1;

	function __construct()
		// Create controls and register them into the form:
		$this->line1 = new Line($this, "line1");

	function render()
		header("Content-Type: text/html; charset=UTF-8");
		echo "<html><body>";
		echo "Please, enter anything you want:";
		$this->button("Dismiss", "dismissButton");
		$this->button("Save", "saveButton");
		echo "Hello, world!";
		echo "</body></html>";

	function dismissButton()

	function saveButton()
		// Here: save $this->line1->getValue() somewhere, then
		// either invoke the render again:
		// ...or return to the caller:
		// ...or continue with another form:
		// AnotherBtForm->enter();

	static function enter()
		$f = new self();

Example of bt form.

No big surprises here, but it's worth to note some points:

Finally, to really see our new bt form come up, we must set an entry in the dashboard of the web site, something like:

UserSession::setCallBackward(Dashboard::class . "::enter");
UserSession::anchor("My first bt form", "com\\acme\\www\\MyBtForm::enter");

And that is pretty all there is to say about bt forms to cover the same feature of a sticky form. The following paragraphes illustrate two really important features that were missing in sticky forms and are now available with bt forms.

Joining bt forms together: goto

Doing a "go-to" to another bt form simply means invoking its "enter()" static method if that class provides that method:


Otherwise we can create the object by ourselves and invoke the render method explicitly:

$f = new AnotherBtForm();

Joining bt forms together: gosub

But what if we need to set a return point back to our bt form? what with its state? and how to return values from the other invoked form (or any other invoked bt function)? The bt form class adds the returnTo() method just to cover this need. The returnTo() method saves the state of our bt form on the stack along with an handler method to invoke on return, then we may invoke the other page:

$this->returnTo("returnEvent", 1, 2, 3);

With the state of our form saved on the stack, AnotherBtForm (or any other bt function) may return its results to our returnEvent() handler. For example, somewhere in the code of the AnotherBtForm there might be a bt return statement like this that returns a value to us:


At that exact moment our form will be instantiated again, its state resumed from the bt stack, and the method returnEvent(1, 2, 3, 5678) invoked, and our bt form class is back in business and with a new value added. Then, our method might do something with that value, for example updating its internal state, and then it might show the form again by invoking the render method.

It is important to stress once again that no value ever leave the server and nothing is left on the page of the user, no magic HTTP redirects or other tricks. Bt form relies only on the features provided by bt_ and nothing else. No need to sign or encrypt anything, no need to keep the volume of the state data low in order to save bandwidth, no way for the remote user to tamper with our application.

Umberto Salsi
Site map
Home / Section index
Still no comments to this page. Use the Comments link above to add your contribute.