Using XFAs - PHP

Let's say you want one screen on your web site to lead into another, like in a traditional login system where the user types his / her username and password into a text field and presses the submit button.  In Fusebox, instead of hard-coding a path to a CGI script or another PHP page in your form's "action" parameter, you simply specify an exit fuseaction, or XFA. 

What's an XFA?

PHP Fusebox filenames must begin with either dsp_, act_, url_, or qry_.  They contain exit fuseactions that are picked up in a circuit's fbx_Switch.php file.

For example, one of your circuits' dynamically-included files will contain references collectively known as XFAs.  When called, these XFAs communicate with the switch/case statement in fbx_Switch.php, telling it to find a matching circuit (case statement), and an XFA definition inside the case statement, one that tells the application where the exit for that fuseaction is.  It helps to remember "X for exit".

To further illustrate, let's focus again on fbx_Switch.php.  Add the following code under the initial case statements:

$XFA["biography"] = "biography.hello_world";

Now your switch statement should look like this:

switch($Fusebox["fuseaction"]) {

      case "main":

      case "Fusebox.defaultFuseaction":

// Add this line:

$XFA["biography"] = "biography.hello_world";

            include("dsp_main.php");

            break;

      default:

            print "I received a fuseaction called <b>'" . $Fusebox["fuseaction"] . "'</b> that circuit <b>'" . $Fusebox["circuit"] . "'</b> does not have a handler for.";

            break;

}

This may take a while to get right in your head.  While fbx_Switch.php dynamically includes files, it also controls the flow of the application.  Think of it as a railroad switch that directs your model train by moving the switch to the correct track.  Your train signals the switch where it wants to go, and the switch moves into place to match the signal sent by the train.  What you've just done is instruct the circuit to go to the bio/ directory (or "biography" circuit if you think about it from the perspective of the application root's fbx_Circuits.php file) when passed an XFA called "biography".  The biography circuit's fbx_Switch.php will have a case statement that looks for the fuseaction "hello_world" and include the files you define for this circuit.

But wait, we're getting ahead of ourselves.  Deeeep breath.  First, we have to understand how these XFAs are passed in the context of the application.

An XFA or exit fuseaction called from a URL:

<a href=\"$PHP_SELF?fuseaction=".$XFA["biography"]."\">Example Link</a>

An XFA or exit fuseaction called from form POST:

<form action=\"$PHP_SELF?fuseaction=".$XFA["biography"]."\" method=\"post\">

Or a GET:

<form action=\"$PHP_SELF\">

<input type=\"hidden\" name=\"fuseaction\" value=\"".$XFA["biography"]."\">

</form>

The beauty of PHP Fusebox is in the abstraction of the file system's real structure: using XFAs, you can send the application to any circuit (directory) you want, and have it perform whatever duties you wish.  As long as the root directory's fbx_Circuits.php contains a matching circuit definition and its fbx_Switch.php contains a corresponding XFA that can tell fbx_Circuits.php where to go next, the sky's the limit!