RPCL Components Hello World

From HTML5 Builder
Jump to: navigation, search

To develop an RPCL component, you need to:

  1. Inherit either directly from Component or from any of its subclasses.
  2. Make your component print the web code (HTML, CSS, JavaScript…) that provides the functionality of the component.
  3. Define properties, functions and events to allow the customization of your component’s look and behavior.

Now, we are going to go through those steps to create a component that prints the message “Hello, World!”.

The Base Source Code

To create a new component, go to Home > New > Other Projects > Other Files, select Component and click Create. On the dialog that will pop up, enter the following data:

  • Ancestor class is the class the new component will inherit from. Since your component will have a visual representation, you can inherit from Control.
  • Classname is the name of the new component. You can call it HelloWorld, for example.
  • Palette Page is the name of the section of the Tool Palette where your component should be placed. Lets place it in a custom section, which we can call Custom Components.
  • Check Create package.

Now click OK. Two files will be generated then:

  • The .inc.php is the definition file for your component, the one you will edit during this tutorial.
  • The .package.php file is an RPCL package file you will need to install your component in HTML5 Builder. You do not need to worry about this file during this tutorial, but you will find everything you need to know about it and more here.

Now, open the .inc.php file on the Code Editor. This is the base source code you will get:

<?php
require_once("rpcl/rpcl.inc.php");

//Class definition
class HelloWorld extends Control
{
    function __construct($aowner = null)
    {
        parent::__construct($aowner);
    }

    function dumpContents()
    {
        parent::dumpContents();
    }
}

?>

Since your component is inheriting from Control, you need to include the RPCL unit where the class is defined, so add the following statement right after require_once("rpcl/rpcl.inc.php");:

use_unit("controls.inc.php");

Print Some Code

Currently, your component does nothing. In order to add some functionality to it, you need to print some code using the inherited dumpContents() method:

function dumpContents()
{
  echo "<div id=\"".$this->_name."\">Hello, World!</div>";
}

Now, the component will print a div HTML element with the message “Hello, World!”, and the component name as identifier.

Install in HTML5 Builder

Now that the component does something, it is time to install it in HTML5 Builder so you can use it in any RPCL application you work on.

First, save all your files, both the package and the component definition file, in the RPCL folder. The recommended approach is to create a separated folder for them in the RPCL folder — as administrator — and give your user rights over that folder, so you can work on its content.

Then, install the package:

  1. Go to Home > Packages, and click Add.
  2. Locate your package file (.package.php), select it and click Open.

From now on, whenever you work on a form from the Designer, your HelloWorld component will be available in the Tool Palette.

Add a Property

Property Declaration

It is time to make our component customizable with a property: Subject. This property, with World as the default value, will make it possible to define who the component should address on the message. That is, if we set the property to Jane, for example, we want the component to print the message “Hello, Jane!”.

Open the component definition file on the Code Editor, and:

  1. Place the text cursor inside the HelloWorld class. For example, right after the block of the dumpContents() method.
  2. Click the Add Published Property button in the Code Editor’s toolbar. A dialog will pop up.
  3. On the dialog, write the name of the new property (Subject) and its default value ("World", quotes included), and click OK.

The following code will be generated on the Code Editor:

protected $_subject="World";

function getSubject() { return $this->_subject; }
function setSubject($value) { $this->_subject=$value; }
function defaultSubject() { return "World"; }

Your component has now a property called Subject.

Property Implementation

Once the property is declared, you must make it work. That is, instead of printing the word ‘World’ when the componend is rendered, you will now print the content of the Subject property. So you must edit your dumpContents() function accordingly:

function dumpContents()
{
  echo "<div id=\"".$this->_name."\">Hello, ".$this->_subject."!</div>";
}

Now, anyone using your component can edit the Subject property to successfully change the message!

See Also