Development

This program 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.

Globals

All the global variables should be written in upper case letters or be capitalized.

In the core library these are values or objects: $PAGE, $LOGIN, $ACTION and these are arrays: $Lang, $Config, $Users... For the global arrays keys are capitalized too.

Paths

Currently we are living in the world of Windows and Unix systems, both in each closed and open source form (¹ Sic! Look for the projects like Wine or ReactOS). That's why I'm trying to be aware of differences between these two worlds. So the filenames should be . One goal is that Apache/PHP environment gives you something that

Paths are stored in two ways - if it is a directory, it should containt trailing slash (/), otherwise it may be name of the file. A list of directories should look like:

	/usr/local/etc/apache22/
	/etc/apache/

If you mix elements without trailing slash (/) you make an internal difference between files and directories, because of concatenation of element and general path.

If locale() looks for the specific data named "example" for "pl" language it will read all the locale/pl/example.php files found it directories specified in $Config['LocalePath'] which probably contains:

Root paths should begin with:

DIRECTORY_SEPARATOR
Drive letter followed with : (for example C:\WINDOWS\). If not specified, current working directory drive letter may be used.
or / for Unix).

Directories

Naming style for directories is to use only lower case letters, digits and underline or hyphen signs eventually ([a-z0-9_-]).

Comments

CSS files to be more easy to understand can be divided by sections, which should describe what is the purpose of the next lines. For example:

/* ### FONTS ### */

body, td, p {
	font-family: "Trebuchet MS", "Lucida Sans Unicode", "Lucida Sans", "Luxi Sans", "Tahoma", "Verdana";
	font-size: 11pt;
}

Default themes contain their style definitions in the file style.css which begins with:

/* ### CSS ### */

Libraries

Web

Vaco Web Library package contains the following files:

Common functions

lib/common.php

This is depreciated library file that will initialize the framework.

Use core.php instead.

Core

lib/core.php

Core initializes the main website engine and (almost) all required modules. It tries to be silent so after including this part you still can send your own output (even if it's not HTML).

If including from other location than the main site root (default is upper directory) you may want to define the real $WEBROOT before including this file. This will affect on including locales, modules, database drivers, etc. Configuration, locales, modules and external pages or scripts are included from this directory first, then (if not present) from $WEBROOT. This is handy when using local tree.

Including this file causes site blocking for maintenance reasons. If the file {$ROOT}MAINTENANCE is not empty, then user will be redirected to $Config['MaintenancePage']. All files that should be available during maintenance should set $Config['Maintenance'] value to true. The redirection to the maintenance page is done by redirect() function so in CLI mode invoking external script is made rather than changing location.

This part seeks for the external configuration file(s) during its initialization part. This would be B files placed in this directory (global) and configuration.php in your site's root directory.

In addition you can set $Config['Filename'] to what you want to be used as a last configuration file. This may be useful to override the whole site configuration (see below).

If for some reasons you want to ignore configuration values (and set all by yourself) you may want to set $Config['Ignore'] value. In that case this file won't try to load configuration from files except for the one set in $Config['Filename'].

Globals

CORELIB

$CORELIB contains path to the core. Default is current directory of this script. You may set this before calling first require. Example:

$CORELIB = "/usr/share/vaco/web/lib/";
require("{$CORELIB}common.php");

It would load the global Vaco engine installed in some Unix system where your script runs.

WEBROOT

$WEBROOT contains path to your root directory. Default is empty string. You may wish to change it if your files lies somewhere outside the web root:

$WEBROOT = dirname(basename(__FILE__));

By default this variable is used to determine where the library files and site pages are.

Several extensions installed as modules to your site or an application should make a global links using this variable.

$MICROTIME

$MICROTIME stores system timestamp used to count page render time. Value of this variable is set as soon as possible in this script.

DIRECTORY_SEPARATOR

In the Apache and PHP environment all subdirectories which are separated by the slash (/) (as it were used in Other-Than-Windows systems) are always fine even in Windows systems. It is better to use just slash sign not the DIRECTORY_SEPARATOR constant, which if not defined (in older PHP versions) will be defined by the

$Registry

Registry is by deault read from the SQL #__config table.

$Config

$Config is an array which contains current configurations.

This is in fact the global configuration including the full content of the registry, so you may treat it as it would be read from the local configuration.php file and (if database access is set) the #__config table.

$Lang

This array is used to store language specific strings.

$Vars

This is a set of local variables used by templates.

$Scripts

Array of javascript files need to include. Page header generator in lib/header.php will look for the file

Depreciated

Following globals are set to be removed for some reasons.

LIB

$LIB is a synonym for the $CORELIB and is provided for compatibility reasons.

Please, avoid using it.

ROOT

$ROOT is a synonym for the $WEBROOT and is provided for compatibility reasons.

Please, avoid using it.

Functions

Web

lib/common.php

function request($name, $default='')

Returns requested value. This is done reading GET and POST variables. All the values are unquoted, no matter magic quotes are set or not in PHP, so whenever used in SQL statements they should be quoted as needed.

function str_eval($str)

If the parameter begins with dollar sign ($) it returns text evaluated as a language specific if found in $Lang variable) or (if not found) the name of the parameter without leading dollar sign.

If the parameter begins with at sign (@) it returns result text of the PHP code.

Perhapse this example code should help you understand:

<?php
require("lib/header.php");
function myfunc() { return " but not quite sure..."; }
$Lang['Yes'] = "No";
echo str_eval("$Yes");		// prints $Lang['Yes'] or just "Yes" if not found
echo str_eval("@myfunc()");
?>

function fname($str)

Returns filename without leading path.

function fext($str)

Returns file extension.

function get_microtime($start=0)

This function will result the interval between $start and current system time in microseconds.

function sgn($value)

Returns the sign of the $value: 1 for positive, 0 if zero (or is not number), -1 if negative.

function is_assoc($var)

Returns true if $var is an associative array.

function str_lower($str, $enc="UTF-8")

Returns lower case string using mbstring functions if available.

function str_upper($str, $enc="UTF-8")

Returns upper case string using mbstring functions if available. Like str_lower() it will try to use mb_convert_case() function if appropriate PHP extension is loaded.

function str_cap($s)

Capitalizes first letter of the string leaving the rest in lower case. This is in Poland called something like "Camel style".

function str_select(...)

Returns the value of the first not false argument.

function str_explode($s, $trim=true)

Expoldes string into an array.

function is_assoc($var)

Returns true if $var is associative array (hash).

function array_clear(&$array)

Clears an array without destroying current structure (values are set to empty strings).

function array_delete($array, $item)

Delete element from array.

function echo_out($handle='', $str='')

Calling this will write output message to the handle.

function redirect($url)

Ends current process and redirects to another page or script (if using CLI scheme it will call the script with arguments extracted from URL).

function echobig($str, $chunk=8192)

This function is useful to send big output and is based on the code by Jason Carlson - SiteSanity and ryan at wonko dot com.

Cite: "Due to the way TCP/IP packets are buffered, using echo to send large strings to the client may cause a severe performance hit. Sometimes it can add as much as an entire second to the processing time of the script. This even happens when output buffering is used".

lib/style.php

This file is a base web layout definition. It will define specific variables like $Style['XML'] and $Style['DOCTYPE'] which are used to generate page header in lib/header.php.

Including this file affects global variable $Style and provides you access to all style_ functions. To see what elements are modified try:

<pre>
<?php
require("lib/style.php");
print_r($Style);
?>
</pre>

You don't need to include this file after your scripts load lib/header.php. On the other hand this part needs at least str_eval() definition so it will load lib/common.php. So if you are making some job before page content goes to the client you may do this in one of the following ways:

<?php
require("lib/common.php");
// some initialization stuff
require("lib/header.php");
// page content using style generators
require("lib/footer.php");
?>

<?php
#require("lib/common.php");	// useless
require("lib/style.php");
// some initialization stuff using style generators
require("lib/header.php");
// page content using style generators
require("lib/footer.php");
?>

function style_linkcaption($caption)

function custom_linkcaption($caption)

Returns anchor text with $Style modifiers. Because many of content generators are written the same way, here is an example definition of style_linkcaption():

function style_boxbegin($caption='')
{
	$s=str_eval($caption);
	if (function_exists('custom_boxbegin')) return custom_boxbegin($s);
	global $Style;
	if ($s) $s=@$Style['Box']['Caption']['Begin'].$s.@$Style['Box']['Caption']['End'];
	return @$Style['Box']['Caption']['Inner'] ? $Style['Box']['Begin'].$s 
		: $s.$Style['Box']['Begin'];
}

function style_boxbegin($caption)

function custom_boxbegin($caption)

Outputs the $Style['Box']['Begin'] and the content of $caption parameter (if not empty) between $Style['Box']['Caption']['Begin'] and $Style['Box']['Caption']['End'].

function style_boxend($status)

function custom_boxend($status)

Outputs the content of $status parameter (if not empty) between $Style['Box']['Status']['Begin'] and $Style['Box']['Status']['End'] and then $Style['Box']['End'].

You may use a pair of functions style_boxbegin() and style_boxend() to create custom box or just one function style_box() as described in "Creating box" section.

function style_boxbreak()

function custom_boxbreak()

Outputs the breaking space inside box. This may be used to create several pages in one module/box.

function style_box($content, $caption, $status)

function custom_box($content, $caption, $status)

Outputs the whole box using previousy defined functions style_boxbegin() and boxend().

lib/authenticate.php

function auth_generate()

Returns randomly generated password.

lib/db.php

Each time this file is included it will try to create default global database connection $SQL if only $Database array is filled. You may include this file twice if you need to change the default connection during page processing.

Note, that you can have more that one connection to database,

Previously used $db variable name was changed to meet naming conventions criteria.

function sql($query, ...)

Return a formatted query. Similar to sprintf() for parsing SQL queries.

Format string passed as a $query parameter is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result, and conversion specifications, each of which results in fetching its own parameter.

Each conversion specification consists of a percent sign (%), followed by one or more of these elements, in order:

• %% - a literal percent character.
• %b - boolean (1 for true and 0 for false)
• %d, %i - the argument is treated as an integer, and presented as a (signed) decimal number
• %f - the argument is treated as a float, and presented as a floating-point number
• %s - the argument is treated as and presented as a string with quotes
• %u - the argument is treated as and presented as a string without quotes

Examples:

echo sql('SELECT * FROM #__table WHERE my_field=%s', $search);

Fundamentals

units/common.pas

function IsFullyQualifiedFileName(const FileName: string): Boolean;

Return TRUE if FileName contains root path.

function IsFullyQualifiedPath(const Path: string): Boolean;

function FullyQualifiedFileName(const FileName: string): string;

function FullyQualifiedPath(const Path: string): string;

function IsRelativePath(const Path: string): Boolean;

<< Go back