Programatically render template area in Magnolia CMS
Problem
I am using Magnolia CMS 5.4 and I want to build a module that will render some content of a page and expose it over REST API. The task is simple but not sure how to approach it and/or where to start.
I want my module to generate partial template or an area of a template for a given reference, let’s say that is “header”. I need to render the header template/area get the HTML and return that as a response to another system.
Solution
First thing the rendering works based on different renderers and those could be JCR, plain text or Freemarker renderer. In Magnolia those are decided and used in RenderingEngine and the implementation: DefaultRenderingEngine. The rendering engine will allow you to render a whole page node which is one step closer to what I am trying to achieve. So let’s see how could this be done:
I’ll skip some steps but I’ve added command and made that work over REST so I could see what’s happening when I send a request to the endpoint. The command extends BaseRepositoryCommand to allow access to the JCR repositories.
This creates your rendering engine and from here you can start rendering nodes with few small gotchas. I’ve tried injecting the rendering engine directly but that didn’t work as all of the internals were empty/null so decided to grab all construct properties and initialise my own version.
Next step is we want to render a page node. First of all the rendering engine works based on the idea it’s rendering for a HttpServletResponse and ties to the request/response flow really well, though we need to put the generated markup in a variable so I’ve added a new implementation of the FilteringResponseOutputProvider:
So idea of the class is to expose the output stream and still preserve the FilteringAppendableWrapper that will allow us the filter the content we want to write. This is not needed in the general case, you can stick to using AppendableOnlyOutputProvider with StringBuilder appendable and easily retrieve the entire page markup.
Once you have the output provider you need a page node and since you are faking it you need to set the Magnolia global env to be able to retrieve the JCR node:
Now we have the content provider and the node we want to render next thing is actually running the rendering engine:
And that’s it, you should have your content rendered and you can use it as you wish.
Now we come to my special case where I want to render just an area of the whole page in this case this is the Header of the page. This is all handled by same renderingEngine though you need to add a rendering listener that overrides the writing process. First inject it in the command:
This is where the magic happens, the AreaFilteringListener will check if you are currently rendering the requested area and if you do it enables the output provider for writing otherwise keeps it locked and skips all unrelated areas. You need to add the listener to the rendering engine like so:
I hear you ask: “But where do we specify the area to be rendered?”, aha here it comes:
The area filtering listener is checking for a specific Magnolia context property to be set: “mgnlArea” if that’s found it will read its value and use it as an area name, check if that area exists in the node and then enable writing once we hit the area. This could be also used through URLs like: https://demopublic.magnolia-cms.com/~mgnlArea=footer~.html and this will give you just the footer area generated as an HTML page.
Interesting article, very useful thanks