basic documentation

README.md

@@ -1,9 +1,85 @@
-#Select3 (yii2-select3)
+# Select3 (yii2-select3)
 
-Is a specialized jquery-based component for Yii Framework 2.0 designed to
-display a DropDownList which breaksdown the options as multi-selectable checkboxes.
+Display a hybrid between a DropDownList and a  Multi-selectable checkboxes.
+
+platform:  Yii Framework 2.0
 
 author:  Cristian Salazar  chileshift.cl/freesoftwarefactory
 
+## Preview
+
+![Preview](example.jpg)
+
+## Usage
+
+1. Via composer, 
+```
+"require": {
+    "php": ">=5.4.0",
+	"freesoftwarefactory/yii2-select3": "(put version here)"
+},
+```
+
+2. In your View
+
+```
+<?php
+use yii\widgets\ActiveForm;
+use freesoftwarefactory\select3\Select3Widget;
+
+$options = 
+[
+    'opt1' => "Chevrolet",
+    'opt2' => "Mazda",
+    'opt3' => "Audi",
+];
+
+
+
+?>
+
+<?php $form = ActiveForm::begin( [ 'id'=>'form1', ]); ?>
+
+<div class='row'>
+    <div class='col-md-3'>
+        <?=$form->field($model, 'someAttributeInYourModel')
+            ->widget(Select3Widget::className(), 
+                [
+                    'prompt' => 'Select Provider',
+                    'options' => $options,
+                    'allSelectable' => true,
+                    'allSelectableLabel' => "(All)",
+                    'visibleAtStartup' => false,
+                ]) ?>
+    </div>
+</div>
+
+<?php ActiveForm::end(); ?>
+```
+
+## Receving Values from this Control
+
+Values are base64+json encoded, that is, when you submits a form using this
+control then you will have something similar to:
+
+```
+eyJvcHQxIjp0cnVlLCJvcHQyIjp0cnVlLCJvcHQzIjpmYWxzZX0=
+```
+
+Which is a base64 encoded version of this:
+
+```
+ {"opt1":true,"opt2":true,"opt3":false}
+```
+
+So, you can just call:
+
+```
+$values = json_decode(base64_decode($model->yourAttribute),true);
+```
 
+Or... just call :)
 
+```
+$values =  Select3Widget::getDecodedValueFrom($model, 'yourAttribute');
+```

Select3Widget.php

@@ -139,15 +139,10 @@ private function getMarkup()
             </div> 
         ";
     }
-
-    private function getUniqueId()
-    {
-        return "select3_".hash('crc32',microtime(true));
-    }
-
-    private function getDecodedValue()
+
+    public static function getDecodedValueFrom($model, $attribute)
     {
-        $value = $this->model[$this->attribute];
+        $value = $model->$attribute;
 
         if(!empty($value))
         {
@@ -158,4 +153,15 @@ private function getDecodedValue()
             return null;
         }
     }
+
+    private function getUniqueId()
+    {
+        return "select3_".hash('crc32',microtime(true));
+    }
+
+    private function getDecodedValue()
+    {
+        return self::getDecodedValueFrom($this->model, $this->attribute);
+    }
+
 }