Merge branch 'Patroklo-master'

CHANGELOG.md

@@ -1,3 +1,10 @@
+2015-10-05 - 1.4.0
+------------------
+* Improve dependency injection.
+* Add comment from field.
+* Add web test.
+* Refactoring.
+
 2015-06-27 - 1.3.1
 ------------------
 * Add param `theme` to `CommentFormWidget`

Module.php

@@ -7,27 +7,117 @@
 
 namespace rmrevin\yii\module\Comments;
 
+use rmrevin\yii\module\Comments\forms\CommentCreateForm;
+use rmrevin\yii\module\Comments\models\Comment;
+use rmrevin\yii\module\Comments\models\queries\CommentQuery;
+use yii\helpers\ArrayHelper;
+
 /**
  * Class Module
  * @package rmrevin\yii\module\Comments
  */
 class Module extends \yii\base\Module
 {
 
-    const NAME = 'comments';
+    /** @var string module name */
+    public static $moduleName = 'comments';
 
     /** @var string|null */
     public $userIdentityClass = null;
 
     /** @var bool */
     public $useRbac = true;
 
+    /**
+     * Array that will store the models used in the package
+     * e.g. :
+     * [
+     *     'Comment' => 'frontend/models/comments/CommentModel'
+     * ]
+     *
+     * The classes defined here will be merged with getDefaultModels()
+     * having he manually defined by the user preference.
+     *
+     * @var array
+     */
+    public $modelMap = [];
+
     public function init()
     {
         parent::init();
 
         if ($this->userIdentityClass === null) {
             $this->userIdentityClass = \Yii::$app->getUser()->identityClass;
         }
+
+        // Merge the default model classes
+        // with the user defined ones.
+        $this->defineModelClasses();
+    }
+
+    /**
+     * @return static
+     */
+    public static function instance()
+    {
+        return \Yii::$app->getModule(static::$moduleName);
+    }
+
+    /**
+     * Merges the default and user defined model classes
+     * Also let's the developer to set new ones with the
+     * parameter being those the ones with most preference.
+     *
+     * @param array $modelClasses
+     */
+    public function defineModelClasses($modelClasses = [])
+    {
+        $this->modelMap = ArrayHelper::merge(
+            $this->getDefaultModels(),
+            $this->modelMap,
+            $modelClasses
+        );
+    }
+
+    /**
+     * Get default model classes
+     */
+    protected function getDefaultModels()
+    {
+        return [
+            'Comment' => Comment::className(),
+            'CommentQuery' => CommentQuery::className(),
+            'CommentCreateForm' => CommentCreateForm::className()
+        ];
+    }
+
+    /**
+     * Get defined className of model
+     *
+     * Returns an string or array compatible
+     * with the Yii::createObject method.
+     *
+     * @param string $name
+     * @param array $config // You should never send an array with a key defined as "class" since this will
+     *                      // overwrite the main className defined by the system.
+     * @return string|array
+     */
+    public function model($name, $config = [])
+    {
+        $modelData = $this->modelMap[ucfirst($name)];
+
+        if (!empty($config)) {
+            if (is_string($modelData)) {
+                $modelData = ['class' => $modelData];
+            }
+
+            $modelData = ArrayHelper::merge(
+                $modelData,
+                $config
+            );
+        }
+
+        return $modelData;
     }
+
 }

README.md

@@ -98,9 +98,110 @@ echo Comments\widgets\CommentListWidget::widget([
 
 ```
 
+Parameters
+----------
+
+### Module parameters
+
+* **userIdentityClass** (required, string) The user identity class that Yii2 uses to provide identity information about the users in the App.
+
+* **useRbac** (optional, boolean) Default TRUE. Defines if the comment system will use Rbac validation to check the comment permissions when trying to update, delete or add new comments.
+
+* **modelClasses** (optional, string[]) Stores the user defined model classes that will be used instead of the default ones in the comment system. Must have a key => classname format. e.g. `'Comment' => '@app\comments\CommentModel'`
+
+
+### Widget parameters
+
+* **entity** (required, string) The entity that will identify the comments under on section from all the comments in this module.
+
+* **theme** (optional, string) In case you want to use a theme in your application you should define here it's location.
+
+* **viewParams** (optional, array) Data that will be sent directly into the widget view files. Must have a key => data format. The key will be the variable name in the view. The variable `CommentsDataProvider` it's already taken.
+
+* **options** (optional, array) Default `['class' => 'comments-widget']`. Option data array that will be sent into the div holding the comment system in your views.
+
+* **pagination** (optional, array) Pagination configuration that will be used in the comment panel.
+Default data:
+```php
+public $pagination = 
+    [
+        'pageParam' => 'page',
+        'pageSizeParam' => 'per-page',
+        'pageSize' => 20,
+        'pageSizeLimit' => [1, 50],
+    ];
+```
+
+* **sort** (optional, array) Type of sorting used to retrieve the comments into the panel. Can be sorted by any of the columns defined in the `comment` table.
+Default data:
+```php
+        'defaultOrder' => [
+            'id' => SORT_ASC,
+        ],
+```
+
+* **showDeleted** (optional, boolean) Default `True`. Defines if the comments panel will show a message indicating the deleted comments.
+
+* **showCreateForm** (optional, boolean) Default `True`. Will show or hide the form to add a comment in this panel.
+
 
 Extending the package
 ---------------------
+
+### Extending Model files
+
+Depending on which ones you need, you can set the `modelMap` config property:
+
+```php
+
+	// ...
+	'modules' => [
+		// ...
+		'comments' => [
+		    'class' => 'rmrevin\yii\module\Comments\Module',
+		    'userIdentityClass' => 'app\models\User',
+		    'useRbac' => true,
+		    'modelMap' => [
+		        'Comment' => '@app\comments\CommentModel'
+		    ]
+		]
+	],
+	// ...
+```
+
+
+Attention: keep in mind that if you are changing the `Comment` model, the new class should always extend the package's original `Comment` class.
+
+
+### Attaching behaviors and event handlers
+
+The package allows you to attach behavior or event handler to any model. To do this you can set model map like so:
+
+```php
+
+	// ...
+	'modules' => [
+		// ...
+		'comments' => [
+		    'class' => 'rmrevin\yii\module\Comments\Module',
+		    'userIdentityClass' => 'app\models\User',
+		    'useRbac' => true,
+		    'modelMap' => [
+		        'Comment' => [
+		            'class' => '@app\comments\CommentModel',
+		            'on event' => function(){
+		                // code here
+		            },
+		            'as behavior' => 
+		                ['class' => 'Foo'],
+		    ]
+		]
+	],
+	// ...
+```
+
+### Extending View files
+
 You can extend the view files supplied by this package using the `theme` component in the config file.
 
 ```php
@@ -118,3 +219,6 @@ You can extend the view files supplied by this package using the `theme` compone
 
 ```
 
+### Extending Widgets
+
+To extend the widget code and behavior you only have to extend the widget classes and call them instead of the package's ones.

composer.json

@@ -31,5 +31,11 @@
     "psr-4": {
       "rmrevin\\yii\\module\\Comments\\": ""
     }
+  },
+  "extra": {
+    "asset-installer-paths": {
+      "npm-asset-library": "vendor/npm",
+      "bower-asset-library": "vendor/bower"
+    }
   }
 }

forms/CommentCreateForm.php

@@ -18,6 +18,7 @@ class CommentCreateForm extends \yii\base\Model
 
     public $id;
     public $entity;
+    public $from;
     public $text;
 
     /** @var Comments\models\Comment */
@@ -30,7 +31,14 @@ public function init()
         if (false === $this->Comment->isNewRecord) {
             $this->id = $Comment->id;
             $this->entity = $Comment->entity;
+            $this->from = $Comment->from;
             $this->text = $Comment->text;
+        } elseif (!\Yii::$app->getUser()->getIsGuest()) {
+            $User = \Yii::$app->getUser()->getIdentity();
+
+            $this->from = $User instanceof Comments\interfaces\CommentatorInterface
+                ? $User->getCommentatorName()
+                : null;
         }
     }
 
@@ -39,11 +47,13 @@ public function init()
      */
     public function rules()
     {
+        $CommentModelClassName = Comments\Module::instance()->model('comment');
+
         return [
             [['entity', 'text'], 'required'],
-            [['entity', 'text'], 'string'],
+            [['entity', 'from', 'text'], 'string'],
             [['id'], 'integer'],
-            [['id'], 'exist', 'targetClass' => Comments\models\Comment::className(), 'targetAttribute' => 'id'],
+            [['id'], 'exist', 'targetClass' => $CommentModelClassName, 'targetAttribute' => 'id'],
         ];
     }
 
@@ -54,6 +64,7 @@ public function attributeLabels()
     {
         return [
             'entity' => \Yii::t('app', 'Entity'),
+            'from' => \Yii::t('app', 'Your name'),
             'text' => \Yii::t('app', 'Text'),
         ];
     }
@@ -66,10 +77,14 @@ public function save()
     {
         $Comment = $this->Comment;
 
+        $CommentModelClassName = Comments\Module::instance()->model('comment');
+
         if (empty($this->id)) {
-            $Comment = new Comments\models\Comment();
+            $Comment = \Yii::createObject($CommentModelClassName);
         } elseif ($this->id > 0 && $Comment->id !== $this->id) {
-            $Comment = Comments\models\Comment::find()
+            /** @var Comments\models\Comment $CommentModel */
+            $CommentModel = \Yii::createObject($CommentModelClassName);
+            $Comment = $CommentModel::find()
                 ->byId($this->id)
                 ->one();
 
@@ -79,6 +94,7 @@ public function save()
         }
 
         $Comment->entity = $this->entity;
+        $Comment->from = $this->from;
         $Comment->text = $this->text;
 
         $result = $Comment->save();

migrations/m151005_165040_comment_from.php

@@ -0,0 +1,18 @@
+<?php
+
+use yii\db\Migration;
+use yii\db\Schema;
+
+class m151005_165040_comment_from extends Migration
+{
+
+    public function up()
+    {
+        $this->addColumn('{{%comment}}', 'from', Schema::TYPE_STRING . ' AFTER [[entity]]');
+    }
+
+    public function down()
+    {
+        $this->dropColumn('{{%comment}}', 'from');
+    }
+}