Location: PHPKode > projects > v-creator > v-creator_1.3-pre3/doc/quick-start-guide.txt
											Quick Start Guide to v-creator v1.3

Copyright (c) 2003 gencon Ltd, all rights reserved.

This file is part of v-creator.

v-creator is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

v-creator is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


This document is intended to provide an introduction to v-creator version 1.0
and it's capabilities. While not a complete treatment of everything v-creator
it should serve as a starting point for those who wish to use v-creator.

About v-creator

v-creator has been designed with a number of goals in mind. The main goal is to
accelerate development of websites for the Internet, intranets and extranets.
It accomplishes this through the use of reusable, tested code in the form of
code modules, reusable sections of HTML  and by providing a consistent
framework to work within. It separates out the presentation HTML from the logic
provided by the PHP code and implements a vary small, simple tag language to
'glue' the HTML and PHP together. 

v-creator can be used to automatically provide basic services required by most
projects including: security, content internationalisation and database
integration. This allows developers to concentrate on the problem at hand
rather than the repetitive low level tasks.

When working with v-creator great freedom is still given to designers and
developers. They can use their normal set of preferred tools to get their job
done and due to the separating of HTML and PHP not tread on each others toes.


Installing v-creator is very simple. Download the current version as a gzipped
tar (.tgz) or zipped (.zip) archive and unpack the content into a directory
outside of the web server's document root. It is advisable though not required
to put it in a directory reflecting the version, for example v-creator_1_0 and
to then create a symlink to it, for example v-creator. There is no further
setup or configuration required for v-creator. All configuration is on a
per-project basis and configured within the project which will be discussed

However there are certain PHP modules that are required to be present:

	OpenSSL package which contains the openssl command line tool.	

	ImageMagick if the image module is to be used.

v-creator Basics

When using v-creator HTML pages are written as normal as is the PHP code.
However each are written independently to separate presentation from logic. To
get the HTML and PHP working together v-creator has a very small, simple tag
language consisting of 12 tags, a v-creator specific comment, an assignment tag
an alias tag and a tag to call functions. In order for a page containing
v-creator tags to be processed they are passed through a page driver. This is
an actual PHP page usually called pageDriver.php which is requested with the
page to process in the query string of the request. An example might be:


Here we have an HTML page called example.vchtml which we are passing to the
page driver to process the v-creator tags. As we will see later use is usually
made of Apache's URL rewriting so that we can represent this is a more elegant


v-creator Data Pool

Before discussing the v-creator tag language it is important to understand how
v-creator stores and passes data around between tags and to and from modules.
v-creator implements a data pool called VC_data which is an array implemented
in PHP. For simplicity we will just call it VC_data. A VC_data value is an
element from this pool. So if we say the VC_data element 'name' we are talking
about the array element $VC_data['name']. Data is then passed around by
storing, retrieving and modify data from this pool.

v-creator Modules

v-creator is designed to work with PHP 'modules'. Each module is simply a PHP
source file that contains a class definition. However there are two types of
modules: v-creator modules and user modules. v-creator modules are supplied
with v-creator as standard and are generally quite generic. user modules are
site or project specific.

v-creator Tag Language

The v-creator tag language has been designed for simplicity. It is intended as
a 'glue' between HTML pages and PHP code and not for heavy logic and processing
(Although some of the developers of v-creator may think otherwise and have a
tendency to use tags over PHP!).

Tags are written into the HTML files and appear as static text. This has the
advantage of not confusing different tools and editors designers of the HTML
may be using. The tags are written using '|{' and '}|' as delimiters.

Below is a simple example using the include tag, INCL,  to bring in a standard
head and footer which could be used on every page of a site:

			<h1>Sample page</h1>
				This is a simple example of a v-creator page.

Writing tags

v-creator tags have the general form:


It should be noted that the tag name should always be in uppercase and there
should be no spaces between the delimiters or either side of the colon. If two
or more tags are used together on the same line one of the separating pipes may
be dropped. For example the two lines that follow behave identically:

	|{TAG:argument}| |{TAG:argument}|

Tags may also be nested inside each other. As an example assume we have VC_data
element 'page' which contains 'header.html'. We can use this value in an
include tag by retrieving it using the TEXT tag:


Tags used for assignment, assigning one VC_data element the value of another,
have the form:


This would assign the value of 'source' to 'target'. A tag form is also
provided for aliasing variables:


This causes 'alias' to be an alias for 'var'. As an example assume we have two
modules. One of them uses 'user_id' and the other 'userid'. Frequently you
would find yourself swapping the values from one to the other with tags like:


Instead of this you can use:


Then whenever changes are made to 'user_id' 'userid' will refer to the same
value and vice versa.

To call a function from a module the same general form is used but the name of
the tag is that of the module and should not be all uppercase, it should follow
the name of the module:


For example to call the function 'autoLogin' implemented by the module user we
would write:


The last form of tag is a v-creator comment which has the form:

	|{<!-- comment -->}|

This can be used to comment v-creator tags, or to comment tags out. Both of
these uses are shown in this example:

	|{<!-- The follow include has been commented out -->}|
	|{<!-- INCL:header.html -->}|

So in total we have five forms of writing tags as summarised below:

	|{<!-- comment -->}|

12 Tags of v-creator

As previously stated v-creator only has 12 tags. These tags are summarised

Tag							Function
==============  ========

COND...CEND			Start and end a Conditional block.
DATA						Retrieve a VC_data raw value.
HIDE						Provides URL query string cloaking.
INCL						Includes another file.
LANG						Retrieves an internationalised message.
LOG							Writes a message to a log file.
LOOP...LEND			Start and end a repeated block.
SEC...SEND			Start and end a conditional block based on security checks.
TEXT						Retrieve a VC_data value with HTML entity translation.
URL							Redirection to a location.

COND (Condition) and CEND (Condition End) tags

The tags COND and CEND are used to mark the beginning and end of a conditional
block of HTML or v-creator tags. Their general form is:


Where var is a VC_data element to be tested to see if it is TRUE. A value can
be tested for FALSE by including an exclamation mark before it:

Note that value is determined as being TRUE or FALSE based on the usual rules
for PHP. If the test fails processing jumps to the ending CEND tag and the
lines skipped over are not processed, if tags, and not included in the rendered
HTML page. Below is an example of using COND and CEND:

				<p>You are logged in.</p>
				<p>Please log in.</p>

This example first calls the function getUserId provided by the standard module
user. The function sets the VC_data element user_id to the ID of the user or
zero if the user is not logged in. We then test user_id to see if it is TRUE in
which case 'You are logged in.' is displayed. If not we jump to the matching
CEND on line 4. We then test to see if user_id is FALSE. If it is 'Please log
in.' is displayed, otherwise we jump to the matching CEND on line 7. When
viewing the HTML source in a browser on of the follow would be seen:

				<p>You are logged in.</p>

				<p>Please log in.</p>

COND and CEND may also be nested inside each other:


DATA tag

The DATA tag is used to retrieve a VC_data element's raw value. It's general form


Where var is the name of a VC_data element. The retrieved value is used to
replace the DATA tag in the generated HTML file. If it is placed inline with
HTML it will appear as part of the HTML. For example if we have a VC_element
called 'hello_message' which contains 'Hello World!' the following would
display 'Hello World!'.


Once parsed this would become:

			<h1>Hello World!</h1>

The DATA tag should be used with caution as it will use the raw value of the
data. A safer method is to use the TEXT tag which works in exactly the same way
as the DATA tag but special values such as '&', '<', '>' and '"' are translated
into HTML entities.

As nested tags are processed recursively the DATA tag can be used to provide
dynamic data, that is it will be evaluated to it's value (as above) and then
it's value will be used in the tag it is nested within. For example if the
VC_data element 'file' contains 'header.html' and we have:


This becomes:


Which then inserts the content of of the file header.html into the current
file. As a more complex example assume we have two VC_data elements 'field1'
and 'count' which contain 'name' and '1' respectively.


This would evaluate as:


Which would become:


HIDE tag

The HIDE tag is used to cloak query parameters passed on a URL. It's general
form is:


An example of using this could be:

	<a href="example.vc?|{HIDE:var1=1&var2=|{TEXT:c}|}|">Example</a>

This would produce a link that looks like:


The links generated are automatically uncloaked by v-creator and are bookmark
safe as well.

INCL (Include) tag

The INCL tag is used to include other files in a HTML page. The file to be
included may be of any type. However only files with the extensions vchtml,
html, htm and text are processed for v-creator tags. Other file types are
included 'as is'. INCL is commonly used to include repeated HTML such as
headers, footers and navigation and also to include v-creator TAG 'functions'.
Included files may include themselves recursively (for example to display nested
tree like structures) but care should be taken to make sure there is some sort
of test to end the inclusion so it is not infinite. Included files may also
include INCL tags to include more files. The general form of the tag is:


An example of using the INCL tag is including a simple copyright notice that
could be included in the footer of every page on a website. For the footer we
create footer.html:

		Copyright &copy; gencon Ltd. 2004

This can then be used in any page as shown here:

			<h1>Include Test</h1>
				This is a simple test to show an included file at work.

The resulting HTML generated and sent to a browser would be:

			<h1>Include Test</h1>
				This is a simple test to show an included file at work.
				Copyright &copy; gencon Ltd. 2004

LANG (Language) tag

The LANG tag provides a way of generating dynamic internationalised content.
The general form of the tag is:


Where id is a message identifier setup in the i18n_messages database table.
Before the LANG tag can be used in a page the session variable
VCSession_language should be set for the user. If VCSession_language is not set
then the default language specified in the project configuration file will be
used. This topic is covered in more depth in the section on

As an example assume we have the following messages setup:

	EN, WELCOME, Welcome
	DE, WELCOME, Willkommen
	FR, WELCOME, Bienvenue
	IT, WELCOME, Benvenuto

The first column is the language code, next is the message identifier and last
is the actual message text. An example of displaying this in the users chosen
language is:



			<a href="test.vc?lang=EN">EN</a>
			<a href="test.vc?lang=DE">DE</a>
			<a href="test.vc?lang=FR">FR</a>
			<a href="test.vc?lang=IT">IT</a>

This page will display the four hyperlinks 'EN', 'DE', 'FR' and 'IT' for the
four languages in this example. Selecting one of them will redisplay the page
passing the selected 'lang' query string which is used to set the chosen
language. The LANG tag will then display one of 'Welcome', 'Willkommen',
'Bienvenue' or 'Benvenuto'.

LOG tag

The LOG tag is used to write messages into the v-creator log file. This can be
used for debugging or for recording information gathered in the running of the
website. It's general form is:


Where text is the message written to the log. 'text' may contain tags such as
the DATA tag to capture values in the current page:

	|{LOG:Current user id is |{DATA:user_id}|}|

The log file written to is determined by the value 'VC_LOG_FILE' in the project
configuration file.

LOOP and LEND (Loop End) tags

The LOOP and LEND tags are used to repeat a block of HTML or v-creator tags.
Their general form is:


Where module is a database module. The module must implement at a minimum a
getDataSet method. v-creator database modules are discussed in detail later.
For now the getDataSet method will retrieve a set of records from a table. The
LOOP/LEND can then be used on each row retrieved in turn. As an example we can
use the standard user module to retrieve a list of all the users defined and
display their information in a table:

		<th>User ID</th>
		<th>User Name</th>
		<th>First Name</th>

SEC (Security) and SEND (Security End) tags

The tags SEC and SEND are used to mark the beginning and end of a conditional
block of code and are similar to the COND and CEND tags. However they do not
test an element for TRUE or FALSE but instead perform a security check against
the current user. Their general form is:


When 'group' is a security group. When the SEC tag is processed a check is made
to see if the current user belongs to the group specified. If they are then the
HTML or tags between the SEC and SEND tags is processed. If not then processing
jumps to the SEND tag. The check may be reversed by using and exclamation mark
before the group:


In which case the HTML or tags between the SEC and SEND tags are processed if
the user is not in the specified group.

A simple example of this is shown below:


				<p>Welcome Admin!</p>

				<p>Welcome User!</p>

The HTML page sent to the browser will then be either:

			<p>Welcome Admin!</p>

			<p>Welcome User</p>

This means that content, navigation and processing and a number of other things
can be tailored to the security level of the user. It also means that users
cannot browse the page's source code to see what is hidden from their security
level as if they are not authorised it is never sent to them.

The actual setting up of users and security groups is cover in another section.

TEXT tag

The TEXT tag is used to retrieve a VC_data element's value with special
characters translated to HTML entities. It's general form is:


Where var is the name of a VC_data element. The TEXT tag which works in exactly
the same way as the DATA tag but special values such as '&', '<', '>' and '"'
are translated into HTML entities. For more information see the DATA tag.

URL tag

The URL tag is used to send a redirect request to the user's browser. It has
the general form:


It may be used at any point in a page due to v-creator buffering output until
all processing is complete. However once a URL tag is encountered no further
processing for the current page will be done. An example of this could be to
use it in combination with SEC and SEND tags to restrict access to a page:



			<p>Welcome Admin!</p>

In this example if the user is not an administrator they will be sent to the
page 'index.vc'. If they are an administrator they will receive the following


			<p>Welcome Admin!</p>

Project Setup

v-creator requires the following steps to setup a project:

	- Import base v-creator database tables.
	- Create the project structure.
	- Create a configuration file.
	- Create a configuration pointer file.
	- Apache virtual host configuration.

Import Database

Included in the v-creator package is a MySQL database that should be imported.
It contains 9 tables, 5 of which are required by the v-creator core classes and
4 are specific to the standard modules supplied:

	 country 				- An list of countries and their ISO codes.
	*i18n_messages 	- Lookup table for internationalised messages.
	 languages 			- List of available languages.
	 postComments 	- Comments to posts used by postComments module.
	 postboard 			- Posts used by postboard module.
	*securityTokens - Security group hierarchy.
	*sessions 			- Session data.
	*user 					- Registered users.
	*userGroups 		- Available security groups.

Tables marked with an asterisk (*) are required.

These tables should be imported into the project's database.

Project Structure

While v-creator itself requires no configuration each project requires two
pieces of configuration. The first is specific to the Apache server the second
is a project configuration file. 

For the following examples the following project structure will be assumed:

'-- var
		'-- www
				|-- v-creator
				'-- project
						|-- config
						|-- logs
						|-- modules
						|-- public
						|		|-- project_config.php
						|		'-- pageDriver.php
						'-- sql

This structure is not imposed because you are using v-creator. It is provided
as a starting point based on the experiences of the v-creator developers.

	v-creator - symlink to the current version being used. 
	project 	- specific site being created. Usually a symlink to a CVS sandbox
							where 'project' is the CVS module for the site.
	config 		- contains multiple v-creator configuration files. 
	logs			- typically where site specific Apache logs are redirected as well
							as v-creator logs.
	modules		- contain site specific v-creator user modules.
	public 		- document root for the website. Therefore nothing below this can
							be seen by users of the server. This means a browser cannot and
							should not access 'config', 'logs', 'modules' and 'sql'.
	project_config.php -
							Pointer to current configuration file.
	pageDriver.php -
							The main v-creator page driver PHP script.
	sql				- usually contains database dumps and sql scripts.

Project Configuration File

Now we get to the actual configuration files that are stored in the 'config'
directory. An example configuration might be:

	define ('VC_ROOT'        			, '/var/www/v-creator/');
	define ('VC_DOCROOT'     			, '/var/www/project/public/');
	define ('VC_CURL_URL'         , 'http://www.example.com/');
	define ('VC_USER_MODULES'     , '/var/www/project/modules/');
	define ('VC_DEFAULT_LANGUAGE' , 'EN');
	define ('VC_DATABASE'         , 'exampledb');
	define ('VC_DB_HOST'          , 'localhost');
	define ('VC_DB_USER'          , 'user');
	define ('VC_DB_PASSWORD'      , 'password');
	define ('VC_CONVERT_PATH'			, '/usr/bin/');
	define ('VC_UPLOAD_PATH'			, VC_DOCROOT.'uploaded/');
	define ('VC_DEBUG'						, false);
	define ('VC_AUTO_SSL'					, true);
	define ('VC_SESSION_TIMEOUT'	, 900);
	define ('VC_LOG_FILE'					, '/var/www/project/logs/vc.log');
	define ('VC_IGNORE_HIDE_TAG'	, false);
	define ("VC_HIDE_TAG_KEY"			, 'e70ba8668dbd0621801ed58ab03258f7');
	define ('VC_CRYPTO_METHOD'		, 'MCRYPT');
	define ('VC_AUTO_DEFINE_GROUPS'	, true);

Each of these settings will be explained next:

	VC_ROOT 							- The directory where v-creator is installed.
	VC_DOCROOT 						- The projects document root.
	VC_CURL_URL 					- The URL of the website document root as seen by CURL.
	VC_USER_MODULES				-	Site specific user modules.
	VC_DEFAULT_LANGUAGE 	- Default language code for internationalisation.
	VC_DATABASE						-	The name of the MySQL database for the project.
	VC_DB_HOST						-	The hostname where the MySQL server is running.
	VC_DB_USER						-	The user name to access the MySQL database.
	VC_DB_PASSWORD				- The password for the user specified in VC_DB_USER.
	VC_CONVERT_PATH				- The directory to ImageMagick's convert command.
	VC_UPLOAD_PATH				-	Directory for user uploaded content.
	VC_DEBUG							- Flag to enable/disable debugging.
	VC_AUTO_SSL						- Flag to enable/disable v-creator's auto SSL feature.
	VC_SESSION_TIMEOUT		- Session inactivity timeout in seconds.
	VC_LOG_FILE						- File to record debugging and LOG tag output.
	VC_IGNORE_HIDE_TAG		- Flag to enable/dis ale HIDE tags.
	VC_HIDE_TAG_KEY				- Cryptographic key used with HIDE tags.
	VC_CRYPTO_METHOD			- Cryptographic method to use: OPENSSL or MCRYPT.
	VC_AUTO_DEFINE_GROUPS - Flg to enable/disable automatic defines using userGroup table.

The value of VC_HIDE_TAG_KEY can be any string and is used to create the key
used to seed the cryptography algorithms. It should only be created once and
then not changed. If the key IS changed then cloaked bookmarks will be broken. The simplest method of generating a random string for this value is to generate an MD5 hash of the current date and time:

	$ date | md5sum
	e70ba8668dbd0621801ed58ab03258f7  -

Configuration Pointer File

When working on a site it is often necessary to be able to use multiple
configuration files. For example a developer's machine may have a slightly
different configuration to the production server. v-creator provides an easy
mechanism for quickly changing between different configurations and yet keep
track of multiple setups.

In the document root (here the 'public' directory) a file called
'project_config.php' is created where 'project' is the name of the project.
This allows multiple projects to share the document root, especially if it is a
large project with sub projects, without the configuration file names clashing.
This file simply contains a single PHP require_once statement for the current
configuration file to be used in the 'config' directory. For example:


To swap to an alternative configuration only this one file needs to be edited.
As the configuration is in the document root we can always find the
configuration file from wherever we are in the hierarchy using:


Apache Virtual Host Configuration

v-creator makes use of a number of Apache and PHP features which are setup
through the Apache configuration file. For the purposes of providing an example
these settings will be shown isolated in a virtual host configuration section:

	ServerName www.example.com
	DocumentRoot /var/www/project/public
	php_flag arg_separator.output &amp;
	php_flag url_rewriter.tags "a=href,area=href,frame=src,input=src,fieldset="
	<Files *.vchtml>
		Order Deny,Allow
		Deny from all
		Allow from
	RewriteEngine On
	RewriteLog /var/www/project/logs/rewrite.log
	RewriteLogLevel 4
	RewriteRule /(.*)\.vc$ /pageDriver.php?page=$1\.vchtml [QSA,L]

Line 3 				- Sets the document root for the project's server.
Line 4 				- Causes PHP to use &amp; instead of & when modifying URLs. This
								is required to generate valid XHTML markup.
Line 5 				- Causes PHP to modify forms correctly when adding a PHPSESSID
								hidden field. Required to generate valid XHTML markup.
Lines 6 to 10 - This nested section makes files ending in vchtml available to
								the local machine only. This prevents users from requesting the
								'raw' v-creator tagged files. However it allows v-creator to
								still retrieve the files using CURL through Apache. When on a
								development machine the local developer may also retrieve the
								'raw' tagged files as well.
Line 11				- Turn on the URL rewriting extension for the virtual host.
Line 12				- Optional. Logs rewriting processing for debugging.
Line 13				- Optional. Setting the rewritting logging level.
Line 14				- Rewrite rule to simplify v-creator URLs. This will allow the
								use of links such as /index.vc and rewrite them as

Database Modules

Database modules in v-creator are the most common way to manipulate and display
database data in an HTML page. Typically there is one database module per table
and each module has the following methods:


As these modules have a common structure a tool has been provided to generate
the code for these modules which can then be customised and additional
functions added. The tool is called genDBmodule and found in the utils
directory of the v-creator distribution. It is called thus:

	php4 genDBmodule.php user password database table key > module

The module name is usually the same as the table with a PHP extension. The key
is a field used to uniquely identify a row in the table. This is usually an

The most common form of customisation for these modules is the addition of
additional selection criteria in the getDataSet method. This is usually done by adding lines of the form:

	if (isset($VC_data['field'])) {
		if ($where) $where .= ' AND ';
		$where .= " field = '" . $VC_data['field'] . "' ";

Where field is the name of the table's field. These lines are then added before the generated line:

	if ($where) $where = ' WHERE '.$where;

It is also common for the defines method to be customised as initially it is an
empty method. The defines method is used to setup any definitions a module
needs. For example defines for field names specific to the module so that they
can be used in DATA tags. Care should be taken to make the defines modules
reentrant by not trying to redefine already defined defines. For example:

	defines() {
		if (!defined('EXAMPLE')) {
			define('EXAMPLE', 'example');
			define('SAMPLE', 'sample');

The defines method can then be invoked before using the module:


Once the module is setup it can be used with the LOOP tag to retrieve sets of
data, used with the maintenance module and an HTML form to update/delete/add
table records and many other uses. They can also be called directly from other
PHP code as well.

As a side note if a module behaves as a database module but it's dataSet is not
retrieved from the database or the getDataSet calls upon multiple other modules
to build it's dataSet then it is reffered to as a 'Synthetic' database module.
Return current item: v-creator