cleanup the block interface, add internal base block teste, added

concret implementation block closes #1063

CHANGELOG.md

@@ -29,6 +29,7 @@ The changelog contains informations about bug fixes, new features or bc breaking
 - [#1051](https://github.com/luyadev/luya/issues/1051) Added new Meida block group, changed default positioning for standard groups, make block creator usage of Project block group by default.
 - [#1057](https://github.com/luyadev/luya/issues/1057) PHP Block CMS View class provides more and better helper methods in order to retrieve config contents.
 - [#1060](https://github.com/luyadev/luya/issues/1060) Filemanager Drag&Drop and Copy&Paste of files enabled (Chrome, Firefox and HTML5 Browsers only).
+- [#1063](https://github.com/luyadev/luya/issues/1063) Cleanup the block interface in order to make concret block implementations.
 - [#999](https://github.com/luyadev/luya/issues/999) Rewritten the CRUD generator and added ability to disable i18n fiel generation.
 
 ### Fixed

envs/dev/blocks/ConcreptImplementationBlock.php

@@ -0,0 +1,215 @@
+<?php
+
+namespace app\blocks;
+
+use luya\cms\base\BlockInterface;
+use luya\cms\frontend\blockgroups\DevelopmentGroup;
+
+class ConcreptImplementationBlock implements BlockInterface
+{
+    /**
+     * Get the name of the block in order to display in administration context.
+     */
+    public function name()
+    {
+        return 'Concrept Block';
+    }
+
+    /**
+     * Returns the configuration array.
+     *
+     * @return array
+     */
+    public function config()
+    {
+        return [];
+    }
+
+    /**
+     * Returns the icon based on material icon names
+     *
+     * @return string
+     */
+    public function icon()
+    {
+        return '<i class="fa fa-icon">icon</i>';
+    }
+
+    /**
+     * Get the output in the frontend context.
+     *
+     * @return string
+     */
+    public function renderFrontend()
+    {
+        return 'frontend!';
+    }
+
+    /**
+     * Get the output in administration context.
+     *
+     * @return string
+     */
+    public function renderAdmin()
+    {
+        return 'admin!';
+    }
+
+    /**
+     * Returns a class of the blocks group.
+     *
+     * @return \luya\cms\base\BlockGroup
+     */
+    public function getBlockGroup()
+    {
+        return DevelopmentGroup::class;
+    }
+
+    // getters & setters from outside
+
+    /**
+     * The the full name based on icon() and name() concated.
+     *
+     * @return string
+     */
+    public function getFullName()
+    {
+        return $this->name();
+    }
+
+    /**
+     * Returns an array with additional help informations for specific field (var or cfg).
+     *
+     * @return array An array where the key is the cfg/var field var name and the value the helper text.
+     */
+    public function getFieldHelp()
+    {
+        return [];
+    }
+
+    private $_envs = [];
+
+    /**
+     * Set an environment option informations to the block with key value pairing.
+     *
+     * @param string $key The identifier key.
+     * @param mixed $value The value for the key.
+     */
+    public function setEnvOption($key, $value)
+    {
+        $this->_envs[$key] = $value;
+    }
+
+    private $_vars;
+
+    /**
+     * Set the values for element vars with an array key value binding.
+     *
+     * @param array $values An array where key is the name of the var-element and value the content.
+     */
+    public function setVarValues(array $values)
+    {
+        $this->_vars = $values;
+    }
+
+    private $_cfgs = [];
+
+    /**
+     * Set the values for element cfgs with an array key value binding.
+     *
+     * @param array $values An array where key is the name of the cfg-element and value the content.
+     */
+    public function setCfgValues(array $values)
+    {
+        $this->_cfgs = $values;
+    }
+
+    private $_placeholders = [];
+
+    /**
+     * Set the value from placeholders where the array key is the name of value the content of the placeholder.
+     *
+     * @param array $placeholders An array with placeholders where key is name and the value the content e.g. `['content' => 'The placheholder Content']`.
+     */
+    public function setPlaceholderValues(array $placeholders)
+    {
+        $this->_placeholders = $placeholders;
+    }
+
+    /**
+     * Returns an array of key value pairing with additional informations to pass to the API and frontend.
+     *
+     * @return array
+     */
+    public function extraVarsOutput()
+    {
+        return ['foo' => 'bar'];
+    }
+
+    /**
+     * Returns all config vars element of key value pairing to pass to the API and frontend.
+     *
+     * @return array
+     */
+    public function getVars()
+    {
+        return [];
+    }
+
+    /**
+     * Returns all config cfgs element of key value pairing to pass to the API and frontend.
+     *
+     * @return array
+     */
+    public function getCfgs()
+    {
+        return [];
+    }
+
+    /**
+     * Returns all config placeholders element of key value pairing to pass to the API and frontend.
+     *
+     * @return array
+     */
+    public function getPlaceholders()
+    {
+        return [];
+    }
+
+    /**
+     * Whether cache is enabled for this block or not.
+     *
+     * @return boolean
+     */
+    public function getIsCacheEnabled()
+    {
+        return false;
+    }
+
+    /**
+     * The time of cache expiration
+     */
+    public function getCacheExpirationTime()
+    {
+        return 60;
+    }
+
+    /**
+     * Whether is an container element or not.
+     */
+    public function getIsContainer()
+    {
+        return false;
+    }
+
+    /**
+     * Return an array of assets
+     *
+     * @todo remove in rc1
+     * @return array
+     */
+    public function getAssets()
+    {
+        return [];
+    }
+}

modules/cms/src/admin/apis/AdminController.php

@@ -26,7 +26,7 @@ public function actionDataBlocks()
             $groupPosition = null;
             foreach (Block::find()->where(['group_id' => $group['id']])->all() as $block) {
                 $obj = Block::objectId($block['id'], 0, 'admin');
-                if (!$obj || in_array($obj->className(), Yii::$app->getModule('cmsadmin')->hiddenBlocks)) {
+                if (!$obj || in_array(get_class($obj), Yii::$app->getModule('cmsadmin')->hiddenBlocks)) {
                     continue;
                 }
 

modules/cms/src/base/Block.php

@@ -8,6 +8,8 @@
  * Until all blocks extends from PhpBlock or TwigBlock directly, the default base block implements the TwigBlock.
  * This is mainly to avoid BC breaks with old blocks. In future all blocks must be extend from PhpBlock or TwigBlock.
  *
+ * @deprecated Will be removed in 1.0.0
+ * @todo Remove in 1.0.0 release.
  * @author Basil Suter <basil@nadar.io>
  */
 abstract class Block extends TwigBlock

modules/cms/src/base/BlockCfg.php

@@ -2,7 +2,12 @@
 
 namespace luya\cms\base;
 
-class BlockCfg extends \luya\cms\base\BlockConfigElement
+/**
+ * Block CFG variables ensurence.
+ * 
+ * @author Basil Suter <basil@nadar.io>
+ */
+class BlockCfg extends BlockConfigElement
 {
     public function toArray()
     {

modules/cms/src/base/BlockConfigElement.php

@@ -4,13 +4,29 @@
 
 use Exception;
 
+/**
+ * Config Element abstraction.
+ * 
+ * In order to make sure all config() elements has same values, this class implement
+ * check routines for
+ * 
+ * + {{\luya\cms\base\BlockCfg}}
+ * + {{\luya\cms\base\BlockVar}}
+ * 
+ * @author Basil Suter <basil@nadar.io>
+ */
 abstract class BlockConfigElement
 {
     public $item = [];
 
     protected $id = null;
 
-    public function __construct($item)
+    /**
+     * 
+     * @param array $item The element config with all fields.
+     * @throws Exception
+     */
+    public function __construct(array $item)
     {
         $this->item = $item;
         if (!$this->has(['var', 'label', 'type'])) {
@@ -43,5 +59,10 @@ protected function get($key, $default = null)
         return $this->item[$key];
     }
 
+    /**
+     * Extract the data from the element.
+     * 
+     * @return array
+     */
     abstract public function toArray();
 }