From 444fb4e8a3e5189868b8b12c5fdccc4bef6868fc Mon Sep 17 00:00:00 2001
From: brettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>
Date: Tue, 13 Apr 2010 19:13:36 +0000
Subject: First version of ecml.

git-svn-id: http://code.elgg.org/elgg/trunk@5722 36083f99-b078-4883-b0ff-0f9b5a30f544
---
 mod/ecml/README.txt | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 mod/ecml/README.txt

(limited to 'mod/ecml/README.txt')

diff --git a/mod/ecml/README.txt b/mod/ecml/README.txt
new file mode 100644
index 000000000..12b6a1c8b
--- /dev/null
+++ b/mod/ecml/README.txt
@@ -0,0 +1,113 @@
+ECML - Elgg Custom Markup Language
+
+CONTENTS:
+	1.  Overview
+	2.  Using ECML Keywords
+		2.1  Built-in keywords
+		2.2  Entities
+		2.3  Views
+	3.  Custom ECML Keywords
+	4.  Hints and Quirks
+
+
+1.  OVERVIEW
+
+	ECML adds support for an extensible keyword	system that allows users
+	to quickly add elements and embed media in their content.  The ECML
+	control panel can be used to granualarly allow ECML keywords in certain
+	contexts and views.
+
+
+2.  USING ECML KEYWORDS
+
+	All ECML keywords are surrounded by two square brackets: [[ and ]].
+	Some keywords, like views and entity lists, take optional parameters.
+
+	Example:
+		[[user_list]] -- Display up to 10 newest users.
+
+		[[user_list: list_type=online]] -- Display up to 10 active users.
+
+		[[user_list: list_type=online, only_with_avatars=true]] -- Display
+			up to 10 active users who have uploaded avatars.
+
+
+2.1  BUILT-IN KEYWORDS
+
+	ECML includes a few built-in keywords to get you started:
+		[[entity]] - Displays a list of users.
+
+		[[view]] - Shows the total members in your site, the currently
+						active members, and other fun stuff.
+
+
+2.2  Entities
+
+	You can generate a list of entities by using the [[entity]] keyword.  This
+	keyword takes similar arguments to the elgg_get_entities() function.  See
+	documentation in that function for a complete list.
+
+	Additional / changed parameters supported by keywords:
+	* owner: The username owner. (You can still use owner_guid)
+
+	Example: To generate a list of all blog posts by the user named 'admin':
+		[[entities: type=object, subtype=blog, owner=admin]]
+
+	Example: To show newest group created:
+		[[entities: type=object, subtype=group, limit=1]]
+
+
+2.1 Views
+
+	Keywords support outputting arbitrary views with the [[view]] keyword and
+	supports passing arguments as name=value pairs.
+
+	Example: Output a text input field with a default value:
+		[[view: input/text, value=This is a test!]]
+
+	NB: Do NOT quote the name or values when passing them.  Also, as of 1.8
+	using commas or = in the name or value is unsupported.
+
+
+3.0  CUSTOM FRONT PAGE KEYWORDS
+
+	Plugins can add their own keywords by replying to the 'get_keywords' hook
+	of type 'sitepages.'  Each keyword must be bound to a valid view.  Almost
+	all functionality in custom keywords could be implemented using the 'view'
+	keyword, but custom keywords provide a simple way for non-techy users to
+	include ready-made views without the fuss of knowing what they're doing.
+
+	Custom keywords support arguments in the same format as views and entities.
+	These arguments are passed to the custom view via the $vars array.  It is
+	the responsibility of the custom view to parse these arguments.
+
+	The below example creates the 'my_plugin_keyword' keyword that displays the
+	view at 'my_plugin/keyword_view.'  This is exactly the same as saying
+	[[view: my_plugin/keyword_view]] but much simpler for the user.
+
+	Example:
+		register_plugin_hook('get_keywords', 'sitepages', 'my_plugin_keywords');
+
+		function my_plugin_keywords($hook, $type, $value, $params) {
+			$value['my_plugin_keyword'] = array(
+				'view' => 'my_plugin/keyword_view',
+				'description' => 'Provides the awesome My Plugin keyword'
+			);
+
+			return $value;
+		}
+
+
+4.  HINTS AND QUIRKS
+
+	* A custom keyword is slightly more complicated to implement, but is
+	much simpler for the end user to use.
+
+	* Custom keywords can contain only alphanumeric and the underscore
+	character.
+
+	* All keywords have limited support for passing arguments but the arguments
+	cannot contain '=' or ','.  If you need complicated arguments for a custom
+	keyword, it's better to split the functionality into multiple keywords and
+	views instead of requiring complicated arguments.
+
-- 
cgit v1.2.3