Automatically Show New Records on a PHPRunner List Page

In multi-user applications, new records may be added while another user is already looking at the List page. A helpdesk is a typical example: customers submit tickets while support staff keep the ticket list open and need to see new items quickly.

This example periodically checks whether new records were added. When new data is detected, the page can either reload automatically or display a notification. Newly arrived records are also highlighted so they are easy to notice.

How it works

The example stores the current number of records in a session variable. JavaScript then sends a small request to the List page at regular intervals. If the number of records has increased, the page knows that new data is available.

This approach is simple and works well for pages where new records normally appear at the top. It is a good idea to sort the data by an ID, timestamp or another appropriate field in descending order so newly added records appear first.

Note: This technique compares the current number of rows with the previous count. Searches, filters or other conditions that change the number of rows can therefore also affect the result.

1. List page: Before Display event

Add the following code to the List page: Before Display event.

PHP

if(postvalue("a") === "check_new" ){
    $_SESSION["new_records"] = 0;

    if($pageObject->numRowsFromSQL > $_SESSION["current_count"]){
        $_SESSION["new_records"] =
            $pageObject->numRowsFromSQL - $_SESSION["current_count"];
    }

    print json_encode(array(
        "action" => $_SESSION["new_records"] > 0 ? "update" : ""
    ));

    exit();
}

$_SESSION["current_count"] = $pageObject->numRowsFromSQL;

$pageObject->setProxyValue(
    "new_records",
    isset($_SESSION["new_records"]) ? $_SESSION["new_records"] : 0
);

unset($_SESSION["new_records"]);

C#

dynamic action = MVCFunctions.postvalue("a");

if(action == new XVar("check_new")){
    XSession.Session["new_records"] = 0;

    if(pageObject.numRowsFromSQL > XSession.Session["current_count"]){
        XSession.Session["new_records"] =
            pageObject.numRowsFromSQL - XSession.Session["current_count"];
    }

    dynamic info = XVar.Array();

    info.InitAndSetArrayItem(
        XSession.Session["new_records"] > 0 ? "update" : "",
        "action"
    );

    MVCFunctions.Echo(MVCFunctions.my_json_encode((XVar)(info)));
    MVCFunctions.Exit();
}

XSession.Session["current_count"] = pageObject.numRowsFromSQL;

pageObject.setProxyValue(
    "new_records",
    XSession.Session.KeyExists("new_records")
        ? XSession.Session["new_records"]
        : new XVar(0)
);

XSession.Session.Remove("new_records");

The first time the page loads, the current row count is saved in the session. The value is also passed to JavaScript through a proxy value so the page can highlight newly added rows after a reload.

2. List page: JavaScript OnLoad event

Add the following code to the List page: JavaScript OnLoad event.

The autoreload variable controls what happens when new records are detected. Set it to true to reload the page automatically, or false to display a message with a reload link.

var autoreload = false;
var new_row_color = "#FF7373";

var message = $("<div class='alert alert-success'>There is new data available. <a href=''>Reload page</a></div>");

if (proxy["new_records"] > 0) {
    var new_rows = pageObj.getAllRecords().splice(
        0,
        proxy["new_records"]
    );

    $.each(new_rows, function(index, row) {
        $("#gridRow" + row.row.id).css(
            "background-color",
            new_row_color
        );
    });
}

function check_new() {
    $.get("", { a: "check_new" }, function(response) {
        var data = JSON.parse(response);

        if (data.action === "update") {
            if (autoreload) {
                window.location.reload();
            } else {
                $(".r-grid").before(message);
            }
        }
    });
}

var seconds = 10;
setInterval(check_new, seconds * 1000);

The example checks for new data every 10 seconds. You can change the value of seconds to match your application.

Choose the interval carefully. A shorter interval makes updates appear faster, but it also creates more requests to the server. If many users keep the same List page open, checking every second or two can create unnecessary load. For most applications, an interval of several seconds or longer is sufficient.

You can also change new_row_color to use a different highlight color.

3. Inline Add

If users add records with Inline Add on the same List page, update the stored count after a record is added. Otherwise, the record added by the current user could be detected as a new record during the next check.

Add the following code to the Add page: After Record Added event.

PHP

if($inline){
    $_SESSION["current_count"]++;
}

C#

if(inline){
    XSession.Session["current_count"]++;
}

Things to keep in mind

This technique is designed for cases where the number of records is a useful indication that new data has arrived. It works especially well for queues, helpdesks, orders, messages and similar pages where new records are normally inserted and displayed at the top.

If users frequently apply searches or filters, or if records are also being deleted, the total row count can change for reasons other than a new record being added. In more complex applications, you may want to track the newest record ID or timestamp instead of relying only on the total number of rows.

The polling interval is another important consideration. Use the longest interval that still provides the responsiveness your users need. This reduces unnecessary requests while still keeping the List page reasonably current.