diff options
Diffstat (limited to 'mod/ecml/README.txt')
-rw-r--r-- | mod/ecml/README.txt | 165 |
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. |