From b47e294403e6e1f5502b0e5d625e55d30c20b91b Mon Sep 17 00:00:00 2001
From: barryhu <513407656@qq.com>
Date: Thu, 26 May 2022 11:06:24 +0800
Subject: [PATCH] docs(*): improve custom hook (#226)

* docs(*): improve custom hook

* fixed(custom hooks): enhance custom hook ability
---
 README.CN.md   | 54 ++++++++++++++++++++++++++++++++++++++++++++++++--
 README.md      | 53 +++++++++++++++++++++++++++++++++++++++++++++++--
 src/Factory.js |  8 +++++++-
 3 files changed, 110 insertions(+), 5 deletions(-)

diff --git a/README.CN.md b/README.CN.md
index 9efc753a7..0c5577d39 100644
--- a/README.CN.md
+++ b/README.CN.md
@@ -419,14 +419,16 @@ registerPlugin().then(() => {
 
 ### 自定义语法
 
+#### sentence Syntax
+如果编译内容没有额外特殊要求，使用普通语法
+
 ```javascript
 /*
  * 生成一个屏蔽敏感词汇的hook
  * 名字叫blockSensitiveWords
- * 范围是整个页面
  * 匹配规则会挂载到实例的RULE属性上
  */
-let BlockSensitiveWordsHook = Cherry.createSyntaxHook('blockSensitiveWords', 'page', {
+let BlockSensitiveWordsHook = Cherry.createSyntaxHook('blockSensitiveWords', Cherry.constants.HOOKS_TYPE_LIST.SEN, {
   makeHtml(str) {
     return str.replace(this.RULE.reg, '***');
   },
@@ -454,6 +456,54 @@ new Cherry({
 });
 ```
 
+
+#### paragraph Syntax
+如果编译内容要求不受外界影响，则使用段落语法
+```javascript
+/*
+ * 生成一个屏蔽敏感词汇的hook
+ * 名字叫blockSensitiveWords
+ * 匹配规则会挂载到实例的RULE属性上
+ */
+let BlockSensitiveWordsHook = Cherry.createSyntaxHook('blockSensitiveWords', Cherry.constants.HOOKS_TYPE_LIST.PAR, {
+  // 开启缓存，用于保护内容
+  needCache: true,
+  // 预处理文本，避免受影响
+  beforeMakeHtml(str) {
+    return str.replace(this.RULE.reg, (match, code) => {
+        const lineCount = (match.match(/\n/g) || []).length;
+        const sign = this.$engine.md5(match);
+        const html = `<div data-sign="${sign}" data-lines="${lineCount + 1}" >***</div>`;
+        return this.pushCache(html, sign, lineCount);
+    })
+  },
+  makeHtml(str, sentenceMakeFunc) {
+    return str;
+  },
+  rule(str) {
+    return {
+      reg: /sensitive words/g,
+    };
+  },
+});
+new Cherry({
+  id: 'markdown-container',
+  value: '# welcome to cherry editor!',
+  engine: {
+    customSyntax: {
+      // 注入编辑器的自定义语法中
+      BlockSensitiveWordsHook: {
+      syntaxClass: BlockSensitiveWordsHook,
+      // 有同名hook则强制覆盖
+      force: true,
+      // 在处理图片的hook之前调用
+      // before: 'image',
+      },
+    },
+  },
+});
+```
+
 ### 自定义工具栏
 
 ```javascript
diff --git a/README.md b/README.md
index 5cada9fdc..ceaa64075 100644
--- a/README.md
+++ b/README.md
@@ -418,14 +418,16 @@ Click [here](./examples/) for more examples.
 
 ### Customize Syntax
 
+#### sentence Syntax
+
+If there are no additional special requirements for the compiled content, use the sentence syntax
 ```javascript
 /*
  * Generate a hook to block sensitive words
  * named blockSensitiveWords
- * The scope is the entire page
  * The matching rules will be attached to the RULE attribute of the instance
  */
-let BlockSensitiveWordsHook = Cherry.createSyntaxHook('blockSensitiveWords', 'page', {
+let BlockSensitiveWordsHook = Cherry.createSyntaxHook('blockSensitiveWords', Cherry.constants.HOOKS_TYPE_LIST.SEN, {
   makeHtml(str) {
     return str.replace(this.RULE.reg, '***');
   },
@@ -453,6 +455,53 @@ new Cherry({
 });
 ```
 
+#### paragraph Syntax
+If the compiled content requires no external influence, use paragraph syntax
+```javascript
+/*
+ * Generate a hook to block sensitive words
+ * named blockSensitiveWords
+ * The matching rules will be attached to the RULE attribute of the instance
+ */
+let BlockSensitiveWordsHook = Cherry.createSyntaxHook('blockSensitiveWords', Cherry.constants.HOOKS_TYPE_LIST.PAR, {
+  // Enable caching to protect content
+  needCache: true,
+  // Pretreatment to avoid external influence
+  beforeMakeHtml(str) {
+    return str.replace(this.RULE.reg, (match, code) => {
+        const lineCount = (match.match(/\n/g) || []).length;
+        const sign = this.$engine.md5(match);
+        const html = `<div data-sign="${sign}" data-lines="${lineCount + 1}" >***</div>`;
+        return this.pushCache(html, sign, lineCount);
+    })
+  },
+  makeHtml(str, sentenceMakeFunc) {
+    return str;
+  },
+  rule(str) {
+    return {
+      reg: /sensitive words/g,
+    };
+  },
+});
+new Cherry({
+  id: 'markdown-container',
+  value: '# welcome to cherry editor!',
+  engine: {
+    customSyntax: {
+      // Inject into the editor's custom grammar
+      BlockSensitiveWordsHook: {
+      syntaxClass: BlockSensitiveWordsHook,
+      // If there is a Hook with the same name and it will be Forcibly covered 
+      force: true,
+      // Called before the hook for processing the picture
+      // before: 'image',
+      },
+    },
+  },
+});
+```
+
 ### Customize Toolbar
 
 ```javascript
diff --git a/src/Factory.js b/src/Factory.js
index 5ad474a90..654d55c35 100644
--- a/src/Factory.js
+++ b/src/Factory.js
@@ -46,11 +46,17 @@ export function createSyntaxHook(name, type, options) {
   const BaseClass = type === HOOKS_TYPE_LIST.PAR ? ParagraphBase : SyntaxBase;
   const optionsWhiteList = ['beforeMakeHtml', 'makeHtml', 'afterMakeHtml', 'rule', 'test'];
   const filteredOptions = filterOptions(options, optionsWhiteList, 'function');
+  const paragraphConfig = { needCache: options.needCache, defaultCache: options.defaultCache };
   return class CustomSyntax extends BaseClass {
     static HOOK_NAME = name;
 
     constructor(editorConfig = {}) {
-      super();
+      if (type === HOOKS_TYPE_LIST.PAR) {
+        super({ needCache: !!paragraphConfig.needCache, defaultCache: paragraphConfig.defaultCache });
+      } else {
+        super();
+      }
+
       this.config = editorConfig.config;
     }