Integrate Third-Party JavaScript Components with PHPRunner

Third-party JavaScript components can be integrated into a PHPRunner application without replacing the generated page. The same general approach works for data grids, charts, editors, calendars and many other browser-based components.

The integration usually has five parts:

1. Add the component’s JavaScript and CSS files to the project.
2. Add a container to the page where the component will be displayed.
3. Make the required data available to JavaScript.
4. Initialize the component after the page is ready.
5. Add only the CSS needed to make the component fit the rest of the application.

In this tutorial we will use Tabulator, a JavaScript data-grid component, as a practical example. The important part is the integration pattern rather than Tabulator itself.

1. Add the third-party files

Download Tabulator from its installation page.

For a traditional browser-based integration, Tabulator provides both JavaScript and CSS files. Copy the files you need into your PHPRunner project’s source folder so they will be available in the generated application.

This example assumes that the files are available at:

• css/tabulator.min.css
• js/tabulator.min.js

Third-party libraries change over time, so always check the current documentation for file names, dependencies and API changes when adapting this example to a newer version.

2. Add a container in Page Designer

Open the List page in Page Designer. Remove any page elements you do not need and insert a Code Snippet into the container where you want the third-party component to appear.

The snippet has two jobs: load the component’s CSS and JavaScript files and create an HTML element where Tabulator will render the table.

PHP

echo '<link href="css/tabulator.min.css" rel="stylesheet">
<script type="text/javascript" src="js/tabulator.min.js"></script>
<div id="example-table"></div>';

C#

MVCFunctions.Echo(@"
<link href='css/tabulator.min.css' rel='stylesheet'>
<script type='text/javascript' src='js/tabulator.min.js'></script>
<div id='example-table'></div>
");

The example-table element is simply a placeholder. Tabulator will use it when the component is initialized.

3. Prepare the data on the server

Next, retrieve the data that will be displayed and pass it to JavaScript. Add the following code to the Before Display event of the same List page.

This example uses tables from the Northwind database. Replace the query with one appropriate for your own database.

PHP

$rs = DB::Query("
    select
        CategoryName,
        UnitsInStock,
        ProductName,
        UnitPrice,
        QuantityPerUnit
    from products p
    inner join Categories c
        on c.CategoryID = p.CategoryID
");

$rows = array();

while ($data = $rs->fetchAssoc())
{
    $rows[] = $data;
}

$pageObject->setProxyValue("tabledata", $rows);

C#

dynamic data;

dynamic rs = DB.Query(@"
    select
        CategoryName,
        UnitsInStock,
        ProductName,
        UnitPrice,
        QuantityPerUnit
    from products p
    inner join Categories c
        on c.CategoryID = p.CategoryID
");

dynamic rows = new List<dynamic>();

while (data = rs.fetchAssoc())
{
    rows.Add(data);
}

pageObject.setProxyValue("tabledata", rows);

The database query can be much simpler if necessary. For example:

$rs = DB::Query("select * from mytable");

The important line is setProxyValue(). It makes the server-side data available to the JavaScript code running on the page.

4. Initialize the component

Open the JavaScript OnLoad event of the same List page.

First, retrieve the data passed from the server. Then create the Tabulator object and tell it which HTML element should contain the table.

var tabledata = proxy["tabledata"];

var table = new Tabulator("#example-table", {
    height: "600px",
    layout: "fitColumns",
    data: tabledata,
    groupBy: "CategoryName",

    columns: [
        {
            title: "Product",
            field: "ProductName",
            width: 200
        },
        {
            title: "Price",
            field: "UnitPrice",
            width: 150
        },
        {
            title: "In Stock",
            field: "UnitsInStock",
            width: 150
        },
        {
            title: "Quantity Per Unit",
            field: "QuantityPerUnit",
            width: 200
        }
    ]
});

Change the column titles and field names to match the data returned by your query.

Understanding the integration pattern

Although this example uses Tabulator, very little of the PHPRunner-specific code is actually related to Tabulator.

The reusable pattern is:

1. Load the library. Add the JavaScript and CSS files required by the component.
2. Create a container. Add an HTML element where the component can render itself.
3. Prepare the data. Use PHPRunner server-side events and the Database API to retrieve any required data.
4. Pass data to JavaScript. Use setProxyValue() when server-side data needs to be available in the browser.
5. Initialize the component. Use JavaScript OnLoad so the component starts after the page and its container are available.

This pattern can be used with many third-party components, including specialized grids, charts, editors, visualization libraries and other JavaScript controls.

Keep third-party code isolated

When integrating an external component, avoid replacing more of the generated PHPRunner page than necessary. Keep the component inside its own container and limit custom CSS to that component whenever possible.

This makes the project easier to maintain because PHPRunner continues to manage the surrounding application structure, navigation, authentication and other generated functionality while the external library handles only the specialized interface you added.

Also keep in mind that third-party libraries have their own release cycles. The PHPRunner integration technique shown here remains the same, but individual JavaScript options, methods and file names may change. Check the component’s current documentation before updating an older implementation.