From ea4403c9240c3778cddc90d48d0a59c4d47dd2d8 Mon Sep 17 00:00:00 2001
From: brettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>
Date: Wed, 15 Sep 2010 15:40:51 +0000
Subject: Adding documentation and examples.

git-svn-id: http://code.elgg.org/elgg/trunk@6933 36083f99-b078-4883-b0ff-0f9b5a30f544
---
 documentation/examples/events/advanced.php         | 10 +++++++
 documentation/examples/events/all.php              | 24 +++++++++++++++
 documentation/examples/events/basic.php            | 13 +++++++++
 documentation/examples/events/basic.php.out        |  0
 documentation/examples/events/emit.php             |  7 +++++
 documentation/examples/hooks/basic.php             | 34 ++++++++++++++++++++++
 documentation/examples/hooks/register/advanced.php | 23 +++++++++++++++
 documentation/examples/hooks/register/all.php      |  8 +++++
 documentation/examples/hooks/register/basic.php    | 14 +++++++++
 .../examples/hooks/register/basic.php.out          |  0
 documentation/examples/hooks/register/emit.php     |  6 ++++
 documentation/examples/hooks/trigger/advanced.php  |  9 ++++++
 documentation/examples/hooks/trigger/basic.php     |  9 ++++++
 13 files changed, 157 insertions(+)
 create mode 100644 documentation/examples/events/advanced.php
 create mode 100644 documentation/examples/events/all.php
 create mode 100644 documentation/examples/events/basic.php
 create mode 100644 documentation/examples/events/basic.php.out
 create mode 100644 documentation/examples/events/emit.php
 create mode 100644 documentation/examples/hooks/basic.php
 create mode 100644 documentation/examples/hooks/register/advanced.php
 create mode 100644 documentation/examples/hooks/register/all.php
 create mode 100644 documentation/examples/hooks/register/basic.php
 create mode 100644 documentation/examples/hooks/register/basic.php.out
 create mode 100644 documentation/examples/hooks/register/emit.php
 create mode 100644 documentation/examples/hooks/trigger/advanced.php
 create mode 100644 documentation/examples/hooks/trigger/basic.php

diff --git a/documentation/examples/events/advanced.php b/documentation/examples/events/advanced.php
new file mode 100644
index 000000000..c6fc2d0fb
--- /dev/null
+++ b/documentation/examples/events/advanced.php
@@ -0,0 +1,10 @@
+<?php
+
+register_elgg_event_handler('create', 'object', 'example_event_handler');
+
+function example_event_handler($event, $type, $params) {
+	// Don't allow any non-admin users to create objects
+	// Returning false from this function will halt the creation of the object.
+	return isadminloggedin();
+}
+
diff --git a/documentation/examples/events/all.php b/documentation/examples/events/all.php
new file mode 100644
index 000000000..63959a9d2
--- /dev/null
+++ b/documentation/examples/events/all.php
@@ -0,0 +1,24 @@
+<?php
+
+register_elgg_event_handler('all', 'object', 'example_event_handler');
+
+// This function will be called for any event of type 'object'
+function example_event_handler($event, $type, $params) {
+	// check what sort of object is passed
+	if ($params instanceof ElggObject) {
+		$subtype = $params->getSubtype();
+
+		switch($subtype) {
+			case 'blog':
+			case 'thewire':
+			case 'pages':
+				return false;
+			default:
+				return true;
+		}
+
+	}
+
+	return true;
+}
+
diff --git a/documentation/examples/events/basic.php b/documentation/examples/events/basic.php
new file mode 100644
index 000000000..b274137b8
--- /dev/null
+++ b/documentation/examples/events/basic.php
@@ -0,0 +1,13 @@
+<?php
+
+register_elgg_event_handler('init', 'system', 'example_event_handler');
+
+function example_event_handler($event, $type, $params) {
+	var_dump($event);
+	var_dump($object_type);
+	var_dump($params);
+
+	return true;
+}
+
+
diff --git a/documentation/examples/events/basic.php.out b/documentation/examples/events/basic.php.out
new file mode 100644
index 000000000..e69de29bb
diff --git a/documentation/examples/events/emit.php b/documentation/examples/events/emit.php
new file mode 100644
index 000000000..f4cd1b127
--- /dev/null
+++ b/documentation/examples/events/emit.php
@@ -0,0 +1,7 @@
+<?php
+
+$params = new ElggObject();
+trigger_elgg_event('test', 'example', $params);
+
+// handlers would be registered by saying
+register_elgg_event_handler('test', 'example', 'example_event_handler');
diff --git a/documentation/examples/hooks/basic.php b/documentation/examples/hooks/basic.php
new file mode 100644
index 000000000..fe0b847a2
--- /dev/null
+++ b/documentation/examples/hooks/basic.php
@@ -0,0 +1,34 @@
+<?php
+
+register_plugin_hook('get_items', 'example', 'example_plugin_hook');
+register_plugin_hook('get_items', 'example', 'example_plugin_hook_2');
+
+$params = array('username' => 'Joe');
+$items = trigger_plugin_hook('get_items', 'example', $params, $default);
+
+var_dump($items);
+
+function example_plugin_hook($hook, $type, $value, $params) {
+	if (is_array($value)) {
+		$value[] = "Hook Value 1";
+		$value[] = "Hook Value 2";
+	}
+
+	return $value;
+}
+
+function example_plugin_hook($hook, $type, $value, $params) {
+	$username = isset($params['username']) ? $params['username'] : NULL;
+	if (is_array($value)) {
+		switch($username) {
+			case 'Joe':
+				$value[] = "Joe's item";
+				break;
+			case 'John':
+				$value[] = "Joe's item";
+				break;
+		}
+	}
+
+	return $value;
+}
diff --git a/documentation/examples/hooks/register/advanced.php b/documentation/examples/hooks/register/advanced.php
new file mode 100644
index 000000000..48cddd480
--- /dev/null
+++ b/documentation/examples/hooks/register/advanced.php
@@ -0,0 +1,23 @@
+<?php
+
+// the output:page hook is triggered by page_draw().
+register_plugin_hook('output', 'page', 'example_plugin_hook_handler', 600)
+register_plugin_hook('output', 'page', 'example_plugin_hook_handler_2', 601);
+
+function example_plugin_hook_handler($event, $type, $value, $params) {
+	// change A to @
+	$value = str_replace('A', '@', $value);
+	
+	return $value
+}
+
+function example_plugin_hook_handler($event, $type, $value, $params) {
+	// change S to $
+	$value = str_replace('S', '$', $value);
+	
+	return $value
+}
+
+$content = 'This is some Sample Content.';
+
+page_draw('Title', $content);
diff --git a/documentation/examples/hooks/register/all.php b/documentation/examples/hooks/register/all.php
new file mode 100644
index 000000000..f2e4407a6
--- /dev/null
+++ b/documentation/examples/hooks/register/all.php
@@ -0,0 +1,8 @@
+<?php
+
+register_plugin_hook('all', 'system', 'example_plugin_hook_handler');
+
+// This function will be called for any event of type 'object'
+function example_plugin_hook_handler($hook, $type, $value, $params) {
+	// logic here.
+}
diff --git a/documentation/examples/hooks/register/basic.php b/documentation/examples/hooks/register/basic.php
new file mode 100644
index 000000000..957e82743
--- /dev/null
+++ b/documentation/examples/hooks/register/basic.php
@@ -0,0 +1,14 @@
+<?php
+
+register_plugin_hook('forward', 'system', 'example_plugin_hook_handler');
+
+function example_plugin_hook_handler($event, $type, $value, $params) {
+	var_dump($event);
+	var_dump($type);
+	var_dump($value);
+	var_dump($params):
+	
+	return true;
+}
+
+
diff --git a/documentation/examples/hooks/register/basic.php.out b/documentation/examples/hooks/register/basic.php.out
new file mode 100644
index 000000000..e69de29bb
diff --git a/documentation/examples/hooks/register/emit.php b/documentation/examples/hooks/register/emit.php
new file mode 100644
index 000000000..bcf991794
--- /dev/null
+++ b/documentation/examples/hooks/register/emit.php
@@ -0,0 +1,6 @@
+<?php
+
+register_elgg_event_handler('test', 'example', 'example_init_system_callback');
+
+$params = new ElggObject();
+trigger_elgg_event('test', 'example', $params);
diff --git a/documentation/examples/hooks/trigger/advanced.php b/documentation/examples/hooks/trigger/advanced.php
new file mode 100644
index 000000000..de33e7a10
--- /dev/null
+++ b/documentation/examples/hooks/trigger/advanced.php
@@ -0,0 +1,9 @@
+<?php
+
+$default = array('Entry 1', 'Entry 2', 'Entry 3');
+
+$menu = trigger_plugin_hook('get_menu_items', 'menu', null, $default);
+
+foreach ($menu as $item) {
+	var_dump($item);
+}
diff --git a/documentation/examples/hooks/trigger/basic.php b/documentation/examples/hooks/trigger/basic.php
new file mode 100644
index 000000000..a32bf9296
--- /dev/null
+++ b/documentation/examples/hooks/trigger/basic.php
@@ -0,0 +1,9 @@
+<?php
+
+$result = trigger_plugin_hook('get_status', 'example', null, true);
+
+if ($result) {
+	var_dump('Plugin hook says ok!');
+} else {
+	var_dump('Plugin hook says no.');
+}
-- 
cgit v1.2.3