added better plugin skeleton and added documentation to some of the examples

diff --git a/documentation/examples/actions/basic.php b/documentation/examples/actions/basic.php
new file mode 100644 (file)
index 0000000..926e11b
--- /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/actions/manual_tokens.php b/documentation/examples/actions/manual_tokens.php
deleted file mode 100644 (file)
index 8dcf61f..0000000
--- a/documentation/examples/actions/manual_tokens.php
+++ /dev/null
@@ -1,6 +0,0 @@
-<?php
-
-$ts = time();
-$token = generate_action_token($ts);
-
-var_dump($ts, $token);

diff --git a/documentation/examples/events/advanced.php b/documentation/examples/events/advanced.php
index 22a407579829dac0db05e088bb6aa6e2b9931902..73edea9dae6746a198ec6b3a7d449ea9e17f5ea1 100644 (file)
--- a/documentation/examples/events/advanced.php
+++ b/documentation/examples/events/advanced.php
@@ -1,10 +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, $params) {
+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
index 238178312e0018d08763117bb335979e2a0563e8..0ad02c1d49f9bd5f19ee9120abf2e5e0b9782384 100644 (file)
--- a/documentation/examples/events/all.php
+++ b/documentation/examples/events/all.php
@@ -1,17 +1,24 @@
 <?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, $params) {
+function example_event_handler($event, $type, $object) {
        // check what sort of object is passed
-       if ($params instanceof ElggObject) {
-               $subtype = $params->getSubtype();
+       if ($object instanceof ElggObject) {
+               $subtype = $object->getSubtype();
 
-               switch($subtype) {
+               switch ($subtype) {
                        case 'blog':
                        case 'thewire':
                        case 'pages':
+                               // prevent these object subtypes from being saved or changed
                                return false;
                        default:
                                return true;
@@ -21,4 +28,3 @@ function example_event_handler($event, $type, $params) {
 
        return true;
 }
-

diff --git a/documentation/examples/events/basic.php b/documentation/examples/events/basic.php
index 91704e60b9b7f3904bc739bad0df77d870302daf..ca27623443d46ad5e473c2c3735b0169dea11f2f 100644 (file)
--- a/documentation/examples/events/basic.php
+++ b/documentation/examples/events/basic.php
@@ -1,13 +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, $params) {
+function example_event_handler($event, $type, $object) {
        var_dump($event);
-       var_dump($object_type);
-       var_dump($params);
+       var_dump($type);
+       var_dump($object);
 
        return true;
 }
-
-

diff --git a/documentation/examples/events/emit.php b/documentation/examples/events/emit.php
deleted file mode 100644 (file)
index b917c6d..0000000
--- a/documentation/examples/events/emit.php
+++ /dev/null
@@ -1,7 +0,0 @@
-<?php
-
-$params = new ElggObject();
-elgg_trigger_event('test', 'example', $params);
-
-// handlers would be registered by saying
-elgg_register_event_handler('test', 'example', 'example_event_handler');

diff --git a/documentation/examples/events/trigger.php b/documentation/examples/events/trigger.php
new file mode 100644 (file)
index 0000000..6ce3a76
--- /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/plugins/README.txt b/documentation/examples/plugins/README.txt
new file mode 100644 (file)
index 0000000..9eb0439
--- /dev/null
+++ b/documentation/examples/plugins/README.txt
@@ -0,0 +1,3 @@
+Plugin Skeleton
+=========================
+

diff --git a/documentation/examples/plugins/skeleton/start.php b/documentation/examples/plugins/actions/.gitignore
similarity index 100%
rename from documentation/examples/plugins/skeleton/start.php
rename to 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 (file)
index 0000000..35f8385
--- /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/skeleton/manifest.xml b/documentation/examples/plugins/manifest.xml
similarity index 100%
rename from documentation/examples/plugins/skeleton/manifest.xml
rename to documentation/examples/plugins/manifest.xml

diff --git a/documentation/examples/plugins/start.php b/documentation/examples/plugins/start.php
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/documentation/examples/plugins/views/default/.gitignore b/documentation/examples/plugins/views/default/.gitignore
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/documentation/stubs/config.php b/documentation/info/config.php
similarity index 100%
rename from documentation/stubs/config.php
rename to documentation/info/config.php

diff --git a/documentation/examples/plugins/manifest_options/manifest.xml b/documentation/info/manifest.xml
similarity index 100%
rename from documentation/examples/plugins/manifest_options/manifest.xml
rename to documentation/info/manifest.xml