diff options
| -rw-r--r-- | mod/ecml/README.txt | 165 | ||||
| -rw-r--r-- | mod/ecml/ecml_functions.php | 30 | ||||
| -rw-r--r-- | mod/ecml/manifest.xml | 2 | ||||
| -rw-r--r-- | mod/ecml/start.php | 4 |
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( |