aboutsummaryrefslogtreecommitdiff
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/coding_standards/best_practices.txt2
-rw-r--r--documentation/coding_standards/javascript_coding_standards.txt11
-rw-r--r--documentation/examples/actions/basic.php22
-rw-r--r--documentation/examples/actions/manual_tokens.php6
-rw-r--r--documentation/examples/events/advanced.php7
-rw-r--r--documentation/examples/events/all.php16
-rw-r--r--documentation/examples/events/basic.php14
-rw-r--r--documentation/examples/events/emit.php7
-rw-r--r--documentation/examples/events/trigger.php11
-rw-r--r--documentation/examples/hooks/advanced.php28
-rw-r--r--documentation/examples/hooks/all.php (renamed from documentation/examples/hooks/register/all.php)4
-rw-r--r--documentation/examples/hooks/basic.php41
-rw-r--r--documentation/examples/hooks/register/advanced.php23
-rw-r--r--documentation/examples/hooks/register/basic.php14
-rw-r--r--documentation/examples/hooks/register/emit.php7
-rw-r--r--documentation/examples/hooks/trigger.php14
-rw-r--r--documentation/examples/hooks/trigger/advanced.php9
-rw-r--r--documentation/examples/hooks/trigger/basic.php9
-rw-r--r--documentation/examples/plugins/README.txt5
-rw-r--r--documentation/examples/plugins/actions/.gitignore0
-rw-r--r--documentation/examples/plugins/languages/en.php24
-rw-r--r--documentation/examples/plugins/manifest.xml93
-rw-r--r--documentation/examples/plugins/start.php12
-rw-r--r--documentation/examples/plugins/views/default/.gitignore0
-rw-r--r--documentation/info/config.php (renamed from documentation/stubs/config.php)0
-rw-r--r--documentation/info/manifest.xml95
26 files changed, 271 insertions, 203 deletions
diff --git a/documentation/coding_standards/best_practices.txt b/documentation/coding_standards/best_practices.txt
index 069ac42aa..df04aa845 100644
--- a/documentation/coding_standards/best_practices.txt
+++ b/documentation/coding_standards/best_practices.txt
@@ -15,6 +15,8 @@ work for developers, which means happier, more productive developers.
* Use self-documenting variable names. $group_guids is better than $array.
+* Use "positive" variable names. Prefer `$enable = true` to `$disable = false`.
+
* Functions returning an array should return an empty array instead of FALSE
on no results.
diff --git a/documentation/coding_standards/javascript_coding_standards.txt b/documentation/coding_standards/javascript_coding_standards.txt
index 7d3b842ec..9939e80ab 100644
--- a/documentation/coding_standards/javascript_coding_standards.txt
+++ b/documentation/coding_standards/javascript_coding_standards.txt
@@ -1,2 +1,13 @@
*** JAVASCRIPT CODING STANDARDS ***
+* Same formatting standards as PHP.
+
+* All functions should be in the elgg namespace.
+
+* Function expressions should end with a semi-colon:
+
+ elgg.ui.toggles = function(event) {
+ event.preventDefault();
+ $(target).slideToggle('medium');
+ };
+
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/actions/manual_tokens.php b/documentation/examples/actions/manual_tokens.php
deleted file mode 100644
index 8dcf61fb1..000000000
--- 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 22a407579..73edea9da 100644
--- 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 238178312..0ad02c1d4 100644
--- 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 91704e60b..ca2762344 100644
--- 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
index b917c6dc0..000000000
--- 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
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/register/all.php b/documentation/examples/hooks/all.php
index 0ff19bc86..76b562335 100644
--- a/documentation/examples/hooks/register/all.php
+++ b/documentation/examples/hooks/all.php
@@ -1,4 +1,8 @@
<?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');
diff --git a/documentation/examples/hooks/basic.php b/documentation/examples/hooks/basic.php
index 71076ee96..734d9e884 100644
--- a/documentation/examples/hooks/basic.php
+++ b/documentation/examples/hooks/basic.php
@@ -1,34 +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('get_items', 'example', 'example_plugin_hook');
-elgg_register_plugin_hook_handler('get_items', 'example', 'example_plugin_hook_2');
+elgg_register_plugin_hook_handler('forward', '404', 'example_plugin_hook_handler');
-$params = array('username' => 'Joe');
-$items = elgg_trigger_plugin_hook('get_items', 'example', $params, $default);
+function example_plugin_hook_handler($hook, $type, $value, $params) {
+ var_dump($hook);
+ var_dump($type);
+ var_dump($value);
+ var_dump($params);
-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_2($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;
+ // we are not changing $value so return null
+ return null;
}
diff --git a/documentation/examples/hooks/register/advanced.php b/documentation/examples/hooks/register/advanced.php
deleted file mode 100644
index e3951c19c..000000000
--- a/documentation/examples/hooks/register/advanced.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<?php
-
-// 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($event, $type, $value, $params) {
- // change A to @
- $value = str_replace('A', '@', $value);
-
- return $value;
-}
-
-function example_plugin_hook_handler_2($event, $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); \ No newline at end of file
diff --git a/documentation/examples/hooks/register/basic.php b/documentation/examples/hooks/register/basic.php
deleted file mode 100644
index 20493e200..000000000
--- a/documentation/examples/hooks/register/basic.php
+++ /dev/null
@@ -1,14 +0,0 @@
-<?php
-
-elgg_register_plugin_hook_handler('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/emit.php b/documentation/examples/hooks/register/emit.php
deleted file mode 100644
index 8382d72ca..000000000
--- a/documentation/examples/hooks/register/emit.php
+++ /dev/null
@@ -1,7 +0,0 @@
-<?php
-
-// @todo this is an event, not a hook
-elgg_register_event_handler('test', 'example', 'example_init_system_callback');
-
-$params = new ElggObject();
-elgg_trigger_event('test', 'example', $params);
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/hooks/trigger/advanced.php b/documentation/examples/hooks/trigger/advanced.php
deleted file mode 100644
index 5901a06e0..000000000
--- a/documentation/examples/hooks/trigger/advanced.php
+++ /dev/null
@@ -1,9 +0,0 @@
-<?php
-
-$default = array('Entry 1', 'Entry 2', 'Entry 3');
-
-$menu = elgg_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
deleted file mode 100644
index ea27a8a98..000000000
--- a/documentation/examples/hooks/trigger/basic.php
+++ /dev/null
@@ -1,9 +0,0 @@
-<?php
-
-$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
index 1602a7358..e31624432 100644
--- a/documentation/examples/plugins/manifest.xml
+++ b/documentation/examples/plugins/manifest.xml
@@ -1,99 +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>Elgg</author>
+ <author>My Name</author>
<version>1.0</version>
- <blurb>A concise description.</blurb>
- <description>This is a longer, more interesting description of my plugin, its features, and other important information.</description>
+ <description>This is a description of my plugin and its features.</description>
<website>http://www.elgg.org/</website>
- <copyright>(C) Elgg 2010</copyright>
- <license>GNU Public License version 2</license>
-
- <requires>
- <type>elgg_version</type>
- <version>2009030802</version>
- </requires>
+ <copyright>(C) My Name or Company 2012</copyright>
+ <license>GNU General Public License version 2</license>
<requires>
<type>elgg_release</type>
- <version>1.8-svn</version>
- </requires>
-
- <screenshot>
- <description>An example screenshot</description>
- <path>graphics/plugin_ss1.png</path>
- </screenshot>
-
- <screenshot>
- <description>Another screenshot</description>
- <path>graphics/plugin_ss2.png</path>
- </screenshot>
-
- <category>admin</category>
- <category>api</category>
-
- <on_enable>setup_function</on_enable>
- <on_disable>teardown_function</on_disable>
- <admin_interface>simple</admin_interface>
-
- <requires>
- <type>php_extension</type>
- <name>gd</name>
- </requires>
-
- <requires>
- <type>php_ini</type>
- <name>short_open_tag</name>
- <value>off</value>
- </requires>
-
- <requires>
- <type>php_extension</type>
- <name>made_up</name>
- <version>1.0</version>
- </requires>
-
- <requires>
- <type>plugin</type>
- <name>fake_plugin</name>
- <version>1.0</version>
+ <version>1.8</version>
</requires>
- <requires>
- <type>plugin</type>
- <name>profile</name>
- <version>1.0</version>
- </requires>
-
- <requires>
- <type>plugin</type>
- <name>profile_api</name>
- <version>1.3</version>
- <comparison>lt</comparison>
- </requires>
-
- <requires>
- <type>priority</type>
- <priority>after</priority>
- <plugin>blog</plugin>
- </requires>
-
- <conflicts>
- <type>plugin</type>
- <name>profile_api</name>
- <version>1.0</version>
- </conflicts>
-
- <provides>
- <type>plugin</type>
- <name>profile_api</name>
- <version>1.3</version>
- </provides>
-
- <provides>
- <type>php_extension</type>
- <name>curl</name>
- <version>1.0</version>
- </provides>
+ <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..ea1e894b2
--- /dev/null
+++ b/documentation/examples/plugins/start.php
@@ -0,0 +1,12 @@
+<?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
+
+}
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
diff --git a/documentation/stubs/config.php b/documentation/info/config.php
index 19e76c8ae..19e76c8ae 100644
--- a/documentation/stubs/config.php
+++ b/documentation/info/config.php
diff --git a/documentation/info/manifest.xml b/documentation/info/manifest.xml
new file mode 100644
index 000000000..baa6cc3fa
--- /dev/null
+++ b/documentation/info/manifest.xml
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
+ <name>My Plugin</name>
+ <author>Elgg</author>
+ <version>1.0</version>
+ <blurb>A concise description.</blurb>
+ <description>This is a longer, more interesting description of my plugin, its features, and other important information.</description>
+ <website>http://www.elgg.org/</website>
+ <copyright>(C) Elgg 2011</copyright>
+ <license>GNU General Public License version 2</license>
+
+ <requires>
+ <type>elgg_version</type>
+ <version>2009030802</version>
+ </requires>
+
+ <requires>
+ <type>elgg_release</type>
+ <version>1.8</version>
+ </requires>
+
+ <screenshot>
+ <description>An example screenshot</description>
+ <path>graphics/plugin_ss1.png</path>
+ </screenshot>
+
+ <screenshot>
+ <description>Another screenshot</description>
+ <path>graphics/plugin_ss2.png</path>
+ </screenshot>
+
+ <category>admin</category>
+ <category>api</category>
+
+ <requires>
+ <type>php_extension</type>
+ <name>gd</name>
+ </requires>
+
+ <requires>
+ <type>php_ini</type>
+ <name>short_open_tag</name>
+ <value>off</value>
+ </requires>
+
+ <requires>
+ <type>php_extension</type>
+ <name>made_up</name>
+ <version>1.0</version>
+ </requires>
+
+ <requires>
+ <type>plugin</type>
+ <name>fake_plugin</name>
+ <version>1.0</version>
+ </requires>
+
+ <requires>
+ <type>plugin</type>
+ <name>profile</name>
+ <version>1.0</version>
+ </requires>
+
+ <requires>
+ <type>plugin</type>
+ <name>profile_api</name>
+ <version>1.3</version>
+ <comparison>lt</comparison>
+ </requires>
+
+ <requires>
+ <type>priority</type>
+ <priority>after</priority>
+ <plugin>blog</plugin>
+ </requires>
+
+ <conflicts>
+ <type>plugin</type>
+ <name>profile_api</name>
+ <version>1.0</version>
+ </conflicts>
+
+ <provides>
+ <type>plugin</type>
+ <name>profile_api</name>
+ <version>1.3</version>
+ </provides>
+
+ <provides>
+ <type>php_extension</type>
+ <name>curl</name>
+ <version>1.0</version>
+ </provides>
+
+</plugin_manifest>