Extensions

Extensions or Plugins are used to add more functionality to Paper Engine products without modifying original code.

Developers Guide(version 1.3.6)

Note: The #Parser init is now deprecated, please use traditional class extends to modify the parser.

This article will outline the basics of creating a plugin for WhiteCrane.

To be able to use all the built in functions with your script you will need to know how the plugin system works, at its very core the plugin function searches the directory and includes the code for execution.

This is a newer a much more revised system. The extension system is now a single class used to transfer code or data to set locations within the script.

Setup

Before writing your script you need to decide which structure to use.

The extension system only has two main modes, basic and enhanced, basic allows you to write standard php code and access any vars or functions available. Enhanced on the other hand allows access to many more features and control however has some limitations. More info below.

Enhanced

Before we begin you must initiate your file in ext or parser mode. This can be done with the following syntax:

// Ext mode
<?php #ext

The extension parser only reads the first line and first 10-13 chars so the syntax MUST be identical or it will not be loaded correctly.

Reading $config and other vars

Upon loading there are a few global's available:

$config, $user and $page

Page(current page) and Self(absolute path to script without final slash) are predefined so its not recommended to use global's for these.

These can be read and modified at will however will not remain changed unless written to the config file before the next execution, therefore when creating a plugin be sure to use the update_config function to save any changes and do not attempt to interpret or manually modify the config file as doing so can damage it. Additionally if you need access to more vars they can be called by setting up global's in your function or class.

Pages: If you need to get a list of pages you can call the Index() function and an unfiltered array will be returned.

Writing $config

To save changes set the $config['item'] and call the update_config after and changes will be written automatically. The items may also be updated directly from a form submit using the same element name as the array key name(booleans must be set on a call to update_config() or they are set to false, if you want to make your booleans independent, store as a string).

Warning: If you are allowing user interaction you NEED to filter the input your self. If not done correctly you may leave you script open for attack, it is NOT recommended you allow form input to the update_config function but if you do remember to filter ALL other $_REQUEST's before running the function.

foreach(array_keys($_REQUEST) as $filter){
    if($filter != 'alloweditem'){
        unset($_REQUEST[$filter]);
    }
    continue;
}

Security

If you need to restrict access the parts of your script or make a user based application there are a few ways of verifying user integrity.

Below are some examples:

// Check if user is logged in
if(isset($_SESSION['logged']) && array_key_exists($_SESSION["logged"],$user)){
    // Code is safe
}
// Check if user is an Administrator
if(isset($_SESSION['logged']) && $user[$_SESSION["logged"]][1] == 1){
    // Code is safe
}
// Check if user is an Administrator or Moderator
if(isset($_SESSION['logged']) && $user[$_SESSION["logged"]][1] == (1|2)){
    // Code is safe
}
// Requesting input of password
if(sha1(strip_tags(substr($_POST['password'],0,32))) == $user[$_SESSION["logged"]][0]){
    // Code is safe
}

Info: The first statement performs an additional check to insure the users account still exists, this can be useful when designing user based app's as some users may need to be removed, while they will not be able to use secured functions they will remain authenticated and will be given an E_NOTICE error(dependent on your php settings).

Example

<?php #ext

#	Extension System Example 1
#	Copyright 2009 Ameoto Systems. All Rights Resurved.
#	Written by TheTooth, thetooth@ameoto.com
	
#	WhiteCrane 1.3.6 r66+

/**
 * Define who we are.
 * Use this to define the infomation about your application and set a namespace for it to run in.
 */
 
define("demo", "Extension System Example 1::Extension System Example 1 for WhiteCrane 1.3.6 r66+<br />Copyright 2009 Ameoto Systems. All Rights Resurved.");
 
/**
 * Set pointers
 * Remember your in an Class enviroment and set an array key for the location and namespace of your app.
 * Note: You must define at lest one location and namespace. For internal functionality set the location as "null".
 */
 
$this->_init['null']['demo'] = 'demo_init';
 
/**
 * Declair functions
 * Place your functions or classes here to be called by the pointer above.
 * Note: You can only call a class constructor from a function.
 */
 
class Demo{
	/**
	 * The function below preforms a regex replacement and sends the result back to the parser with a simple return.
	 */
	function parser($code){
		return $this->_code = preg_replace(
		'/(http:\/\/)([^\s,]*)www\.youtube\.com\/watch\?v\=([a-z0-9-_]{11})/i',
		'<a href="http://www.youtube.com/watch?v=">YouTube </a>',
		$code);
	}
}
 
/**
 * Logical interation inside functions and referencing classes is very clean.
 * And will never cause a function colision in this instance.
 */
 
function demo_init($code){
	$demo = new Demo();
	return $demo->parser($code);
}
 
/**
 * API interaction
 * The class operator below calls the Parser class and sends the current parser data to the function.
 */
 
$parser->demo_init();
?>
+
links