3 - Introducing WebBox-es

Explains what are WebBox-es and their differences with templates. The PHP code of the WebBox-es declares template {{#variables}} in the onRender() function, by using WebApp::addVar(). Gives some tips about good programming practices with WebBox-es. Introduces as well the files init.php, global.php, before_page.php and after_page.php.

Test Browse Download

Table of Contents


WebBox-es

A WebBox is a template which has also some PHP code associated with it. It is a self-contained and independent template which can be easily included in other pages or in other applications. In fact, it may also have some JavaScript code, CSS stylesheets, SQL queries etc., associated with it.

It is denoted by the tag <WebBox> and it has an ID attribute:

  <WebBox id="box_id">
    <!-- content of WebBox -->
  </WebBox>

The identifier must be different for each WebBox used in the application.

1 - The PHP code of the WebBox-es

The PHP code (as well as JS code, CSS styles etc.) are associated to the WebBox by means of box_id, the identifier of the WebBox. When the framework parses a <WebBox> tag, it looks for a file named box_id.php in the same folder where the WebBox template is. If it finds such a file, it includes it.

The box_id.php file must contain the definition of a PHP class that extends the class WebObject, like this:

  <?php
  class box_id extends WebObject
  {
    .
    .
    .
  }
  ?>

See this example: templates/menu/menu.html, templates/menu/menu.php.

The class WebObject is defined by the framework. Among other things, it also contains the member functions WebObject::init(), WebObject::onParse() and WebObject::onRender(). We will discuss in the next tutorial the first two functions, and will deal here only with the last one.

2 - The function onRender()

The function onRender() of the class WebObject is called by the framework at the time of the HTML page construction (the page that is sent to the browser), just before the template of the WebBox is outputed (rendered). Actually WebObject::onRender() is an abstract (empty) function, and the framework expects the class box_id to override it, in order to do something useful for the WebBox.

What is usually done in box_id::onRender() is assigning values to the variables used in the template of the WebBox box_id, so that the template is rendered properly. These values are assigned by the function WebApp::addVar("var_name", "var_value"). E.g. see how it is done in the WebBox tip: templates/tip/tip.html, templates/tip/tip.php. The framework replaces the variables {{#rand}} and {{#tip_text}} by the values assigned in onRender() and generates HTML code.

3 - Files related to a WebBox

Besides the file that contains the template of the WebBox and the box_id.php that contains its PHP class, there may be other files as well that belong to the WebBox. These are: box_id.js that contains the JavaScript code of the WebBox, box_id.css that contains the stylesheet of the WebBox, etc. (we will see the others later). If the framework finds such files, it automatically integrates them in the generated HTML page. For example, it includes box_id.js and box_id.css in the <head> of the page. As an example, see the files of the WebBox menu.

Of these files, the template is the most important. There can be a WebBox without JS code or without PHP code, but there cannot be a WebBox without TPL(template) code.

4 - Differences with templates

A WebBox is defined inside a template file and the TPL code of the WebBox is inside the <WebBox> tag (is the content of the <WebBox> element). However a WebBox is different from a template because it can also have its own PHP code. Another difference is that a template must include explicitly the JS code and the CSS code (if it has its own), see this example, however, for a WebBox the framework handles them automatically, by including them at the <head> of the page

TOC

Tips about using WebBox-es

TOC

Study the sample application

Here we will highlight and discuss some of the features of the sample application, so that we can understand it better.

TOC

Exercises

Before starting the exercises, make a copy of the application app2 to the folder test/app2 and a copy of app3 to the folder test/app3. If you have problems with doing this then see the first tutorial, second exercise.

1 - Use webbox menu in application app2

  1. $ cd test/app2/templates
  2. Open the file header.html and append the line:
    <include src="{{#UP_PATH}}app3/templates/menu/menu.html" />
  3. Refresh the application app2 in browser.

UP_PATH contains the path of the parent folder of the application.

If you view the HTML code of app2 (in browser), you will notice that menu.js and menu.css have been included as well in the <head> of the page.

2 - Use webbox tip in application app2

  1. $ cd test/app2/templates
  2. Open the file header.html and append the line:
    <Include src="{{#UP_PATH}}app3/templates/tip/tip.html" />
  3. Refresh the application app2 in browser. You will get an error, because the TIP_PATH constant is unknown in app2.
  4. Open tip.php and replace the include statement with:
    $tip_path = dirname(__FILE__)."/";
    include_once $tip_path."fun.get_random_tip.php";
    Do the same thing with fun.get_random_tip.php.
  5. Refresh the application app2 in browser. You will see that the tip is displayed, but it has no styles. This is because the framework does not reckognize tip_styles.css as being the stylesheet of webbox tip. Make a copy of it with the name tip.css:
    $ cp tip_styles.css tip.css
  6. Refresh again the application. Finally it should be OK.

__FILE__ is a PHP constant and dirname() is a PHP function.

3 - Enable counting

  1. Open the file config/const.Options.php and set the constant COUNT_CLICKS to true.
  2. Test the application and see what happens. Then make it false and test the application again.

COUNT_CLICKS is not a framework constant, it is defined and used by the application app3.

4 - Test before_page.php and after_page.php

  1. Open the files before_page.php and after_page.php and uncomment the print statements.
  2. Test the application and see what happens. Then comment them again.

5 - Modify the tip webbox

  1. Suppose that we don't want to display a random tip, but we want to display the tips in their order. So, when we first open the app we should see the first tip, and each time that we open another page we should see the next tip. When we are at the end of the tips we should start again from the beginning. Can you do it yourself? You can use state variables and the functions WebApp::addSVar(), WebApp::setSVar() and WebApp::getSVar().

  2. Now suppose that we want to control ourselves the rotation of the tips. That is, the tip will stay the same when we switch the pages, however it will have some buttons like this: '<'(previous), '>'(next), '<<'(first), '>>'(last). When we click the button next we should get the next tip, etc. How can we do this? Think about it.