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

Main service

You will need to use the PanelContentService:

...
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:

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) :

PlayerDateScore
Martin12/5/20162 300.50
Nadia5/1/20173260.00

You can use the following code:


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:

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.