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

diff --git a/mod/ecml/README.txt b/mod/ecml/README.txt
index 12b6a1c8b0629655bdaf1ce4eb45b2c480b4d1d6..c72e8c0c4b85c466208e7ca767e831b424441434 100644 (file)
--- 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 f0dcafa241dd32fd9f165f46841a1a9325d7ba77..e818a8f99103d94152dc0b170b94592020801a88 100644 (file)
--- 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;
 
@@ -165,28 +167,6 @@ function ecml_keywords_tokenize_params($string) {
 //     return $params;
 }
 
-/**
- * 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()
  *

diff --git a/mod/ecml/manifest.xml b/mod/ecml/manifest.xml
index 266dbcc17e8a90d7efdf02c068fafd65b2af16e7..f74c78de0b0201dec6a18c6fec3c7c493fbb8e68 100644 (file)
--- 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 51082e9c660e0e717672f5edb29934332696c1b4..d1a86f82bfd05cc836ce99e1be6e21e365e74692 100644 (file)
--- 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(