Merge branch 'master' of github.com:shish/shimmie2

core/extension.class.php

@@ -20,23 +20,33 @@
  *
  * \code
  * // ext/hello/main.php
+ * public class HelloEvent extends Event {
+ *     public function __construct($username) {
+ *         $this->username = $username;
+ *     }
+ * }
+ * 
  * public class Hello extends Extension {
- *     public void onPageRequest(PageRequestEvent $event) {
+ *     public function onPageRequest(PageRequestEvent $event) {
  *         global $page, $user;
- *         $this->theme->display_hello($page, $user);
+ *         send_event(new HelloEvent($user->name));
+ *     }
+ *     public function onHello(HelloEvent $event) {
+ *         $this->theme->display_hello($event->username);
  *     }
  * }
  *
  * // ext/hello/theme.php
  * public class HelloTheme extends Themelet {
- *     public void display_hello(Page $page, User $user) {
- *         $page->add_block(new Block("Hello!", "Hello there ".html_escape($user->name));
+ *     public function display_hello($username) {
+ *         global $page;
+ *         $page->add_block(new Block("Hello!", "Hello there ".html_escape($username));
  *     }
  * }
  *
  * // ext/hello/test.php
  * public class HelloTest extends SCoreWebTestCase {
- *     public void testHello() {
+ *     public function testHello() {
  *         $this->get_page("post/list");
  *         $this->assert_text("Hello there");
  *     }
@@ -67,17 +77,42 @@
  * find the thread where the original was posted >_<
  */
 abstract class Extension {
+	/** this theme's Themelet object */
 	var $theme;
+
+	/** @private */
 	var $_child;
 
 	// in PHP5.3, late static bindings can take care of this; __CLASS__
 	// used here will refer to the subclass
 	// http://php.net/manual/en/language.oop5.late-static-bindings.php
+	/** @private */
 	public function i_am(Extension $child) {
 		$this->_child = $child;
-		if(is_null($this->theme)) $this->theme = get_theme_object($child, false);
+		if(is_null($this->theme)) $this->theme = $this->get_theme_object($child, false);
 	}
 
+	/**
+	 * Find the theme object for a given extension
+	 */
+	private function get_theme_object(Extension $class, $fatal=true) {
+		$base = get_class($class);
+		if(class_exists('Custom'.$base.'Theme')) {
+			$class = 'Custom'.$base.'Theme';
+			return new $class();
+		}
+		elseif ($fatal || class_exists($base.'Theme')) {
+			$class = $base.'Theme';
+			return new $class();
+		} else {
+			return false;
+		}
+	}
+
+	/**
+	 * Override this to change the priority of the extension,
+	 * lower numbered ones will recieve events first
+	 */
 	public function get_priority() {
 		return 50;
 	}

core/util.inc.php

@@ -344,7 +344,6 @@ function make_http(/*string*/ $link) {
 
 /**
  * Make a form tag with relevant auth token and stuff
- * (Added optional Form ID field for helping jquery.)
  *
  * @retval string
  */
@@ -507,23 +506,6 @@ function _count_execs($db, $sql, $inputarray) {
 	$null = null; return $null;
 }
 
-/**
- * Find the theme object for a given extension
- */
-function get_theme_object(Extension $class, $fatal=true) {
-	$base = get_class($class);
-	if(class_exists('Custom'.$base.'Theme')) {
-		$class = 'Custom'.$base.'Theme';
-		return new $class();
-	}
-	elseif ($fatal || class_exists($base.'Theme')) {
-		$class = $base.'Theme';
-		return new $class();
-	} else {
-		return false;
-	}
-}
-
 /**
  * Compare two Block objects, used to sort them before being displayed
  *

index.php

@@ -12,20 +12,14 @@
  * which links to images on an image board, with no wiki or messaging, and so
  * on and so on...
  * 
- * To learn about the innards of SCore, start with the \ref overview.
- *
- *
- * \page overview High Level Overview
- *
  * Dijkstra will kill me for personifying my architecture, but I can't think
  * of a better way without going into all the little details.
- *
  * There are a bunch of Extension subclasses, they talk to eachother by sending
- * and recieving Event subclasses. The topic of conversation is decided by the
- * initial PageRequestEvent, and each extension puts its notes into the shared
- * Page data store. Once the conversation is over, the Page is passed to the
+ * and recieving Event subclasses. The primary driver for each conversation is the
+ * initial PageRequestEvent. If an Extension wants to display something to the
+ * user, it adds a block to the Page data store. Once the conversation is over, the Page is passed to the
  * current theme's Layout class which will tidy up the data and present it to
- * the user.
+ * the user. To see this in a more practical sense, see \ref hello.
  *
  * To learn more about the architecture:
  *
@@ -36,7 +30,6 @@
  *
  * \li \ref scglobals
  * \li \ref unittests
- * \li \ref hello
  *
  * \page scglobals SCore Globals
  *