Introduction

Purpose

This document explains how to create sites quickly and easily by using the N+ technology.

N+ requirements

A site which uses N+ Site Builder has the following requirements:

1. The web server must be Apache 1.3.9 or later. The Apache module PHP 4.0.3pl1-0 (or later) must be installed.
2. An SQL database must be installed on the computer. Actually, the system is tested on MySQL 3.23.32, but it's free to use any SQL-92 compilant database server.
3. The recommended operating system is Linux, Debian distribution (Potato).

Setting up an N+ site

This is a short overview on setting up a site using the N+ technology.

Environment

There must be a server with Apache/PHP4 and a SQL server installed on it.

Database

Create a Site Config file (XML). The N+ Builder can construct an SQL script from it. Executing this script on the SQL database server will create all the databases the N+ site requires.

The final version of the N+ Builder will contain an easy-to-use user interface to do this job.

Pages

Create some Master HTML files (and if you want, some Jewelmine HTML files) with your favourite HTML editor. Put N+ markup language tags into your HTML code in order to define boxes, items, conditions etc.

Start N+ Builder. Open a project and organize your HTML files into pages. Fill the page parameters, session informations, etc.

Press the "compile" button when you are ready. As a result you get one PHP script for each page. If you run these PHP scripts, the same HTML outputs will appear, which were loaded into the N+ Builder.

Engine Scripts

Create your engine scripts. You should write one PHP script for each page. A script may have one engine function for each page, box or item.

To access database (document), URL parameter and session handling functions, use the functions and objects of the N+ PHP library.

If you redesign a modul's HTML file - using the same box and variable names, etc. - the pre-written PHP engine script can be used.

N+ system architecture

Basics

The "natural" unit of web-programming is the page. When the visitor invokes an HTTP request by clicking on a link (or selecting a bookmark, typing a URL, submitting a form etc.), the server's response is a HTML page. In case of dynamic content a program is executed, which creates the HTML file, that is sent back to the visitor by the webserver.

In case of N+, a page basically means the PHP script, which is created by N+ Builder. The following elements are needed to build a page:

• The master HTML file,
• Jewelmine HTML files (optional),
• Page parameters,
• Page includes (references to engine PHP scripts).

The page will follow the structure of the master HTML file.

The base unit of the page is the box. There are three kind of boxes:

• page,
• box,
• item.

There must be one "page" type box defined for each page. In other words, a box defined as "page" is the page itself.

The item is a box which the PHP code will render out in run-time as many times as there are data items available. It is possible to design items which have different even/odd design.

When talking about boxes we mean all three types. (Differences coming from items will be remarked.)

The generated PHP code

A PHP code is generated for each page based on the master HTML file.

The first part of the code are the box functions. Executing a box function will print out its content. If a box contains another box, it will print out the inner box by simply calling it. Calling the main box (the first "page" type box) will print out the whole page. The box functions contain all the HTML codes.

Each box having any variables defined has a data provider routine. The data provider routine returns an array, which contains all the values of the variables defined in the box. Entering the box, it checks if this routine exists, and then calls it. A box without data provider function fills the variables with default values in order to be able to show something even without engine script.

In the PHP script, at the place of a variable, there will be a piece of code which prints out (or, if it's an object, renders out by calling a method) the appropiate element of the variable array.

The next part of the generated code is the startup code and the class definitions. All that are required for later usage (e.g. data provider functions may use the global URL object prepared here).

The "operative" part of the code comes last. First, the initializer routine (which is in the engine script) is loaded. The initializer routine should open databases, check the URL variables, etc. If a problem occurs, it can even perform a HTTP redirect. After this, there is a call to the main box (page) function in order to print out the whole page. Finally, a call comes to the cleanup routine (it's also in the engine script).

Box features

Boxes are defined by marking a part of the HTML code. Boxes are identified by their names; box names must be unique within a page. Box names should begin with a letter and may continue with lower case letters, numbers and underscore. The length of the name should be kept under 32 characters.

A box defined in the HTML file will turn to a PHP function, which: calls the engine function of the box for data, replaces variables with values, then prints out the content of the box.

The name of the box function will be prefixed by "box_" (or "page_", or "item_", depending on the type of the box). The engine function must have the same name as the box joined to "get_" prefix (if the box name is defined as "newsbx", then the data provider function must have the name "get_box_newsbx").

Boxes can be nested. If a box contains another box, the variables of the inner box will be filled by the data provider function of the inner box.

Boxes (only "box" type ones) can be replaced with other boxes usually defined in the jewelmine HTML file. The outer box (or page) will have a variable with the same name as the inner box if there is a list of the names of the alternative boxes at the box definition. The data provider function of the outer box can control the alternative boxes. It is also possible to turn off the box.

Designers often put sample texts and pictures into boxes in order to make it feel like a real page. These texts shouldn't appear in the PHP code so they should be commented out using N+ comments.

Item features

Item is a kind of box. The body of the box will be repeated as many times as many data items the data provider routine returns.

An item without any variables is meaningless, so it must contain at least one.

Designers usually replace items to see a typical page layout. These repeated items should be commented out (using N+ comment mark). They remain visible in the HTML code, but N+ will ignore them.

The value of the typical number of the iteration can be given at the item definition. This "default" value is only used by the generated PHP code when it runs without the engine. When running without the engine, the program will replace the item body with generated fake values, so the page will look real.

It is possible to define more than one layouts for an item by simply marking each part as if they were items (without naming them). The additional layouts must to have the same variables inside, because they have common engine function with the first one. For example, differently colored even and odd lines can be made using this feature.

Variables

The function of the variable is simple: the whole variable mark will be replaced by a data value provided by the engine function by returning a result array which contains all the values, where the index is the variable name. In case of an item, this array has another index, which is a continous number and starts from zero. The size of the array tells the generated PHP code how many times the item has to be printed out.

There is no limitation on the length or type of the data, but don't put any program-generated HTML code into a variable, if it's possible. Not only because it may crash the design, but it might also hurt the convention that all the design elements must be defined in the HTML files.

Variable names should begin with a letter and may be continued by lower case letters, numbers and underscore. The length of the name should be kept under 32 characters.

Variables can be placed anywhere in the HTML code, even into the middle of an HTML tag. The only rule is that variables must be inside a box, because the data provider function of the box is what fills the values.

Variable names must be unique within a box. If the same variable name is used within a box the same value will appear at each position.

It's possible to define a variable before the placing of it (using "ahead" mark), but only if it's inside an HTML tag. It's worth using when the variable definition inside the HTML tag would cause trouble (for example, if you put a variable definition into a "font" tag's "color" attribute, possibly it makes very hard to edit the HTML file). For details, see the syntax section.

Select object

While checkbox and radio buttons can be handled by putting variable definitions into the appropiate place in the HTML code, "select" (some HTML editors call it "popup") can't. N+ is using an object (called "Select") to solve this problem.

Without marking anything, the "select" HTML tag (including all the "option" tags inside) turns into PHP code, which creates and fills an object. The data provider function should modify the prepared object's state by calling its public methods. After this, the generated PHP code will render it out by calling a method for the object. The name of the variable will get the name of the "select" tag's "name" attribute with the "select_" prefix.

The data provider function can add and remove items, set the selected item, or change the name of the select (it's very useful inside an item type box). It can even create a whole new select. When entering the data provider function, the object will be in the same state as it was in the original design. If the data provider routine does not change it (only puts it into the result array), then the generated PHP code will render the same HTML code as it was in the HTML file.

URL object

The URL object is a simple tool for rendering proper URLs and for keeping and passing URL variables. Using URL object for rendering links is also necessary for the traffic tracking system.

Upon entering the generated code, a global object (called "params") will be created and will be filled with the appropriate parameters taken from the URL (you have to tell the N+ builder the parameter list of each page). This initial state of the global URL object can be restored by calling its "reset" method.

The initialization routine can add, modify and delete its variables, it can even reset its initial state in order to keep changes permanent and to avoid losing them at a next "reset" method call.

The "params" object contains all the variables which should be passed to another pages. It also has the information which pages using which parameters.

If a link is marked for generating the URL dynamically, it will be handled as a variable, and the data provider routine should copy the global URL object into the variable array. The mark should not only contain the name of the variable but the target URL as well.

First, the data provider routine has to reset the global URL object to its initial state, then modify any variables if necessary. Finally, it should copy the prepared object into the variable array. If the box contains more URLs, or if it's an item, the data provider routine may reset the object more times.

At the moment of rendering, all information is present for rendering out a proper URL in the (generated) box code. Basic variables are coming from the URL parameters, additional variables are set up by initialization and some variables are modified by the data provider routine of the box and finally, the target page is generated into the render method call. So, at run-time, the object can render the URL reference and the URL variables, but only those variables which are required by the target URL.

The data provider routine can also discard all variables of a URL, or it can change the target page, or it can change the whole URL by calling its methods.

The usage of the global URL is important because this object already contains information on tracking.

The URL object can be also used to render out a set of hidden variables. The place of the hidden variables must be marked with an N+ mark, which contains not only the target page reference, but the list of variables to be supressed, too. These variables does not have to be render this time, because they will come from user input form variables.

Condition

It's possible to mark a part of the HTML code, which is printed out only if the given conditions are true. The condition consists of a variable, a relational mark and a static value. The conditions must be inside a box. The value of the variable will be set by the data provider routine of the box.

All conditions will be evaluated as true, if the data provider routine is not present, even if they except each other in order to show the whole page design.

Conditions can contain boxes and other conditions.

Markup Language syntax

General marking

General mark:

General mark with comment:

Comment mark:

Commands

Page definition:

Box definition:

Box definition with alternative boxes:

Item definition:

The "count" attribute defines the number of default item repetition number.

Note: item must contain at least one variable.

Item definition with multiple layouts:

Note: the two item layouts must have the same variables.

Condition:

Variable definitions

General variable:

$varname$

Image location variable:

Note: "pic.gif" is used only to show the HTML properly. The whole "src" tag will be replaced with the value of the variable

Variable-ahead (example):

Font's color and size will be changed to "var1" and "var2".

URL:

URL variable:

Page name is optional.

Hidden variables:

"Page" and "supress" is optional.

Special:

Select:

Note: the whole select will be replaced by a Select object.

Coding conventions and object methods

Box data providing function

All the data providing functions should contain a startup and a cleanup routine. They are named:

• init()
• terminate()

The name of the data provider is "get_" followed by the box's name. The data provider function returns an array filled with the values required by the box. The indexes of the array are the names of the values.

Example box:

Data provider routine for example box:

Item differences:

The only difference for items that the return array has two indexes. The first index is a continous number from zero (the second is the variable name), so the size of the array tells how many times the item should be replaced.

Example item:

Data provider routine for example item:

Class Url

There are a global object called "$params" which holds all the variables. By calling its methods, you can set and get variables etc. (see method list).

Class Select

A "select" tag will generate a global Select object. You can add, modify, remove items (option) etc. by calling its methods. The name of the object takes the "name" attribute of the "select" tag, with a "select_" prefix.