Connecting Data Files
Typically, data source connection parameters are stored within the report template. For working with file data sources such as XML, JSON, Excel, and CSV, no additional actions are required as all the necessary algorithms are included in the report generator script. However, if needed, you can use other methods to connect data by leveraging the report generator's JavaScript functions. This can be done by using the onBeforeRender event of the report object. Data can be directly loaded into a special DataSet object, which is used to store it. The DataSet contains functions for loading data from XML/XSD and JSON files. After loading the files, you need to call the regData() function of the report object to connect the data, passing the prepared DataSet object as an argument.
Example of loading data from an XML file using an XSD schema:
index.php |
<?php use Stimulsoft\Report\StiReport;
$report = new StiReport(); $report->onBeforeRender = 'beforeRender'; $report->render(); ?>
function onBeforeRender(args) { let dataSet = new Stimulsoft.System.Data.DataSet("SimpleDataSet"); dataSet.readXmlSchemaFile("Demo.xsd"); dataSet.readXmlFile("Demo.xml");
let report = args.report; report.regData(dataSet.dataSetName, "", dataSet); report.dictionary.synchronize(); }
|
Information |
Data scheme loading is not essential. If you want to use data scheme, you should add it before XML data loading.
|
Example of loading data from a JSON file:
index.php |
<?php use Stimulsoft\Report\StiReport;
$report = new StiReport(); $report->onBeforeRender = 'beforeRender'; $report->render(); ?>
function onBeforeRender(args) { let dataSet = new Stimulsoft.System.Data.DataSet("SimpleDataSet"); dataSet.readJsonFile("Demo.json");
let report = args.report; report.regData(dataSet.dataSetName, "", dataSet); report.dictionary.synchronize(); }
|
The full example code is available on GitHub.
In addition to the readXmlFile() and readJsonFile() functions, there are also readXml() and readJson() functions, which accept data in the form of a string or object.
Information |
The function report.dictionary.synchronize() is necessary for synchronizing the connected data with the report template's data dictionary. When this function is called, the report dictionary will be created based on the structure of the data loaded into the DataSet. The synchronization function is not required if the dictionary is pre-created and its structure matches the connected data.
|
To view and modify file data connection parameters before loading, you need to define the onBeginProcessData event for the component, for example:
index.php |
<?php use Stimulsoft\Report\StiReport;
$report = new StiReport(); $report->onBeginProcessData = 'beginProcessData'; $report->render(); ?>
function onBeginProcessData(args) { if (args.connection == "MyJsonConnection") args.pathData = "Data/Demo.json"; }
|
The event arguments will include information about the connection to the file data source, specifically, the connection name and type in the report template, as well as the path to the data file. A detailed description of the available property values transmitted in the event arguments can be found in the Report Engine Events section.
You are allowed to change the path to the data file. In this case, after the event completes, the report generator will request the file from the new path specified in the arguments. For example, if you need to change the path to the JSON data file for the specified connection:
index.php |
<?php use Stimulsoft\Report\StiReport;
$report = new StiReport(); $report->onBeginProcessData = 'beginProcessData'; $report->render(); ?>
function onBeginProcessData(args) { if (args.connection == "MyJsonConnection") args.pathData = "Data/Demo.json"; }
|
Information |
The onBeginProcessData event will be invoked twice for an XML data source: first time to read an XSD scheme, second time to read an XML data file.
|
To view or modify the loaded data before connecting it and generating the report, you need to define the onEndProcessData event for the component.
index.php |
<?php use Stimulsoft\Report\StiReport;
$report = new StiReport(); $report->onEndProcessData = 'onEndProcessData'; $report->renderHtml(); ?>
function onEndProcessData(args) { let dataSet = args.dataSet; }
|
In the event arguments, information about the file data source connection will be passed, including the connection name and type saved in the report template, as well as the prepared DataSet object containing the tables and rows of data obtained from the file source. A detailed description of the available property values passed in the event arguments is available in the Report Engine Event section.
Loading file data on the PHP server-side
Sometimes it's necessary to control file data loading on the server-side or, for example, create a data array using code. For this, instead of specifying the file path, you can specify the path to a PHP script or service that contains the logic for fetching the data. A simple PHP data loading script might look like this:
Example of a simple PHP data loading script:
json.php |
<?php echo file_get_contents('Data/Demo.json'); ?>
|
In this case, the data path in the report template should be set to the URL of this file, for example:
File Data Source |
https://localhost/data/json.php
|
It is possible to use variables or expressions when specifying the path to the file data source. Variables or expressions are defined in curly braces. You can use multiple expressions anywhere in the data file path, for example:
File Data Source |
https://localhost/data/{VariableJsonFileName}.json https://localhost/data/json.php?id={VariableId} https://localhost/{VariableCategory}/{VariableId}
|
This way, one data source can be transformed into REST syntax, eliminating the need to create multiple similar data sources for retrieving similar data. Combined with server-side PHP logic and report generator events, this can make the data source even more flexible.
You can also use data from OData stores to create reports. In this case, you must perform authentication using a username, password, or token. The authentication parameters are specified in the OData connection string, separated by a ";" delimiter.
index.php |
// Authorization using a user account var oDataDatabase = new Stimulsoft.Report.Dictionary.StiODataDatabase("OData", "OData", "https://services.odata.org/V4/Northwind/Northwind.svc;AddressBearer=adress;UserName=UserName;Password=Password;Client_Id=Your Client ID", false, null);
// Authorization using a user token var oDataDatabase = new Stimulsoft.Report.Dictionary.StiODataDatabase("OData", "OData", "https://services.odata.org/V4/Northwind/Northwind.svc;Token=Enter your token", false, null);
report.dictionary.databases.add(oDataDatabase); report.dictionary.synchronize();
// Query with data filter var productsDataSource = report.dictionary.dataSources.getByName("Products"); if (productsDataSource != null) productsDataSource.sqlCommand = "Products?$filter=ProductID eq 2";
|