Differences

This shows you the differences between two versions of the page.

--- component_class [2021/03/08 09:59] – sahl
+++ component_class [2023/08/15 11:49] (current) – sahl
@@ Line 22: / Line 22: @@
 </code>
-===== Component configuration =====
+===== Component properties =====
-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:
+In order for components to work correctly, all variables needed for configuring the component should be implemented as //properties//. This can be done with the addPropertyMap function, which expect an array of property keys and default values.
+To extend the component from above to make the text and text color configurable, do this:
 <code php>
 class textOutput extends Component {
-  protected $properties = array(
+  public function __construct() {
-    'text' => 'Hello world',
+    $this->addPropertyMap(array(
-    'color' => 'black'
+      'text' => 'Hello world',
+      'color' => 'black'
+    );
+    parent::__construct();
   );
@@ Line 47: / Line 52: @@
 </code>
-Note how the configuration properties is easily set and read.
+Note how the configuration properties are easily set and read.
 ===== HTML output =====
@@ Line 54: / Line 59: @@
   * 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 three data-elements: io_url, componentclass and componentproperties for internal handling.
-  * 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 ====
 <code html output.html>
-<div class="platform_component platform_component_textoutput" id="example_output" data-componentproperties="..." data-redraw_url="..." data-componentclass="textOutput">
+<div id="example_output" data-componentproperties="..." data-redraw_url="..." data-componentclass="textOutput">
 <span style="color:red;">Platform4PHP is cool</span>
 </div>
 </code>
-==== Javascript and CSS handling ====
+==== Javascript and CSS loading ====
-Javascript and css files are included by overwriting the //$js_files// and //$css_files// arrays in the class.
+A component will typically need its own css-files and javascript to function properly. These can just be included in the constructor using either ''Component::JSFile()'' and ''Component::CSSFile()''. Platform will ensure that each file is only included once.
 <code php>
 class textOutput extends Component {
-  protected $js_files = ['filetoinclude.js'];
+  public function __construct() {
-  protected $css_files = ['filetoinclude.css'];
+    static::JSFile('script.js');
+    static::CSSFile('style.css');
+    parent::__construct();
+  );
 }
 </code>
-The javascript file should always use the following template:
+==== Using CSS ====
-<code js textoutput.js>
+Using CSS is easy. Setting the ID of the component is accomplished using the ''SetID()'' function and classes can be added to the component using ''AddClass()''.
-  addPlatformComponentHandlerFunction('CLASS_IN_LOWERCASE', function(item) {
-    // Do your stuff here!
+==== Using Javascript ====
-  });
+All components have an associated javascript object named ''Platform.Component''. In javascript this object can be obtained from any component using the Jquery ''platformComponent()'' function, such as:
+<code js>
+var component_object = $('#my_component').platformComponent();
 </code>
-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:
+This object have the following functions:
+^Function^Description^
+|redraw()|Redraw the component.|
+|addIOForm(form, func, failfunc)|Set a form to be posted to the component backend. See below.|
+|backendIO(values, func)|Send some information to the component backend (and get an answer). See below.|
+|timedIO(values, callback, polltime, precision)|Send some information to the component backend at a timed interval.|
+|removeTimedIO()|Stop sending information to the component backend at a timed interval.|
-<code js textoutput.js>
+==== Communicating between the frontend and backend ====
-  addPlatformComponentHandlerFunction('textoutput', function(item) {
-    // Do your stuff here!
+Use the ''backendIO(values, func)'' javascript function to communicate between the frontend and backend. All values provided through the //values// parameter will be passed as ''$_POST'' parameters and can be handled by overwriting the ''handleIO()''-function in your PHP component class. Everything you return from this function will be passed back to the javascript-function //func//.
-  });
+=== Example ===
+<code js script.js>
+mycomponent.backendIO({event: 'setvalue', value: 'myvalue'}, function(data) { console.log('This is called with the return values from the PHP function.'); console.log(data);})
 </code>
-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.
+This will immediately pass the variables to the ''handleIO()''-function, where they can be handled.
-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.
+<code php component.php>
+public function handleIO() : array {
+  if ($_POST['event'] == 'setvalue' && $_POST['value'] == 'myvalue') return ['status' => true, 'text' => 'This was exactly as expected.'];
+  else return ['status' => false, 'text' => 'I didn\'t expect that input!'];
+}
+</code>
-Therefore no component should be initiated in the render-functions. They can be initiated in the ''prepareData''-function.
-===== Component event model =====
+==== Passing forms into the backend ====
-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:
+Forms can also be passed into the backend, much like the example above. Here you just use the ''addIOForm(form, func, failfunc)''. The //form// parameter is a jquery selector pointing to your form. The //func// parameter is a function called after the form is submitted with success and the //failfunc// parameter is a function called if the form fails.
-^event^Effect^
+When the form is submitted it is directed to the ''handleIO()''-function in your PHP component class.
-|disable|Disables the component, by rendering a black square over it.|
-|enable|Re-enables the component.|
+=== Example ===
-|disable_others|Disable every other component except this.|
-|enable_others|Re-enables every other component except this.|
+<code js script.js>
-|redraw|Redraws the component by fetching its content from the server. See below.|
+mycomponent.addIOForm($('#myform'), function(data) { console.log('This is called on success.'); })
+</code>
+When the form is submitted (and validates in the frontend), it will be intercepted by the component and the form output will end up in the ''handleIO()'' PHP function:
+<code php component.php>
+public function handleIO() : array {
+  $form = new \Platform\Form(); // You need to get the appropriate form.
+  if (! $form->validate) return ['status' => 0, 'form_errors' => $form->getAllErrors()];
+  return ['status' => 1, 'message' => 'This entire array is returned to javascript'];
+}
+</code>
+There are some requirements to the return value when handling forms. First you must return a value //status// in your return array. This should be 0 if form validation failed, and 1 if form validation succeeded. If the form failed you should also return all form errors in the //form_errors// field of your return array.
+In addition to this, you are free to return whatever values you want. These will be returned to the functions in javascript.
+=== Form handling without javascript ===
+For basic form handling, you can do this without using javascript.
+<code php component.php>
+  class myComponent {
+    ...
+    $form = new \Platform\Form(); // You need to get the appropriate form.
+    $this->registerForm($form);
+    ...
+  }
+</code>
+This will ensure that the form is handled by the component ''handleIO()''-function when it is submitted.
+==== Sending events directly to the backend ====
+Typically events are handled using the ''on()'' function in javascript, but in Platform you can redirect these events to the backend directly. This can be done using the ''registerEvent()'' function, where you name the event you want passed to the backend. The event name will be passed in the ''$_POST['event']'' variable and can be handled in the ''handleIO()'' function. All event parameters are lost when doing this.
+<code php component.php>
+class MyComponent {
+   ...
+   $this->registerEvent('mycustomevent');
+   public function handleIO() {
+     if ($_POST['event'] == 'mycustomevent') {
+       // Handle the custom event
+     }
+   }
+}
+</code>
+==== Special return instructions (reserved words) ====
+When returning an array from the ''handleIO()'' function, there are some reserved words you can use to trigger a special behaviour in the frontend.
+^Keyword^Description^
+|data|Attach data attributes to the component.|
+|destroy|Destroy the component in the DOM|
+|properties|Update the component properties in the frontend.|
+|redirect / target|Redirect the user to another URL. An optional target can be provided|
+|script|Javascript that will be executed in the frontend.|
+|trigger|Trigger an event on the component, which will bubble if the component doesn't handle it.|
+=== Example ===
+You can execute generic javascript.
+<code php>
+  public function handleIO() {
+    return ['script' => 'alert(\'This will cause an alert in the frontend!\');'];
+  }
+</code>
+If you change component properties in the ''handleIO()''-function you will need to pass them back to the front-end.
+<code php>
+  public function handleIO() {
+    return ['properties' => $this->getEncodedProperties()];
+  }
+</code>
+If the component is redrawable, the redraw can also be executed by returning true in the //redraw//-key:
+<code php>
+  public function handleIO() {
+    return ['redraw' => true];
+  }
+</code>
+==== Putting it all together ====
+In this example we will make a component which prompts the user for a name and age, and then displays this information afterwards. This is obtained 100 % in PHP:
+<code php example.php>
+class myExample extends Component {
+  public $form = null;
+  public function __construct() {
+    // Set component properties
+    $this->setPropertyMap([
+      'name' => '',
+      'age' => 0
+    ]);
+    // Construct form
+    $this->form = new Form('name_age_form');
+    $this->form->addField(TextField::Field('Name', 'name'));
+    $this->form->addField(TextField::Field('Age', 'age'));
+    $this->form->addField(SubmitButton::Field('Send', 'send'));
+    // Attach form to component
+    $this->registerForm($this->form);
+    // Redirect the resetcomponent event to the backend
+    $this->registerEvent('resetcomponent');
+  }
+  public function renderContent() {
+    // Check if name is attached to component
+    if ($this->name) {
+      // Display text
+      echo 'You have entered '.$this->name.' as name and '.$this->age.' as age.';
+      // Display a link to reset the component
+      $menuitem = new MenuItem('Reset component', '#TRIGGER=resetcomponent');
+      $menuitem->render();
+    } else {
+      // Display the form
+      $this->form->render();
+    }
+  }
+  public function handleIO() {
+    // Check if form is submitted.
+    if ($this->form->isSubmitted()) {
+      // Validate form
+      $result = $this->form->validate();
+      // Send error if not validated
+      if (! $result) return ['status' => false, 'form_errors' => $form->getAllErrors()];
+      // Get values and transfer to component properties
+      $values = $this->form->getValues();
+      $this->name = $values['name'];
+      $this->age = $values['age'];
+      // Return status, updated properties and a redraw request.
+      return ['status' => true, 'properties' => $this->getEncodedProperties(), 'redraw' => true];
+    }
+    // Check if reset was triggered
+    if ($_POST['event'] == 'resetcomponent') {
+      // Clear properties
+      $this->name = '';
+      $this->age = 0;
+      // Return updated properties and a redraw request.
+      return ['properties' => $this->getEncodedProperties(), 'redraw' => true];
+    }
+  }
+}
+</code>
+===== Components in headless scripts =====
+If you use components in headless scripts, which are scripts that doesn't contain a complete html page, but are instead meant to be loaded dynamically, be sure to call the ''Page::setPagestarted()'' function before adding your components. Otherwise included javascript and css-files will not load correctly.
+===== Adding to the DOM using javascript =====
+If you load components onto your page using javascript (by loading a PHP script which generate components), you need to execute the ''Platform.apply()'' jquery function on the DOM node where the components comes into existence in order to initialize them.
+<code php>
+var html = SOME HTML CONTAINING COMPONENTS.
+var node = domnode.html(html);
+Platform.apply(node);
+</code>
 ===== 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:
+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:
 <code php>
@@ Line 131: / Line 326: @@
 </code>
-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.
+If a component is to redraw itself, it needs to know if it should validate itself for security reasons. By default it will fail to redraw if it can't detect a valid session.
 To skip this check, then overwrite the static variable:
@@ Line 141: / Line 336: @@
 In this case everyone can replay the Ajax redraw request and see the content of the component.
+===== Extending the component javascript class =====
-==== Prevent disabling ====
+If you want to extend the javascript object associated with your custom component, this can be done in three easy steps.
+==== 1. Give the component an unique class name ====
+You first need to give your component a unique DOM class name, which is accomplished by overwriting the ''$component_class'' static variable in your component
+<code php>
+protected static $component_class = 'my_custom_platform_component';
+</code>
+==== 2. Create a new javascript class for your component ====
+Now create a new javascript class for your component. It must extend the Platform.Component class:
+<code js>
+class MyCustomPlatformComponentClass extends Platform.Component {
+ // Code goes here
+}
+</code>
+==== 3. Associate the DOM class with the javascript class ====
+This is done like this in javascript:
+<code js>
+Platform.Component.bindClass('MyCustomPlatformComponentClass', my_custom_platform_component);
+</code>
-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.