Updated ECML docs.

Removed the _ as a valid keyword character (it looks funny).
Added the media sites in start.php.
Fixed bug that prevented [[view]] from working.  Consequently, [[view]] now requires a src="" attribute.


git-svn-id: http://code.elgg.org/elgg/trunk@5740 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 101 insertions, 64 deletions

diff --git a/mod/ecml/README.txt b/mod/ecml/README.txt
index 12b6a1c8b..c72e8c0c4 100644
--- a/mod/ecml/README.txt
+++ b/mod/ecml/README.txt
@@ -1,113 +1,150 @@
-ECML - Elgg Custom Markup Language
+ECML - Elgg Customizable 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
+	2.  Security
+	3.  Using ECML Keywords
+		3.1  Utility keywords 'entity' and 'view'
+		3.2  Embedded 3rd party media
+	4.  Custom ECML Keywords
+	5.  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
+	control panel can be used to granularly allow ECML keywords in certain
 	contexts and views.
 
 
-2.  USING ECML KEYWORDS
+2.  SECURITY
+
+	From the ECML control panel in the administration section the
+	administrator can select which sections of the site support
+	ECML.  For each section registered to display ECML, the administrator
+	can select which keywords to deny.  For example, this is useful to
+	prevent users from inserting an Elgg view into a blog page.
+
+3.  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.
+	Examples:
+		[[userlist]] -- Display up to 10 newest users.
+		[[youtube src="http://www.youtube.com/watch?v=kCpjgl2baLs"]] -- Embed a YouTube video.
+		[[view src="input/text"]] -- Display a textarea
 
-		[[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.
+3.1  UTILITY KEYWORDS 'entity' AND 'view'
 
+	ECML includes a few built-in keywords to get you started.  They are
+	mainly for embedding content from 3rd party sites, but also include
+	two utility views to help non-programmers quickly display content.
 
-2.1  BUILT-IN KEYWORDS
+	The two utility keywords available are [[entity]] and [[view]].
 
-	ECML includes a few built-in keywords to get you started:
-		[[entity]] - Displays a list of users.
+	[[entity]] - Displays a list of entities using similar arguments to the
+	elgg_get_entities() function.  See documentation for that function for
+	the full list of supported arguments and default values.
 
-		[[view]] - Shows the total members in your site, the currently
-						active members, and other fun stuff.
+	Additional / changed parameters supported by keywords:
+		* owner: The username owner. (You can still use owner_guid)
 
+	Example: Displays a list of all blog posts by the user named 'admin':
+		[[entity type=object subtype=blog owner=admin]]
 
-2.2  Entities
+	Example: Displays newest group created:
+		[[entity type=object subtype=group limit=1]]
 
-	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)
+	[[view]] - Displays a valid Elgg view passing any optional parameters to
+	the view.
+
+	Example: Display a text input:
+		[[view src="input/text"]]
+
+	Example: Display a textarea with a default value:
+		[[view src="input/longtext" value="This is an example of a quoted value!"]]
+
 
-	Example: To generate a list of all blog posts by the user named 'admin':
-		[[entities: type=object, subtype=blog, owner=admin]]
+3.2  EMBEDDED 3RD PARTY MEDIA
 
-	Example: To show newest group created:
-		[[entities: type=object, subtype=group, limit=1]]
+	ECML provides support for embedding media from a few of the most common
+	media sites:
 
+	* Youtube -- [[youtube src="URL"]]
+	* Vimeo -- [[vimeo src="URL"]]
+	* Slideshare -- [[slideshare id="ID"]] (NB: Use the "wordpress.com" embed
+	link surrounded by two [[s and ]]s.)
 
-2.1 Views
 
-	Keywords support outputting arbitrary views with the [[view]] keyword and
-	supports passing arguments as name=value pairs.
+4  CUSTOM ECML KEYWORDS (AKA "THE 'C' in ECML)
 
-	Example: Output a text input field with a default value:
-		[[view: input/text, value=This is a test!]]
+	Plugins can add their own ECML keywords.  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.
 
-	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.
+	To register your own ECML keywords, reply to the 'get_keywords'
+	hook of type 'ecml' and append to the passed array with a key that is
+	your keyword name and a value that is an array of a description and view.
 
+	Arguments passed to the keyword are accessible to the keyword view via
+	the $vars array.  It is	the responsibility of the custom view to parse
+	these arguments.
 
-3.0  CUSTOM FRONT PAGE KEYWORDS
+	The below example creates the 'buttonizer' keyword that turns the user's
+	text into an HTML button.  It uses the view at 'buttonizer/ecml/buttonizer.'
 
-	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.
+	How a user will call the keyword:
 
-	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.
+		[[buttonizer text="This is my button!"]]
 
-	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.
+	How to implement this in a plugin:
 
-	Example:
-		register_plugin_hook('get_keywords', 'sitepages', 'my_plugin_keywords');
+		buttonizer/start.php:
+			register_plugin_hook('get_keywords', 'ecml', 'buttonizer_ecml_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'
-			);
+			function buttonizer_ecml_keywords($hook, $type, $value, $params) {
+				$value['buttonizer'] = array(
+					'view' => 'buttonizer/ecml/buttonizer',
+					'description' => 'Makes your text a button!  What could be better?'
+				);
 
-			return $value;
-		}
+				return $value;
+			}
 
+		buttonizer/views/default/buttonizer/ecml/buttonizer.php:
+			$text = $vars['text'];
 
-4.  HINTS AND QUIRKS
+			echo elgg_view('input/button', array(
+				'value' => $text,
+				'type' => 'button'
+			));
+
+	This is exactly the same as saying:
+
+		[[view src="buttonizer/ecml/buttonizer" text="This is my button!"]]
+
+	but is much simpler for the user.
+
+
+5.  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.
+	* A custom keyword is safer.  Since ECML can be disabled for certain
+	views, many administrators disable the entity and view keywords in
+	user-accessible pages like blogs, pages, and files.
+
+	* Custom keywords can contain only alphanumeric characters.
+
+	* To pass a complex argument to a keyword, quote the value.
 
-	* 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.
+	* If making a custom keyword, avoid underscores in your params.  They
+	look funny.