My first website

1. Introduction

The present tutorial describes - based on the Basics - how to build a website with the Adventure PHP Framework. To make things easy the design of the example page is not too complex.

The website should provide space for a key visual, a header, a menu and an area where content and footer can be placed. The content view should be filled with dynamic content dependent on the request parameters given. The site should have the following appearance:

3. Installation and configuration

The author assumes that you have downloaded the code pack on the Downloads page. These packages are named like apf-codepack-*.[zip | tar.gz | tar.bz2]. They only contain the basic libraries of the framework, the structure of a web project and the configuration files must be added by oneself.

To start the creation your first web project the code pack must be extracted in the document root of your local webserver installation. To have a basis for discussion this folder should be named apps/. For clearness reasons this folder should be created in the folder testwebsite/ that directly exists under the document root.

As a second step the structure of the website and the configuration files necessary must be created. Please refer to the Basics chapter for more details. This task is now done step-by-step in the next chapters.

3.1. Folder structure of the web page

The structure of the program of the web page should be hosted in the following folders created under testwebsite/apps/:

Code

sites/
      testwebsite/
                  pres/
                       templates/
                       documentcontroller/

The folders templates and documentcontroller are intended to be filled with the template and controller files responsible for the generation of the page.

3.2. Create bootstrap file

The framework is designed to deliver any web application with just one file - the bootstrap file. For this reason we have to create such a file in the testwebsite/ folder. The content of that file can merely be copied from the code box provided below. To keep things simple again the application will be designed as a page controller application without front controller parts.

PHP-Code

// include the page controller (APF core library)
include_once('./apps/core/pagecontroller/pagecontroller.php');

// include the front controller
import('core::frontcontroller', 'Frontcontroller');

// create and configure front controller
$fC = &Singleton::getInstance('Frontcontroller');
$fC->setContext('projectone');

// start request processing and send result to the client
echo $fC->start('sites::testwebsite::pres::templates', 'website');

3.3. Create template files

As already defined within the code listing the initial template file must be stored in the testwebsite/apps/sites/testwebsite/pres/templates folder and named website.html. This file contains the basic HTML code that defines the HTML body and the views described in chapter 2. The file may have the following content (stripped-down):

Html-Code

<html>
<head>
  <title>TestWebSite</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <style type="text/css">
    [..]
  </style>
</head>
<body>
  <center>
    <table width="800" border="0" cellpadding="0" cellspacing="0" class="table_layout">
      <tr>
        <td class="table_keyvisual">
          K e y
          <br />
          V i s
          <br />
          u a l
         </td>
        <td class="table_header">
          Header
        </td>
      </tr>
      <tr>
        <td class="table_menu">
          <br />
          Home
          <br />
          Impress
        </td>
        <td class="table_content">
          Content
        </td>
      </tr>
    </table>
  </center>
</body>
</html>

Now we can test the project starting our locally installed webserver (e.g. XAMPP or APACHE of IIS with the PHP 4 or PHP 5 module loaded) and requesting the URL

Code

http://localhost/testwebsite/

by any type of browser. The website printed above must be displayed there.

4. Creating dynamic views

To add more flexibility in administrating the page the central views like header, menu and content area are now spinned off into seperate template files. To show this parts of the page they are included on the place they have to be displayed. For that purpose three template files will be created in the folder testwebsite/apps/sites/testwebsite/pres/templates:

header.html: Content of the headers
menu.html: Content of the menu
content.html: Content of the website

Now the cetral template file website.html must be changed as described below:

Html-Code

<html>
<head>
  <title>TestWebSite</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <style type="text/css">
    [..]
  </style>
</head>
<body>
  <center>
    <table width="800" border="0" cellpadding="0" cellspacing="0" class="table_layout">
      <tr>
        <td class="table_keyvisual">
          K e y
          <br />
          V i s
          <br />
          u a l
        </td>
        <td class="table_header">
          <core:importdesign
            namespace="sites::testwebsite::pres::templates"
            template="header"
          />
        </td>
      </tr>
      <tr>
        <td class="table_menu">
          <core:importdesign
            namespace="sites::testwebsite::pres::templates"
            template="menu"
          />
        </td>
        <td class="table_content">
          <core:importdesign
            namespace="sites::testwebsite::pres::templates"
            template="content"
          />
        </td>
      </tr>
    </table>
  </center>
</body>
</html>

To gain insight to the usage of the <core:importdesign /> please have a look at the Standard taglibs at chapter 1.2. The newly created template files must have the following content:

header.html:

APF-Template

Header

menu.html:

APF-Template

<br />
  Home
  <br />
  Impress

content.html:

APF-Template

Content

With this step all necessary preparations are done to be able to maintain central content. Another F5 to

Code

http://localhost/testwebsite/

should display the same site described in chapter 3.4.

5. Dynamic content

Now building up on the separation of a web page into single views described in chapter 4, this section points out the way of displaying dynamic content in the content view. Therefore the content to be displayed should be controllable through the URL parameter Page.

To generate the behaviour described above the menu view must be updated to indicate which page has to be displayed. The code could look like this:

menu.html:

APF-Template

<br />
<a href="./?Page=Home">Home</a>
<br />
<a href="./?Page=Impress">Impress</a>

Clicking in the navigation nodes the bootstrap file (index.php) is called including the URL parameter Page. To render dynamic content two methods are available out-of-the-box:

5.1. Content from text files

A straight-forward way of displaying dynamic content from text files is to use the <doc:createobject /> taglib described in the Standard taglibs in chapter 3.1. This taglib must be configured to meet the requirements depicted above. The library expects the text files countaining the contents to be located in language dependent files within the ./frontend/content/ folder that exists in parallel to the bootstrap file. Assuming that the content should be displayed in english language the files

./frontend/content/c_en_home.html
./frontend/content/c_en_impress.html

must be created. Due to the fact, that the content wants to be displayed in the content view the file content.html must be changed to

APF-Template

<core:addtaglib
   namespace="tools::html::taglib"
   class="CreateDocumentFromFileTag"
   prefix="doc"
   name="createobject"
/>
<doc:createobject requestparam="Page" defaultvalue="Home" />

The taglib class expects the file names in lower letters only. On Windows machines other spellings don't matter, but operating the application on LINUX-link operating systems, the desired file cannot be found.

5.2. Content from a database

Another possibility is to read content from a database table and integrate it into the content view. To achieve this the developer can make use of a document controller that reads and displays the content.

For a start a database table must be created to store the content. The following SQL statement may be used to create such a table:

APF-Template

CREATE TABLE demopage_content (
  PageID tinyint(5) NOT NULL auto_increment,
  PageURLName varchar(50) NOT NULL default '',
  PageTitle varchar(50) NOT NULL default '',
  PageContent text NOT NULL,
  PRIMARY KEY (PageID),
  UNIQUE KEY PageURLName (PageURLName),
  KEY PageTitle (PageTitle)
) ENGINE=MyISAM;

As mentioned under section 5.1 the content view template (content.html) must be adapted as follows:

APF-Template

<@controller
   namespace="sites::testwebsite::pres::documentcontroller"
   class="content_v1_controller"
@>

This XML tag defines a document controller for the current DOM node. This controller is mentioned to be a MVC-pattern-style (Document-)Controller to the current node. The class itself inherits from BaseDocumentController that is a standardized interface class to all document controller containing important methods to generate dynamic content during transformation of a DOM node.

Since the content is read from a database (here: MySQL), the component ConnectionManager is being used. The controller class contained in

Code

testwebsite/apps/sites/testwebsite/pres/documentcontroller/content_v1_controller.php

should be filled with the following code:

PHP-Code

import('tools::request', 'RequestHandler');

class content_v1_controller extends BaseDocumentController {

   public function transformContent(){

      $cM = &$this->getServiceObject('core::database','ConnectionManager');
      $SQL = &$cM->getConnection('content-database');

      // define the URL parameter
      $page = RequestHandler::getValue('Page','Home');

      // escape value to avoid SQL injections
      $page = $SQL->escapeValue($page);

      // select content from the desired table
      $select = 'SELECT PageContent
                 FROM demopage_content
                 WHERE PageURLName = \''.$page.'\'
                 LIMIT 1';
      $result = $SQL->executeTextStatement($select);
      $data = $SQL->fetchData($result);

      // insert content to the current node
      $this->setContent($data['PageContent']);

   }

}

The source code of the controller class should be self-explanatory. In general the functionality included there only fetches content from a database and displays the content found there.

In order to access the database the connection manager expects the configuration file under

Code

testwebsite/apps/config/core/database/projectone/DEFAULT_connections.ini

The name of the file is constructed by the path

Code

testwebsite/apps/config/core/database/{CONTEXT}/

and the name

Code

{ENVIRONMENT}_connections.ini

Please note, the {CONTEXT} is the application's context configured within the bootstrap file above (projectone). Details on configuration can be taken from the Configuration chapter.

The content of the file must be adapted to the current machine, but must contain the following content:

APF-Konfiguration

[content-database]
DB.Host = "" ; Server name or IP address of the database
DB.User = "" ; User
DB.Pass = "" ; Password
DB.Name = "" ; Name of the database
DB.Type = "MySQLx"
[DB.DebugMode = "true|false"
DB.Charset = "utf8"
DB.Collation = "utf8_general_ci"]

6. Conclusion

The present tutorial described how to create a web page using the Adventure PHP Framework and display dynamic content from files or a database table. A deficiency of the implementing still lies in the fact that it is not checked whether contents really exist in the database. In the case of the solution discussed in chapter 5.2 a blank content page is displayed containing no error message if no content is available. By use of the file variation this is already implemented in the taglib.

Moreover the chapter 5.2 solution lacks of the possibility to create, maintain and delete contents. This task can only be handled with database administration tools like PHPMyAdmin or a tool created for this task separately.

To keep things simple the controller source code this tutorial was not implemented in the three tier architecture merely used in object orientated applications. This would have increased the degree of complexity by the need to introduce a business and database layer to the application. The business layer normally returns so called domain objects to the presentation layer and takes care of situations where no content can be displayed. To complete the architecture discussion the business layer makes use of the database layer of the application to gather the database content. Within the database layer the database component utilizes the ConnectionManager class to have a generic database abstraction layer. More suggestions on this topic can be found in the tutorials

7. Source code downloads

The source code provided in the present tutorial can be downloaded using the file tutorial_testwebsite.zip. The framework's core libraries are not included but can be obtained on the Downloads page.

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.

There are no comments belonging to this article.

My first website

1. Introduction

2. Requirements

3. Installation and configuration

3.1. Folder structure of the web page

3.2. Create bootstrap file

3.3. Create template files

4. Creating dynamic views

5. Dynamic content

5.1. Content from text files

5.2. Content from a database

6. Conclusion

7. Source code downloads

Comments

QUICKNAVI