winter/modules/cms/classes/ComponentBase.php

<?php namespace Cms\Classes;

use Str;
use Lang;
use Config;
use Cms\Classes\CodeBase;
use Cms\Classes\CmsException;
use October\Rain\Extension\Extendable;

/**
 * Component base class
 *
 * @package october\cms
 * @author Alexey Bobkov, Samuel Georges
 */
abstract class ComponentBase extends Extendable
{
    use \System\Traits\AssetMaker;
    use \System\Traits\PropertyContainer;
    use \October\Rain\Support\Traits\Emitter;

    /**
     * @var string A unique identifier for this component.
     */
    public $id;

    /**
     * @var string Alias used for this component.
     */
    public $alias;

    /**
     * @var string Component class name or class alias used in the component declaration in a template.
     */
    public $name;

    /**
     * @var boolean Determines whether the component is hidden in the back-end UI.
     */
    public $isHidden = false;

    /**
     * @var string Icon of the plugin that defines the component. 
     * This field is used by the CMS internally.
     */
    public $pluginIcon;

    /**
     * @var string Component CSS class name for the back-end page/layout component list.
     * This field is used by the CMS internally.
     */
    public $componentCssClass;

    /**
     * @var boolean Determines whether Inspector can be used with the component.
     * This field is used by the CMS internally.
     */
    public $inspectorEnabled = true;

    /**
     * @var string Specifies the component directory name.
     */
    protected $dirName;

    /**
     * @var Cms\Classes\Controller Controller object.
     */
    protected $controller;

    /**
     * @var Cms\Classes\PageCode Page object object.
     */
    protected $page;

    /**
     * @var array A collection of external property names used by this component.
     */
    protected $externalPropertyNames = [];

    /**
     * Component constructor. Takes in the page or layout code section object
     * and properties set by the page or layout.
     */
    public function __construct(CodeBase $cmsObject = null, $properties = [])
    {
        if ($cmsObject !== null) {
            $this->controller = $cmsObject->controller;
            $this->page = $cmsObject;
        }

        $this->properties = $this->validateProperties($properties);

        $className = Str::normalizeClassName(get_called_class());
        $this->dirName = strtolower(str_replace('\\', '/', $className));
        $this->assetPath = Config::get('cms.pluginsDir').dirname(dirname($this->dirName));

        parent::__construct();
    }

    /**
     * Returns information about this component, including name and description.
     */
    abstract public function componentDetails();

    /**
     * Returns the absolute component path.
     */
    public function getPath()
    {
        return base_path().Config::get('cms.pluginsDir').$this->dirName;
    }

    /**
     * Executed when this component is first initialized, before AJAX requests.
     */
    public function init()
    {
    }
    
    // @deprecated: Remove this line if year >= 2015
    public function onInit()
    {
    }

    /**
     * Executed when this component is bound to a page or layout, part of 
     * the page life cycle.
     */
    public function onRun()
    {
    }

    /**
     * Executed when this component is rendered on a page or layout.
     */
    public function onRender()
    {
    }

    /**
     * Dynamically handle calls into the controller instance.
     * @param string $method
     * @param array $parameters
     * @return mixed
     */
    public function __call($method, $parameters)
    {
        if (method_exists($this, $method)) {
            return call_user_func_array([$this, $method], $parameters);
        }

        if (method_exists($this->controller, $method)) {
            return call_user_func_array([$this->controller, $method], $parameters);
        }

        throw new CmsException(Lang::get('cms::lang.component.method_not_found', [
            'name' => get_class($this),
            'method' => $method
        ]));
    }

    /**
     * Returns the component's alias, used by __SELF__
     */
    public function __toString()
    {
        return $this->alias;
    }

    //
    // External properties
    //

    /*
     * Description on how to access external property names.
     *
     * # When
     * pageNumber = "7"
     * $this->propertyName('pageNumber'); // Returns NULL
     * $this->paramName('pageNumber');    // Returns NULL
     *
     * # When
     * pageNumber = "{{ :page }}"
     *
     * $this->propertyName('pageNumber'); // Returns ":page"
     * $this->paramName('pageNumber');    // Returns "page"
     *
     * # When
     * pageNumber = "{{ page }}"
     *
     * $this->propertyName('pageNumber'); // Returns "page"
     * $this->paramName('pageNumber');    // Returns NULL
     */

    /**
     * Sets names used by external properties.
     * @param array $names The key should be the property name,
     *                     the value should be the external property name.
     * @return void
     */
    public function setExternalPropertyNames(array $names)
    {
        $this->externalPropertyNames = $names;
    }

    /**
     * Sets an external property name.
     * @param string $name Property name
     * @param string $extName External property name
     */
    public function setExternalPropertyName($name, $extName)
    {
        return $this->externalPropertyNames[$name] = $extName;
    }

    /**
     * Returns the external property name when the property value is an external property reference.
     * Otherwise the default value specified is returned.
     * @param string $name The property name
     * @param mixed $default
     * @return string
     */
    public function propertyName($name, $default = null)
    {
        return array_get($this->externalPropertyNames, $name, $default);
    }

    /**
     * Returns the external property name when the property value is a routing parameter reference.
     * Otherwise the default value specified is returned.
     * @param string $name The property name
     * @param mixed $default
     * @return string
     */
    public function paramName($name, $default = null)
    {
        if (($extName = $this->propertyName($name)) && substr($extName, 0, 1) == ':') {
            return substr($extName, 1);
        }

        return $default;
    }

    /**
     * @deprecated Returns a defined property or parameter value.
     * @todo Remove this method if year >= 2015
     * @see Docs: Components > External Parameters
     * @param $name The property or parameter name to look for.
     * @param $default A default value to return if no value is found.
     * @return string
     */
    public function propertyOrParam($name, $default = null)
    {
        $value = $this->property($name, $default);

        if (substr($value, 0, 1) == ':') {
            return $this->param(substr($value, 1), $default);
        }

        return $value;
    }
}