In this example we will create a custom zone to display information from the database. We will create a few pages in our website and have a full control of them. They won't be managed on "Menu management" tab. Our custom zone class will tell the system how much pages there are and what is their content.

Please read following articles before proceeding:

• ImpressPages zones and pages
• Hello world plugin example

Pages, automatically generated based on the data from the database.

Please download the source code and analyze it while reading this tutorial. Follow the instructions in readme.txt file on how to install this complete code and read the tutorial to understand how we have built it.

To display the records from the database we need to have them in the database. To ease this task we will use a plugin “AddressBook” from earlier example. This plugin creates a table in the database and Create / Read / Update / Delete functionality.

We already have "AddressBook" plugin installed. Now we need to create a new plugin that will register database records as pages on the system. We will call it "AddressBook zone". So we need to create a basic file structure for this plugin and install it. Follow the steps in "Hello world" plugin and replace "hello_world" with "address_book_zone".

"AddressBook" plugin supply the interface to manage database records. But we still don't have methods to access data from PHP. We will create db.php class in "Address book zone" plugin. This class has two methods:

• getContacts - get all records
• getContact - get one record by id

There is no update and delete functions because we will not do these actions using PHP.

We need two views:

• a list of all contacts
• information about one contact

We will create template class with two functions. One to display one record and other to display the list of the records.

In ImpressPages CMS all pages should extend general "Element" class. We will create "RootElement". It will be responsible to print the list of all records. Look at "Zone" class on how the "RootElement" class is used.

This class will generate the content of each record. In the same way as RootElement it also extends general "Element" class. See "Zone" class how it is used.

Zone class is the main and the most important file in this tutorial. Zone is the class that registers pages on the system. Each page is an object that extends general "Element" class. We have two such classes:

• RootElement - displays a list of records
• Element - displays one record

Our "Zone" class extends general "Zone" class and implements three functions:

• getElements - get an array of elements by specified criteria. Usually used to generate a menu.
• getElement - get an element by id
• findElement - find appropriate element by specified url and get variables

ImpressPages CMS core will execute these functions to gather the information about the pages in this zone.

Now we have a class "Zone" that gets information from the database, creates appropriate "Element" objects and supply that information to the website. But we need to tell the system to use this class. Login to administration panel, go to Developer -> Zones and press "New record". Fill in following information:

• Name - any name you like to give for this new zone
• Key - string which will be used in PHP code to address this zone (without special symbols)
• Template - choose template file (by default main.php)
• Associated module group - write "example"
• Associated module - write "address_book_zone"

This action registers this new "Zone" class. Now it can be used in our code. See bellow.

Open main.php file in your theme and add this line of code. Decide yourself where do you like to place it.

This code prints a link to root of our new zone.

When we press above generated link following steps are executed:

• ImpressPages is requested for a new page
• ImpressPages detects that requested URL belongs to zone "custom_zone"
• ImpressPages finds record "custom_zone" in zones list and look which module is associated to it (in this case examples/address_book_zone)
• ImpressPages creates object from the file examples/address_book_zone/zone.php and executes method findElement($urlVars, $getVars). This method returns appropriate page Object of class RootElement.
• system.php file in our plugin catches event when 'main' block of theme layout is geneated and prepopulates it with required data (this step is different in 1.x version).

That's how the list of database records appear on the screen:

The same workflow is executed when exact record is pressed. But in this case findElement function of zone returns Object of class Element instead of RootElement.

Please download the source code (at the beginning of this tutorial) and read the comments in it to find more details.