My first website

1. Introduction

The Adventure PHP Framework understands itself as a tool to create web pages and web applications. This tutorial shows you how to create dynamic web pages efficiently. It is based in chapters Basics, Hello World! and Download, installation and first steps which are recommended to read prior working through this chapter.

2. Requirements

To be able to walk you through this tutorial using a real-life sample let us briefly define the requirements of the web page to build.

The page should consist of three areas:

  • Header: The header area contains the logo of the page and the main navigation. Navigation may contain any number of items but limited to the space designers reserved for this purpose.
  • Content area: This area takes 100% of the page's width and has variable height containing the main content of the page..
  • Footer: The lower area of the page is dedicated to common content and links (e.g. impress). Content is identical for all pages.

Location and view of the above described areas should be as outlined within the following wireframe:

Tutorial: My first website with the Adventure PHP Framework

Logo and Navigation are placed side-by-side in the header area. Content and footer area both take 100% of the width available but are placed one-above-the-other. At least they take a minimum height of the contained content.

This tutorial focuses on the technical implementation of web pages with the APF. Details on creating and using CSS is consciously excluded.

3. The basis

To create a website with the APF a few basic configurations are necessary. This includes the installation and configuration of the framework as well as creating the structure of folders and namespaces. The subsequent chapters walk you through the basic setup step-by-step to quickly get to creating your web page.

3.1. Installation and configuration

Please create a new project with an IDE of your choice (the APF Team recommends PHPStorm). Based on the suggestions in chapter Download, installation and first steps please create the following basic folder structure:

Code
/APF /htdocs /images /css /js

APF will be used for the installation of the framework and is not HTTP-accessible due to security reasons. htdocs contains all resources that should be accessible from the outside like out bootstrap file, images, CSS and Java-Script files.

Installing the Adventure PHP Framework means downloading a apf-codepack-* and apf-configpack-* from Downloads and extracting the content to the APF folder. The above folder structure thus extends itself as follows:

Code
/APF /config /core /extensions /modules /tools /htdocs /images /css /js

The config folder contains sample configuration files that we will use later on. All other folders contain the code base of the framework.

3.2. Creating the application structure

Similar to the folder structure of the APF code base we are now creating a separate area to store the code files of our web page. The folder structure is thus extended as follows:

Code
/APF /config /core /extensions /modules /tools /PAGE /htdocs /images /css /js

Folder PAGE now takes all code files we will create during the following chapters. Chapter Class loading describes how you can separate framework components from your custom application code. To do so we now define a custom Vendor named PAGE having an own StandardClassLoader configured. The class loader then refers to the /PAGE directory instead of /APF.

Within the application we'll also create templates and controllers within the following chapters. For this reason, let's complete the folder structure as follows:

Code
/APF /config /core /extensions /modules /tools /PAGE /controller /templates /htdocs /images /css /js

3.3. Creating the bootstrap file

The APF has been designed to work with one central bootstrap file that handles all incoming requests. This not only eases implementation but also provides exactly one entry point to your application that can be secured accordingly.

A template of a simple index.php is described under Basics. For a start, we copy and paste the content to a newly created index.php file in htdocs:

PHP code
include('../APF/core/bootstrap.php'); use APF\core\singleton\Singleton; use APF\core\frontcontroller\Frontcontroller; $fC = Singleton::getInstance(Frontcontroller::class); echo $fC->start('...', '...');

By default, a ClassLoader for vendor APF is registered. Due to the fact that we intend to separate framework code from application code it is required to configure an additional class loader for vendor PAGE with an appropriate configuration:

PHP code
include('../APF/core/bootstrap.php'); use APF\core\loader\RootClassLoader; use APF\core\loader\StandardClassLoader; $classLoader = new StandardClassLoader('PAGE', '../PAGE'); RootClassLoader::addLoader($classLoader); use APF\core\singleton\Singleton; use APF\core\frontcontroller\Frontcontroller; $fC = Singleton::getInstance(Frontcontroller::class); echo $fC->start('...', '...');

As described in chapter Class loading you can not only separate code registering a custom ClassLoader but also configuration. Please note hints on using this within the following chapters.

3.4. Creating the master template

As a last step of the basic configuration we have to create a master template that acts as an entry point to our application. Thus, please create main.html within folder /PAGE/templates. You may initially fill the file with any kind of text content but this is not necessary.

Our index.php file now is extended as follows:

PHP code
include('../APF/core/bootstrap.php'); use APF\core\loader\RootClassLoader; use APF\core\loader\StandardClassLoader; $classLoader = new StandardClassLoader('PAGE', '../PAGE'); RootClassLoader::addLoader($classLoader); use APF\core\singleton\Singleton; use APF\core\frontcontroller\Frontcontroller; $fC = Singleton::getInstance(Frontcontroller::class); echo $fC->start('PAGE\templates', 'main');

Calling the bootstrap file within your browser you either see a blank page or the content you've entered to the master template. Basic installation and configuration is now finished.

4. Creating the web page structure

According to the requirements described in chapter 2 the web page consists of three areas: header, content area and footer. Within the following chapter we now create the necessary templates and contents in a step-by-step fashion.

4.1. Basic template

The basic template main.html is considered a central entry point for your application but also contains the basic structure of your web page or application. For this reason, we now fill the file with the basic HTML structure for the above noted areas:

APF template
<!DOCTYPE html> <html> <head> <title>My Web Page</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="/css/styles.css" /> <script type="text/javascript" src="/js/scripts.js"></script> </head> <body> <header> <img src="/images/header-logo.png" alt="My Web Page" /> <nav> ... </nav> </header> <section id="content"> ... </section> <footer> ... </footer> </body> </html>

Within the <nav /> tag the main navigation should be presented, <section id="content"/> contains the content of the page and <footer /> is supposed to shows the footer.

The following chapters now fill these areas with the appropriate content. Creating the basic template is now done.

4.2. URL structure

After creating the master template it is recommended to decide which URL structure should be used for your project. This for instance implies how dynamic pages are addressed to be shown within the content area or how navigational elements are built.

In order to keep this tutorial simple and clear, the following chapters only dela with displaying dynamic content. This can be done easily by a dedicated URL parameter that contains the unique identifier of the desired page. Therefor we will use the page parameter. In case it is present, the page referred to by it's value should be displayed. If not present, the start page will be shown.

The structure described within the last paragraph is used to display dynamic content within the content area. To keep this tutorial simple the standard URL layout will be used that is fully supported by the APF. Details can be taken from chapter URL rewriting).

4.3. Header

The upper area of the page - the header - contains the logo of the page and the navigation. The latter one is provided to visitors to reach the different pages of the web site.

To ease future enhancement of the page the navigation should be extracted to a separate template. For this reason, we add the following tag to the <nav /> block of the master template:

APF template
<core:importdesign namespace="PAGE\templates" template="navi" />

The <core:importdesign /> tag expects the navi.html file to be located under /PAGE/templates containing the content of the navigation. The file itself will be filled with a static navigation:

APF template
<ul> <li><a href="/">Home</a></li> <li><a href="/?page=page1">Page 1</a></li> <li><a href="/?page=page2">Page 2</a></li> <li><a href="/?page=page3">Page 3</a></li> </ul>

Clicking the first element the user is presented the start page. All other links lead to dedicated pages. As a unique identifier alphanumeric values have been taken but you are free to choose different kind of values as desired.

Within the lower area of the page generic content is displayed and for instance a link to the impress of the page. As for the Header also this content should be extracted to a separate template.

For this reason, we add the following tag to the <<footer /> block of the master template:

APF template
<core:importdesign namespace="PAGE\templates" template="footer" />

The <core:importdesign /> tag expects the footer.html file to be located under /PAGE/templates containing the content of the footer. The file itself will be filled with a static content as follows:

APF template
<p> ... </p> <nav> <ul> <li><a href="/?page=impress">Impress</a></li> <li><a href="/?page=contact">Contact</a></li> </ul> </nav>

The text denoted within the <p /> tags is meant to contain general information about the page. The below navigation refers to legally compulsive pages such as the impress or offers the possibility to contact the site owner.

4.5. Content area

Let us now focus on the content area of the page. Display of the content should also be realized by a separate template as done within all other previous chapters. This is because changes only affect the basic template and extracted functionality can easily be re-used.

To display content within the main area please create template file content.html under /PAGE/templates and fill with any kind of content.

The master template now is added the following lines within the <section /> tag:

APF template
<core:importdesign namespace="PAGE\templates" template="content" />

Creating the web page structure is now done. Chapter 5 describes different possibilities to display content.

5. Display dynamic content

Chapter 4 described creating the basic structure of the page as well as the URL layout. Based on these chapters we are now able to display dynamic content of the website.

The two following chapters contain two different implementations: content from simple text files and from an external data source.

5.1. Content from text files

A very simple way to display dynamic content from text files within the content area of a page is to use the <core:importdesign /> tag. It supports to determine the name of the template via URL parameter.

In order to leverage from this existing functionality please fill /PAGE/templates/content.html with the following content:

APF template
<core:importdesign namespace="PAGE\content" template="[page=start]" incparam="page" />

The tag definition already tells details about the setup: the dynamic content is expected to reside under /PAGE/content and the URL parameter to determine the page template name is page as described in chapter 4.2.

To display content please generate folder /PAGE/content and create three files named start.html (see navigation from chapter 4.3) and impress.html as well as contact.html (see navigation from chapter 4.4). You can now fill them with the desired content.

Due to the fact that <core:importdesign /> both supports text as well as HTML/XML you can create static and dynamic content. Moreover, you may want to use APF tags or (Document-)Controller declarations.

5.2. Content from the database

Another option displaying content is using a data source. For this reason we want to use a simple database table that stores a unique identifier and the content of the page.

The table can be created using the following SQL statement:

APF template
CREATE TABLE pages ( page_id varchar(10) NOT NULL, page_content text NOT NULL, PRIMARY KEY (page_id) );

To display the content stored within the above table please adapt file content.html located in /PAGE/templates:

APF template
<@controller class="PAGE\controller\ContentController" @>

The <@controller /> tag refers to a (Document-)Controller that is assigned to process the template or the DOM node respectively. A simple implementation can be found within the following code box:

PHP code
namespace PAGE\controller; use APF\core\pagecontroller\BaseDocumentController; use APF\core\database\ConnectionManager; use APF\core\database\DatabaseConnection; class ContentController extends BaseDocumentController { public function transformContent() { $conn = $this->getConnection(); $pageId = $conn->escapeValue( $this->getRequest()->getGetParameter('page', 'home') ); $select = 'SELECT page_content FROM pages WHERE page_id = \'' . $pageId . '\' LIMIT 1'; $result = $conn->executeTextStatement($select); $data = $conn->fetchData($result); if($data !== false){ $this->getDocument()->setContent($data['page_content']); } } /** * @return DatabaseConnection */ private function getConnection() { /* @var $cM ConnectionManager */ $cM = & $this->getServiceObject('APF\core\database\ConnectionManager'); return $cM->getConnection('content-database'); } }
Please note that a database configuration must be created for the desired database prior to usage of the controller. Details on usage and configuration of database connections with the APF can be read about in chapter ConnectionManager.

6. Further reading

Having finished with this tutorial it is recommended to proceed as follows to get familiar with the APF:

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.