Using Soy Templates

Invocation

All invocations run through the SoyTemplateRenderer class' render method. It takes three parameters:

  • (String) – the fully-qualified plugin module key – e.g., jira.webresources:soy-templates
  • (String) – the Soy template's name, including its namespace – e.g., JIRA.Templates.Headers.pageHeader
  • (Map<String,Object>) – the data for the template. The keys should match with the names of the parameters in the Soy template.

Registering templates

To register your Soy template, you will need to add it to a web-resource somewhere.

JIRA has a web-resource called soy-templates, which is defined in system-webresources-plugin.xml. For core JIRA assets, you should start there.

You can add a Soy template that is available on either the server-side only, or on both the server and client.

<web-resource key="soy-templates">
    <dependency>com.atlassian.soy.soy-template-plugin:soy-deps</dependency>


    <!-- Available to the server-side only -->
    <resource type="soy" name="links" location="/templates/jira/links.soy"/>
 
    <!-- Make available to the client-side in JS as well... -->
    <transformation extension="soy">
        <transformer key="soyTransformer"/>
    </transformation>
    <resource type="download" name="Links.soy.js" location="/templates/jira/links.soy"/>
</web-resource>

Calling from JSP

<%@ taglib uri="webwork" prefix="ui" %>
<%@ taglib uri="webwork" prefix="ww" %>
<%
     String someOtherValue = "http://www.example.com/";
%>
<ui:soy moduleKey="'jira.webresources:soy-templates'" template="'JIRA.Templates.Links.helpLink'">
    <ui:param name="'isLocal'" value="true" />
    <ui:param name="'url'"><%= someOtherValue %></ui:param>
    <ui:param name="'title'"><ww:text name="'example'"/></ui:param>
</ui:soy>

Calling from Velocity

#set($someOtherValue = "http://www.example.com/"
$soyRenderer.render('jira.webresources:soy-templates','JIRA.Templates.Links.helpLink',{
    'isLocal': true,
    'url': ${someOtherValue},
    'title': $i18n.getText('example')
})

Calling from JavaScript

function getHtmlString() {
    return JIRA.Templates.Links.helpLink({
        isLocal: true,
        url: "http://www.example.com/",
        title: AJS.I18n.getText("example")
    });
}
 
var domElement = jQuery(getHtmlString())[0];

Calling from a Java Class

(info) This is not recommended.

// see below to inject
private SoyTemplateRenderer soyTemplateRenderer;
 
public String getHtml()
{
    Map<String, Object> data = new HashMap<String,Object>();
    data.put("isLocal", true);
    data.put("url", "http://www.example.com");
    data.put("title", getI18nHelper().getText("example"));
    return this.soyRenderer.render("jira.webresources:soy-templates", "JIRA.Templates.Links.helpLink", data);
}
 
private com.atlassian.jira.util.I18nHelper getI18nHelper()
{
    // ... up to you
}

You inject the SoyTemplateRenderer differently in JIRA core and plugins. See the examples below.

Injecting in JIRA Core

The SoyTemplateRenderer cannot be injected via pico, so get it from an injectable SoyTemplateRendererProvider:

public MyConstructor(SoyTemplateRendererProvider soyTemplateRendererProvider)
{
	this.soyRenderer = soyTemplateRenderer.getRenderer();
}

Injecting in a Plugin

Import the SoyTemplateRenderer in your atlassian-plugin.xml:

<component-import key="soyTemplateRenderer" interface="com.atlassian.soy.renderer.SoyTemplateRenderer"/>

Then it can be directly injected:

public MyConstructor(SoyTemplateRenderer soyTemplateRenderer)
{
	this.soyRenderer = soyTemplateRenderer;
}
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport