How to verify that the `replace` filter works as expected during AnQiCMS template debugging?

In the template development process of AnQiCMS, we often encounter scenarios where we need to process string content, andreplaceFilter is one of the most practical tools.It can help us easily replace specific parts of a string.However, in practical applications, ensuring that this filter works as we expect is an indispensable part of debugging the template.

UnderstandingreplaceFilter

AnQiCMS provides a series of powerful template filters that allow us to perform data conversion on template variables without writing complex logic. Among them,replaceThe core function of the filter, as the name implies, is to replace a certain 'old word' with a 'new word' in a string.

Its basic syntax is very intuitive:{{ 变量 | replace:"旧词,新词" }}

For example, if there is a variablesiteNamehas a value of"AnQiCMS 是一个内容管理系统", and we want to replace 'Content Management System' with 'CMS', you can use it like this:{{ siteName | replace:"内容管理系统,CMS" }}The output will be:AnQiCMS 是一个CMS

It is also important to understand some special cases:

• If the 'old word' is an empty string(""),replaceThe filter will exhibit a special behavior: it will insert the word 'new word' after each UTF-8 character sequence in the original string and at the beginning of the string. For example:{{ "欢迎使用安企CMS" | replace:",-" }}It will output-欢-迎-使-用-安-企-C-M-S-.
• If the 'new word' is an empty string(""),replaceThe filter will directly delete the matched 'old word'. For example:{{ "欢迎使用安企CMS" | replace:"安企," }}It will output欢迎使用CMS.

VerifyreplaceWhether the filter works as expected

When debugging the template, we have various methods to verifyreplaceFilter.

1. The most direct way: output directly on the page

This is the simplest and most commonly used validation method. Apply yourreplaceThe variable of the filter is directly output to the HTML page, and then check whether the page rendering result meets the expectations.

Suppose we have a variablearticleContentAmong them is a text, we suspect that a brand name may be misspelled and needs to be replaced:

{# 假设 articleContent 变量的值是 "这是安企CMS的测试文章，安企CMS提供卓越服务。" #}
<p>原始内容：{{ articleContent }}</p>
<p>替换后内容：{{ articleContent | replace:"安企CMS,AnQiCMS" }}</p>

Save the template and refresh the page, and we can immediately see the comparison of the content before and after the replacement, so as to judge whether the replacement is successful.

2. CombinesetLabel and condition judgment (if) to validate

When the replacement logic is complex or further processing is needed based on the replacement result, direct output may not be sufficient, we can usesettags to capturereplacethe result of the filter, then useifThis helps us verify whether the replacement has achieved a specific effect, such as whether a word has been successfully deleted or whether a new word has been successfully inserted.

{% set originalText = "这是一篇关于GoLang和Go的文章。" %}
{% set replacedText = originalText | replace:"GoLang,Go" %}

<p>原始文本: {{ originalText }}</p>
<p>替换后文本: {{ replacedText }}</p>

{% if replacedText | contain:"GoLang" %}
    <p>错误：替换后仍然包含 'GoLang'。</p>
{% else %}
    <p>验证成功：'GoLang' 已被成功替换。</p>
{% endif %}

Through this method, we can not only see the replaced result, but also confirm the accuracy of the replacement through automated judgment.containFilter (used to determine if a string contains a substring) is very useful here.

3. UsedumpDeep exploration of filter variables

If the replacement result does not match the expected, especially when dealing with special characters, whitespace, or when the variable type is uncertain,dumpThe filter will be your powerful assistant.dumpThe filter can output the internal structure, type, and value of variables in detail, helping us to understandreplaceWhat is the actual input received by the filter, and how is the replacement result represented at the bottom level.

{% set problemText = "  Hello World  " %}
<p>原始文本（dump）：{{ problemText | dump }}</p>

{% set replacedProblemText = problemText | replace:" ","-" %}
<p>替换后文本（dump）：{{ replacedProblemText | dump }}</p>

PassdumpWe can clearly see whether the spaces in the string are ordinary spaces or other whitespace characters, and how the replacement operation affects the structure of the entire string.

4. Handle replacements with HTML content: combinedsafeFilter

If yourreplaceThe filter needs to process strings containing HTML tags and the content after replacement should be parsed as HTML by the browser, not plain text, then it must usesafeFilter. Otherwise, the browser will display all HTML tags as plain text.

{% set htmlContent = "<p>原始内容</p><span>需要替换的词</span>" %}
{% set replacedHtml = htmlContent | replace:"需要替换的词,<b>已替换</b>" %}

<h3>不使用 safe 过滤器：</h3>
<div>{{ replacedHtml }}</div> {# 会显示 HTML 标签 #}

<h3>使用 safe 过滤器：</h3>
<div class="result">{{ replacedHtml | safe }}</div> {# 浏览器会解析 HTML #}

When validating, it is necessary to check the plain text output (withoutsafe）and HTML parsing output (withsafe），Ensure that the label structure is replaced correctly, and no unintended HTML damage is introduced. Also, remind yourself to usesafeIt means that we trust the security of this HTML content and must prevent potential XSS attacks.

Examples of practical application scenarios

• Unified brand name：Replace all occurrences of '安企CMS' with 'AnQiCMS' in the article.
• Correct typographical errors:Batch correct a fixed and common typo in the template.
• Process sensitive words:.Replace some sensitive words in the content submitted by users (although it is more recommended to handle it on the backend, the frontend can also be used for testing).
• Formatted display:toYYYY-MM-DDIn the date string of the format:-with/so that it can beYYYY/MM/DDForm display (even though there are special time formatting tags).

By the above method, we can efficiently and accurately verify during the AnQiCMS template debugging process.replaceFilter whether it works as expected, ensuring the correct display of content and the stability of the template.

---

Common Questions (FAQ)

1.replaceDoes the filter support regular expression replacement?In the AnQiCMS templatereplaceFilterNot supportedRegular expression.It performs a simple string literal replacement.If you need to perform complex content replacement based on regular expressions, this usually should be implemented in the backend logic or through the "Full Site Content Replacement" function in the AnQiCMS backend, rather than at the template layer.

2. 为什么我使用replaceReplaced HTML content, but the original tags are displayed on the page instead of the parsed HTML?This is usually because you forgot to add it on the variable after the replacement|safeFilter.AnQiCMS (and many modern template engines) to prevent XSS attacks, defaults to escaping all output HTML tags.{{ 变量 | replace:"旧,新" | safe }}.

3. EnglishreplaceThe filter did not take effect, what should be checked?First check if the spelling and case of the 'old word' and 'new word' are accurate.replaceThe filter is case-sensitive.Then, confirm that the variable **is indeed a string type, and its content matches the expected "old word" exactly.Finally, check if the grammar is correct, such as whether the comma separators are used correctly, and whether the quotation marks are closed.|dumpFilter to view the actual value and type of variables to better locate the problem.