Advanced content rendering

Using $page.renderContent() will output the content of the current page or blog post just like it is displayed in Confluence. When more control is needed over the HTML there are more methods that can be used to output $page.renderContent():

  • $page.renderContent(pageLayout)
  • $page.renderContent(pageLayout, macroOverrides)

Page Layouts

Page layouts are a powerful way for users to layout content in Confluence. Scroll Viewport allows templates to control how page layouts are rendered to HTML.

You can override the default pagelayout by creating a file called overrides/pagelayout.vm.

You don't have to reference that pagelayout when calling $page.renderContent, since it is the default.

To control the rendering of page layouts:

  1. Create a page layout template in overrides/grid-pagelayout.vm:

    $grids.setup(                                           ## Define styling information for each cell
        {                                                   ## in a particular page layout section
            "single": ["width: 1000px;"],
            "three_equal": ["width: 333px;", "width: 333px;", "width: 333px;"],
            "three_with_sidebars": ["width: 200px;", "width: 600px;", "width: 200px;"],
            "two_equal": ["width: 500px;", "width: 500px;"],
            "two_left_sidebar": ["width: 300px", "width: 700px"],
            "two_right_sidebar": ["width: 700px", "width: 300px"]
        }
    )
    
    #foreach($pageLayoutSection in $pageLayout.sections)    ## loop through the sections (stacked page layouts)
        <div>
        #foreach($cell in $pageLayoutSection.cells)         ## loop through the cells of each section and
                                                            ## access the styling information for each cell
            #set( $gridStyle = $grids.get($pageLayoutSection.type, $velocityCount) )
            <div style="$gridStyle">
                $cell.content
            </div>
        #end
        </div>
    #end
    CODE
  2. Where you are rendering the content, reference the page layout template like this:

    $page.renderContent("overrides/grid-pagelayout.vm")
    CODE

Macro Overrides

Macros in Confluence render their own HTML markup, which may or may not be suitable for a theme. Therefore Scroll Viewport provides a macro override that define how a macro is rendered.

To define and register a macro override:

  1. Create a macro override template in overrides/panels.vm:

    <div class="panel panel-default">
        #if($params.title)
            <div class="panel-heading">
                <h3 class="panel-title">$params.title</h3>
            </div>
        #end
        <div class="panel-body">
            $body
        </div>
    </div>
    CODE
  2. Where you are rendering the content, reference the page layout template like this:

    $page.renderContent("overrides/grid-pagelayout.vm", {
        "panel" : "overrides/panels.vm"
    })
    CODE

In the macro override template you can access the following placeholders:

  • $macroName – the name of the macro
  • $params – a map of parameters of the macro
  • $body – the body of the macro (null of macros with no body)
  • $stringUtils – org.apache.commons.lang.StringUtils
  • $stringEscapeUtils – org.apache.commons.lang.StringEscapeUtils

This approach only works for simple macros, because it makes only the macro parameters available to the rendering context, but does not execute the macro as such.

For more complex macros, please look at this issue and comment, vote (!) and watch: Unable to locate Jira server for this macro. It may be due to Application Link configuration.

HTML Manipulation

Confluence HTML markup contains some Confluence specific classes. If a CSS framework requires other classes, these need to be replaced.

There is no proper way to do that yet, but you can use $stringUtils to replace strings in the rendered content like this:

#set( $content = $page.renderContent("overrides/grid-pagelayout.vm", {
    "panel" : "overrides/panels.vm"
}))
$stringUtils.replace($content, "confluenceTable", "table table-striped");
CODE

Cookie Notice

We use cookies to create a secure and effective browsing experience for our website visitors and to understand how you use our site (i.e. Google Analytics). For more information:
Click Here

OK Don't track me.