Brimbox Logo Brimbox Version 2.3.4 Released

Programming Brimbox Modules>>

Brimbox is designed so a programmer can add functionality just by adding a module. Almost all databases need custom reports and views, so Brimbox leaves this task to the Brimbox programmer. These are the skills you will need to program a Brimbox module. You should be able to:

  1. Post a form and use a PHP object.
  2. If you want to format your output a little CSS would help.
  3. PHP, agility with PHP arrays is very helpful.
  4. SQL is a must, the more PostgreSQL the better, you should be able to handle a self-referential table, subjoins, subqueries, and data type conversions.

These are some of the aspects of a module. First, get the state variables from the posted state information using the bb_work class (extended and called as $main). Follow this methodology:

  1. Brimbox $POST is loaded in the controller and is the equivalent PHP $_POST in many ways. The Brimbox algorithm does something similar to a Post/Redirect/Get (PRG) algorithm. This simplifies the use of $_POST (or $POST). One thing different between $POST and $_POST is form variables are localized. The Brimbox controller prepends the posting module name to form variables that are not declared global using rel="global" attribute in a form object (not an HTML standard). This allows a Brimbox programmer to navigate the mandatory form posts when switching modules.
  2. Load the current module state into the $arr_state array using $arr_state = $main->load($con, $module);. Brimbox has an algorithm for preserving state so a module state can be kept while visiting other modules. If the state of a different module is needed the module name (like “abc_filename”) can be substituted in for the current module $module.
  3. Modify $arr_state with the new post information for preservation handling the form postback or module entrance. Typical functions when doing this are $main->process, $main->post, $main->set and $main->state (See The Form Process Methods). See the documented functions contained in the class bb_work extended to class bb_main instantiated as $main.
  4. Update the state_table with the processed $arr_state variable by calling method $main->update($con, $module, $arr_state);.

The snippet below handles form variables called “my_key” and “row_type” on postback preserving state and creating PHP variables $my_key and $row_type for immediate use. Note that by properly using the native Brimbox form posting and retrieving functions to handle form variables, the form variable row_type will not be confused with a form variable of the same name in another module (row_type is used in almost all the standard modules):

<?php
//global $POST brought in from controller
$arr_state = $main->load($con, $module);
//process the variables
$row_type = $main->process('row_type', $module, $arr_state, 1);
$my_key = $main->process('my_key', $module, $arr_state, 0);
//save the state for later use
$main->update($con, $module, $arr_state);
?>

Return any information desired as module output based on the postback or state variables, or anything else desired. The $con database connection is already set by the controller, or the index.php file, so the database connection need not be made in the module.

<?php
$query = 
"SELECT * FROM data_table " . 
"WHERE row_type = " . $row_type . " AND key1 = " . $my_key . ";";

$result = $main->query($con, $query);

while($row = pg_fetch_array($result)){
//output data
}
?>

Render the required form with your custom variables. You must also echo the module variables into the form, the controller needs them. There are native functions to do this. All modules must have a form and you should use the echo_button method to create your submit buttons. This will invoke the Brimbox posting algorithm through the Javascript function bb_submit_form().

You can also use the Javascript function bb_submit_form() directly to submit the form, placing it in a HTML event handler (like onChange or onClick). If you wish, bb_submit_form() could be placed in another Javascript function, presumably this function would also be called through an event handler. Always submit the form using this function, as bb_submit_form() is mandatory for the controller to work.

<?php
$main->echo_form_begin();
$main->echo_module_vars();

echo "<input name=\"my_key\" type=\"text\"  value=\"" . $my_key . "\" />";
echo "<input name=\"row_type\" type=\"text\"  value=\"" . $row_type . "\" />";

$params = array('number'=>1,'label'=>"Module Button");
$main->echo_button("submit_data", $params);

$main->echo_form_end();
?>

Note: there is function $main->echo_input($name, $value, $params) which could also be used to echo your custom input form objects.

Updated: 2017-07-30

Documents

Definitions