User Tools

Site Tools


component_class

This is an old revision of the document!


Component class

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

Simple component

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();
$mycomponent->render();

Component configuration

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.

HTML output

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.

Example

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 handling

Javascript for the component can be included using the static function requireJS(). For example:

class textOutput extends Component {
 
  // ...
 
  public function __construct() {
    self::requireJS('textoutput.js');
  }
 
  // ...
}

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.

Component event model

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:

eventEffect
disableDisables the component, by rendering a black square over it.
enableRe-enables the component.
disable_othersDisable every other component except this.
enable_othersRe-enables every other component except this.
redrawRedraws the component by fetching its content from the server. See below.

Automatic component redraw

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.

Advanced redrawing

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.

Prevent disabling

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.

component_class.1596802715.txt.gz · Last modified: 2020/08/07 12:18 by sahl

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki