×

You're using an outdated browser

For a better experience, keep your browser up to date. Check here for the latest version.

Manual

Advanced content rendering

Matt Reiner

Matt Reiner Last update: Jul 3, 2019

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.

Info

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
  2. Where you are rendering the content, reference the page layout template like this:

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

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>
  2. Where you are rendering the content, reference the page layout template like this:

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

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

Info

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: VPRT-202

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");

2x2.11
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