.png)
Our Replace and Render plugin is a curious beast. It's a plugin that you won't know you need until you do and if used on its own it's next to useless. However, our customers describe it as a "vital part of [the] macro toolkit" and today I'm going to explain why.
|
The Replace and Render plugin is available for free, as part of our Essentials Plugin Pack for Confluence. It provides a set of macros that can be used to take the output of one macro and use it as the input for another. So when it's combined with other plugins and macros, it can really help you out of a hole, enabling you to create solutions that might otherwise require bespoke plugin development. Replace and Render is often used in conjunction with macros like the SQL and Run macros, as well as the Reporting and Scaffolding plugins. It can be the missing link between your macros and creating great custom reporting, automatically generated content and useful related links. |
|
|
Here's a few explained examples of what you can do with the Replace and Render plugin.
Auto-populate menus, with Replace and Render and the SQL macro
{replace-and-render}
{replace-item:%items%}
{sql:table=false}
select concat('{search-option:value=', valueFoo, '}',
valueFoo ,'{search-option}') FROM testFoo WHERE...
{sql}
{replace-item}
{replace-body}
{search-form}
{search-select:match=label}
%items%
{search-select}
{search-submit:Search}
{search-form}
{search-results}
{replace-body}
{replace-and-render}
|
|
Here we have some pseudo-code for the SQL macro that queries a database and outputs a list of values. The Replace and Render macro then takes these values and uses them as input in another plugin, in this case I've used the Advanced Search plugin. So for example, you could get a list of customers from a database, creating a drop down list of them to filter a space filled with customer reports. The benefit is that the list would update itself automatically - if you acquire a new customer - no problem, the menu will be updated automatically so long as they are in your database.
|
Generate a list of recent blogs by the author, with Replace and Render and the Reporting Plugin
|
In this example we use the report-info macro to get the current page creator's user name. This username is then passed to the replace and render macro which puts it into a report query, displaying recent blogs created by that user. You could then put this code in a theme template and have it automatically list other blogs produced by whoever wrote the blog.
|
|
{replace-and-render}
{replace-item:%page_author%}{report-info:content:
creator > user:name}{replace-item}
{replace-body}
{report-block:maxResults=50}
{content-reporter:spaces=@all|type=news}
{date-sort:content:modification date|order=descending}
{content-reporter}
{user-filter:content:creator|users=%page_author%}
{report-body}
* {report-info:content:title|link=true}
{report-body}
{report-block}
{replace-body}
{replace-and-render}
|
Display related Google News articles, with Replace and Render and User Macros
{replace-and-render}
{replace-item:%id%}{report-info:page:labels}{replace-item}
{replace-body}
{relatednews:%id%}
{replace-body}
{replace-and-render}
{relatednews} is a user macro, with no body, that produces
Wiki Markup - it takes labels passed to it, removes the
spaces and commas and passes that to the RSS macro:
#set($params = $param0)
#set($params = $params.split(', '))
#set($keywords = '')
#foreach($param in $params)
#set($keywords = $keywords + $param + '%20')
#end
#set($output="{rss:url=http://news.google.com/news?
output=rss&q=" + $keywords + "|showTitlesOnly=true|
titleBar=false|max=5}")
|
|
The Replace and Render plugin also works with user macros. In this example a list of Google News articles is created based on the labels on the current page. The report-info macros grab the page labels, it's then passed to the replace and render macro which allows the user macro to use them. The relatednews macro just removes the problematic spaces and commas and generates the RSS macro that grabs an RSS feed of search results based on the labels.
|
The examples above are only meant to illustrate the kinds of thing you can do with Replace and Render plugin - there may well be other better ways to achieve the example results with specific plugins. The point about them though, is that they show you how you could use the Replace and Render plugin along with other existing macros which you already know and understand, to gain plugin-like abilities, without having to create your own plugins.
This plugin works really well with the Advanced Search plugin configurations explained in my last blog. Why not check out what else Adaptavist plugins can do for you? Take a look at our range of Confluence plugins.
Get help with this plugin over on our Community site.
