RPCL Components Data-Awareness
One of the key features of the RPCL is its support for database interaction. You can easily create RPCL applications with components that use and manage data from a database. Those components are called data-aware components.
Contents
Implementation
All data-aware components implement a property named DataSource that is supposed to point to a Datasource component:
protected $_datasource = null;
function readDataSource() { return $this->_datasource; }
function writeDataSource($value) { $this->_datasource = $this->fixupProperty($value); }
function defaultDataSource() { return null; }
Note: Use Component’s
fixupProperty()method is used before storing the new value.
With the Datasource component, your own components will be able to easily access and modify the data provided by a DataSet component.
Single Field
If your component only needs to read a field from the current row of the data provided by a DataSet component, implement a property named DataField:
protected $_datafield = "";
function readDataField() { return $this->_datafield; }
function writeDataField($value) { $this->_datafield = $value; }
function defaultDataField() { return ""; }
Read
Then, you can use Component’s readDataFieldValue() method to retrieve the value at any time. The method will return false if there is no value, so you can use a fallback value instead, or a different property.
$value = $this->readDataFieldValue();
if ($value === false)
$value = $this->_fallbackproperty;
If the value of the field might be a boolean, and you need to know whether there was no value or there was a false, use Component’s hasValidDataField() method instead:
$value = null;
if($this->hasValidDataField())
$value = $this->_datasource->DataSet->fieldget($this->_datafield);
else
$value = $this->_fallbackproperty;
Write
If your component must also be able to modify the value of the field on the database, there are additional steps you must follow:
- Print hidden fields on the form with information about the current record from the database, to let the RPCL know which record to update.
- When the form is submitted, check whether there is a new value for the field, and perform the update in that case.
To print the hidden fields, call Component’s dumpHiddenKeyFields() method from your component’s dumpContents() method:
$this->dumpHiddenKeyFields();
You should then write the code for the data update in the preinit() method of your component:
function preinit()
{
// Check whether there is a new value defined:
$submitted = $this->input->{$this->Name};
if (is_object($submitted))
{
// Update the field with the new data.
$this->updateDataField($submitted->asString());
}
}
Help Resources
Sample Applications
You can access the code of any default component from the RPCL folder. For example:
- stdctrls.inc.php. It defines for example he CustomLabel class, which implements single-field read-only data-awareness. It is the class the Label component extends.