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
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
- There must not be two WebBox-es in the same web application
with the same ID.
- All the files of a WebBox (.js,
.css, .db, etc.) must have the
same name as the ID of the WebBox, otherwise the
framework will not reckognize them as belonging to this WebBox.
- You can place more than one WebBox in a template file, however
it is recomended to place each WebBox in a separate template,
without other HTML code that does not belong to it. It is recomended
to name this template box_id.html.
- It is recomended to place all the files related to a WebBox in a
separate folder, for better readability and structure of the
application.
- Never print anything from the PHP code, except maybe for
debug!
- Never construct HTML code in the PHP, put all the HTML in the
template instead!
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.
- The menu of pages now is implemented as a WebBox.
Have a look at its files. Notice that
menu.html does not include explicitly the JS and CSS code
of the menu (like templates) because it is done automatically
by the framework.
- Notice how are included several webboxes in
Page 2. To include a webbox we simply include the template
that contains the webbox (it is a template inclusion).
-
Study the different implementations of the tip webbox
and notice what is wrong with them (it is explained in the comments).
(Make sure that you select Code View in the file browser.)
- The application has defined a constant TIP_PATH in
config/const.Paths.php and then has used it in several
places, like in
tip.php,
fun.get_random_tip.php, etc.
This is better than hardcoding paths, because in case that you move
or rename this folder, you have to change just the value of a constant
and not every occurrence of the path.
- The framework outputs a wellcome message each time that you initiate
the application. This is done using the function
WebApp::message() in the file
init.php.
-
The application has also support for counting clicks and displaying
them, however it is optional. See how it is done:
config/const.Options.php,
init.php,
global.php.
- The constant COUNT_CLICKS is not a framework constant,
it is defined and used by the application.
- The functions WebApp::addSVar(),
WebApp::getSVar(),
WebApp::setSVar() are used to handle
state variables (or session variables,
or persistent variables). We will see more about state variables
later.
-
The files
init.php,
global.php, as well as
before_page.php and
after_page.php are optional.
- init.php
- This file is included by the framework only the first time that
the application is openned (at the beginning of the session).It may
be used to initialize any thing.
- global.php
- This file is included every time, if it exists. It may contain
functions, constants and variables that are used throughout the
whole application.
- before_page.php
- This file is included before each page is parsed.
- after_page.php
- This file is included after each page is constructed.
Browse also the
empty-sample
application.
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
- $ cd test/app2/templates
- Open the file
header.html and append the line:
<include src="{{#UP_PATH}}app3/templates/menu/menu.html" />
- 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
- $ cd test/app2/templates
- Open the file
header.html and append the line:
<Include src="{{#UP_PATH}}app3/templates/tip/tip.html" />
- Refresh the application app2 in browser. You will get an
error, because the TIP_PATH constant is unknown in
app2.
- 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.
- 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
- Refresh again the application. Finally it should be OK.
__FILE__ is a PHP constant and dirname() is a PHP
function.
3 - Enable counting
- Open the file
config/const.Options.php and set the constant
COUNT_CLICKS to true.
- 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
- Open the files
before_page.php and
after_page.php
and uncomment the print statements.
- Test the application and see what happens. Then comment them again.
5 - Modify the tip webbox
- 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().
- 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.