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

4 files changed, 109 insertions, 92 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.
 
diff --git a/mod/ecml/ecml_functions.php b/mod/ecml/ecml_functions.php
index f0dcafa24..e818a8f99 100644
--- a/mod/ecml/ecml_functions.php
+++ b/mod/ecml/ecml_functions.php
@@ -42,9 +42,11 @@ function ecml_parse_view_match($matches) {
 			break;
 
 		case 'view':
-			// parses this into an acceptable array for $vars.
-			$info = ecml_keywords_parse_view_params($params_string);
-			$content = elgg_view($info['view'], $info['vars']);
+			// src is a required attribute of view
+			$vars = ecml_keywords_tokenize_params($params_string);
+			$vars['ecml_keyword'] = $keyword;
+			$vars['ecml_params_string'] = $params_string;
+			$content = elgg_view($vars['src'], $vars);
 
 			break;
 
@@ -166,28 +168,6 @@ function ecml_keywords_tokenize_params($string) {
 }
 
 /**
- * Extract the view and vars for view: keyword
- *
- * @param $string
- * @return array views, vars
- */
-function ecml_keywords_parse_view_params($string) {
-	$vars = ecml_keywords_tokenize_params($string);
-
-	// the first element key is the view
-	$var_keys = array_keys($vars);
-	$view = $var_keys[0];
-
-	$info = array(
-		'view' => $view,
-		'vars' => $vars
-	);
-
-	return $info;
-
-}
-
-/**
  * Returns an options array suitable for using in elgg_get_entities()
  *
  * @param string $string "name=value, name2=value2"
diff --git a/mod/ecml/manifest.xml b/mod/ecml/manifest.xml
index 266dbcc17..f74c78de0 100644
--- a/mod/ecml/manifest.xml
+++ b/mod/ecml/manifest.xml
@@ -3,7 +3,7 @@
 	<field key="name" value="ECML V2" />
 	<field key="author" value="Curverider" />
 	<field key="version" value="1.0" />
-	<field key="description" value="Elgg Custom Markup Language v2 adds support for easy customization of pages and embedding media." />
+	<field key="description" value="Elgg Customizable Markup Language v2 adds support for easy customization of pages and embedding media." />
 	<field key="category" value="service" />
 	<field key="category" value="official" />
 	<field key="provides" value="ecml2" />
diff --git a/mod/ecml/start.php b/mod/ecml/start.php
index 51082e9c6..d1a86f82b 100644
--- a/mod/ecml/start.php
+++ b/mod/ecml/start.php
@@ -110,7 +110,7 @@ function ecml_parse_view($hook, $entity_type, $return_value, $params) {
 
 	// give me everything that is not a ], possibly followed by a :, and surrounded by [[ ]]s
 	//$keyword_regex = '/\[\[([a-z0-9_]+):?([^\]]+)?\]\]/';
-	$keyword_regex = '/\[\[([a-z0-9_]+)([^\]]+)?\]\]/';
+	$keyword_regex = '/\[\[([a-z0-9]+)([^\]]+)?\]\]/';
 	$CONFIG->ecml_current_view = $params['view'];
 	$return_value = preg_replace_callback($keyword_regex, 'ecml_parse_view_match', $return_value);
 
@@ -128,7 +128,7 @@ function ecml_parse_view($hook, $entity_type, $return_value, $params) {
  * @return unknown_type
  */
 function ecml_keyword_hook($hook, $entity_type, $return_value, $params) {
-	$keywords = array('youtube', 'slideshare', 'vimeo');
+	$keywords = array('entity', 'view', 'youtube', 'slideshare', 'vimeo');
 
 	foreach ($keywords as $keyword) {
 		$return_value[$keyword] = array(