Generating HTML

In this section, you will learn how to obtain a HTML content from a panel. The examples are in Java but they are applicable to Groovy

Check the Java setup or ScriptRunner setup if not already done.
You may also want to browse the API J avadoc

Main service

You will need to use the PanelRenderingService:

CODE

...
import com.valiantys.software.elements.api.render.PanelRenderingService;

@Named
public class MyService {
	private final PanelRenderingService panelRenderingService;

	public MyService(PanelRenderingService panelRenderingService) {
		this.panelRenderingService= panelRenderingService;
	}

}

Expected HTML structure

The panel HTML generation has the following dom structure:

CODE

<table class="...">
    <thead>
		<tr><td>...</td></tr>
	</thead>
	<tbody>
		<tr><td>...</td></tr>
	<tbody>
	<tfoot>
		<tr><td>...</td></tr>
	</tfoot>
</table>

The presence of the header (thead) and footer (tfoot) is configurable.

Basic HTML generation

JAVA

public void doStuff() throws ElementsException {
    IssueRef issueA = ...;
	PanelRef panelRef = PanelRef.byName("My panel");
    String htmlContent = panelRenderingService.renderPanel(issueA, panelRef);
}

This code snipplet will output a HTML table structure (like described above), with header, footers (if defined in panel attributes) and one line per panel item.

Every attribute content will be output mostly as in the panel view.

Adding own class names

By default, the generated table has an AUI class name. This can be changed with the RenderOptions :

JAVA

class MyCssClassProvider extends DefaultCssClassProvider {
	public String getTableClass() {
		return "my-table";
	}
}

public void doStuff() throws ElementsException {
    IssueRef issueA = ...;
	PanelRef panelRef = PanelRef.byName("My panel");
    String htmlContent = panelRenderingService.renderPanel(issueA, panelRef, new RenderOptions().withCssClassProvider(new MyCssClassProvider()));
}

This code will output the same thing as the basic generation would, except for the table :

Table with alternate class

XML

<table class="my-table">
...
</table>

You can check the API javadoc for the full set of methods available. Most of the HTML elements classes can be overriden

Changing the content formatting

The render options allows you to change the way attribute content are formatted.

In the case when default formatting does not fit your needs, you can specify alternate content formatters.

If you want to display the issue summary instead of issue type and key :

JAVA

class MyIssueFormatter implements IssueFormatter {
	public String formatHtml(Long value, AttributeInfo attributeInfo, boolean isFooter, FormatHelper<Issue> formatHelper) {
		Issue issue = formatHelper.getEntity();
		return "<b>" + formatHelper.escapeHtml(issue.getSummary()) + "</b>";
	}
}

public void doStuff() throws ElementsException {
    IssueRef issueA = ...;
	PanelRef panelRef = PanelRef.byName("My panel");
	RenderOptions renderOptions = new RenderOptions();
	renderOptions.withContentFormatter(new MyIssueFormatter());
    String htmlContent = panelRenderingService.renderPanel(issueA, panelRef, renderOptions);
}

When the panel rendering service encounters an issue attribute, it will use your formatter instead of the default one.

When implementing a formatter, you can return a HTML fragment. This is your responsibility to escape user text.

You can add one content formatter by type.

Render options

Render options allows you to control the behaviour of the renderPanel method:

Security

renderOptions.overrideSecurity(). When using this option, you can disable permission checking and access the panel even if current logged in user does not have the permission
renderOptions.withUser(anotherUser). Use anotherUser permissions to access the panel.

Output control

renderOptions.withCssClassProvider(new CssClassProvider(...)). This option let you override the default class names in the generated HTML elements.
renderOptions.withContentFormatter(new XXXFormatter()). This option let you change the way contents are formatted in the HTML
renderOptions.withHeader(true/false). Enables/disables header generation (true by default).
renderOptions.withFooter(true/false). Enables/disables footer generation.

Using renderOptions.withFooter(true) only has effect if at least one attribute has a footer defined.