Continued work on the plugin API and added some documentation.

2 files changed, 114 insertions, 4 deletions

diff --git a/ratatoeskr/sys/plugin_api.php b/ratatoeskr/sys/plugin_api.php
index e021e15..e5625f8 100644
--- a/ratatoeskr/sys/plugin_api.php
+++ b/ratatoeskr/sys/plugin_api.php
@@ -9,28 +9,94 @@
  * See "ratatoeskr/licenses/ratatoeskr" for more information.
  */
 
-require_once(dirname(__FILE__) . "/db.php");
-
+require_once(dirname(__FILE__) . "/models.php");
 
+/*
+ * Class: RatatoeskrPlugin
+ * An abstract class to be extended in order to write your own Plugin.
+ */
 abstract class RatatoeskrPlugin
 {
 	private $id;
+	
+	/*
+	 * Variables: Protected variables
+	 *
+	 * $kvstorage - The Key-Value-Storage for the Plugin.
+	 * $smarty - Access to the global smarty object.
+	 */
 	protected $kvstorage;
 	protected $smarty;
 	
+	
+	/*
+	 * Constructor: __construct
+	 * Performing some neccessary initialisation stuff.
+	 * If you are overwriting this function, you *really* should call parent::__construct!
+	 * 
+	 * Parameters:
+	 * 	$id - The ID of the plugin (not the name).
+	 */
 	public function __construct($id)
 	{
 		global $smarty;
 		$this->id        = $id;
+		
 		$this->kvstorage = new PluginKVStorage($id);
 		$this->smarty    = $smarty;
 	}
 	
-	public function get_id() { return $this->id; }
+	/*
+	 * Functions: Some getters
+	 * 
+	 * get_id - get the Plugin-ID
+	 * get_additional_files_dir - Path to directory with the additional files
+	 * get_template_dir - Path to template directory
+	 */
+	final public function get_id() { return $this->id; }
+	final protected function get_additional_files_dir() { return dirname(dirname(__FILE__)) . "/plugin_extradata/" . $this->id; }
+	final protected function get_template_dir() { return dirname(dirname(__FILE__)) . "/templates/plugintemplates/" . $this->id; }
+	
+	/*
+	 * Function: register_url_handler
+	 * Easy way for register a URL handler
+	 * 
+	 * Parameters:
+	 * 	$name - Name of URL
+	 * 	$objfunction - Name of object function.
+	 */
+	final protected function register_url_handler($name, $objfunction)
+	{
+		register_url_handler($name, array($this, $objfunction));
+	}
 	
+	final protected function register_settings_page($get, $validate, $set, $structure)
+	
+	/*
+	 * Functions: Functions that are called at special events
+	 * 
+	 * init - Will be called after plugin is loaded. You should register your stuff here.
+	 * install - Will be called after installation. If your plugin needs to initialize some database stuff or generate files, this is the right function.
+	 * uninstall - Will be called during uninstallation. If you used the install function you should undo your custom installation stuff.
+	 */
 	public function init() {}
 	public function install() {}
 	public function uninstall() {}
 }
 
+$url_handlers = array();
+/*
+ * Function: register_url_handler
+ * Register an URL handler. See <urlprocess.php> for more details.
+ * 
+ * Parameters:
+ * 	$name - The name of the new URL
+ * 	$callback - The Function to be called (see <url_process>).
+ */
+function register_url_handler($name, $callback)
+{
+	global $url_handlers;
+	$url_handlers[$name] = $callback;
+}
+
 ?>
diff --git a/ratatoeskr/sys/urlprocess.php b/ratatoeskr/sys/urlprocess.php
index e81a0d4..2274197 100644
--- a/ratatoeskr/sys/urlprocess.php
+++ b/ratatoeskr/sys/urlprocess.php
@@ -9,6 +9,11 @@
  * See "ratatoeskr/licenses/ratatoeskr" for more information.
  */
 
+/*
+ * Class: Redirect
+ * Exception that can be thrown inside an <url_action_simple>.
+ * throw new Redirect(array("..", "foo")); will redirect to "../foo" and won't touch $data.
+ */
 class Redirect extends Exception
 {
 	public $nextpath;
@@ -18,9 +23,22 @@ class Redirect extends Exception
 		parent::__construct();
 	}
 }
-
+/*
+ * Class: NotFoundError
+ * An Exception
+ */
 class NotFoundError extends Exception { }
 
+/*
+ * Function: url_action_simple
+ * Generate an action in a more simple way.
+ * 
+ * Parameters:
+ * 	$function - A callback that gets the $data var as an input and returns the new $data var. Can throw an <Redirect> Exception.
+ * 
+ * Returns:
+ * 	A callback that can be used as an url action.
+ */
 function url_action_simple($function)
 {
 	return function(&$data, $url_now, &$url_next) use ($function)
@@ -37,6 +55,16 @@ function url_action_simple($function)
 	};
 }
 
+/*
+ * Function: url_action_subactions
+ * Generate an action that contains subactions. Subactions can redirect to ".." to go to the level above.
+ * 
+ * Parameters:
+ * 	$actions - Associative array of actions.
+ * 
+ * Returns:
+ * 	A callback that can be used as an url action.
+ */
 function url_action_subactions($actions)
 {
 	return function (&$data, $url_now, &$url_next) use ($actions)
@@ -47,6 +75,22 @@ function url_action_subactions($actions)
 	};
 }
 
+/*
+ * Function: url_process
+ * Choose an appropiate action for the given URL.
+ * 
+ * Parameters:
+ * 	$url - Either an array containing the URL components or the URL (both relative).
+ * 	$actions - Associative array of actions.
+ * 	           Key is the name (anything alphanumeric, should usually not start with '_', reserved for special URL names, see beneath).
+ * 	           Value is a callback of the form: function(&$data, $url_now, &$url_next). $data can be used for shared data between subactions. $url_next can be modified in order to redirect to another action / stop the routing.
+ * 
+ * Special actions:
+ * 	_default - If nothing was found, this is the default.
+ * 	_notfound - If not even _default exists or NotFoundError was thrown.
+ * 	_prelude - If existant, will be executed before everything else.
+ * 	_epilog - If existant, will be executed after evrything else.
+ */
 function url_process($url, $actions, &$data)
 {
 	$epilog_running = 0;