1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
ECML - Elgg Customizable Markup Language
CONTENTS:
1. Overview
2. Security
3. Using ECML Keywords
3.1 Utility keywords 'entity' and 'view'
3.2 Embedded 3rd party media
4. Custom ECML Keywords
5. Embed support
6. 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 granularly allow ECML keywords in certain
contexts and views.
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 square brackets: [ and ].
Some keywords, like views and entity lists, take optional parameters.
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
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.
The two utility keywords available are [entity] and [view].
[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.
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]
Example: Displays newest group created:
[entity type=object subtype=group limit=1]
[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!"]
3.2 EMBEDDED 3RD PARTY MEDIA
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)
4 CUSTOM ECML KEYWORDS (AKA "THE 'C' in ECML)
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.
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 view, a description,
and usage instructions.
Optionally, the array can pass a 'restricted' => array() value of views
that this keyword is valid in. This is not overrideable by the admin
interface and is useful for forcing security on possibly dangerous
keywords.
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.
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.'
How a user will call the keyword:
[buttonizer text="This is my button!"]
How to implement this in a plugin:
buttonizer/start.php:
register_plugin_hook('get_keywords', 'ecml', 'buttonizer_ecml_keywords');
function buttonizer_ecml_keywords($hook, $type, $value, $params) {
$value['buttonizer'] = array(
'name' => 'Buttonizer',
'view' => 'buttonizer/ecml/buttonizer',
'description' => 'Makes your text a button! What could be better?',
'usage' => 'Use [buttonizer text="My text"] to make "My text" a button!'
);
return $value;
}
buttonizer/views/default/buttonizer/ecml/buttonizer.php:
$text = $vars['text'];
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!"]
or even:
[view src="input/button" value="This is my button!" type="button"]
but is much simpler for the user.
5. EMBED SUPPORT
ECML and the Embed plugin are closely related in that Embed serves
as a sort of front end for ECML. Especially with 3rd party web
services, where URLs and embed codes vary greatly, having a system
in place that allows a user to easily generate and insert ECML
is benificial.
Currently, only web services ECML keywords are supported in the
embed plugin. Registering a web service keyword looks like this:
$value[youtube] = array(
'name' => 'Youtube',
'view' => "ecml/keywords/youtube",
'description' => 'Embed YouTube videos',
'usage' => 'Use src="URL".',
// important bits
'type' => 'web_service',
'params' => array('src', 'width', 'height') // a list of supported params
'embed' => 'src="%s"' // a sprintf string of the require param format. Added automatically to [keyword $here]
);
6. HINTS AND QUIRKS
* A custom keyword is slightly more complicated to implement, but is
much simpler for the end user to use.
* 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.
* If making a custom keyword, avoid underscores in your params. They
look funny.
* Are disabled keywords in comments still working? This is probably
because a parent view is including comments directly. For example:
blog page handler:
...logic...
echo elgg_view_entity($blog);
...logic...
view object/blog:
...logic...
echo $blog;
echo elgg_view_comments($blog);
The output of object/blog includes the output of the comments, so if
the view object/blog allows the youtube the comments will also be parsed
for ECML. The solution is to keep views for the object and comments
separate.
blog page handler:
echo elgg_view_entity($blog);
...logic...
echo elgg_view_comments($blog);
view object/blog:
...logic...
echo $blog
Alternatively, you can keep the blog and comments in the object view, but
pull out the blog into its own view to register with ECML.
view object/blog:
...logic...
echo elgg_view('blog/blog', array('blog' => $blog);
...logic...
elgg_view_comments($blog);
view blog/blog:
...logic...
echo $blog
|
