Php WebStarter

Project Setup

In order to use NetBeans effectively throughout the rest of the course you will need to install two NetBeans plugins (perhaps you've already done the Php plugin). From NetBeans,
  1. Select Tools ⇾ Plugins from the menus
  2. Click the Available Plugins tab, scroll down and check these names in the Php category:
    PHP
    Smarty Framework
    Then click the Install button.
Once you get going with Smarty, you may be inclined to alter the syntax colorization scheme. To access the color go to
Tools ⇾ Options (In MAC, NetBeans ⇾ Preferences)
Select the Fonts & Colors tab and choose Smarty Templates from the Language dropdown.

Installation

Download the source archive WebStarter.zip and install WebStarter as a Php from Existing Sources project into the directory corresponding to your /default URL.

At the next installation step, the Run Configuration, it will ask for the Project URL. Setting it to
http://localhost/default/PhpStarter/
will allow you to start up the project from the browser using the green run button.

Smarty Compile Cache

In order to achieve the speed of pure Php, Smarty compiles the templates used into Php files, but it needs a directory writable by the Web process to store these compiled files. Our initialization chooses the subdirectory:
app/cache
For deployment on a Windows machine, no further preparation is necessary, but on MAC or Linux systems, this chosen directory must explicitly be made accessible. The simplest approach is to make it world-writable by running this shell command from the WebStarter directory:
$ chmod 777 app/cache

Php Web Programs

Web database applications, like other User Interface applications can be split into our usual three parts: Model, View and Controller. When doing web programming with Php in the simplest sense, the Controller and View parts of a single web activation are usually merged into one file:
<?php

/* Controller: Php code */


?>
<!DOCTYPE html>
<html>

<!-- View:HTML mode with
Php variable embeddings -->


</html>
As indicated, the Controller part is exclusively Php code. This is where we should do the work of accessing the database and processing the results to create variables suitable for usage in the View section below where the simplest case of variable usage is of this form:
<?php echo $var ?>
with a scalar variable $var generated in the controller part. In many circumstances we need to pass an array variable, $array_var, in which case the usage may have this form:
<?php foreach( $array_var as $key => $value ): ?>
 ... <?php echo $key ?> ... <?php echo $value ?> ...
<?php endforeach ?>
A boolean variable $status generated in the controller is often used like this:
<?php if ( $status ): ?>
  ...
<?php endif ?>

Web Frameworks

There are two significant limitations to the simple single-file response generation mechanism which described above:
  1. The Controller-View separation is not at all enforced in any way and so Php scripts generated in this way need not follow the suggested approach.
  2. There is no obvious way to load separate common features to each page such as headers, navigation links and footers from the content which is different in each page.
A web framework addresses these two issues by allowing the Controller and View parts to be in separate files which are joined through some mechanism. It also provides some way to express a "page template" of common page features in which page-specific content can be embedded.

Smarty Templates

Our Php web page coding will employ the system:
Smarty Templates
which is a Php-based system creating a separate (but related) template language for usage within the View portion of a web response. When this system is employed, the controller and view parts are separate files hooked together by a Smarty-specific call, for example:

mypage.php
// Controller: just Php
$var = /* something */;
$data = [
    'var' => $var
];
$smarty->assign($data);
$smarty->display("mypage.tpl");

mypage.tpl
<!-- 
View template script: 
HTML with Smarty-specific 
code insertions.
-->
You sent me {$var}
 
This simplistic usage just barely touches the surface of what Smarty can do. The most significant feature for the sake of this starter program is to provide a mechanism whereby the common features of each page can be expressed in a layout in which every template inserts its page-specific content. For example:

mypage.tpl
{extends file="layout.tpl"}
 
{block name="content"}
<!-- View: HTML with
Smarty-specific insertions.
-->
You sent me {$var}
{/block}
 

layout.tpl
<!DOCTYPE html>
<html>
...
<body>
...
{block name="content"}{/block}
...
</body>
</html>
In this case, when mypage.tpl template is rendered, it sees the extends usage and assumes its content to be sections delimited by named blocks. These blocks are meant to be embedded within the layout.tpl file which provides a common page structure.

Structure of the WebStarter project

This document develops a web application meant to be the starting point for creating other Php/Smarty web applications. It present starter pages created from Php controller files with Php includes, Smarty view templates, CSS stylesheets and image files. This web app uses BootStrap (v. 3.3.7) to build in responsiveness suitable for smartphones and tablets.

You can see some of the nascent Smarty template usage in the above examples. In particular expressions enclosed within {...} define Smarty features in the template (.tpl) files. Php variables are passed from the controller part to the Smarty view file and appear as Smarty expressions of the form {$var}.

Source Files

index.php       (website root page)
sample.php      (template for page creation)
templates/      (Smarty template folder)
  .htaccess     (Apache-specific deny folder access)
  index.tpl
  sample.tpl

Support files:

include/                (web-inaccessible include files)
  .htaccess             (Apache-specific deny folder access)
  session.php           (Session class)
  rb.php                (RedBeanPhp ORM file)
  smarty.php            (common Smarty inclusion)
  libs/                 (Smarty library files)
  myplugins/            (user-defined Smarty plugins)
css/                    (local CSS files)
  bootstrap.min.css     (bootstrap 3.3.7 CSS with small customization)
  layout.css            (customizations CSS)
js/                     (javascript files)
  bootstrap.min.js      (bootstrap 3.3.7 JavaScript)
  jquery.min.js         (jQuery 3.1.1 support)
img/                    (website images)
  header.png            (header image)
setup/                  (web-inaccessible Php command-line scripts)
  .htaccess             (Apache-specific deny folder access)
app/                    (web-inaccessible Php command-line scripts)
  .htaccess             (Apache-specific deny folder access)
  cache/                (Smarty Template Compilation)
The idea is that in a multi-page website, each new page starts out as a copy of sample.php/sample.tpl. The common basis, shared header and links files are established by layout.tpl

Web-inaccessible folders

The include directory holds files included by web-accessible scripts, but it should not be web-accessible. To prevent web access, we place the Apache-specific file within the directory:

.htaccess
deny from all
The same is done for the directories setup, app, and templates. If you attempt to access one of these hidden directories by keying in the URL directly, you'll get a "Forbidden" error message.

Smarty initialization

In order to engage Smarty templates, every Php file which uses them must do some initializations. The required steps are contained in this file:

include/smarty.php
<?php
require_once(__DIR__ . "/libs/Smarty.class.php");
$smarty = new Smarty();
$smarty->template_dir = realpath(__DIR__ . "/../templates");
$smarty->compile_dir = realpath(__DIR__ . "/../app/cache");
$smarty->addPluginsDir(__DIR__ . '/myplugins');
 
require_once __DIR__ . "/session.php";
 
$smarty->assign('session', $session);
The Php controller files (at the top directory level) engage Smarty by simply including this file:
require_once "include/smarty.php";
The Php statements dictate: These directories all have absolute paths so that a Php script held within a subdirectory should still be able to achieve the Smarty initializations.

Layout Features

Here is the layout template file used along with included links:
template/layout.tpl  
template/links.tpl  
The included file links.tpl, used within layout.tpl, is based on an HTML unordered list. The bootstrap styles render the unordered lists into navigational placement.

Sample pages

The sample page files based on the layout template are these:

index.php
<?php
require_once "include/smarty.php";
 
$data = [
];
$smarty->assign($data);
$smarty->display("index.tpl");

sample.php
<?php
require_once "include/smarty.php";
 
$data = [
  'page_title' => 'Sample',
];
$smarty->assign($data);
$smarty->display("sample.tpl");

templates/index.tpl
{extends file="layout.tpl"}
 
{block name="content"}
<h2>Home</h2>
 
{/block}

templates/sample.tpl
{extends file="layout.tpl"}
 
{block name="localstyle"}
{/block}
 
{block name="content"}
<h2>Sample</h2>
 
{/block}

Bootstrap modifications

When you use BootStrap, a key issue is making it do something other than its default behavior. You can create a "customized" version of the BootStrap code by going to this site:
Customize and Download
The only customization I have done is to the CSS file in two places: With these alterations in place, go to the bottom of the page and click the huge button:

You download a zip archive bootstrap.zip. Expanded, the two files used are:
css/bootstrap.min.css
js/bootstrap.min.js
The other JavaScript file required is the jQuery file jquery.min.js gotten from here:
jQuery Download
The two JavaScript files are only there for menu support.

Additional style settings

Our key CSS layout file is:
css/layout.css  
This downloads New pages can be created by duplicating the two "sample" files and making changes. For the most part, additions and changes to the template are made within the "main" block and then making modifications to these files. Page-specific modifications to the CSS (via additional stylesheets or local style settings) can be made by creating a block within the template file:

sample.tpl
{extends file="layout.tpl"}
 
{block name="localstyle"}
...
{/block}
 
...
If you use a style section within this localstyle block, you have to be aware that Smarty is parsing it. In some cases you want the style code to be left alone, i.e., left as "literal." To achive this use the Smarty literal operator:

sample.tpl
{extends file="layout.tpl"}
 
{block name="localstyle"}
{literal}
<style type='text/css'>
  ....
</style>
{/literal}
{/block}
 
...

Smarty expression filters

Note the important Smarty expression syntax in layout.tpl:
{$page_title|default: basename(dirname($smarty.server.PHP_SELF))}
The variable $page_title is to be generated and passed in by the controller section. If you were to use the simpler form:
{$page_title}
then this variable would be required; Smarty would generate an error if not defined. The actual usage filters the expression through the default filter. The Smarty syntax "|" suggests the UNIX-style "pipe" which achieves an analogous effect in UNIX shell languages.

The actual usage means that if $page_title is undefined, then the expression becomes the value of
basename(dirname($smarty.server.PHP_SELF))
which is the name of the directory, i.e. "WebStarter" in this case. We could use this same filter without a default value:
{$page_title|default}
The outcome is that if $page_title is undefined, the value of the expression is empty.


© Robert M. Kline