helma.org/wiki/New Skin Features in Helma 1.6

Version 21

hannes — Wed, 02 May 2007 15:35:38 +0000

51	=== Processed parameters and nested Nested Macros ===
53	Helma 1.6 introduces features to automatically process supports nested macros as macro tag parameters before passing them to the macro function. If a macro parameter is wrapped as <code>$[name]</code>, the value is replaced with the object registered in <code>res.handlers</code> with that namevalues.
54
55	<% page.image linkto=$[handlerName] %>
56
57	If a macro paramter is wrapped as <code>$(...)</code>, it is passed to a callback <code>app.processMacroParameter</code>. The callback takes the unprocessed parameter value as argument and returns the processed value.
58
59	app.processMacroParameter = function(value) {
60	if (value == "header")
61	return "<h1>Page List</h1>";
62	}
63
64	<% page.list prefix=$(header) %>
65
66	Helma 1.6 also allows macros as macro parameter values.

Version 20

hannes — Thu, 05 Apr 2007 00:20:42 +0000

84	The first is the <code>unhandledMacro</code> <code>onUnhandledMacro</code> callback. If this is defined (in the global scope or on the handler object, depending on whether the macro is global or not), it is invoked with the name of the unhandled macro, followed by the macro parameters.
86	function unhandledMacro(nameonUnhandledMacro(name, param)
94	Note that <code>unhandledMacro</code> <code>onUnhandledMacro</code> is only invoked if Helma was actually able to resolve the handler object, i.e. everything up to the actual macro name.

Version 19

hannes — Wed, 04 Apr 2007 15:23:08 +0000

80	=== Fix quoted parameter parsing ===
81
82	In Helma 1.5 and earlier, a "%>" sequence was interpreted as macro end tag even if it was contained in a quoted parameter string. Helma 1.6 fixes this, making it possible to pass strings containing macro tags as parameter values to be rendered as skin by the macro function.
83
103
104	=== Namespaces for global macros ===
105
106	It is now possible to use global macros that are defined in a namespace as opposed to the global scope itself.
107
108	app.globalMacroPath = ["myapp.macros", "helma.macros", ""];
109
110	Helma will loop through the namespaces defined in app.globalMacroPath until it finds the macro or filter it is looking for.
111
112	=== Fix quoted parameter parsing ===
113
114	In Helma 1.5 and earlier, a "%>" sequence was interpreted as macro end tag even if it was contained in a quoted parameter string. Helma 1.6 fixes this, making it possible to pass strings containing macro tags as parameter values to be rendered as skin by the macro function.

Version 18

hannes — Wed, 04 Apr 2007 14:56:00 +0000

19	=== Macro pipes/filters filters ===
25	Filter functions must have a _filter suffix and get two arguments: the return value of the previous macro/filter macro or filter in the chain, and a parameter object with the attributs in the filter tag. They are expected to return the filtered macro output. Macro and filter return values are converted to string only at the end of the chain. It is therefore possible to pass other objects between macros and filters:
41	=== Deep/Reach-through macro invocation Deep macros ===

Version 17

hannes — Wed, 04 Apr 2007 14:51:00 +0000

3	=== Subskins ===
4
5	It is now possible to have multiple skins in one skin resource. Subskins are delimited using a <code><% #subname %></code> tag.
6
7	main skin body
8	<% #subskin1 %>
9	subskin 1 body
10	<% #subskin2 %>
11	subskin 2 body
12
13	Subskins can be referenced from the outside as "skinname#subname". While a skin or subskin is being rendered (i.e. from macros contained in that skin), it is possible to reference other local subskins just using "#subname". Skin objects also provide a getSubskin() method\|http://helma.zumbrunn.net/reference/Skin.html.
14
15	renderSkin("mainskin");
16	renderSkin("mainskin#subskin1");
17	renderSkin(skin.getSubskin("subskin2"));
18
6	Helme 1.6 introduces a new filter feature to further process macro output.
7
12
17	function format_filter(argformat_filter(date, param)
18	return argdate.format();
30	Since deep macro invocation poses a potential security risk for applications that support skins by untrusted users, this feature The handler object path is disabled resolved by default calling method <code>getMacroHandler(name)</code> successively on each handler path element. The method takes the next path element as string and must be enabled with is supposed to return the allowDeepMacros setting in appnext path element, similar to getChildElement(name) for request path resolution.properties or server.properties file:
32	For untyped JavaScript objects, macro path resolution also works in an autmatic way by following object properties. allowDeepMacros =For prototyped HopObjects, truethis mechanism is disabled because of security considerations.
34	=== Nested Processed parameters and nested Macros ===
36	Helma 1.6 allows macros as introduces features to automatically process macro attribute valuestag parameters before passing them to the macro function. If a macro parameter is wrapped as <code>$[name]</code>, the value is replaced with the object registered in <code>res.handlers</code> with that name.
38	<% page.image linkto=$[handlerName] %>
39
40	If a macro paramter is wrapped as <code>$(...)</code>, it is passed to a callback <code>app.processMacroParameter</code>. The callback takes the unprocessed parameter value as argument and returns the processed value.
41
42	app.processMacroParameter = function(value) {
43	if (value == "header")
44	return "<h1>Page List</h1>";
45	}
46
47	<% page.list prefix=$(header) %>
48
49	Helma 1.6 also allows macros as macro parameter values.
50
55	=== New standard failmode attribute Unhandled macros ===
57	Helma macros support a 1.6 introduces two new standard attribute, in addition to <code>prefix</code>, <code>suffix</code>, <code>default</code> and <code>encoding</code>features for dealing with unhandled macros.
59	The <code>failmode</code> attribute,first is the <code>unhandledMacro</code> callback. if definedIf this is defined (in the global scope or on the handler object, will cause error messages for failed depending on whether the macro is global or unresolved macros to be generated or suppressednot), it is invoked with the name of the unhandled macro, followed by the macro parameters.
61	function unhandledMacro(name, param) {
62	if (name == "dynamacro") {
63	// actually do something useful
64	} else {
65	return "oops, unhandled macro " + name;
66	}
67	}
68
69	Note that <code>unhandledMacro</code> is only invoked if Helma was actually able to resolve the handler object, i.e. everything up to the actual macro name.
70
71	If a macro is not defined, and no <code>undefinedMacro</code> method is defined on the handler object, the generation of an error message can be controlled using the <code>failmode</code> attribute. If defined, it will cause error messages for failed or unresolved macros to be generated or suppressed.
72
67	=== Compatibility and Security issues ===
71	===The one know security implication introduced by the new features is with deep/reach-through macro invocation and untrusted skin authors, Security issues ===since it allows skin authors to reach objects that may not be meant to be reached. This is why automatic property walkthrough is disabled for prototyped HopObjects.
73	The one know security implication introduced by the new features is with deep/reach-through macro invocation and untrusted skin authors, since it allows skin authors to reach objects that may not be meant to be reached. Therefore, this feauture is disabled by default and must be activated using the allowDeepMacros property.
74
76	=== Known bugs ===

Version 16

hannes — Tue, 20 Mar 2007 12:34:55 +0000

41	=== Fix quoted parameter parsing ===
42
43	In Helma 1.5 and earlier, a "%>" sequence was interpreted as macro end tag even if it was contained in a quoted parameter string. Helma 1.6 fixes this, making it possible to pass strings containing macro tags as parameter values to be rendered as skin by the macro function.
44
49
50	=== Fix quoted parameter parsing ===
51
52	In Helma 1.5 and earlier, a "%>" sequence was interpreted as macro end tag even if it was contained in a quoted parameter string. Helma 1.6 fixes this, making it possible to pass strings containing macro tags as parameter values to be rendered as skin by the macro function.

Version 15

hannes — Tue, 20 Mar 2007 12:34:12 +0000

41	=== Fix quoted parameter parsing ===
42
43	In Helma 1.5 and earlier, a "%>" sequence was interpreted as macro end tag even if it was contained in a quoted parameter string. Helma 1.6 fixes this, making it possible to pass strings containing macro tags as parameter values to be rendered as skin by the macro function.
44

Version 14

hannes — Tue, 20 Mar 2007 12:18:51 +0000

29	Since deep macro invocation poses a potential security risk for applications that support skins by untrusted users, this feature is disabled by default and must be enabled with the allowDeepMacros setting in app.properties or server.properties file:
30
31	allowDeepMacros = true
32
38	=== Positional macro arguments parameters ===
42	<% image "dancer.gif" alt="Maggie Helma dancing her feet off" %>
63	The one know security implication introduced by the new features is with deep/reach-through macro invocation and untrusted skin authors, since it allows skin authors to reach objects that may not be meant to be reached. It is therefore planned to implement an application property that allows to switch Therefore, this feature offfeauture is disabled by default and must be activated using the allowDeepMacros property.

Version 13

hannes — Mon, 19 Mar 2007 17:57:54 +0000

43	function dancer_macro(paramimage_macro(param, imageName) { ...
45	=== New standard failmode attribute ===

Version 12

hannes — Mon, 19 Mar 2007 17:56:12 +0000

37	=== Positional macro arguments ===
38
39	In addition to named parameters, macro functions can now be invoked with positional parameters. If the attribute name and equals sign is omitted from an parameter, it is interpreted as positional parameter. Positional parameters are passed to macro and filter functions after the parameter object containing any named parameters.
40
41	<% image "dancer.gif" alt="Maggie dancing her feet off" %>
42
43	function dancer_macro(param, imageName) { ... }
44
61	Currently, the default attribute is never used for property macros.

Version 11

hannes — Fri, 16 Mar 2007 20:36:12 +0000

19	//You You can use regular expressions directly as filters:
20
56
57	=== Known bugs ===
58
59	Currently, the default attribute is never used for property macros.

Version 10

klemens — Fri, 16 Mar 2007 17:53:29 +0000

19	//You can use regular expressions directly as filters:
20
21	var regexp_filter = new RegExp("\\w*");
22

Version 9

zumbrunn — Fri, 16 Mar 2007 12:22:33 +0000

52	The other new features should not affect security, since it just allows to call macros that were already callable before. The skin sandboxing feauture feature hasn't changed and works the same as before. Macro filters are currently not affected by the sandbox.

Version 8

hannes — Fri, 16 Mar 2007 11:29:39 +0000

50	The one know security implication introduced by the new features is with deep/reach-through macro invocation and untrusted skin authors, since it allows skin authors to reach objects that may not be meant to be reached. It is therefore planned to implement an application property that allows to switch this feature off.
51
52	The other new features should not affect security, since it just allows to call macros that were already callable before. The skin sandboxing feauture hasn't changed and works the same as before. Macro filters are currently not affected by the sandbox.

Version 7

hannes — Fri, 16 Mar 2007 11:23:08 +0000

Version 6

hannes — Fri, 16 Mar 2007 11:23:02 +0000

7	Filter functions must have a _filter suffix and get two arguments: the return value of the previous macro/filter in the chain, and a parameter object with the attributs in the filter tag. They are expected to return the filtered macro output. Macro and filter return values are converted to string only at the end of the chain. It is therefore possible to pass other objects between macros and filters:
9	<% now \| format %>
10
11	function now_macro(param) {
12	return new Date();
13	}
14
15	function format_filter(arg, param) {
16	return arg.format();
17	}
18
12	Helma 1.6 allows macros to be invoked over several property path links.
13
17	Helma 1.6 allows macros as macro attribute values.
18
20	The main reasons to reject this over the years have been that this is ugly, and that it results in unreadable skins. But then, isn't recursion one of the coolest concepts in programming? If you think it's ugly, just don't use it. Otherwise, it may save you a handsome amount of macro writing.
21
31
32	=== Compatibility issues ===
33
34	All the changes and new features in Helma 1.6 skins are backwards compatible with Helma 1.5.
35
36	=== Security issues ===
37
38	The

Version 5

hannes — Fri, 16 Mar 2007 11:12:03 +0000

1	Helma 1.6 contains a number of Skin/Macro enhancements that aim to make Helma's rendering infrastructure more flexible and powerful powerful.
3	==== Macro pipes/filterspipes/filters ===
9	==== Deep/Reach-through macro invocationinvocation ===
13	==== Nested MacrosMacros ===
17	==== failmode attributeattribute ===
19	New Helma macros support a new standard attribute: failmode=silent\|verbose.attribute, Default value is silent for request/response/session/param handlersin addition to <code>prefix</code>, <code>suffix</code>, <code>default</code> and verbose for app object handlers (mimicking implicit Helma 1<code>encoding</code>.5 behaviour)
20
21	The <code>failmode</code> attribute, if defined, will cause error messages for failed or unresolved macros to be generated or suppressed.
22
23	<% failLoudly failmode="verbose" %>
24	<% failQuitely failmode="silent" %>
25
26	The default value is silent for request/response/session/param handlers, and verbose for app object handlers (mimicking implicit Helma 1.5 behaviour).

Version 4

hannes — Fri, 16 Mar 2007 10:59:49 +0000

Version 3

hannes — Fri, 16 Mar 2007 10:59:41 +0000

Version 2

hannes — Fri, 16 Mar 2007 10:55:13 +0000

11	<% page.author.name %>

Version 1

hannes — Fri, 16 Mar 2007 10:54:54 +0000

Set tags to helma 1.6, Skin Rendering, templates

1	Helma 1.6 contains a number of Skin/Macro enhancements that aim to make Helma's rendering infrastructure more flexible and powerful
3	==== Macro pipes/filters
4
5	<% text \| truncate max="300" \| uppercase %>
6
7	Filter functions must have a _filter suffix and get two arguments: the return value of the previous macro/filter in the chain, and a parameter object with the attributs in the filter tag. They are expected to return the filtered macro output.
8
9	==== Deep/Reach-through macro invocation
10
11	<% page.author.name %
12
13	==== Nested Macros
14
15	<% page.link content=<% messages.storylink %> %>
16
17	==== failmode attribute
18
19	New standard attribute: failmode=silent\|verbose. Default value is silent for request/response/session/param handlers, and verbose for app object handlers (mimicking implicit Helma 1.5 behaviour)