mm_tpl 2.3.9 → 2.4.1

package/README.md

@@ -1,2 +1,167 @@
 # mm_tpl
- 这是超级美眉模板帮助类模块，用于MVC模式下的视图渲染
+
+这是超级美眉模板帮助类模块，用于MVC模式下的视图渲染。基于art-template模板引擎，提供了更强大的模板渲染功能。
+
+## 安装
+
+```bash
+npm install mm_tpl
+```
+
+## 基本使用
+
+### 1. 初始化模板引擎
+
+```javascript
+const Tpl = require('mm_tpl');
+const tpl = new Tpl({
+    // 可选配置参数
+    root: process.cwd(),           // 根目录
+    default_dir: "./template/",    // 默认模板目录
+    default_theme: 'default',      // 默认主题
+    extname: ".html",             // 模板文件扩展名
+    cache_root: './cache',        // 缓存目录
+    cache_extname: '.cache.html'  // 缓存文件扩展名
+});
+```
+
+### 2. 基础模板渲染
+
+```javascript
+// 简单变量替换
+const result = tpl.render("<div>${message}</div>", {
+    message: "Hello World"
+});
+
+// 输出: <div>Hello World</div>
+```
+
+### 3. 循环渲染
+
+```javascript
+// 数组循环
+const arrayResult = tpl.render(`
+    <ul>
+        ${loop arr value idx}
+            <li>${idx}: ${value}</li>
+        ${/loop}
+    </ul>
+`, { 
+    arr: [123, 234] 
+});
+
+// 对象循环
+const objectResult = tpl.render(`
+    <dl>
+        ${loop obj value key}
+            <dt>${key}</dt>
+            <dd>${value}</dd>
+        ${/loop}
+    </dl>
+`, { 
+    obj: { name: "张三", age: 25 } 
+});
+```
+
+### 4. 视图渲染
+
+```javascript
+// 设置全局变量
+$.globalBag.siteName = "我的网站";
+
+// 设置视图变量
+tpl.viewBag.title = "首页";
+
+// 渲染视图文件
+const html = tpl.view("./views/index.html", {
+    user: { name: "张三" }
+});
+```
+
+### 5. 缓存机制
+
+```javascript
+// 使用缓存渲染视图
+const html = tpl.view("./views/page", {
+    data: someData
+}, {
+    cache: true,                // 是否使用缓存
+    cache_filename: "./cache"   // 缓存文件名
+});
+
+// 清除指定目录的缓存
+tpl.clear_cache('./views/mall');
+```
+
+### 6. 钩子系统
+
+#### 添加函数钩子
+```javascript
+$.hook.addFunc('list', async function(viewBag, req, type) {
+    // 处理列表逻辑
+    return someData;
+});
+```
+
+#### 添加动作钩子
+```javascript
+$.hook.addAction('header', function(viewBag, param) {
+    return "<header>网站头部</header>";
+}, 1, "headerAction");
+```
+
+#### 添加过滤器钩子
+```javascript
+$.hook.addFilter('content', function(viewBag, content, param) {
+    return content.replace("旧文本", "新文本");
+}, 1, "contentFilter");
+```
+
+#### 使用钩子
+```javascript
+// 运行函数钩子
+await tpl.runFunc('list', {
+    query: { page: 1 }
+}, 'article');
+
+// 在模板中使用动作钩子
+${hook_action('header')}
+
+// 在模板中使用过滤器钩子
+${hook_filter('content', '原始内容')}
+```
+
+## 高级特性
+
+### 1. 主题支持
+```javascript
+// 设置当前主题
+tpl.current_theme = "dark";
+```
+
+### 2. 模板规则
+模块内置支持多种模板规则，包括：
+- nativeRule: 原生语法规则
+- artRule: art-template语法规则
+- htmlRule: HTML注释语法规则
+- jsRule: JavaScript语法规则
+- pyRule: Python风格语法规则
+
+### 3. 错误处理
+```javascript
+const html = tpl.view("./template.html", data);
+if (tpl.error) {
+    console.error("渲染错误:", tpl.error);
+}
+```
+
+## 注意事项
+
+1. 确保模板目录具有正确的读写权限
+2. 使用缓存时注意及时清理过期缓存
+3. 钩子的优先级数值越小，执行顺序越靠前
+4. 建议在生产环境开启模板缓存以提高性能
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mm_tpl",
-    "version": "2.3.9",
+    "version": "2.4.1",
     "description": "这是超级美眉模板帮助类模块，用于MVC模式下的视图渲染",
     "main": "index.js",
     "scripts": {
@@ -28,6 +28,6 @@
     "homepage": "https://github.com/qiuwenwu/mm_tpl#readme",
     "dependencies": {
         "art-template": "^4.13.2",
-        "mm_expand": "^1.7.0"
+        "mm_expand": "^1.7.9"
     }
 }

package/test.js

@@ -1,35 +1,54 @@
 const Tpl = require('./index.js');
 
-// async function test() {
-// 	var tpl = new Tpl();
-// 	var body = tpl.render("<a>${test} + 123123</a>", {
-// 		test: 123
-// 	});
-// 	console.log(body);
-// }
+/**
+ * 基础模板渲染测试函数
+ * 演示简单的变量替换功能
+ * @async
+ */
+async function test() {
+	var tpl = new Tpl();
+	var body = tpl.render("<a>${test} + 123123</a>", {
+		test: 123
+	});
+	console.log(body);
+}
 
-// async function test() {
-// 	var tpl = new Tpl();
-// 	// var body = tpl.render("<a>${loop arr value idx} ${idx} ${ value } ${/loop} + 123123</a>", { arr: [123,234] });
+/**
+ * 数组/对象循环渲染测试函数
+ * 演示模板中的循环功能
+ * @async
+ */
+async function test() {
+	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 } });
+	// 对象循环示例
+	var body = tpl.render("<a>${ loop obj value key } ${ key } ${ value } ${/loop} + 123123</a>", { obj: { a: 123, b: 467 } });
 
-// 	// var body = tpl.render("<a><!--[ for(var i = 0; i < arr.length; i++){ ]--> ${ arr[i] } <!--[ } ]--> + 123123</a>", {
-// 	// 	arr: [123, 234]
-// 	// });
+	// 传统for循环示例
+	// var body = tpl.render("<a><!--[ for(var i = 0; i < arr.length; i++){ ]--> ${ arr[i] } <!--[ } ]--> + 123123</a>", {
+	// 	arr: [123, 234]
+	// });
 
-// 	// 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] });
-// 	console.log(body);
-// }
+	// 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] });
+	console.log(body);
+}
 
+/**
+ * 模板视图渲染测试函数
+ * 演示全局变量和视图渲染的使用
+ * @async
+ */
 async function test() {
 	console.log("测试开始")
 	var tpl = new Tpl();
 	// 设置全局变量
 	$.globalBag.name = "超级美眉Art模板引擎";
 
-	// 设置实例化视图变量
+	// 设置实例视图变量
 	tpl.viewBag.name = "系统名称";
 
 	// 渲染视图
@@ -38,66 +57,76 @@ async function test() {
 	console.log(body);
 }
 
-// async function test() {
-// 	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;
-// 		}
-// 		console.log("列表", m);
-// 	});
-
-// 	$.hook.addAction('test', function aa(m, param) {
-// 		// console.log(param, m);
-// 		return "<div>你好吗？</div>";
-// 	}, 2);
-
-// 	$.hook.addAction('test', function(m, param) {
-// 		return "<div>你好！</div>";
-// 	}, 1, "测试动作1");
-
-// 	$.hook.addFilter('test', function(m, ret, param) {
-// 		console.log("测试", ret);
-// 		// console.log(param, ret, m);
-// 		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("./ad", {
-// 		arr: [123, 234],
-// 		message: "hello world！"
-// 	}, {
-// 		// 是否读取缓存文件, 如果为false, 但有cache_filename, 表示只保存缓存，但不读取
-// 		cache: false,
-// 		// 缓存文件名
-// 		cache_filename: "./test"
-// 	});
-// 	// 删除指定目录的缓存文件
-// 	// tpl.clear_cache('./mall');
-// 	console.log(body);
-// }
+/**
+ * 钩子和动作测试函数
+ * 演示带有动作和过滤器的钩子系统
+ * @async
+ */
+async function test() {
+	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;
+		}
+		console.log("列表", 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) {
+		console.log("测试", 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("./ad", {
+		arr: [123, 234],
+		message: "hello world！"
+	}, {
+		// 是否读取缓存文件，如果为false但有cache_filename，则只保存缓存但不读取
+		cache: false,
+		// 缓存文件名
+		cache_filename: "./test"
+	});
+	// 删除指定目录下的缓存文件
+	// tpl.clear_cache('./mall');
+	console.log(body);
+}
+
+// 执行测试
 test();