The $parameters array

The other thing a box might like as input is a list of parameters, since those are pretty much a staple of web development (form input, passing parameters via the URL).  Well for that we have $parameters.

$parameters is an array containing all of the parameters passed to the current box.  These can be the additional attributes to your <xt:box /> call, the array we passed as a second parameter to loader_box(), and even the parameters passed on the URL if the box is called as an action (in which case $parameters is an array version of the global $cgi object).

In the case of an action, using $parameters instead of $cgi ensures that your box can be called in multiple contexts without any modifications.

So now we can take advantage of the $parameters array to complete our hello box from before:

<?php

echo 'hello ' . $parameters['to'];

?>

The settings.php file

For boxes, the settings.php file takes a more passive role than for forms, for which it contains the definition of the form itself.  The settings.php for a box, instead, is used to describe the box's purpose as well as any parameters that it uses.

In describing the parameters, it is similar to a form settings.php file, since each parameter is described in the same syntax as a MailForm widget.  In fact, come Sitellite 4.2, these definitions will be used to create a box selection wizard for dynamically inserting boxes into page content and sidebars.  For now, they serve to document your box for the purposes of perusal in the AppDoc app.

An example settings.php file, which can be found in the inc/app/sitellite/boxes/intl/setLang folder, is as follows:

; <?php /*

[Meta]

name        = setLang
description = Sets the language cookie to the specified language...

[choice]

alt         = "Language choice"
type        = text
rule 0      = "not empty, You must enter a language choice."

[goHome]

alt         = Send visitor to /index instead of previous screen
type        = boolean

; */ ?>

The first section, named [Meta], describes the box's purpose.  This is the metadata section of the settings.php file.  Below that we have two sections [choice] and [goHome] representing the two parameters this box accepts.  You can also see that the [choice] parameter is required, since it has a rule assigned to it, while [goHome] does not and is therefore optional.

I probably shouldn't say this, but settings.php files are optional and are not required for a box to run.  So for quick programming tasks, you may want to skip this part.  However, if you want other apps or users to be able to integrate more easily with your boxes and apps, then it's necessary to tell them how to do so in the form of settings.php files.

Next: Accessing app-wide properties

Page 1: As I mentioned in my previous ar...
Page 2: Calling our box
Page 3: The access.php File
Page 4: The $parameters array
Page 5: Accessing app-wide properties

All Tutorials