Overriding a macro

Macros can be overridden with the override_macro construct. The best way to explain this concept is by looking at some code. Let's assume we have a macro like this:

<macro name="hello_world">
	Hello <b>world</b>
</macro>

If you want to change what the hello_world macro does, you can override it. Here is an example:

<override_macro name="hello_world">
	Hello WORLD
</override_macro>

With this code, any call to the hello_world macro will print "Hello WORLD" instead of "Hello world". The original code will be completely ignored in this case. If you want to reuse the original code, you should use the overridden command explained below.

It is important to remember that the signature of the macro must be kept intact while overriding it. In other words, you must keep the same parameters and everything else it may have defined. For example, consider this macro:

<macro name="badge" dot_parameter="intro" parameters="title, subject" requires="user">
    ...
</macro>

If you want to override it, you must keep its definition intact, except that now you will use the override_macro tag instead of macro:

<override_macro name="badge" dot_parameter="intro" parameters="title, subject" requires="user">
    ...
</override_macro>

You should also note that a macro can be overridden more than once. So this works:

<macro name="hello_world">
	Hello <b>world</b>
</macro>

<override_macro name="hello_world">
	Hello WORLD
</override_macro>

<override_macro name="hello_world">
	HELLO WORLD
</override_macro>

If you call the hello_world macro above, the result is unpredictable. It may return "Hello WORLD" or "HELLO WORLD" and you will never know what is going to happen until you call it. Multiple overrides like that are only useful when you want to keep adding new code to the chain, but before explaining more about this we must stop and have a look at the overridden command.

The overridden Command

When you override a macro, you can always call the original code with the overridden command. Let's look at a simple example:

<macro name="site_header">
	Welcome to my website.
</macro>

<override_macro name="site_header">
	<n.overridden/>
	Here you can find great articles!
</override_macro>

With this code, the site_header macro now prints the full message: "Welcome to my website. Here you can find great articles!". The overridden command reuses the original code while avoiding duplication. Now let's look at a macro that has parameters:

<macro name="site_header" parameters="name">
	Hi <n.name/>, welcome to my website.
</macro>

<override_macro name="site_header" parameters="name">
	<n.overridden name="[n.name/]"/>
	Here you can find great articles!
</override_macro>

As you can see, it is possible to call the overridden command with parameters. The parameters you can use are those defined by the original macro. In the example above, the "name" parameter is forwarded to the overridden call in order to keep the original header working as before. This is usually what we want in practice, but keep in mind that any value can be passed to those parameters.