Skip to main content

JSReport

🚧Documentation Under Construction

We are actively working to improve this documentation. The content you see here may be incomplete, subject to change, or may not fully reflect the current state of the feature. We appreciate your understanding as we continue to enhance our docs.

Brightspot seamlessly integrates with JSReport, enhancing document generation capabilities. In response to limitations observed with traditional HTML → PDF tools, this collaboration presents a practical solution for creating dynamic documents. The integration allows users to generate customized PDFs, Word documents, Excel sheets, and PowerPoint presentations directly from Brightspot, utilizing JSReport's template-based approach for a robust document generation process.

What is JSReport?​

JSReport is a server-based service that utilizes Handlebars templates to produce various document types. These templates, along with associated assets, are stored on the JSReport server, and documents are generated by making REST calls with the required data in JSON format.

Integration overview​

Brightspot's integration with JSReport offers a straightforward yet powerful set of features:

  • Document Generation API—APIs for generating a document for a provided object. Both a generic API and one leveraging Brightspot's View System are provided.
  • Config API—An API for providing configuration details for connecting to a JSReport server. A default implementation is provided for which configuration details are retrieved from environment settings.
  • Preview Implementation—An implementation of Brightspot's Preview System for JSReport, allowing editors a live preview of generated documents in the CMS.

Configuration​

There are two alternatives for configuring the JSReport integration within Brightspot, providing flexibility to accommodate various project requirements.

  • Out-of-the-Box Configuration—This approach simplifies the initial configuration process and leverages environment variables to seamlessly provide essential details for the JSReport integration. The required configuration parameters include the JSReport server's URL, username, password, and optional timeout configurations. This straightforward method ensures a quick and efficient setup for users seeking a hassle-free configuration experience.
  • Custom Configuration API—Recognizing the diverse needs of projects, Brightspot provides an API that allows users to implement bespoke ways of supplying JSReport configuration details. This empowers developers to choose the most suitable configuration approach that best fits the project's unique needs.

Out-of-the-Box Configuration​

For the out-of-the-box configuration, the following environment variables need to be supplied:

KeyTypeDescription
brightspot/jsreport/defaultjava.lang.StringName of the default configuration to use. Swap in this value for \{configName\} for the other keys.
brightspot/jsreport/config/\{configName\}/classjava.lang.StringJava class name of the JsReportServiceProvider to use. For this out-of-the-box solution the value should be com.psddev.jsreport.DefaultJsReportServiceProvider.
brightspot/jsreport/config/\{configName\}/endpointjava.lang.StringURL used to connect to the JSReport server.
brightspot/jsreport/config/\{configName\}/usernamejava.lang.StringUsername used to authenticate with JSReport.
brightspot/jsreport/config/\{configName\}/passwordjava.lang.StringPassword used to authenticate with JSReport.
brightspot/jsreport/config/\{configName\}/callTimeoutjava.lang.StringAPI Call Timeout in seconds.
brightspot/jsreport/config/\{configName\}/connectTimeoutjava.lang.StringAPI Connect Timeout in seconds.
brightspot/jsreport/config/\{configName\}/writeTimeoutjava.lang.StringAPI Write Timeout in seconds.
brightspot/jsreport/config/\{configName\}/readTimeoutjava.lang.StringAPI Read Timeout in seconds.

For additional details on environment settings, see Configuring Dari.

Custom configuration API​

To implement the Custom Configuration API for JSReport integration in Brightspot, you extend the provided JsReportServiceProvider abstract class. This class allows you to define your own method of supplying a JSReport configuration, offering flexibility to adapt to project-specific needs. Below is an example of implementing a JsReportServiceProvider in which the configuration comes from fields in Brightspot's Sites & Settings admin area.

1
import com.psddev.cms.db.ToolUi;

2
import com.psddev.cms.tool.CmsTool;

3
import com.psddev.dari.db.Modification;

4
import com.psddev.dari.db.Recordable;

5


6
@Recordable.FieldInternalNamePrefix("jsreport.")

7
public class JsReportGlobalSettings extends Modification<CmsTool> {

①
8


9
    private static final String TAB = "Integrations";

10
    private static final String CLUSTER = "JS Report";

11


12
    @ToolUi.Tab(TAB)

13
    @ToolUi.Cluster(CLUSTER)

14
    private String endpoint;

15


16
    @ToolUi.Tab(TAB)

17
    @ToolUi.Cluster(CLUSTER)

18
    private String username;

19


20
    @ToolUi.Tab(TAB)

21
    @ToolUi.Cluster(CLUSTER)

22
    @ToolUi.Secret

23
    private String password;

24


25
    public String getEndpoint() {

26
        return endpoint;

27
    }

28


29
    public void setEndpoint(String endpoint) {

30
        this.endpoint = endpoint;

31
    }

32


33
    public String getUsername() {

34
        return username;

35
    }

36


37
    public void setUsername(String username) {

38
        this.username = username;

39
    }

40


41
    public String getPassword() {

42
        return password;

43
    }

44


45
    public void setPassword(String password) {

46
        this.password = password;

47
    }

48
}

49


50
import java.time.Duration;

51


52
import com.psddev.cms.tool.CmsTool;

53
import com.psddev.dari.db.Singleton;

54
import com.psddev.jsreport.JsReportServiceProvider;

55
import net.jsreport.java.service.JsReportService;

56
import net.jsreport.java.service.JsReportServiceImpl;

57
import net.jsreport.java.service.ServiceTimeout;

58


59
public class JsReportGlobalSettingsServiceProvider extends JsReportServiceProvider {

②
60


61
    @Override

62
    public JsReportService getJsReportService() {

63
        JsReportGlobalSettings settings = Singleton.getInstance(CmsTool.class).as(JsReportGlobalSettings.class);

③
64
        if (settings != null && settings.getEndpoint() != null && settings.getUsername() != null && settings.getPassword() != null) {

65
            ServiceTimeout serviceTimeout = new ServiceTimeout();

66
            serviceTimeout.setCallTimeout(Duration.ofMinutes(1));

67
            serviceTimeout.setConnectTimeout(Duration.ofMinutes(1));

68
            serviceTimeout.setWriteTimeout(Duration.ofMinutes(1));

69
            serviceTimeout.setReadTimeout(Duration.ofMinutes(1));

70
            return new JsReportServiceImpl(

④
71
                settings.getEndpoint(),

72
                settings.getUsername(),

73
                settings.getPassword(),

74
                serviceTimeout);

75
        }

76
        return null;

77
    }

78
}
  • ①

    A Modification on CmsTool allows us to add new fields to the Sites & Settings admin area. The class contains fields for configuring:

    • Endpoint URL
    • Username
    • Password
  • ②An extension of JsReportServiceProvider allows us to create a custom solution for providing configuration for JSReport.
  • ③The JsReportGlobalSettings object is retrieved using the BSP Singleton API.
  • ④A JsReportServiceImpl object is created with the configuration from the JsReportGlobalSettings object.

This custom configuration supplier can then be enabled via the following environment variables:

KeyTypeDescription
brightspot/jsreport/defaultjava.lang.StringName of the default configuration to use. Swap in this value for \{configName\} for the other keys.
brightspot/jsreport/config/\{configName\}/classjava.lang.StringJava class name of the JsReportServiceProvider to use. For this custom solution the value should be com.yourcompany.JsReportGlobalSettingsServiceProvider.

JSReport document generation API​

The JsReportDocumentGenerator utility class in Brightspot simplifies the process of generating documents using JSReport. This utility class provides two distinct methods, catering to different use cases, allowing developers to seamlessly integrate JSReport document generation within their Brightspot projects. This topic describes each method and its use cases.

Raw data method​

createDocument(String template, Object data)

Creates a Document for the specified JSReport template and input data.

  • Parameters:

    • template: The JSReport template to use, specified by either the template name or short ID.
    • data: The data used to render the JSReport template, typically represented as a java.util.Map to convey JSON data.

  • Return:

    • A Document object containing the document produced by JSReport, including the document's content and content type.

Usage example

1
String templateName = "myTemplate";

2
Map<String, Object> jsonData = // ... prepare JSON data

3
Document generatedDocument = JsReportDocumentGenerator.createDocument(templateName, jsonData);

View system method​

createDocument(String template, Class dateEntryView, Object content)

Creates a Document using the specified template, dateEntryView, and content, leveraging the Brightspot view system.

  • Parameters:

    • template: The entry view used to find an appropriate view model. If null, the DefaultJsReportTemplate annotation will be checked for a default template.
    • dateEntryView: The entry view used to find an appropriate view model.
    • content: The content providing data for document generation.

  • Return:

    • A Document object containing the document produced by JSReport, including the document's content and content type.

Usage example

1
Object content = Query.from(MyRecord.class).first(); // contrived example for getting cotent from BSP DB

2
Document generatedDocument = JsReportDocumentGenerator.createDocument(null, JsReportViewModel.class, content);

3


4
@JsonView

①
5
@ViewInterface

②
6
@DefaultJsReportTemplate("myPdf")

③
7
public class JsReportViewModel extends ViewModel<MyRecord> {

④
8


9
    public String getTitle() {

⑤
10
        return model.getHeadline();

11
    }

12


13
    public String getCompany() {

⑥
14
        return model.getCompany();

15
    }

16
}
  • ①Specifies that the ViewModel can be converted to JSON, which is the primary format JSReport accepts.
  • ②Specifies that the ViewModel is a ViewInterface, meaning any public getter methods are included in data.
  • ③Specifies that the default JSReport template to use for this viewmodel has the name "myPdf". This will be used in the API call from line #2 since a null value was passed for the template parameter.
  • ④Marks this class as a ViewModel for the "MyRecord" class.
  • ⑤This will result in a "title" key in the resulting JSON passed to JSReport.
  • ⑥This will result in a "company" key in the resulting JSON passed to JSReport.

Enabling JSReport preview​

The JSReport preview implementation in Brightspot offers editors the invaluable capability to visualize how JSReport-generated documents will look as they create assets. This functionality enhances the content creation experience by providing a real-time preview of the documents, ensuring they meet the desired format and appearance.

Key Details:

  • Real-Time Document Preview—Editors can preview JSReport-generated documents directly within the Brightspot interface, gaining immediate insights into the document's appearance during the content creation process. This feature leverages the standard Brightspot preview system, so editors can view the preview within the content edit form in a separate browser tab.
  • PDF and Microsoft Office suite support—Preview for both PDF and Microsoft Office documents (Word, Excel, PowerPoint) is supported. For Microsoft Office, the documents must be uploaded to a Microsoft endpoint for preview to function.
  • View System-based document generation—The preview system requires using the Brightspot view system for converting Brightspot data models into the JSON that is sent to JSReport, as described below.
  • Simple Configuration—Some simple configuration is required in Sites & Settings to enable the preview.

View system​

Each content type providing a JSReport preview must have an associated ViewModel class that implements the interfaces JsReportMicrosoftOfficePreviewEntryView and/or JsReportPdfPreviewEntryView. Implementing these interfaces marks the ViewModel as the entry point for generating the JSON that will be sent to JSReport to generate the document.

Preview configuration​

To enable JSReport preview:

  1. Click > Admin > Sites & Settings.

  2. In the Sites widget, select the site for which you want to configure JSReport preview, or select Global to configure JSReport preview for all sites.

  3. Expand CMS > Preview.

  4. Under Preview Types, add a JS Report Microsoft Office or JS Report PDF preview type configuration. Under this object, add one or more configurations with the following fields set:

    1. Data View—This is the ViewModel that would be used.
    2. Template—The JSReport template to use in the preview. This has a default value if the ViewModel selected under Data View has a @DefaultJsReportTemplate annotation.