This is Uberghey CMS                                             version 0.3.0

Contents:
1. Introduction
2. Coding Style
3. Module Coding

.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-.
1. Introduction

  This file contains instructions, guidelines and other useful information for
those who wish to try hacking at Uberghey CMS.

.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-.
2. Coding Style

* Indentation happens using tabs, and with your text editor's tab width set to 8
  characters.
* Assignments and arithmetics are written as follows:
  $variable = $x + $y;
* Function calls are mare with no space after the function name:
  function($argument1, $argument2);
* Documentation in phpDocumentor style API documentation (www.phpdoc.org) is
  heavily encouraged.
* Non-logical blocks (such as a sequence of code) can be commented as such:
  // A comment {
  code;
  more code;
  // A comment }

---------------------------------------
2.1 Block style

Blocks are written as follows (using an if block as the example):

/* Comments go on the previous line using either of the commenting styles */
if (condition == value) {
	code;
} else { // else lines on the same line as the preceding if block's }
	code;
}

.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-.
3. Module Coding

  Coding modules for Uberghey CMS is a fairly straight-forward business, and
it has been designed to be so simple for ease of expansion.

---------------------------------------
3.1 Expanding your module beyond the first file

  You may wish to put more code into a module than fits in one file. This can
be done by creating a subfolder under the modules folder and putting those
files in there. A good idea would be to structure this folder as follows:

/setup - the Uberghey CMS system folder
 /modules - the Uberghey CMS modules folder
  modulename.php - your module's main file
  /modulename - same name as your module main file, bar the extension
   /data - put your module's data in here
   /code - put extra module code in here
   i18n.??.inc - internationalisation files - see bellow
...................
Internationalisation

  The Uberghey CMS internationalisation function (i18n) supports the module
system, and to i18n-ify your module, create files in the modulename folder
(above) containing something similar to the following (Danish i18n):

filename: setup/modules/modulename/i18n.dk.inc
                                  code begins----------------------------------
<?PHP
// i18n for the modulename module
$i18nstrings["Replace the text with this, plus the contained argument, which is ##0##!"] = "Replace the text with this, plus the contained argument, which is ##0##!";
?>
                                   code ends-----------------------------------

---------------------------------------
3.3 Module file structure

  The following is a heavily commented example of a module, which does nothing
at all really...

filename: setup/modules/modulename.php
                                  code begins----------------------------------

<?PHP
/**
* Example Module for Uberghey CMS
* @author	Dan Jensen <admin@leinir.dk>
* @date		2006-02-21
* @version	0.1
* @copyright	Lesser GNU Public License -  www.gnu.org/copyleft
*/

// The following registers 
$modules_names[] = "Module Name";
$mopules_versions[] = "0.1";
$modules_descriptions[] = "A description of what the module does";

// Register the module's module setup function into the module setup function registry
$modules_setup[] = "modulesetup_modulename";

// Register the module's parser functions into the module parsing function registry
$modules[] = "parse_modulename";
$modules[] = "parse_modulename_more";

// Usergroup defaults {
/* Set the default user permissions for this module.
   Notice especially the naming convention here, as it is required
   by the permissions system to manage modules properly */
$usergroups_global_default["modules_modulename_view"] = true;
$usergroups_global_default["modules_modulename_edit"] = false;
// Usergroup defaults }

// Give the user some help, show them what they can do with this module {
$page_help["&#92;replace(txt1)"] = "Will replace with a text, containing txt1";
$page_help["&#92;replacemore(txt1)"] = "Will replace with a text, containing txt1, through a function";
// Give the user some help, show them what they can do with this module }

/**
* modulename_replacer replaces a text with a longer text, containing that same text
*
* @param	$replacewith	Replace this text with a longer text
*
* @return	string		The replacement text
*/
function modulename_replacer($replacewith) {
	return i18n("Replace the text with this, plus the contained argument, which is ##0##!", array($replacewith));
}

// All parse functions take one required argument $page_data, containing unparsed page data, and returns the parsed $page_data
function parse_modulename($page_data) {
	global $setup_folder;
	while (true) {
		$begpos = strpos($page_data, "\\replace("); //where does the first item
		if ($begpos === false) break; //all items have been parsed, no need to check more
		$endpos = strpos($page_data, ")", $begpos + 8); //feed end
		$text = substr($page_data, $begpos + 9, ($endpos - $begpos) - 9);
		
		if (isAllowed("modules_modulename_view")) {
			$replacewith = i18n("Replace the text with this, plus the contained argument, which is ##0##!", array($text));
		} else {
			$replacewith = i18n("You are not authorised to view this!");
		}
		
		$page_data = str_replace("\\readrss($text)", $replacewith, $page_data);
	}
	return $page_data;
}

// All parse functions take one required argument $page_data, containing unparsed page data, and returns the parsed $page_data
function parse_modulename_more($page_data) {
	global $setup_folder;
	while (true) {
		$begpos = strpos($page_data, "\\replacemore("); //where does the first item
		if ($begpos === false) break; //all items have been parsed, no need to check more
		$endpos = strpos($page_data, ")", $begpos + 12); //feed end
		$text = substr($page_data, $begpos + 13, ($endpos - $begpos) - 13);
		
		if (isAllowed("modules_modulename_view")) {
			$replacewith = modulename_replacer($text);
		} else {
			$replacewith = i18n("You are not authorised to view this!");
		}
		
		$page_data = str_replace("\\readrss($text)", $replacewith, $page_data);
	}
	return $page_data;
}

// The module setup function takes no arguments, and returns the HTML code for what will be put into the module setup box on the website
function modulesetup_modulename() {
	if (isAllowed("modules_modulename_edit")) {
		return "<div>" . i18n("This text is what will show up in the module setup, when the user goes to configure it.") . "</div>";
	} else {
		return "<div>" . i18n("You are not authorised to view this!") . "</div>";
	}
}
?>
                                   code ends-----------------------------------

---------------------------------------
3.4 Breadcrumbs

  The setup mode breadcrumbs trail is created from the $_REQUEST variables in
the following order:

  $_REQUEST["module"] (a substring, removing the modulesetup_ part)
  $_REQUEST["module_section"]
  $_REQUEST["module_subsection"]
  $_REQUEST["module_action"]

  All of these are put through i18n(), so if a translation exists, this is
shown in stead of the contents of the variable itself (you can i18n english as
well, that way you can translate a short, lowercase and technical sounding
"modulename" to a proper English text like "Module Name")

---------------------------------------
3.5 Particularly interesting functions

  The following is an in no way exhaustive list of functions that might be
interesting to you when writing a module.

...................
i18n($translateme, $array)
  Returns a translated string of the string $translateme, in International
English (aka British English), replacing texts in the format ##number## with
the contents of the element in that position in the array $array.

examples:
i18n("Translate me") with the language set to dk might return "Overst mig"
i18n("Translate me") with the language set to fr might return "Translate me"
  (The above will happen if there is no translation available)
i18n("Text ##0## replacement", array("stuff")) with the language set to dk
  might return "Tekst stuff erstatning"

...................
siteURL($removepagename)
  Returns the website's URL, and if $removepagename is true, the index.php name
is removed from the URL

examples:
siteURL() might return http://www.sitename.com/subsite/index.php
siteURL(true) might return http://www.sitename.com/subsite/

...................
thisPageURL($header = false, $absoluteurl = true)
  Returns the full URL to the current page, in html format normally, if $header
is true in header format (with & in stead of &amp;), and if $absoluteurl is
true including the protocol, port (if applicable) and full domain name.

examples:
thisPageURL() might return ./index.php?page_id=13&amp;language=en&amp;user_id=username
thisPageURL(true) might return ./index.php?page_id=6&language=en
thisPageURL(false, true) might return http://www.sitename.com/subsite/index.php?page_id=101&amp;language=en

...................
getUserInfo($login, $which_info)
saveUserInfo($login, $which_info, $info)

  getUserInfo will return the user information $info about $which_info saved
using saveUserInfo about the user $login.

examples:
getUserInfo("username", "name") might return "Full Name"
getUserInfo("username", "email") might return "email@sitename.com"
saveUserInfo("username", "email", "newaddress@newsite.com") returns true when saved and false when failed
