RPCL Components Properties

Properties can be used to set up components at design time, or during server-side runtime. The more properties you define for your components, the more customizable and flexible they are.

Implementation

The RPCL implements properties (as well as events) through PHP’s magic functions __get() and __set().

The following naming convention is used in the RPCL:

readPublicProperty()

Getter for a public property named PublicProperty.

getPublishedProperty()

Getter for a published property named PublishedProperty.

readOnPublicEvent()

Getter for a public event named OnPublicEvent.

getOnPublishedEvent()

Getter for a published event named OnPublishedEvent.

readjsOnPublicEvent()

Getter for a public JavaScript event named OnPublicEvent.

getjsOnPublishedEvent()

Getter for a published JavaScript event named OnPublishedEvent.

The equivalent methods to set the value of a property would use write instead of read, and set instead of get. For published properties, you must also define a method with the prefix default (instead of set or get), returning a value to be used as default for the property, so HTML5 Builder can use the returned value as default.

Properties and events are defined by their getter method, not by the property itself, both for logic and documentation purposes. For example:

• getCaption() defines the name of the property, as far as the RPCL is concerned, as Caption. The name of the PHP property the method actually returns ($this->_caption by convention) does not matter. It might even return an expression instead. When someone uses the component, that property would be accessed as ComponentName->Caption, both for write and read actions.
• Documentation for the property should be placed right before the getter, not before the PHP property. The PHP property, as well as any setter or default method, do not need to be documented at all.

Enumerated Properties

In the RPCL, defines are used by convention with the following syntax:

// For the possible values of the SomeProperty property:
define("spValue1", "spValue1");
define("spValue2", "spValue2");

That way, if you use spValue1 in your code, it gets translated to the string "spValue1".

If you want your enumerated property values to be listed in HTML5 Builder for a given property, follow these instructions.

Object Properties

Your components might contain properties that are meant to contain a reference to an object. That reference, when the user interacts with the component or the component is loaded from a resource file, is a string.

But inside your component you want that property to point directly to the referenced object, instead of being a string. So, when the property is assigned a new string, you must parse that string to get the actual object, and then assign the object to the property.

The Component class provides a method, fixupProperty(), that does exactly that. It gets the string as argument, and returns a reference to the matching object. You can use this method inside the setter method for your object property:

protected function writePropertyName($value)  
{ 
    $this->_propertyname = $this->fixupProperty($value); 
}

If no valid object named as $value is found, the given string will be returned back.

When a component is loaded from a resource file, the referenced object might not be loaded yet for the time the setter method gets called for your component, and fixupProperty() will return back the property value as a string instead of an object. That is why, when you have object properties, you must overwrite the loaded() method (which takes place when the objects are loaded from a resource file, as part of their lifecycle), and try to resolve the object reference from the string there.

function loaded()
{
    parent::loaded();
    $this->writePropertyName($this->_propertyname);
}

Development

Add a Public Property

To add a public property to a custom component, click on the part of the code where you want the property definition added, go to Edit > Add Public Property…, enter a name for the property and a default value, and click OK.

For example, for a property called Text with a default value of "", the following code would be generated for you:

protected $_text="";

function readText() { return $this->_text; }
function writeText($value) { $this->_text=$value; }
function defaultText() { return ""; }

Add a Published Property

To add a published property to a custom component, click on the part of the code where you want the property definition added, go to Edit > Add Published Property, enter a name for the property and a default value, and click OK.

For example, for a property called Text with a default value of "", the following code would be generated for you:

protected $_text="";

function getText() { return $this->_text; }
function setText($value) { $this->_text=$value; }
function defaultText() { return ""; }

Publish a Public Property

To publish a public property on a custom component, click on the part of the code where you want the new code to be added, go to Edit > Published Public Property, enter the name of the public property to be published, and click OK.

For example, for a public property called Text, the following code would be generated for you:

function getText() { return $this->readtext(); }
function setText($value) { $this->writetext($value); }

Visibility Levels

In PHP, class properties can be public, protected or private. The implications of each of those levels of PHP properties visibility is better explained in the PHP official documentation.

For RPCL components, there are two component properties visibility levels to consider: public and published. Component properties must still have a PHP visibility level, that does not change. Component visibility levels are a different way to let you control the way users can access component properties, no matter what the PHP visibility level of those properties is. Also, notice that any component property can be both public and published, which might render convinient in certain situations.

Public

Public properties are suitable for base components, those intented to be extended by child components. Base components usually retain the most of the functionality, and you can then publish on child components only the inherited properties you need.

You can create a public property like this:

protected $_testproperty = 'default';
function readTestProperty() { return $this->_testproperty; }
function writeTestProperty($value) { $this->_testproperty=$value; }
function defaultTestProperty() { return 'default'; }

You can then work with public properties like this:

$MyFirstComponent->TestProperty = 'value';
echo $MyFirstComponent->TestProperty;

That is, read and write methods are interfaces to the protected $_testproperty variable, and are automatically called thanks to PHP magic functions (__set() and __get()).

Published

Published properties are the only ones displayed in the Object Inspector, so you must use this properties if you want to be able to change them at design time.

To publish a property, just provide getter and setter methods for it:

function getTestProperty() { return $this->readTestProperty(); }
function setTestProperty($value) { $this->writeTestProperty($value); }

Providing a getter for default property value can be also convenient:

function defaultTestProperty() { return 'value'; }

Note in these examples functions call read and write methods. So these getter, setter and default getter functions are just interfaces to public properties. But you can publish a non-public property instead, there is no restriction to which properties can be or not published. For example, you could publish a protected property like this:

protected $property;
function getProperty() { return $this->property; }
function setProperty($value) { $this->property = $value; }
function defaultProperty() { return 'value'; }

See Also

• Properties Integration with HTML5 Builder, Property Editors.