www.icosaedro.it

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.

References

it\icosaedro\web\bt_\Form - Reference for the bt_ form class, with source code available, subject of this tutorial.
Sample web site - Web site built using bt forms. The source code is available along with the PHPLint package under the stdlib/com/acme/www directory.
PHPLint - A PHP source code validator program. Includes the "standard library" that comes along with several others PHP programming tools of general usage, including the bt form class itself.

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:

<?php
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()
	{
		parent::__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>";
		$this->open();
		echo "Please, enter anything you want:";
		$this->line1->render();
		$this->button("Dismiss", "dismissButton");
		$this->button("Save", "saveButton");
		echo "Hello, world!";
		$this->close();
		echo "</body></html>";
	}

	function dismissButton()
	{
		UserSession::invokeCallBackward();
	}

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

	static function enter()
	{
		$f = new self();
		$f->render();
	}

}

Example of bt form.

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

A "namespace" statement is mandatory to let the class autoloader find out our com\acme\www\MyBtForm class.
Note that the "use" statement declares the web\bt_\Form class, NOT the sticky class web\Form.
Our bt form must then extend the bt form class. The minimal requirement is to implement the render method to display the page.
All the controls we already used for sticky forms can be used here again. In this case we use the Line control to let the user enter some text.
A constructor is mandatory in order to create the controls inside our form. Each control then takes care to register itself into the form so that its state can be saved, resumed and retrieved from postbacks automatically. And do not forget to invoke the parent constructor; PHPLint would warn about that anyway.
A static method we named here "enter()" might be needed to allow external code to invoke this mask via bt_. That method might also receive the initial parameters to display some specific information in the form, for example the primary key of a data base record. In more articulated cases the client code may also explicitly instantiate our bt form class and set its internal state before invoking its render() method. Chose the way you prefer.
Our render() method displays the form as usual, and puts two buttons in it along with the respective event handler methods.
The dismissButton() handler is supposed to bring back the user to the caller mask as set on the bt stack, so it invokes UserSession::invokeCallBackward(). We assume here the original caller did actually prepared that return point.
The saveButton() handler should validate and save the data. What to do next depends on the specific application. Several possible options are illustrated in the comments to the source code.

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:

AnotherBtForm::enter();

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

$f = new AnotherBtForm(); $f->render();

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); AnotherBtForm::enter();

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:

UserSession::invokeCallBackward(5678);

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

Comments

Contact

Site map

Home / Section index

Still no comments to this page. Use the Comments link above to add your contribute.

PHPLint - Web tools - Bt form

Contents

References

Creating a bt form

Joining bt forms together: goto

Joining bt forms together: gosub