RPCL Components Persistance

The RPCL provides object persistance using the webserver session. This way, you do not need to send parameters through GET or POST, or implement a session mechanism yourself.

Published properties are automatically serialized or userialized by the framework at the right time. That is, when you run a Page, at the end of the process published properties are serialized with their latest values; next time the PHP script is executed, properties will be recovered from the session. This way, you can work with your application in the same state it was left in the previous POST.

Simple Persistance Test

Best way to understand component persistance is to test it yourself. Follow instructions below to set up a persistance sample, and run it:

1. Start a project for an RPCL application.
2. Add two buttons (Button component) and a one-line input field (Edit component) to it. Both components are standard components.
3. On the OnClick event of the first button, change the color of the input field (for example, to #FF0000).
4. On the OnClick event of the second button, change the caption of the input field (for example, to "Hello, Session!".

If you run this application and click the first button, the color of the input field will change. If you then click the second button, the text of the input field will change, and its new color will remain. Without session persistance, the color would have returned to its initial value.

Additional Data

Sometimes, you might want to persist more than your component’s published properties. To do so, override serialize() and unserialize() to store and retrieve data, respectively, using the $_SESSION object. Such data should be stored in qualified $_SESSION keys, else data from different components might conflict.

For example, you could persist a non-published $title property of a component named Journal like this:

function serialize()
{
    parent::serialize();
    $owner = $this->readOwner();
    if ($owner != null)
    {
        $prefix = $owner->readNamePath().'.'.$this->_name.'.Journal.';
        $_SESSION[$prefix."Title"] = $this->title;
    }
}

function unserialize()
{
    parent::unserialize();
    $owner = $this->readOwner();
    if ($owner != null)
    {
        $prefix = $owner->readNamePath().'.'.$this->_name.'.Journal.';
        if (isset($_SESSION[$prefix."Title"]))
            $this->title = $_SESSION[$prefix."Title"];
    }
}

Notice that you can use persistance for any object, not only components. But such an object must inherit from Persistent.

Loading State

You can know if a component is being loaded from a resource file or the PHP session by checking whether its control state is set to csLoading or not:

if( ($this->ControlState & csLoading) === csLoading )
{
  // The code here will only be executed when the component is being loaded.
}

Tip: To run code when the component is not being loaded, replace === with !==.

Session Reset

When developing your application, at some point you will want to reset the session, since after code changes session stored data can lead to unexpected results in your application. You can destroy your session data by running your next PHP script with the following GET key-value pair: restore_session=1. For example, if your script is mypage.php, you would call it like mypage.php?restore_session=1.

When you run your application in a web browser from HTML5 Builder, it always appends this to the URL to prevent unexpected results.