RPCL Components Data-Awareness

From HTML5 Builder
Jump to: navigation, search

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.

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:

See Also

Personal tools