mm_tpl 2.4.6 → 2.4.7

package/README.md

@@ -2,6 +2,19 @@
 
 超级美眉模板引擎模块，基于art-template模板引擎，提供强大的MVC模式视图渲染功能，支持钩子系统、主题切换和缓存机制。
 
+[English Documentation](README_EN.md) | [中文文档](README.md)
+
+## 目录
+
+- [特性](#特性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [高级特性](#高级特性)
+- [API 参考](#api-参考)
+- [注意事项](#注意事项)
+- [开发](#开发)
+- [许可证](#许可证)
+
 ## 特性
 
 - 🚀 基于art-template高性能模板引擎

package/README_EN.md

@@ -0,0 +1,327 @@
+# mm_tpl
+
+Super Meimei Template Engine Module, based on art-template engine, provides powerful MVC pattern view rendering functionality with hook system, theme switching, and caching mechanism.
+
+[中文文档](README.md) | [English Documentation](README_EN.md)
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Advanced Features](#advanced-features)
+- [API Reference](#api-reference)
+- [Notes](#notes)
+- [Development](#development)
+- [License](#license)
+
+## Features
+
+- 🚀 High-performance template engine based on art-template
+- 🔧 Support for multiple template syntax rules
+- 🎨 Theme switching and template file priority search
+- ⚡ Built-in caching mechanism for performance optimization
+- 🔌 Powerful hook system support
+- 📁 Flexible directory structure support
+- 🛡️ Comprehensive error handling mechanism
+
+## Installation
+
+```bash
+npm install mm_tpl
+```
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install mm_tpl
+```
+
+### 2. Initialize Template Engine
+
+```javascript
+const {Tpl} = require('mm_tpl');
+
+// Create template instance
+const tpl = new Tpl({
+    root: process.cwd(),           // Root directory
+    default_dir: "./template/",    // Default template directory
+    default_theme: 'default',      // Default theme
+    extname: ".html",             // Template file extension
+    cache_root: './cache',        // Cache directory
+    cache_extname: '.cache.html', // Cache file extension
+    rules: [nativeRule, artRule, htmlRule, jsRule, pyRule, pyRule2] // Template rules
+});
+```
+
+### 3. Basic Template Rendering
+
+```javascript
+// Simple variable substitution
+const result = tpl.render("<div>${message}</div>", {
+    message: "Hello World"
+});
+// Output: <div>Hello World</div>
+
+// Compile template function
+const compiled = tpl.compile("<div>${name} - ${age}</div>");
+const result2 = compiled({ name: "John", age: 25 });
+// Output: <div>John - 25</div>
+```
+
+### 4. Loop Rendering
+
+```javascript
+// Array loop
+const arrayResult = tpl.render(`
+    <ul>
+        ${loop arr value idx}
+            <li>${idx}: ${value}</li>
+        ${/loop}
+    </ul>
+`, { 
+    arr: [123, 234] 
+});
+
+// Object loop
+const objectResult = tpl.render(`
+    <dl>
+        ${loop obj value key}
+            <dt>${key}</dt>
+            <dd>${value}</dd>
+        ${/loop}
+    </dl>
+`, { 
+    obj: { name: "John", age: 25 } 
+});
+
+// Traditional for loop
+const forResult = tpl.render(`
+    <ul>
+        <!--[ for(var i = 0; i < arr.length; i++){ ]-->
+            <li>${arr[i]}</li>
+        <!--[ } ]-->
+    </ul>
+`, {
+    arr: [123, 234]
+});
+
+// Each loop
+const eachResult = tpl.render(`
+    <ul>
+        ${each arr}
+            <li>${$value}</li>
+        ${/each}
+    </ul>
+`, {
+    arr: [123, 234]
+});
+// Output: 
+// <ul>
+//     <li>123</li>
+//     <li>234</li>
+// </ul>
+```
+
+### 5. View Rendering
+
+```javascript
+// Set global variables
+$.globalBag.siteName = "My Website";
+
+// Set view variables
+tpl.set({
+    title: "Homepage",
+    keywords: "keywords"
+});
+
+// Render view file
+const html = tpl.view("./views/index.html", {
+    user: { name: "John" }
+});
+// Output: Rendering result <div>Hello World</div>
+
+// Get view variable
+const title = tpl.get("title");
+
+// Delete view variable
+tpl.del("keywords");
+```
+
+### 6. Caching Mechanism
+
+```javascript
+// Use cache for view rendering
+const html = tpl.view("./views/page", {
+    data: someData
+}, {
+    cache: true,                // Whether to use cache
+    cache_filename: "./cache"   // Cache filename
+});
+
+// Clear cache
+tpl.clearCache('./views/mall'); // Clear cache for specific directory
+// or
+tpl.clearCache(); // Clear all cache
+```
+
+### 7. Hook System
+
+#### Add Function Hook
+```javascript
+$.hook.addFunc('list', async function(viewBag, req, type) {
+    // Process list logic
+    var query = req.query;
+    if (query.user_id) {
+        viewBag.user_id = query.user_id;
+    }
+    return someData;
+}, 100, 'listFunc'); // sort: priority, alias: alias
+```
+
+#### Add Action Hook
+```javascript
+$.hook.addAction('header', function(viewBag, param) {
+    return "<header>Website Header</header>";
+}, 1, "headerAction");
+```
+
+#### Add Filter Hook
+```javascript
+$.hook.addFilter('content', function(viewBag, content, param) {
+    return content.replace("old text", "new text");
+}, 1, "contentFilter");
+```
+
+#### Execute Hooks
+```javascript
+// Execute function hook
+const result = await tpl.runFunc('list', { query: { page: 1 } }, 'article');
+
+// Execute action hook
+const actionResult = tpl.runHook('header', { param: 'value' });
+
+// Use hooks in template
+const html = tpl.render(`
+    <div>
+        ${hookAction('header')}
+        ${hookFilter('content', 'original content')}
+    </div>
+`, data);
+```
+
+#### Delete Hooks
+```javascript
+// Delete specific hook
+$.hook.delFunc('list', 'listFunc');
+$.hook.delAction('header', 'headerAction');
+$.hook.delFilter('content', 'contentFilter');
+
+// Clear all hooks
+$.hook.clear();
+```
+
+## Advanced Features
+
+### 1. Theme and Directory Support
+```javascript
+// Set current theme
+tpl.current_theme = "dark";
+
+// Template file search order (priority from high to low):
+// 1. diy directory (custom directory)
+// 2. Current theme directory
+// 3. Default theme directory
+```
+
+### 2. Template Rules
+Built-in support for multiple template rules, including:
+- nativeRule: Native syntax rules
+- artRule: art-template syntax rules
+- htmlRule: HTML comment syntax rules
+- jsRule: JavaScript syntax rules
+- pyRule: Python-style syntax rules
+
+### 3. Error Handling
+```javascript
+const html = tpl.view("./template.html", data);
+if (tpl.error) {
+    console.error("Rendering error:", tpl.error);
+}
+```
+
+### 4. Character Escaping
+```javascript
+// Automatically escape special characters
+const escaped = tpl.escape("<div>${content}</div>");
+// Output: <div>·$·{content}</div>
+
+// Restore escaped characters
+const restored = tpl.escape(escaped, true);
+// Output: <div>${content}</div>
+```
+
+### 5. Global Mounting
+```javascript
+// Automatically mount to global object
+if (global.$ && !$.Tpl) {
+    $.Tpl = Tpl;
+    $.tpl = new Tpl();
+}
+```
+
+## API Reference
+
+### Tpl Class Methods
+
+- `constructor(config)` - Constructor, create template instance
+- `setConfig(config)` - Set configuration parameters
+- `render(body, model, options)` - Render template string
+- `compile(body, options)` - Compile template to function
+- `view(file, model, options)` - Render template file
+- `set(obj)` - Set view data
+- `get(key)` - Get view data
+- `del(keys)` - Delete view data
+- `clearCache(path, file)` - Clear cache
+- `runFunc(name, req, ...args)` - Execute function hook
+- `runHook(name, req, ...args)` - Execute action hook (alias of runFunc)
+- `escape(body, restore)` - Escape/restore characters
+
+### Hook Class Methods
+
+- `addFunc(name, func, sort, alias)` - Add function hook
+- `addAction(name, func, sort, alias)` - Add action hook
+- `addFilter(name, func, sort, alias)` - Add filter hook
+- `runFunc(name, model, req, ...args)` - Execute function hook
+- `runAction(name, model, ...args)` - Execute action hook
+- `runFilter(name, model, ret, ...args)` - Execute filter hook
+- `delFunc(name, alias)` - Delete function hook
+- `delAction(name, alias)` - Delete action hook
+- `delFilter(name, alias)` - Delete filter hook
+- `clear(name)` - Clear hooks
+
+## Notes
+
+1. **Dependencies**: Requires `art-template` and `mm_expand` dependency packages
+2. **Directory Permissions**: Ensure template directories have read/write permissions
+3. **Cache Management**: Clean expired cache promptly to avoid memory leaks
+4. **Hook Priority**: Lower numerical values indicate higher priority and earlier execution
+5. **Async Processing**: Hook functions support async operations, pay attention to error handling
+6. **File Search**: Template files are searched in priority order, ensure files exist
+7. **Character Escaping**: Automatic handling of template syntax characters to avoid conflicts
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Check code coverage
+npm run coverage
+```
+
+## License
+
+MIT License

package/hook.js

@@ -1,3 +1,4 @@
+
 const {
 	types
 } = require("util");

package/index.js

@@ -1,8 +1,8 @@
 const template = require('art-template');
-const Hook = require('./hook.js');
 const {
 	Base
 } = require('mm_expand');
+const Hook = require('./hook.js');
 const {
 	nativeRule,
 	artRule,

package/package.json

@@ -1,27 +1,33 @@
 {
     "name": "mm_tpl",
-    "version": "2.4.6",
-    "description": "这是超级美眉模板帮助类模块，用于MVC模式下的视图渲染",
+    "version": "2.4.7",
+    "description": "Super Meimei Template Engine - High-performance template engine based on art-template with MVC pattern, hook system, theme switching and caching mechanism",
     "main": "index.js",
     "scripts": {
         "dev": "nodemon test.js",
-        "test": "node test.js"
+        "test": "node test.js",
+        "coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
     },
     "repository": {
         "type": "git",
         "url": "git+https://gitee.com/qiuwenwu91/mm_tpl.git"
     },
     "keywords": [
+        "template",
+        "engine",
         "mvc",
         "web",
         "view",
-        "model",
-        "controller",
         "render",
-        "template"
+        "art-template",
+        "hook",
+        "theme",
+        "cache",
+        "nodejs",
+        "javascript"
     ],
     "author": "邱文武",
-    "license": "ISC",
+    "license": "MIT",
     "bugs": {
         "url": "https://gitee.com/qiuwenwu91/mm_tpl/issues"
     },
@@ -29,5 +35,16 @@
     "dependencies": {
         "art-template": "^4.13.4",
         "mm_expand": "^1.9.7"
-    }
+    },
+    "engines": {
+        "node": ">=12.0.0"
+    },
+    "files": [
+        "index.js",
+        "hook.js",
+        "tpl_rule.js",
+        "README.md",
+        "README_EN.md",
+        "package.json"
+    ]
 }

package/.gitattributes

@@ -1,5 +0,0 @@
-# Auto detect text files and perform LF normalization
-* text=auto
-*.js linguist-language=JavaScript
-*.css linguist-language=JavaScript
-*.html linguist-language=JavaScript

package/cache/test.cache.html

@@ -1,27 +0,0 @@
-<!DOCTYPE html>
-<html>
-	<head>
-		<meta charset="utf-8">
-		<title>超级美眉Art模板引擎-游戏测试</title>
-	</head>
-	<body>
-		<div>游戏主题</div>
-		<div><div class="bar_user">
-	<div>用户ID：1</div>
-	<div>当前项目ID：2</div>
-	<div>hello world！</div>
-</div>
-
-<div class="bar">导航栏</div>
-<!-- 广告位 -->
-<div class="ad"><div>
-	<p>这是一个广告位！</p>
-</div>
-</div>
-<style>
-	.bar {
-		font-weight: 800;
-	}
-</style></div>
-	</body>
-</html>

package/template/default/test.html

@@ -1,36 +0,0 @@
-<!DOCTYPE html>
-<html>
-	<head>
-		<meta charset="utf-8">
-		<title>${globalBag.name}</title>
-	</head>
-	<body>
-		<h5>${viewBag.name}</h5>
-		<ul>
-			${loop arr value idx}
-			<li>${ value }</li>
-			${/loop}
-		</ul>
-		<ul>
-			<!--[ for(var i = 0; i < arr.length; i++) { ]-->
-			<li>${ arr[i] }</li>
-			<!--[ } ]-->
-		</ul>
-		<ul>
-			<!--{loop arr value idx}-->
-			<li>${ value }</li>
-			<!--{/loop}-->
-		</ul>
-		<script type="text/javascript">
-			/*[loop arr value idx]*/
-			var a_${idx} = ${value};
-			/*[/loop]*/
-		</script>
-		${viewBag.name}
-		## "计算" ##
-		123123'"""#
-		"price" + "NIHAO"
-		#"""'
-		## "#计算" ##
-	</body>
-</html>

package/template/diy/ad.html

@@ -1,3 +0,0 @@
-<div>
-	<p>这是一个广告位！</p>
-</div>

package/template/game/bar.html

@@ -1,17 +0,0 @@
-<div class="bar_user">
-	${@hookFilter('test', hookAction('test', '好的'), '真的')}
-	<div>用户ID：${viewBag.user_id}</div>
-	<div>当前项目ID：${viewBag.project_id}</div>
-	<div>${message}</div>
-</div>
-
-<div class="bar">导航栏</div>
-<!-- 广告位 -->
-<div class="ad">
-	${@view('./ad')}
-</div>
-<style>
-	.bar {
-		font-weight: 800;
-	}
-</style>

package/template/game/test.html

@@ -1,11 +0,0 @@
-<!DOCTYPE html>
-<html>
-	<head>
-		<meta charset="utf-8">
-		<title>${globalBag.name}-游戏测试</title>
-	</head>
-	<body>
-		<div>游戏主题</div>
-		<div>${@view('./bar.html')}</div>
-	</body>
-</html>

package/test.js

@@ -1,143 +0,0 @@
-const {Tpl} = require('./index.js');
-
-/**
- * 基础模板渲染测试函数
- * 演示简单的变量替换功能
- * @async
- */
-async function test1() {
-	var tpl = new Tpl();
-	var body = tpl.render("<a>${test} + 123123</a>", {
-		test: 123
-	});
-	$.log.debug(body);
-}
-
-/**
- * 数组/对象循环渲染测试函数
- * 演示模板中的循环功能
- * @async
- */
-async function test2() {
-	var tpl = new Tpl();
-	// 数组循环示例
-	// var body = tpl.render("<a>${loop arr value idx} ${idx} ${ value } ${/loop} + 123123</a>", { arr: [123,234] });
-
-	// 对象循环示例
-	var body = tpl.render("<a>${ loop obj value key } ${ key } ${ value } ${/loop} + 123123</a>", { obj: { a: 123, b: 467 } });
-
-	// 传统for循环示例
-	// var body = tpl.render("<a><!--[ for(var i = 0; i < arr.length; i++){ ]--> ${ arr[i] } <!--[ } ]--> + 123123</a>", {
-	// 	arr: [123, 234]
-	// });
-
-	// each循环示例
-	// var body = tpl.render("<a>${ each arr } ${ arr[$index] } ${/each} + 123123</a>", { arr: [123,234] });
-	// var view = tpl.render("<a>${ each arr } ${ $value } ${/each} + 123123</a>", { arr: [123,234] });
-	$.log.debug(body);
-}
-
-/**
- * 模板视图渲染测试函数
- * 演示全局变量和视图渲染的使用
- * @async
- */
-async function test3() {
-	var tpl = new Tpl();
-	// 设置全局变量
-	$.globalBag.name = "超级美眉Art模板引擎";
-
-	// 设置实例视图变量
-	tpl.viewBag.name = "系统名称";
-
-	// 渲染视图
-	var body = tpl.view("./test.html", { arr: [123,234] });
-	$.log.debug(tpl.error);
-	$.log.debug(body);
-}
-
-/**
- * 钩子和动作测试函数
- * 演示带有动作和过滤器的钩子系统
- * @async
- */
-async function test4() {
-	var tpl = new Tpl();
-
-	// 设置全局变量
-	$.globalBag.name = "超级美眉Art模板引擎";
-
-	// 设置实例视图变量
-	tpl.viewBag.name = "系统名称";
-	tpl.current_theme = "game";
-	tpl.dir = "";
-
-	// 添加列表函数钩子
-	$.hook.addFunc('list', async function(m, req, type) {
-		var query = req.query;
-		if (query.user_id) {
-			m.user_id = query.user_id;
-		}
-		if (query.project_id) {
-			m.project_id = query.project_id;
-		}
-		$.log.debug("列表", m);
-	});
-
-	// 添加动作钩子
-	$.hook.addAction('test', function aa(m, param) {
-		return "<div>你好吗？</div>";
-	}, 2);
-
-	$.hook.addAction('test', function(m, param) {
-		return "<div>你好！}</div>";
-	}, 1, "测试动作1");
-
-	// 添加过滤器钩子
-	$.hook.addFilter('test', function(m, ret, param) {
-		$.log.debug("测试", ret);
-		return ret.replace("你", "您");
-	}, 1, "测试过滤");
-
-	// 删除动作钩子
-	$.hook.delAction('test', "aa");
-	$.hook.delAction('test', "测试动作1");
-	// $.hook.delFilter('test', "测试过滤");
-
-	// 运行函数钩子
-	await tpl.runFunc('list', {
-		query: {
-			user_id: 1,
-			project_id: 2
-		}
-	}, 'article');
-
-	// 使用缓存渲染视图
-	var body = tpl.view("./test", {
-		arr: [123, 234],
-		message: "hello world！"
-	}, {
-		// 是否读取缓存文件，如果为false但有cache_filename，则只保存缓存但不读取
-		cache: false,
-		// 缓存文件名
-		cache_filename: "./test"
-	});
-	// 删除指定目录下的缓存文件
-	// tpl.clear_cache('./mall');
-	$.log.debug("渲染结果", body);
-}
-
-// 执行测试
-async function demo() {
-	$.log.debug("测试开始");
-	$.log.debug("测试1");
-	await test1();
-	$.log.debug("测试2");
-	await test2();
-	$.log.debug("测试3");
-	await test3();
-	$.log.debug("测试4");
-	await test4();
-}
-
-demo();