16 files changed, 261 insertions, 0 deletions
diff --git a/documentation/examples/actions/basic.php b/documentation/examples/actions/basic.php
new file mode 100644
index 000000000..926e11b79
--- /dev/null
+++ b/documentation/examples/actions/basic.php
@@ -0,0 +1,22 @@
+<?php
+/**
+ * Demonstrates adding an annotation through an action
+ *
+ * This action adds a rating annotation to an entity. If this was coming from
+ * a five-star rating tool, the rating would be a number between 0 and 5. The
+ * GUID of the entity being rating is also submitted to the action.
+ */
+
+$rating = get_input('rating');
+$guid = get_input('guid');
+
+$entity = get_entity($guid);
+if (!$entity) {
+	register_error(elgg_echo('rating:failure'));
+	forward(REFERER);
+}
+
+$entity->annotate('rating', $rating);
+
+system_message(elgg_echo('rating:success'));
+forward(REFERER);
diff --git a/documentation/examples/crontab.example b/documentation/examples/crontab.example
new file mode 100644
index 000000000..f25f5cb07
--- /dev/null
+++ b/documentation/examples/crontab.example
@@ -0,0 +1,28 @@
+# Crontab example.
+#
+# This file is an example of triggering Elgg cron events. It hits a URL to
+# trigger the events. For testing, you can simulate the cronjob by loading the
+# URL in a browser.
+#
+# See http://docs.elgg.org/wiki/Cron for more information
+#
+# @author Marcus Povey
+
+# Location of GET (see: http://docs.elgg.org/wiki/What_is_get)
+GET='/usr/bin/GET'
+
+# Location of your site (don't forget the trailing slash!)
+ELGG='http://www.example.com/'
+
+# The crontab
+# Don't edit below this line unless you know what you are doing
+@reboot $GET ${ELGG}cron/reboot/
+* * * * * $GET ${ELGG}cron/minute/
+*/5 * * * * $GET ${ELGG}cron/fiveminute/
+15,30,45,59 * * * * $GET ${ELGG}cron/fifteenmin/
+30,59 * * * * $GET ${ELGG}cron/halfhour/
+@hourly $GET ${ELGG}cron/hourly/
+@daily $GET ${ELGG}cron/daily/
+@weekly $GET ${ELGG}cron/weekly/
+@monthly $GET ${ELGG}cron/monthly/
+@yearly $GET ${ELGG}cron/yearly/
diff --git a/documentation/examples/events/advanced.php b/documentation/examples/events/advanced.php
new file mode 100644
index 000000000..73edea9da
--- /dev/null
+++ b/documentation/examples/events/advanced.php
@@ -0,0 +1,13 @@
+<?php
+/**
+ * This snippets demonstrates how returning false changes the normal operation
+ * of Elgg.
+ */
+
+elgg_register_event_handler('create', 'object', 'example_event_handler');
+
+function example_event_handler($event, $type, $object) {
+	// Don't allow any non-admin users to create objects
+	// Returning false from this function will halt the creation of the object.
+	return elgg_is_admin_logged_in();
+}
diff --git a/documentation/examples/events/all.php b/documentation/examples/events/all.php
new file mode 100644
index 000000000..0ad02c1d4
--- /dev/null
+++ b/documentation/examples/events/all.php
@@ -0,0 +1,30 @@
+<?php
+/**
+ * If you register an 'all' string for the event name, the handler function will
+ * be called for all events with that name, regardless of event type. The same
+ * can be done for the event type argument. Registering 'all' for both
+ * argyuments results in a handler being called for every event.
+ */
+
+elgg_register_event_handler('all', 'object', 'example_event_handler');
+
+// This function will be called for any event of type 'object'
+function example_event_handler($event, $type, $object) {
+	// check what sort of object is passed
+	if ($object instanceof ElggObject) {
+		$subtype = $object->getSubtype();
+
+		switch ($subtype) {
+			case 'blog':
+			case 'thewire':
+			case 'pages':
+				// prevent these object subtypes from being saved or changed
+				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..ca2762344
--- /dev/null
+++ b/documentation/examples/events/basic.php
@@ -0,0 +1,17 @@
+<?php
+/**
+ * This snippet demonstrates how to register for an event. It dumps the
+ * parameters that the handler receives to the screen. The third argument
+ * of the handler function is an object that is related to the event. For
+ * the 'init', 'system' eveny, it is null.
+ */
+
+elgg_register_event_handler('init', 'system', 'example_event_handler');
+
+function example_event_handler($event, $type, $object) {
+	var_dump($event);
+	var_dump($type);
+	var_dump($object);
+
+	return true;
+}
diff --git a/documentation/examples/events/trigger.php b/documentation/examples/events/trigger.php
new file mode 100644
index 000000000..6ce3a76f0
--- /dev/null
+++ b/documentation/examples/events/trigger.php
@@ -0,0 +1,11 @@
+<?php
+/**
+ * These two snippets demonstrates triggering an event and how to register for
+ * that event.
+ */
+
+$object = new ElggObject();
+elgg_trigger_event('test', 'example', $object);
+
+// elsewhere a handler could be registered by saying
+elgg_register_event_handler('test', 'example', 'example_event_handler');
diff --git a/documentation/examples/hooks/advanced.php b/documentation/examples/hooks/advanced.php
new file mode 100644
index 000000000..ca036c46a
--- /dev/null
+++ b/documentation/examples/hooks/advanced.php
@@ -0,0 +1,28 @@
+<?php
+/**
+ * This snippet demonstrates how to change the value of a hook. The content
+ * passed into the hook is 'This is some Sample Content.'. After the two hook
+ * handlers are done, the new content is 'This is some $@mple Content.'.
+ */
+
+// the output:page hook is triggered by elgg_view_page().
+elgg_register_plugin_hook_handler('output', 'page', 'example_plugin_hook_handler', 600);
+elgg_register_plugin_hook_handler('output', 'page', 'example_plugin_hook_handler_2', 601);
+
+function example_plugin_hook_handler($hook, $type, $value, $params) {
+	// change a to @
+	$value = str_replace('a', '@', $value);
+
+	return $value;
+}
+
+function example_plugin_hook_handler_2($hook, $type, $value, $params) {
+	// change S to $
+	$value = str_replace('S', '$', $value);
+
+	return $value;
+}
+
+$content = 'This is some Sample Content.';
+
+echo elgg_view_page('Title', $content);
diff --git a/documentation/examples/hooks/all.php b/documentation/examples/hooks/all.php
new file mode 100644
index 000000000..76b562335
--- /dev/null
+++ b/documentation/examples/hooks/all.php
@@ -0,0 +1,12 @@
+<?php
+/**
+ * This snippet demonstrates how to register for multiple hooks with the same
+ * type.
+ */
+
+elgg_register_plugin_hook_handler('all', 'system', 'example_plugin_hook_handler');
+
+// This function will be called for any hook of type 'system'
+function example_plugin_hook_handler($hook, $type, $value, $params) {
+	// logic here.
+}
diff --git a/documentation/examples/hooks/basic.php b/documentation/examples/hooks/basic.php
new file mode 100644
index 000000000..734d9e884
--- /dev/null
+++ b/documentation/examples/hooks/basic.php
@@ -0,0 +1,17 @@
+<?php
+/**
+ * The handler for a plugin hook receives information about the hook (name and
+ * type), the current value for the hook, and parameters related to the hook.
+ */
+
+elgg_register_plugin_hook_handler('forward', '404', 'example_plugin_hook_handler');
+
+function example_plugin_hook_handler($hook, $type, $value, $params) {
+	var_dump($hook);
+	var_dump($type);
+	var_dump($value);
+	var_dump($params);
+
+	// we are not changing $value so return null
+	return null;
+}
diff --git a/documentation/examples/hooks/trigger.php b/documentation/examples/hooks/trigger.php
new file mode 100644
index 000000000..4216fd6c0
--- /dev/null
+++ b/documentation/examples/hooks/trigger.php
@@ -0,0 +1,14 @@
+<?php
+/**
+ * The current value for the hook is passed into the trigger function. Handlers
+ * can change this value. In this snippet, we check if the value of true was
+ * changed by the handler functions.
+ */
+
+$result = elgg_trigger_plugin_hook('get_status', 'example', null, true);
+
+if ($result) {
+	var_dump('Plugin hook says ok!');
+} else {
+	var_dump('Plugin hook says no.');
+}
diff --git a/documentation/examples/plugins/README.txt b/documentation/examples/plugins/README.txt
new file mode 100644
index 000000000..704f56598
--- /dev/null
+++ b/documentation/examples/plugins/README.txt
@@ -0,0 +1,5 @@
+Plugin Skeleton
+=========================
+This directory includes a plugin skeleton to be used as the starting point when
+creating a new plugin. Just create a new directory in /mod/ and copy the files
+and directories into it. Then update the manifest and start coding.
+\ No newline at end of file
diff --git a/documentation/examples/plugins/actions/.gitignore b/documentation/examples/plugins/actions/.gitignore
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/documentation/examples/plugins/actions/.gitignore
diff --git a/documentation/examples/plugins/languages/en.php b/documentation/examples/plugins/languages/en.php
new file mode 100644
index 000000000..35f838560
--- /dev/null
+++ b/documentation/examples/plugins/languages/en.php
@@ -0,0 +1,24 @@
+<?php
+/**
+ * The core language file is in /languages/en.php and each plugin has its
+ * language files in a languages directory. To change a string, copy the
+ * mapping into this file.
+ *
+ * For example, to change the blog Tools menu item
+ * from "Blog" to "Rantings", copy this pair:
+ * 			'blog' => "Blog",
+ * into the $mapping array so that it looks like:
+ * 			'blog' => "Rantings",
+ *
+ * Follow this pattern for any other string you want to change. Make sure this
+ * plugin is lower in the plugin list than any plugin that it is modifying.
+ *
+ * If you want to add languages other than English, name the file according to
+ * the language's ISO 639-1 code: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+ */
+
+$mapping = array(
+	'string:here' => 'Display string here',
+);
+
+add_translation('en', $mapping);
diff --git a/documentation/examples/plugins/manifest.xml b/documentation/examples/plugins/manifest.xml
new file mode 100644
index 000000000..e31624432
--- /dev/null
+++ b/documentation/examples/plugins/manifest.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
+	<name>My Plugin</name>
+	<author>My Name</author>
+	<version>1.0</version>
+	<description>This is a description of my plugin and its features.</description>
+	<website>http://www.elgg.org/</website>
+	<copyright>(C) My Name or Company 2012</copyright>
+	<license>GNU General Public License version 2</license>
+
+	<requires>
+		<type>elgg_release</type>
+		<version>1.8</version>
+	</requires>
+
+	<category>communication</category>
+
+</plugin_manifest>
diff --git a/documentation/examples/plugins/start.php b/documentation/examples/plugins/start.php
new file mode 100644
index 000000000..3af50ce38
--- /dev/null
+++ b/documentation/examples/plugins/start.php
@@ -0,0 +1,22 @@
+<?php
+/**
+ * Describe plugin here
+ */
+
+elgg_register_event_handler('init', 'system', 'my_plugin_init');
+
+function my_plugin_init() {
+	// Rename this function based on the name of your plugin and update the
+	// elgg_register_event_handler() call accordingly
+
+	// Register a script to handle (usually) a POST request (an action)
+	$base_dir = elgg_get_plugins_path() . 'my_plugin/actions/my_plugin';
+	elgg_register_action('my_plugin', "$base_dir/my_action.php");
+
+	// Extend the main CSS file
+	elgg_extend_view('css/elgg', 'my_plugin/css');
+
+	// Add a menu item to the main site menu
+	$item = new ElggMenuItem('my_plugin', elgg_echo('my_plugin:menu'), 'my_url');
+	elgg_register_menu_item('site', $item);
+}
diff --git a/documentation/examples/plugins/views/default/.gitignore b/documentation/examples/plugins/views/default/.gitignore
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/documentation/examples/plugins/views/default/.gitignore