aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorbrettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>2010-04-15 02:34:52 +0000
committerbrettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>2010-04-15 02:34:52 +0000
commitc7ef93621e50dc3d6ded212e076de510ec2a263f (patch)
treeecec9580e4cfe6fdb8b5857dae2078eec81aacc2
parent527c9dca0b5d71513adff8c7f8df6b88315bc6cf (diff)
downloadelgg-c7ef93621e50dc3d6ded212e076de510ec2a263f.tar.gz
elgg-c7ef93621e50dc3d6ded212e076de510ec2a263f.tar.bz2
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
-rw-r--r--mod/ecml/README.txt165
-rw-r--r--mod/ecml/ecml_functions.php30
-rw-r--r--mod/ecml/manifest.xml2
-rw-r--r--mod/ecml/start.php4
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(