Property Editors

For those properties with a value other than plain text, you should register a property editor. Property editors provide an user-friendly experience to edit special properties from the Object Inspector.

Property editors support component inheritance. That is, if you register an editor for a property in a component, that editor will be available in all the children of the component.

Built-in Property Editors

HTML5 Builder provides several built-in property editors you can register for your components’ properties in their package.

Booleans

Register boolean properties with registerBooleanProperty("ComponentName", "PropertyName");. The Object Inspector will display a checkbox for the property.

Predefined Values

You can register a list of possible values for a property:

registerPropertyValues("ComponentName", "PropertyName", array("Value1", "Value2", "Value3"));

The Object Inspector will display a combo box for the property with the list of predefined values, so the user can choose between them.

From Other Components

You can get the list of possible values of a property generated from the return values of a method in all the existing instances of another component (and children) using the registerPropertyValues() function with the following syntax:

registerPropertyValues("ComponentName","PropertyName",array('GeneratorComponentName::ValuesMethod'));

Where:

• ComponentName is the name of the component with the target property.
• PropertyName is the name of the target property, the one to which the list of possible values will be attached.
• GeneratorComponentName is the name of the component from whose instances (and those of its children) the list of values will be generated.
• ValuesMethod is the name of the method that will be executed in all the existing instances of GeneratorComponentName to get a list of possible values for PropertyName.

Objects

If your property must be assigned a reference to an instance of a component, use the registerPropertyValues() function to register the property. When given only one option in the array of possible values, instead of a combo box with only one value, HTML5 Builder will fill the combo with the list of instances of the given component (and children).

registerPropertyValues("ComponentName","PropertyName",array("PropertyComponentName"));

Superproperties

Components can also contain superproperties. A superproperty is a property that groups several individual properties (subproperties), and they are displayed on the Object Inspector nested under the superproperty. HTML5 Builder supports one level of subproperties only, that is, you cannot group subproperties under a superproperty which is also a subproperty.

Superproperties are implemented as properties with a PHP class as value. For example, the Gradient class defines a superproperty, and is used in all controls.

HTML5 Builder recognizes superproperties automatically, no additions to the components package are needed. Yet, you might need to register some of the subproperties. To refer to subproperties, use the following syntax: SuperpropertyName.SuboropertyName.

For example, to register the boolean subproperty Enabled of the superproperty State:

registerBooleanProperty("ComponentName", "State.Enabled");

Dialogs

The dialog property editors are designed to make properties with complex or unfriendly values, such as arrays or web colors, more user-friendly. The built-in dialog editors are available, with their source, among the native editors inside the plugins folder in HTML5 Builder’s installation directory. You can register them with the following function:

registerPropertyEditor("ComponentName", "PropertyName", "PropertyEditorClassName", "native");

Custom Property Editors

You can write your own dialog property editors in Delphi. To create a property editor , you need to:

• Create a new package.
• Add D4PHPTools.dcp to the requires clause.
• Add D4PHPIntf to your uses clause.
• Inherit from ·TD4PHPPropertyEditor:

TSamplePropertyEditor = class(TD4PHPPropertyEditor)
public
    function Execute(value: string; out newvalue: string): boolean; override;
end;

• Write the logic. For example:

{ TSamplePropertyEditor }

function TSamplePropertyEditor.Execute(value: string; out newvalue: string): boolean;
var
    rgbColor: TColorRef;
begin
    with TColorDialog.Create(application) do begin
        try
            //Set to black if none
            if (value = '') then value := '#000000';

            //Strip the #
            if (value[1] = '#') then value := copy(value, 2, length(value));

            //Get the color
            color := RGB(
                StrToInt('$' + Copy(value, 1, 2)),
                StrToInt('$' + Copy(value, 3, 2)),
                StrToInt('$' + Copy(value, 5, 2))
                );

            result := execute;

            //Convert the color to the new value
            if (result) then begin
                rgbColor := ColorToRGB(color);
                newvalue := '#' + Format('%.2x%.2x%.2x', [GetRValue(rgbColor), GetGValue(rgbColor),
                                                          GetBValue(rgbColor)]);
            end;
        finally
            free;
        end;
    end;
end;

• Compile your package, and copy your .bpl file Inside the plugins folder in HTML5 Builder’s installation directory.

Now your custom native property editor is installed in HTML5 Builder, and you can register them in the components package with the following function:

registerPropertyEditor("ComponentName", "PropertyName", "PropertyEditor", "native");

Where:

• ComponentName is the name of the component with the target property.
• PropertyName is the name of the target property, the one for which the editor should be available.
• PropertyEditor is the name of the class of the property editor (Delphi or PHP)..

Native property editors like the sample above get the current value in the value parameter (always a string). If you want to update the component, set the new value on newvalue and return true as the result for the method. The sample property editor above just pops up the ColorDialog, sets the color to the current value and if the user accepts the selection, converts the color back to HTML format and returns true.

The D4PHPIntf.pas file contains all the things you can use right now to interact with HTML5 Builder. Also, inside the plugins folder in HTML5 Builder’s installation directory, you will find the source code for the built-in native property editors, to help you get started.