Quick Tutorial - Printing Reports

Description

This tutorial will demonstrate the fundamentals of implementing Printing from your mobile device. Note that Reports object and printing is not supported on all platforms.

Resources

The Report Object

Reports are an effective way to display your data in a printed format. The reports created within your BSP project are controlled using the Report object, found under Objects > Reports folder in the data source tree.

Print() and PrintToPDF() can be used to generate a report using the data on the device and the query specified for the report. Print() will generate a report and open the print dialog screen on your device to choose a printer to print the report. PrintToPDF() will create the indicated report and print within the device as a PDF.

If the query assigned to a report requires a parameter, you can set this parameter using the SetQueryParam() method. You can also set report variables using SetVariable().

Print() Method

The Print() method is one of two ways to print a report. Executing this method will prompt the user to choose a printer registered on the device for which the report will print from.

This method takes in one string argument that names the report to be printed. To use this functionality, create an expression that calls the Print() method and assign it to an action property for a control or form in your project.

Upon executing this method the print dialog will appear on the device, where the user can preview the report, select the printer, the number of copies to print, change the page size and execute the print job. However this does depend on the device capabilities if all or a subset of these functions will be available.

In BrightWeb, the report will be laid out as a web page, which will be navigated to in the browser window.

The Print() method will return 0 if the execution was successful or return an integer error code. It is recommended to use this within the expression to ensure the operations are robust and performed correctly.

Below is an example code snippet:

local.result = Report.Print("Report1");

IF(local.result <> 0)

{

Form.MessageBox("Report.Print() Error", local.result, 0);

}

PrintToPDF() Method

Like the Print() method, PrintToPDF() can be used to generate a report in the form of PDF document that can later be printed or send by an email. The PrintToPDF() method will print the report as a PDF document and save it to a specified location on the device.

PrintToPDF() has two arguments, the first being the name of the report to be printed and the second being a string containing the file path and filename for the generated PDF. It should be noted that this method is only supported on Android and BrightWeb applications and server-side scripts.

By executing this method through an expression, the report will be printed and stored in the file specified by the second parameter. If execution of the method was unsuccessful the method will return the integer error code, otherwise it will return 0.

Below is example code to print a report as a PDF, storing the file in a sub-directory in the BrightForms Project Directory.

local.vNow = DateTime.Now();

local.vPath = System.GetProjectPath() & "./pdf/";

IF(File.FileExists(local.vPath) <> true)

{

File.CreateDirectory(local.vPath);

}

local.vFile = local.vPath & DateTime.Format(local.vNow, "yyyMMddHHmmss") & ".pdf";

local.result = Report.PrintToPDF("Report1", local.vFile);

IF(local.result <> 0)

{

Form.MessageBox("Report.PrintToPdf() Error", local.result, 0);

}

In BrightWeb, this method may be used in conjunction with the System.MarkFileForDownload() method, which will allow users to download PDF files generated on the server. For example:

local.vNow = DateTime.Now();

local.vPath = "../data/pdf/";

IF(File.FileExists(local.vPath) <> true)

{

File.CreateDirectory(local.vPath);

}

local.vFilename = DateTime.Format(local.vNow, "yyyMMddHHmmss") & ".pdf";

local.vFile = local.vPath & local.vFilename;

local.result = Report.PrintToPDF("Report1", local.vFile);

IF(local.result <> 0)

{

Form.MessageBox("Report.PrintToPdf() Error", local.result, 0);

}

ELSE

{

System.MarkFileForDownload(local.vFile, local.vFilename);

}

BrightServer is running as a service, running the expression above will generate a PDF file on the server's filesystem in BrightServer's 'data' directory in a 'pdf' sub-folder. After this, the user will be prompted to save the PDF file to their local file system.

Viewing PDFs through BrightForms

As of BrightForms 9.1, PDF and other types of files may be viewed on iOS and Android platforms using the Form.ViewDocument() method. For example, the following method may be used to open a PDF file specified by the edtOutputFile control:

Form.ViewDocument(edtOutputFile);

For BrightForms for Android version 9.0, the System.RunProgram() method may be used in conjunction with the SetObjectState() method. In conjunction with the URI, the Android intent must also be specified with the RunProgram() method.

System.ResetObjectState();

System.SetObjectState("#bs-intent-mime-type#", "application/pdf");

Local.uri = "file://" & local.edtOutputFile;

System.RunProgram(local.uri, "android.intent.action.VIEW");

Exercise

The PrintingStart.bsp project allows users to create and view test records on the device to test report generation. This may be performed via the 'View/Create Records' button on the main form, which will open a sub-form able to create local records on the device.

In addition to this functionality from the main form, there are a number of Print buttons which are not assigned any expressions. Create expressions for these buttons performing the following:

Print - Print the 'Report1' report on the device
PrintToPDF - Print the 'Report1' report as a PDF to a location on the device, loading the location into the edtOutputField control
PrintToPDF, Download - Create an expression which will let the user download the 'Report1' report using the Report.PrintToPDF() method, then using BrightWeb's System.MarkFileForDownload() method.
ViewPDF - Open the PDF file location in edtOutputField on the device.

A completed solution may be found in the PrintingFinished.bsp file.

Running on BrightWeb, the associated printingweb.bep must also be deployed with the correct database configuration. Please also ensure that the test database and tables have been created on the data source.