Creating a custom renderer for a Forms input

This document will describe how to create a custom renderer for a Forms input.

When saving a complex object to the value of an input, it is advised to create a renderer. A renderer will insure that the value of the input is displayed correctly and therefore is easily readable by the user.We will use the Rating Input as an example of how to implement your own renderer. 

In order to create a renderer, the first requirement is to create a definition that extends fcmix:renderer.

[fcnt:ratingRenderer] > jnt:content, mix:title, jmix:droppableContent, jmix:hiddenType, fcmix:renderer

Once the definition is in order, we can create the following structure in our project:

The .wzd file will be used by Forms to parse the component definition and the .jsp file will be the view for our renderer.

The contents of the .wzd file should reflect:

renderer {
   label "Rating Renderer"
   name "rating"
}

• Label: name of input (camelcased if necessary) followed by Renderer​
• Name: name of input (camelcased if necessary), value will be assigned to rendererName property of the created definition

The .jsp file houses the custom functionality of how to render the result of the input. For example, Rating renderer contains the following code:

<%@ taglib prefix="jcr" uri="http://www.jahia.org/tags/jcr" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="utility" uri="http://www.jahia.org/tags/utilityLib" %>
<%@ taglib prefix="template" uri="http://www.jahia.org/tags/templateLib" %>
<%@ taglib prefix="functions" uri="http://www.jahia.org/tags/functions" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
<%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>
<%@ taglib prefix="query" uri="http://www.jahia.org/tags/queryLib" %>

<%--@elvariable id="currentNode" type="org.jahia.services.content.JCRNodeWrapper"--%>
<%--@elvariable id="currentResource" type="org.jahia.services.render.Resource"--%>
<%--@elvariable id="flowRequestContext" type="org.springframework.webflow.execution.RequestContext"--%>
<%--@elvariable id="out" type="java.io.PrintWriter"--%>
<%--@elvariable id="renderContext" type="org.jahia.services.render.RenderContext"--%>
<%--@elvariable id="script" type="org.jahia.services.render.scripting.Script"--%>
<%--@elvariable id="scriptInfo" type="java.lang.String"--%>
<%--@elvariable id="url" type="org.jahia.services.render.URLGenerator"--%>
<%--@elvariable id="workspace" type="java.lang.String"--%>
<@ if (_.isEmpty(data.type) || data.type === "static") { for (rating=0; rating < data.value; rating++) {@>
<span><i class="fa fa_2x <@=data.css@>"></i></span>
<@}} else if (data.type === "variable") {@>
<span><i class="fa_2x <@=data.css@>"><p><@=data.value@></p></i></span>
<@} else {@>
<span><i class="fa fa_2x <@=data.css@>"></i></span>
<@}@>

The variable data represents the value that is saved to the input upon submission. Using Underscore's variable interpolation, we can retrieve and display any of the information that was provided as apart of our input’s value.

The final step in setting up our custom renderer, is that our input value must be an object and requires the property rendererName: nameOfOurRenderer. For example:

{
   rendererName "rating",
   value: value,
   ...properties
}

Upon viewing submission results, Forms will check whether there is a renderer defined in the value of the input. If rendererName property is detected, it will use the appropriate view to render the result.