Grantlee模板系统扩展指南：自定义标签与过滤器开发

概述

Grantlee是一个基于Qt的模板引擎，它允许开发者通过插件机制扩展模板系统的功能。本文将详细介绍如何在Grantlee中创建自定义过滤器和标签，以及如何将它们打包成可重用的库。

自定义过滤器开发

过滤器是Grantlee模板系统中的基本构建块，它接收一个输入对象和可选参数，处理后返回字符串结果。

基础过滤器实现

要创建自定义过滤器，需要继承Grantlee::Filter类并实现doFilter方法：

class TwiceFilter : public Grantlee::Filter {
  QVariant dofilter(const QVariant &input, 
                   const QVariant &arg = QVariant(), 
                   bool autoescape = false) const override {
    auto str = getSafeString(input);
    return str + str;
  }
  
  bool isSafe() const override { return true; }
};

这个示例过滤器会将输入字符串重复两次输出。在模板中使用方式为：{{ name|twice }}

带参数的过滤器

过滤器可以接收参数实现更复杂的功能：

class RepeatFilter : public Grantlee::Filter {
  QVariant dofilter(const QVariant &input, 
                   const QVariant &arg, 
                   bool autoescape) const override {
    auto str = getSafeString(input);
    
    if (arg.type() != QMetaType::Int)
      return str; // 优雅处理错误
    
    for (int i = 0; i < arg.toInt(); ++i) {
      str.get().append(str);
    }
    return str;
  }
  
  bool isSafe() const override { return true; }
};

使用示例：{{ name|repeat:"3" }}会输出输入字符串3次。

错误处理最佳实践

过滤器应该优雅处理所有错误情况，而不是抛出异常。当参数无效时，返回原始输入或空字符串是推荐的做法。

自动转义与安全性

Grantlee提供了自动转义功能来防止XSS攻击，过滤器开发者需要考虑输出内容的安全性。

• isSafe()方法：指示过滤器是否安全（即不会引入不安全内容）
• autoescape参数：反映当前模板的自动转义状态

安全过滤器应该始终返回true，表示它们不会引入需要转义的内容。

自定义标签开发

标签比过滤器更强大，可以控制模板的解析和渲染流程。

简单标签实现

创建自定义标签需要两个步骤：

1. 继承Grantlee::AbstractNodeFactory实现工厂类
2. 继承Grantlee::Node实现节点类

class CurrentTimeNode : public Grantlee::Node {
public:
  void render(Grantlee::OutputStream *stream, 
             Grantlee::Context *c) const override {
    (*stream) << QDateTime::currentDateTime().toString();
  }
};

class CurrentTimeTagFactory : public Grantlee::AbstractNodeFactory {
  Grantlee::Node *getNode(const QString &tagContent, 
                         Grantlee::Parser *p) const override {
    QStringList parts = smartSplit(tagContent);
    parts.removeFirst(); // 移除标签名
    
    if (!parts.isEmpty())
      throw Grantlee::Exception(Grantlee::TagSyntaxError, 
                               "current_time不接受参数");
    
    return new CurrentTimeNode();
  }
};

带结束标签的复杂标签

许多标签需要开始和结束标记，如if、for等。这类标签需要解析中间内容：

Node* IfNodeFactory::getNode(const QString &tagContent, Parser *p) const {
  QStringList parts = smartSplit(tagContent);
  parts.removeFirst(); // 移除"if"
  
  auto argsList = getFilterExpressionList(parts);
  auto node = new IfNode(argsList, p);
  
  // 解析直到遇到else或endif
  auto trueList = p->parse(node, QStringList{"else", "endif"});
  node->setTrueList(trueList);
  
  auto nextToken = p->takeNextToken();
  if (nextToken.content == "else") {
    auto falseList = p->parse(node, "endif");
    node->setFalseList(falseList);
    p->removeNextToken(); // 跳过endif标签
  }
  
  return node;
}

这种模式可以扩展到支持多个中间标记，如elif等。

创建插件库

要使自定义标签和过滤器可用，需要将它们打包为Qt插件：

class MyLibrary : public QObject, public Grantlee::TagLibraryInterface {
  Q_OBJECT
  Q_INTERFACES(Grantlee::TagLibraryInterface)
  
public:
  MyLibrary(QObject *parent = 0) : QObject(parent) {
    m_nodeFactories.insert("mytag", new MyNodeFactory());
    m_filters.insert("myfilter", new MyFilter());
  }
  
  QHash<QString, Grantlee::AbstractNodeFactory*> nodeFactories() {
    return m_nodeFactories;
  }
  
  QHash<QString, Grantlee::Filter*> filters() {
    return m_filters;
  }
};

JavaScript扩展

Grantlee还支持使用JavaScript编写标签和过滤器，这为模板设计者提供了更大的灵活性。

var EchoNode = function(content) {
  this.content = content;
  this.render = function(context) {
    return content.join(" ");
  };
};

function EchoNodeFactory(tagContent, parser) {
  var content = tagContent.split(" ");
  content = content.slice(1, content.length);
  return new Node("EchoNode", content);
};
EchoNodeFactory.tagName = "echo";
Library.addFactory("EchoNodeFactory");

JavaScript扩展的关键点：

• 使用Library全局对象注册工厂
• 工厂函数返回Node对象
• 节点必须实现render方法

总结

Grantlee的扩展系统提供了强大的自定义能力，无论是通过C++还是JavaScript。理解过滤器和标签的工作原理，以及如何正确处理自动转义和安全问题，是开发高质量扩展的关键。通过创建可重用的插件库，可以在多个项目中共享自定义模板功能。