PX:Basic Tutorial

From Peroxide

Introduction

This is a short and very basic introduction to the perOXide framework. I assume that you are familiar with the PHP programming language and have a PHP editor of your liking. The easiest way to program with perOXide is the peroxIDE but it is not required.

You should have a running perOXide installation on your development machine. See the Installation page for detailed installation instructions.

The framework concept

To make sure that you and I talk about the same thing let me first explain the main concept of perOXide. We do not try to reinvent the wheel here, so any web application as it concerns perOXide is just a series of pages that are interconnected to each other by using links or forms. perOXide does not enforce any special way of how you code your application, it simply provides a lot of functionality to make your life easier. There are five different types of files that perOXide recognizes:

Pages - what the name says, these are plain PHP pages that make up your application.
Snippets - reusable code snippets that are used within your application. The nOx component framework is simply a library of snippets.
Styles - any kind of server sided stylesheets. This can be XSLT stylesheets or nOx templates, or no styles at all if you decide to do your application in plain HTML - remember that perOXide is freedom of choice.
Resources - resources are XML files which contain internationalization information for your application. Of course you are free to not use resources at all if you don't need them.
External files - any kind of client sided files like CSS stylesheets, JavaScript files, images and more. These are not directly controlled by perOXide but perOXide can interact with them (e.g using the JavaScript integration of nOx).

perOXide project structure

Any perOXide project is always structured the same way on your harddisc, hence if you have seen one, you have seen all, which is a good thing.^[1] The typical layout is:

content - holds all project content
- pages - holds all pages
- snippets - holds project related snippets
- styles - holds templates and xslt stylesheets
- resources - holds internationalization files
- external - holds images, css files, javascript files etc.
cache - holds the cache and the error logs
SpawnConfig.php - the configuration file
Runner.php - the main entry point

Our first application

The first application would be a classical "Hello World!" however this would not quite show what you can do with perOXide. That's why we do something different here. Let us build a simple (and i mean a very simple) guestbook here. In its simplest form this would be a form where you can add a text plus a submit button that puts your text into a database.

Creating a page stub

Let's begin by creating a simple page within the pages subfolder of your perOXide installation. Name it guestbook.php and open it with an editor of your choice. Now fill in some html code for building up a simple submit form.

<html>
  <head><title>Simple guestbook</title></head>
  <body>
    <h1>Our guestbook</h1>
    <form method="post">
      <input type="hidden" name="filename" value="guestbook.php"/>
      <textarea name="content">Enter text here</textarea>
      <br/>
      <input type="submit" name="submitted" value="Submit"/>
    </form>
  </body>
</html>

This is pretty much straightforward, the form gets submitted back to the same page where it came from. To try this new page enter the following URL in your browser: http://[your server's name]/[path to perOXide]/Runner.php?filename=guestbook.php. This should show the form which can be submitted. Of course, nothing will happen yet.

Saving entries to database

Next step would be to save the submitted text to the database, so we can display it later on. And this is where the trouble usually starts. You would have to do the following steps:

create a table in your database
read the input from the request
make sure noone tries to inject SQL
create an insert statement with the data you got
connect to the database (maybe even in a way that not hardcodes the type of database you connect to)
fire your statement
close the resultset
close connection to database

The good news is, perOXide takes care of all steps except step 2. You just have to tell it how. perOXide abstracts all database access to an object model. Inside your application you only work with objects and never write a single line of SQL yourself. And here is, how.

Creating an object for saving the data

First off, you need to create a database object for the data you save. For our simple purpose, we probably only need the text that was entered to be saved inside the database. So create a new file named guestbookentry.php in the snippets folder of your perOXide installation. Fill in the following code:

<?php

includeEngine("DBObject.php"); // include perOXide's DBObject class

class GuestbookEntry extends DBObject {

    private $content;

    public function __construct() {
        // make sure that the parent constructor is called
        parent::__construct();
    }

    // this tells perOXide, how your table is built up
    public function tableDefinition() {
        return
        "content XL"; // we have one field named "content" of type XL (which is Text or Clob)
    }

    // setter function for setting the content
    public function setContent( $value ) {
        $this -> content = $value;
    }

    // getter function for getting the content
    public function getContent() {
        return $this -> content;
    }
}
?>

To make an object database aware you have to derive it from the DBObject class that is part of the perOXide framework. The sample code simply defines an object that contains one field named content which will hold the content of the guestbook entry. The tableDefinition function tells perOXide how our table will look like. The table field names directly correspond to the field names in our object. Finally there is a getter and setter function to access our private field from outside. If you use the peroxIDE you will find a getter/setter making tool as well as a DBObject wizard in there which helps you creating the tableDefinition() function. Pretty easy so far. And that's nearly all you need to write. Save that file and open up the page again so we can put this baby to good use.

Storing the data

From our request we got the contents of the text area. Now we just need to add code to the page which puts this into database.

<live>
includeSnippet("guestbookentry.php"); // includes our snippet

// check if the submit button was pressed
if ( isset($_REQUEST['submitted']) ) {
  // create a new entry
  $entry = new GuestbookEntry();
  // fill in the content from the request
  $entry -> setContent($_REQUEST['content']);
  // save the object to database
  $entry -> store();
}
</live>

The <live> tags telling perOXide's caching system that the code between them needs to be executed every time the page is requested. For now just think of them as a special way of writing <?php ... ?>, as we will cover the caching system later. First up, we need to include the class that we have just created. This is done by calling the includeSnippet function. You could have used a simple include or require to accomplish the same thing, however includeSnippet automatically looks up the file inside the configured snippets path of your peroxide installation. If you decide to change that path later, this is just a matter of configuration and you don't need to change any of your pages. Therefore it is always a good idea to use includeSnippet instead of the usual include or require functions. Next up, we check if the form was actually submitted, by checking if the request contains a submitted field. Then we create a new object of GuestbookEntry, write the content from the request into this object and call the store method of the GuestbookEntry object. This method is inherited from the DBObject class which we derived our GuestbookEntry class from. Calling store will cause perOXide to analyze the object, create an SQL insert or update statement and fire this statement to the database. Now open up your page again, enter some text and submit the form. You will get an error message similar to this:

guestbook.php: Error:
Error executing SQL:  SELECT count(*) AS thecount FROM peroxide_guestbookentry WHERE id= ? :
Table 'test2.peroxide_guestbookentry' doesn't exist
Severity:256
File:D:\devel\Peroxide\web\engine\SQLQuery.php at line 63

What went wrong? Well from the error message you can tell, that the database does not know the table we are trying to store our data in. Now didn't I promise that perOXide will take care of creating the table for us? Indeed it does, however you need to tell perOXide to do so.

Creating a setup page

We could put the table setup code right into the page we have just written, but then the table would be created everytime the page is called, which is most probably not what we want. So we should write a nice setup page that will create the table for us. Create a new page called setup.php and fill in the following code:

... put some nice html here ...

<live>
includeSnippet("guestbookentry.php");
$entry = new GuestbookEntry();
$entry -> createTable();
echo "Tables successfully created!";
</live>

... and some other nice html here ...

This looks quite similar to storing an object. Instead of calling the store method, we call createTable which will again cause perOXide to analyze that object and its tableDefinition function which provides information about how the class fields should be represented inside the database. Then perOXide will check, if the table exists in the database. If the table does not exist yet, perOXide will create the table. So now save your setup page and run it. This will create the missing table and make our guestbook work. Now let's try our guestbook page again. When you submit the form, it looks like nothing happens. Well actually we are saving the comment in the database, but since we do not display any of the comments on that page, it looks like nothing happens. So now we have to read all the items from the database and display them on our page, so our guestbook is actually becoming a guestbook.

Reading from database

Reading entries from the database is just as easy as writing them to the database. Let's add some code which will read the entries and outputs some HTML table to our guestbook.php.

...
<live>
  includeSnippet("guestbookentry.php");
  $entry = new GuestbookEntry();
  // load all entries from the database
  $allEntries = $entry -> qbe();

  echo '<table width="100%">';
  foreach( $allEntries as $entry ) {
  echo '<tr><td>'.$entry -> getContent().'</td></tr>';
  }
  echo '</table>';
</live>
...

Again this is working quite the same way as storing an object to the database. We simply have to create an object instance of the type we want (in our case the GuestbookEntry) type) and then call the qbe function on that object instance. The qbe function does a so-called query by example, meaning it takes the GuestbookEntry object that you are calling this function upon as an example and searches objects which are similar to your example object. Since we didn't set up anything on the object before calling qbe the function will simply return all objects of that type that are located in the database as an array of objects. In the foreach loop we then iterate these objects and create a table with the contents that have been submitted.

Wrap-Up

So far, we have created a very simple guestbook using perOXide. This tutorial showed:

How a perOXide project is built up.
What pages, snippets, resources, styles and external files are.
How and where to create pages and snippets.
Why you should use the includeSnippet function to include snippets.
How to create a database object.
How to instruct perOXide to create a database table.
How to read and write objects from and to the database.

As you might have noticed, this guest book currently leaves much to be desired. The HTML is hard coded into the pages, there could be more fields like a submit date and the name of the poster, the comments list could be paged, there is no facility to edit or delete entries and much more. We will tackle most of this in the Core Features Tutorial, so this is where you should go next.

Got Questions or Feedback? Send a mail to feedback@peroxideframework.org!

[1]

PX:Basic Tutorial

From Peroxide

Contents

Introduction

The framework concept

perOXide project structure

Our first application

Creating a page stub

Saving entries to database

Creating an object for saving the data

Storing the data

Creating a setup page

Reading from database

Wrap-Up

Views

Personal tools

Navigation

Search

Toolbox