Handling configurable default parameters in a macro

Help / Discuss
1

I’m working on a macro that provides an administration section for setting the default values.

To simplify, let’s say I’m writing a letteravatar macro that takes a name and that show the initials of this name: {{letteravatar name="Alex Smith" /}}, that would show “AS” in a circle. Their should be a parameter that allows setting a background, like this: {{letteravatar name="Alex Smith" background="yellow" /}}. If a background parameter is not provided, a default background should be used. I want this default background to be configurable.

The solution I see is to:

  • define a background parameter (WikiMacroParameterClass) for this macro, with no default value and set the parameter as non mandatory
  • define a configuration class that allows the user to set a default value in the administration page
  • fallback to a hard-coded default value in the macro’s code in case the configuration is missing (this is mostly defensive programming and the fallback default value should never be used normally).

This allows the user not to specify the parameter if they don’t need to, and the wysiwyg editor not to add the background parameter when adding the macro with it. However, this has an important drawback: the user does not see the default parameter value when using the WYSIWYG editor, and any automated tool neither. For instance, a documentation tool trying to get the default values won’t find them and may “think” the default values are the empty string. Another drawback is that this requires setting the default values in the macro code, in the parameter definitions and in the configuration class.

What would be a way to cleanly achieve configurable default parameters? Should I avoid this default configuration?

2

What you can do is define an advanced background parameter (annotate it as PropertyAdvanced - see https://extensions.xwiki.org/xwiki/bin/view/Extension/Properties%20Module#HPopulateaJavaBean - so that it’s not visible to users unless they show advanced parameters - advanced params might only be “hidden” when there are more than 5 params, I don’t remember) and in its description say that if not defined, it’ll default to the default value specified. Then in the Macro Parameter Descriptor for background compute the default value by getting its value from the configuration parameter. By doing this the WYSIWYG will display the default value.

3

Note that you’ll need to write it in java.

4

Thanks @vmassol, I’ll look into this! Sorry, I see your reply just now.