The component class is a base UI class providing a close binding between PHP and Javascript. The class is intended to be subclassed.

In order to create a new, simple component just override the renderContent-function, such as:

class helloWorld extends Component {
 
  public function renderContent() {
    echo 'Hello world';
  }
}
 
$mycomponent = new helloWorld();
 
// Start page
 
$mycomponent->render();

To make your component configurable, override the $properties array with some default values. To extend the component from above to make the text and text color configurable, do this:

class textOutput extends Component {
 
  protected $properties = array(
    'text' => 'Hello world',
    'color' => 'black'
  );
 
  public function renderContent() {
    echo '<span style="color:'.$this->color.';">';
    echo $this->text;
    echo '</span>';
  }
}
 
$mycomponent = new textOutput();
$mycomponent->text = 'Platform4PHP is cool';
$mycomponent->color = 'red';
$mycomponent->render();

Note how the configuration properties is easily set and read.

The base component will render a div with the following properties:

• The id will match the id set by the SetID() function. If no ID is set, one will be auto-generated.
• It will add a class platform_component
• It will add a class platform_component_CLASSNAME where CLASSNAME is the name of the class.
• It will add up to three data-elements: redraw_url, componentclass and componentproperties for internal handling.

output.html

<div class="platform_component platform_component_textoutput" id="example_output" data-componentproperties="..." data-redraw_url="..." data-componentclass="textOutput">
<span style="color:red;">Platform4PHP is cool</span>
</div>

Javascript and css files are included by overwriting the $js_files and $css_files arrays in the class.

class textOutput extends Component {
 
  protected $js_files = ['filetoinclude.js'];
  protected $css_files = ['filetoinclude.css'];
}

The javascript file should always use the following template:

textoutput.js

  addPlatformComponentHandlerFunction('CLASS_IN_LOWERCASE', function(item) {
    // Do your stuff here!
  });

CLASS_IN_LOWERCASE should be exchanged with the class name of the PHP class in lowercase, so for the class textOutput, it should read like this:

textoutput.js

  addPlatformComponentHandlerFunction('textoutput', function(item) {
    // Do your stuff here!
  });

The item variable passed is a Jquery-selector pointing to the DOM node of the component. This will always point to a single node, so there is no need to iterate it. If several components of the same type exists, the function will be called multiple times.

It is very important that all components are initiated before page output is started, as the javascript and css files will not be included otherwise. This also includes sub-components, so if a component uses other components they should also be initiated before the page is started.

Therefore no component should be initiated in the render-functions. They can be initiated in the prepareData-function.

Components are designed to work with the Javascript/Jquery event model, so communication is expected to take place by triggering events on the DOM node containing the component. There are some built-in events already available on all basic components:

It is possible for Platform-components to automatically redraw themselves, if they are designed correctly. The condition for a component to be able to redraw itself, is that it must be able to do so, based solely on the content of its properties. In other words, the component should be able to render by doing just the following:

$component = new textOutput();
$component->setPropertyMap(PROPERTIES NEEDED TO RENDER COMPONENT);
$component->render();

In this case, you can force the component to redraw, by just triggering the Javascript redraw event on it.

If you make a component which isn't able to redraw itself, then you should overwrite the static variable:

protected static $can_redraw = false;

If a component is to redraw itself, it needs to know if it should validate itself for security reasons. By default it will validate the active user and fail to redraw if it can't detect a valid session.

To skip this check, then overwrite the static variable:

protected static $is_secure = false;

In this case everyone can replay the Ajax redraw request and see the content of the component.

Some components are purely visual and shouldn't be allowed to be disabled. To prevent a component from becoming disabled, set the static $can_disable variable to false in the php file.