Widget.php

Go to the documentation of this file.

<?php

namespace Rsi\Fred\Controller;

use Rsi\Fred\User;

class Widget extends \Rsi\Thing{

  const CHILD_ID_SEPARATOR = '__';

  //configuration options
  const CAPTION = 'caption';
  const DEFAULT_VALUE = 'defaultValue';
  const DISPLAY = 'display'; //!< Display type (see DISPLAY_* constants).
  const HELP = 'help'; //!< Help string (translated).
  const HINT = 'hint'; //!< Hint string (translated).
  const PARAMS = 'params'; //!< Extra parameters (prefix the key with a '@' to point to the value of another widget).
  const RIGHT = 'right'; //!< Optional different right with respect to the controller. If the user has the right, then (s)he
    // may view the widget. If the level is also met, the widget is also writeable.
  const TRAILER = 'trailer'; //!< Trailer string (translated).
  const TAGS = 'tags'; //!< Extra tags for help, hint, and trailer.
  const WIDGET_HELP = 'widgetHelp'; //!< General widget help (translated).
  const CLASS_NAME = 'className';

  //checks
  const MIN = 'min'; //!< Minimum value.
  const MAX = 'max'; //!< Maximum value.
  const REQUIRED = 'required'; //!< True for required. Set to self::VALID_FUNC to let the validation function handle this. Use
    // an array with [reference,operator,value] to make this dependable on the value of another widget.
  const VALID_FUNC = 'validFunc'; //!< Specific validation function (called with value and index; returns true if OK).
  const WIDGETS = 'widgets'; //!< Optional child widgets (key = name, value = widget object).
  const SECURITY_CHECKS_IGNORE = 'securityChecksIgnore'; //!< Security checks to ignore (array with checks to ignore, true =
    // all).

  //display options (note: alphabetical order)
  const DISPLAY_HIDDEN = 'h'; //!< Do not show (only hidden)
  const DISPLAY_MINIMAL = 'm'; //!< Show only value (without input element(s)).
  const DISPLAY_READABLE = 'r'; //!< Show input element(s), but read-only.
  const DISPLAY_WRITEABLE = 'w'; //!< Show editable input element(s).

  const EVENT_ACTION_PREFIX = 'controller:widget:action:';

  public $defaultValue = null;
  public $help = null;
  public $min = null;
  public $max = null;
  public $required = null;
  public $trailer = null;
  public $widgetHelp = null;
  public $validFunc = null;

  public $parent = null; //!< Optional parent widget.

  protected $_controller = null;
  protected $_id = null;
  protected $_widgets = null; //!< Optional child widgets.
  protected $_securityChecksIgnore = []; //!< Security checks to ignore.
  protected $_config = []; //!< Widget configuration (see constants).
  protected $_display = null;
  protected $_params = null;
  protected $_right = null;
  protected $_tags = null;

  public function __construct($config = null){
    $this->_config = $config ?: [];
    // Note: At this moment we do not perform the initialization, because the widget is not yet connected to a controller. When
    // the controller gets set, the widget will be initialized.
  }

  protected function init(){
    $this->configure($this->_config = array_merge(
      $this->_controller->config(['widget',lcfirst(\Rsi\File::basename(get_called_class()))],[]),
      $this->_config
    ));
    $this->publish(['controller','securityChecksIgnore']);
    $this->publish('parent',self::READWRITE);
  }
  /**
   * Update the widget configuration.
   * @param array $config  New configuration (key-value pairs). Old values, which are not in the new configuration, are
   *   preserved.
   */
  public function update($config){
    $this->_config = array_merge($this->_config,$config);
    $this->configure($config);
  }
  /**
   * Get single configuration value.
   * @param string $key  Key.
   * @param mixed $default  Default value.
   * @return mixed  Value.
   */
  protected function config($key,$default = null){
    return \Rsi\Record::get($this->_config,$key,$default);
  }
  /**
   * Public configuration.
   * @return array  Public configuration for this widget in key => value pairs.
   */
  public function clientConfig(){
    $config = array_merge(
      [self::CLASS_NAME => get_called_class()],
      $this->get([self::DEFAULT_VALUE,self::DISPLAY,self::MIN,self::MAX,self::REQUIRED])
    );
    if($params = $this->config(self::PARAMS)){
      foreach($params as $key => $value) if(substr($key,0,1) != '@') unset($params[$key]);
      if($params) $config[self::PARAMS] = array_values($params);
    }
    if($this->validFunc) $config[self::VALID_FUNC] = is_array($this->validFunc)
      ? (is_object($this->validFunc[0]) ? get_class($this->validFunc[0]) : $this->validFunc[0]) . '::' . $this->validFunc[1]
      : $this->validFunc;
    if($this->trailer) $config[self::TRAILER] = $this->trans->str($this->trailer,$this->tags);
    if($this->help) $config[self::HELP] = true;
    if($this->widgetHelp) $config[self::WIDGET_HELP] = true;
    if($this->widgets){
      $widgets = [];
      foreach($this->widgets as $id => $widget) $widgets[$id] = array_filter($widget->clientConfig());
      $config[self::WIDGETS] = $widgets;
    }
    return $config;
  }

  public function caption($id = null){
    $caption = $this->config(self::CAPTION);
    return $this->trans->str($caption === null ? $this->_controller->caption($id ?: $this->id) : $caption);
  }

  public function hint($id = null){
    $hint = $this->config(self::HINT);
    return $hint === null
      ? $this->trans->str($this->_controller->hint($id ?: $this->id),$this->tags) ?:
        $this->trans->str($this->_controller->hint(\Rsi\File::basename(get_called_class())),$this->tags)
      : $this->trans->str($hint,$this->tags);
  }
  /**
   * Convert a value from user format to standard, internal format.
   * @param mixed $value  Value in user format.
   * @return mixed  Value in standard, internal format.
   */
  public function convert($value){
    return $value;
  }
  /**
   * Convert a value from client format to standard, internal format.
   * @param mixed $value  Value in client format.
   * @return mixed  Value in standard, internal format.
   */
  public function clientConvert($value){
    return $value;
  }
  /**
   * Convert an internal value before it is stored in the request data.
   * @param mixed $value  Value in internal format.
   * @return mixed  Value in request data format.
   */
  public function dataConvert($value){
    return $value;
  }
  /**
   * Format a value from standard, internal format to user format.
   * @param mixed $value  Value in standard, internal format.
   * @return mixed  Value in user format.
   */
  public function format($value){
    return $value;
  }
  /**
   * Format a value from standard, internal format to client format.
   * @param mixed $value  Value in standard, internal format.
   * @return mixed  Value in client format.
   */
  public function clientFormat($value){
    return $value;
  }
  /**
   * Format a tag value.
   * @param mixed $value  Value in standard, internal format.
   * @return mixed  Value in user format.
   */
  public function formatTag($value){
    return $this->format($value);
  }
  /**
   * Purge function that will be called first.
   * @param mixed $value  Raw value.
   * @return string  Purged value.
   */
  protected function purgeBase($value){
    return $value;
  }
  /**
   * Purge a value.
   * @param mixed $value  Raw value.
   * @return string  Purged value.
   */
  public function purge($value){
    $value = $this->purgeBase($value);
    foreach(get_class_methods($this) as $method)
      if((strlen($method) > 5) && (substr($method,0,5) == 'purge') && ($method != 'purgeBase')) $value = call_user_func([$this,$method],$value);
    return $value;
  }
  /**
   * Note if an action is expected.
   * @param string $action
   */
  public function expect($action){
    $this->_controller->expect($this->id,$action);
  }
  /**
   * Execute an action on a child widget.
   * The widget must determine the child from the ID. E.g. for a list the ID could be [list,5,name] (name of the 5th record on
   * the list). The 'name' child widget will be called then (with 5 as the index).
   * @param array $id  Complete compound ID, including the ID of this parent.
   */
  protected function executeChild($id){
    $this->fred->externalError('Unknown child widget',['class' => get_called_class(),'id' => $id]);
  }
  /**
   * Execute an action on this widget.
   * Security checks are executed before. All input and output is handled through the request component. An action can only
   * trust the values from the data array. An action must check if the widget is writeable for actions that perform 'write
   * like' behaviour.
   */
  public function execute(){
    if(!$this->security->check($this->securityChecksIgnore,$this->_controller->expected($this->id,$action = $this->_controller->action)))
      $this->fred->externalError('Suspicious widget action call',['class' => get_called_class()]);
    elseif(count($id = explode(self::CHILD_ID_SEPARATOR,$this->request->widgetId)) > 1) $this->executeChild($id);
    elseif(!method_exists($this,$method = 'action' . ucfirst($action)))
      $this->fred->externalError('Unknown widget action',['class' => get_called_class(),'action' => $action]);
    else{ //action on this widget
      call_user_func([$this,$method]);
      $this->event->trigger(self::EVENT_ACTION_PREFIX . lcfirst(\Rsi\File::basename(get_called_class())) . ':' . $action,$this,array_pop($id));
    }
  }
  /**
   * Check if a value is empty.
   * @param mixed $value
   * @return bool  True when empty.
   */
  public function nothing($value){
    return \Rsi::nothing($value);
  }

  protected function checkMin($value,$index = null){
    return $this->nothing($this->min) || ($value >= $this->min);
  }

  protected function checkMax($value,$index = null){
    return $this->nothing($this->max) || ($value <= $this->max);
  }
  /**
   * Required check.
   * This check will only be called when the value is empty.
   * If the required parameter has the value self::VALID_FUNC, then the checkValidFunc() function will be used to determine
   * whether the value is correct (allowed empty).
   * If the required parameter is an array, the first entry is seen as an reference to another widget (e.g. 'List__*__Name' -
   * where the asterisk will be replaced with the current index). Its value will then be used for an comparison with an
   * operator (2nd entry) and a value (3rd entry). If this comparison returns true, the value is required.
   */
  protected function checkRequired($value,$index = null){
    if($this->required === self::VALID_FUNC) return $this->checkValidFunc($value,$index);
    if(is_array($required = $this->required)){
      $id = explode(self::CHILD_ID_SEPARATOR,str_replace('*',$index,array_shift($required)));
      $widget = $this->_controller->widgets[$widget_id = array_shift($id)];
      $ref = $widget->purge($this->request->complex(['widget',$widget_id]));
      $ref = $this->_controller->view->convert ? $widget->convert($ref) : $widget->clientConvert($ref);
      $required = \Rsi\Str::operator($id ? \Rsi\Record::get($ref,$id) : $ref,array_shift($required),array_shift($required),true);
    }
    return !$required;
  }

  protected function checkValidFunc($value,$index = null){
    return $this->validFunc ? call_user_func($this->validFunc,$value,$index) : true;
  }
  /**
   * Check a value.
   * @param mixed $value  Value in standard, internal format.
   * @param int $index  Index for mutual children.
   * @return string  Error code (empty = OK).
   */
  public function check($value,$index = null){
    if($this->nothing($value)) return $this->checkRequired($value,$index) ? null : 'required';
    foreach(get_class_methods($this) as $method)
      if(($method != 'checkRequired') && (strlen($method) > 5) && (substr($method,0,5) == 'check') && !call_user_func([$this,$method],$value,$index))
        return lcfirst(substr($method,5));
    return null; //OK
  }

  protected function actionHelp(){
    $type = self::HELP;
    switch($this->request->type){
      case 'widget': $type = self::WIDGET_HELP; break;
    }
    $this->request->result = [
      'caption' => $this->trans->str($this->_controller->helpCaption,$this->tags),
      'help' => $this->trans->str(($this->widgets[$this->request->id] ?? $this)->$type,$this->tags)
    ];
  }

  protected function setController($value){
    $this->_controller = $value;
    $this->init();
  }

  protected function getDisplay(){
    if($this->_display === null){
      if(!$this->user->authorized($this->right,User::RIGHT_LEVEL_READ)) $this->_display = false;
      else{
        $this->_display = $this->config(self::DISPLAY,$this->_controller->display);
        if(($this->_display > self::DISPLAY_READABLE) && !$this->user->authorized($this->right,User::RIGHT_LEVEL_WRITE))
          $this->_display = self::DISPLAY_READABLE;
        if($this->parent) $this->_display = min($this->_display,$this->parent->display);
      }
    }
    return $this->_display;
  }

  protected function getFred(){
    return $this->_controller->fred;
  }

  protected function getId(){
    if($this->_id === null){
      $this->_id = false;
      if($this->parent){
        foreach($this->parent->widgets as $id => $widget) if($this === $widget){
          $this->_id = $this->parent->id . self::CHILD_ID_SEPARATOR . $id;
          break;
        }
      }
      elseif($this->_controller) foreach($this->_controller->widgets as $id => $widget) if($this === $widget){
        $this->_id = $id;
        break;
      }
    }
    return $this->_id;
  }

  protected function getParams(){
    if($this->_params === null){
      $this->_params = [];
      if($params = $this->config(self::PARAMS)) foreach($params as $key => $value){
        if(substr($key,0,1) == '@'){
          $key = substr($key,1);
          if(array_key_exists($value,$this->request->data)) $value = $this->request->data[$value];
          else{
            $widget = $this->_controller->widgets[$value];
            $value = $widget->clientConvert($this->request->complex(['widget',$value]));
            if($widget->check($value)) $value = false;
          }
        }
        $this->_params[$key] = $value;
      }
    }
    return $this->_params;
  }

  protected function getReadable(){
    return $this->display >= self::DISPLAY_READABLE;
  }

  protected function getRight(){
    if($right = $this->config(self::RIGHT)) return $right;
    if($right !== false) return $this->_controller->right;
    return null;
  }

  protected function getTags(){
    if($this->_tags === null){
      $this->_tags = $this->config(self::TAGS,[]);
      if($this->_config) foreach($this->_config as $key => $value)
        $this->_tags[$key] = is_array($value) || is_object($value) ? (bool)$value : $value;
      if(!$this->nothing($this->min)) $this->_tags[self::MIN] = $this->formatTag($this->min);
      if(!$this->nothing($this->max)) $this->_tags[self::MAX] = $this->formatTag($this->max);
    }
    return $this->_tags;
  }

  protected function getWidgets(){
    if($this->_widgets === null){
      $this->_widgets = $this->config(self::WIDGETS,[]);
      foreach($this->_widgets as $widget){
        $widget->parent = $this;
        $widget->controller = $this->_controller;
      }
    }
    return $this->_widgets;
  }

  protected function getWriteable(){
    return $this->user->authorized($this->right,User::RIGHT_LEVEL_WRITE);
  }

  protected function _get($key){
    return array_key_exists($key,$this->_config) ? $this->_config[$key] : $this->_controller->component($key);
  }

}