Writing a panel content

In this section, you will learn how to write a panel content. 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 PanelContentService:

CODE

...
import com.valiantys.software.elements.api.content.PanelContentService;

@Named
public class MyService {
	private final PanelContentService panelContentService;

	public MyService(PanelContentService panelContentService) {
		this.panelContentService = panelContentService;
	}

}

Copying a panel

Copy a panel with the same structure, from one issue to another is simple:

JAVA

public void doStuff() throws ElementsException {
	Issue issueA = ...;
	Issue issueB = ...;
    Panel panel = panelContentService.getPanel(IssueRef.byId(issueA.getId()), "My panel", new ReadOptions());
	panelContentService.setPanelContent(IssueRef.byId(issueB.getId()), PanelRef.byName("My panel"), panel);
}

The code above copies a panel content from issueA to issueB.

Calculate attribute and footers are ignored.

After copying panel, issue panel items history are also created

Creating a panel from scratch

Writing values attribute by attribute

Creating a PanelData structure from scratch if possible thanks to the createPanelBuilder methods in PanelContentService.

If you want to create a panel with the following structure (assuming Player, Date and Score are well defined in project panel administraction) :

Player	Date	Score
Martin	12/5/2016	2 300.50
Nadia	5/1/2017	3260.00

You can use the following code:

JAVA

public void doStuff() throws ElementsException {
	...
	IssueRef issueA = ...;
	IssueRef issueB = ...;
	PanelRef panelRef = PanelRef.byName("My panel");
    PanelBuilder builder = panelContentService.createPanelBuilder(issueA, panelRef);
	
	builder.panelItem().user(AttributeRef.byName("Player"), "martin").dateValue(AttributeRef.byName("Date"), new Date(2016, 5, 12)).numberValue(AttributeRef.byName("Score"), 2300.5d);
	builder.panelItem().user(AttributeRef.byName("Player"), "nadia").dateValue(AttributeRef.byName("Date"), new Date(2017, 1, 5)).numberValue(AttributeRef.byName("Score"), 3260d);

	panelContentService.setPanelContent(issueB, panelRef, builder.build());
}

builder.panelItem() is used any time you want to create a new line in your panel.

Writing values directly

If you already know the attributes order in the panel and this order is not subject to change, then you can write the attributes by value directly:

JAVA

public void doStuff() throws ElementsException {
	...
	IssueRef issueA = ...;
	IssueRef issueB = ...;
	PanelRef panelRef = PanelRef.byName("My panel");
    PanelContentBuilder builder = panelContentService.createPanelContentBuilder();
	
	builder.panelItem().user("martin").dateValue(new Date(2016, 5, 12)).numberValue(2300.5d);
	builder.panelItem().user("nadia").dateValue(new Date(2017, 1, 5)).numberValue(3260d);

	panelContentService.setPanelContent(issueB, panelRef, builder.build());
}

This is simpler to write, but if the order of the attributes changes in the target panel, then your code will fail at panel validation. In this case, this is safer to write values with named attributes like in the previous example.

After writing values, issue panel item history is also created

Write Options

You can change the behaviour of the setPanelContent method with this parameter.

Security

writeOptions.withOverrideSecurity(true) will allow to write the panel content even if the current writer does not have the permission
writeOptions.withWriter(anotherUser) uses the user in parameter as writer.
writeOptions.withDefaultWriter() uses current logged in user as write (default behaviour)

Validation

writeOptions.withEntityCheck(true) enforces entity checking. When you set this option, every entity reference in the panel data will be checked for missing entity. If an entity is missing, the panel will not be written and an exception will be thrown.

By default, entities are not checked.

Overwrite

writeOptions.withOverwrite(true) allows to overwrite an already existing panel.

By default, panels are not overwritten. Trying to write an existing panel will throw an exception.