Merge pull request #32 from codex-editor/syntax-sugar

Syntax sugar

Author: n0str

EditorJS/BlockHandler.php

@@ -119,6 +119,9 @@ private function validate($rules, $blockData)
             }
 
             $rule = $rules[$key];
+
+            $rule = $this->expandToolSettings($rule);
+
             $elementType = $rule['type'];
 
             /**
@@ -128,6 +131,9 @@ private function validate($rules, $blockData)
                 if (!in_array($value, $rule['canBeOnly'])) {
                     throw new EditorJSException("Option '$key' with value `$value` has invalid value. Check canBeOnly param.");
                 }
+
+                // Do not perform additional elements validation in any case
+                continue;
             }
 
             /**
@@ -191,6 +197,7 @@ private function sanitize($rules, $blockData)
                 $rule = $rules[$key];
             }
 
+            $rule = $this->expandToolSettings($rule);
             $elementType = $rule['type'];
 
             /**
@@ -259,4 +266,48 @@ private function getDefaultPurifier()
 
         return $sanitizer;
     }
+
+    /**
+     * Check whether the array is associative or sequential
+     *
+     * @param array $arr – array to check
+     *
+     * @return bool – true if the array is associative
+     */
+    private function isAssoc(array $arr)
+    {
+        if ([] === $arr) {
+            return false;
+        }
+
+        return array_keys($arr) !== range(0, count($arr) - 1);
+    }
+
+    /**
+     * Expand shortified tool settings
+     *
+     * @param $rule – tool settings
+     *
+     * @throws EditorJSException
+     *
+     * @return array – expanded tool settings
+     */
+    private function expandToolSettings($rule)
+    {
+        if (is_string($rule)) {
+            // 'blockName': 'string' – tool with string type and default settings
+            $expandedRule = ["type" => $rule];
+        } elseif (is_array($rule)) {
+            if ($this->isAssoc($rule)) {
+                $expandedRule = $rule;
+            } else {
+                // 'blockName': [] – tool with canBeOnly and default settings
+                $expandedRule = ["type" => "string", "canBeOnly" => $rule];
+            }
+        } else {
+            throw new EditorJSException("Cannot determine element type of the rule `$rule`.");
+        }
+
+        return $expandedRule;
+    }
 }

README.md

@@ -131,6 +131,59 @@ Example:
     }
 ```
 
+### Short settings syntax
+
+Some syntax sugar has been added.
+
+Tool settings can be a `string`. It defines tool's type with default settings.
+```json
+"header": {
+  "text": "string",
+  "level": "int"
+}
+```
+
+It evaluates to:
+```json
+"header": {
+  "text": {
+    "type": "string",
+    "allowedTags": "",
+    "required": true
+  },
+  "level": {
+    "type": "int",
+    "allowedTags": "",
+    "required": true
+  }
+}
+```
+
+Tool settings can be an `array`. It defines set of allowed valus without sanitizing.
+```json
+"quote": {
+  "alignment": ["left", "center"],
+  "caption": "string"
+}
+```
+
+It evaluates to:
+```json
+"quote": {
+  "alignment": {
+    "type": "string",
+    "canBeOnly": ["left", "center"]
+  },
+  "caption": {
+      "type": "string",
+      "allowedTags": "",
+      "required": true
+    }
+}
+```
+
+Another configuration example: [/tests/samples/syntax-sugar.json](/tests/samples/syntax-sugar.json)
+
 ### Nested tools
 
 Tools can contain nested values. It is possible with the `array` type.

tests/SyntaxSugarTest.php

@@ -0,0 +1,83 @@
+<?php
+
+use EditorJS\EditorJS;
+use EditorJS\EditorJSException;
+
+/**
+ * Class SyntaxSugarTest
+ *
+ * Check simplified configuration structure
+ */
+class SyntaxSugarTest extends TestCase
+{
+    const CONFIGURATION_FILE = TESTS_DIR . "/samples/syntax-sugar.json";
+
+    /**
+     * Sample configuration
+     */
+    public $configuration;
+
+    /**
+     * Setup configuration
+     */
+    public function setUp()
+    {
+        $this->configuration = file_get_contents(SyntaxSugarTest::CONFIGURATION_FILE);
+    }
+
+    public function testShortTypeField()
+    {
+        $data = '{"blocks":[{"type":"header","data":{"text":"CodeX <b>Editor</b>", "level": 2}}]}';
+
+        $editor = new EditorJS($data, $this->configuration);
+        $result = $editor->getBlocks();
+
+        $this->assertEquals('CodeX Editor', $result[0]['data']['text']);
+        $this->assertEquals(2, $result[0]['data']['level']);
+    }
+
+    public function testShortTypeFieldCanBeOnly()
+    {
+        $callable = function () {
+            new EditorJS('{"blocks":[{"type":"header","data":{"text":"CodeX <b>Editor</b>", "level": 5}}]}',
+                $this->configuration);
+        };
+
+        $this->assertException($callable, EditorJSException::class, null, 'Option \'level\' with value `5` has invalid value. Check canBeOnly param.');
+    }
+
+    public function testShortIntValid()
+    {
+        new EditorJS('{"blocks":[{"type":"subtitle","data":{"text": "string", "level": 1337}}]}', $this->configuration);
+    }
+
+    public function testShortIntNotValid()
+    {
+        $callable = function () {
+            new EditorJS('{"blocks":[{"type":"subtitle","data":{"text": "test", "level": "string"}}]}', $this->configuration);
+        };
+
+        $this->assertException($callable, EditorJSException::class, null, 'Option \'level\' with value `string` must be integer');
+    }
+
+    public function testInvalidType()
+    {
+        $callable = function () {
+            $invalid_configuration = '{"tools": {"header": {"title": "invalid_type"}}}';
+            new EditorJS('{"blocks":[{"type":"header","data":{"title": "test"}}]}', $invalid_configuration);
+        };
+
+        $this->assertException($callable, EditorJSException::class, null, 'Unhandled type `invalid_type`');
+    }
+
+    public function testMixedStructure()
+    {
+        $data = '{"time":1539180803359,"blocks":[{"type":"header","data":{"text":"<b>t</b><i>e</i><u>st</u>","level":2}}, {"type":"quote","data":{"text":"<b>t</b><i>e</i><u>st</u>","caption":"", "alignment":"left"}}]}';
+        $editor = new EditorJS($data, $this->configuration);
+        $result = $editor->getBlocks();
+
+        $this->assertEquals(2, count($result));
+        $this->assertEquals('test', $result[0]['data']['text']);
+        $this->assertEquals('<b>t</b><i>e</i>st', $result[1]['data']['text']);
+    }
+}

tests/samples/syntax-sugar.json

@@ -0,0 +1,20 @@
+{
+  "tools": {
+    "header": {
+      "text": "string",
+      "level": [2, 3, 4]
+    },
+    "subtitle": {
+      "text": "string",
+      "level": "int"
+    },
+    "quote": {
+      "text": {
+        "type": "string",
+        "allowedTags": "i,b"
+      },
+      "caption": "string",
+      "alignment": ["left", "center"]
+    }
+  }
+}