How does the `urlencode` filter specifically apply to URL parameters in AnQiCMS templates?

In AnQiCMS template development, building dynamic URLs is a common requirement.Whether linking to the search results page, filtering list, or passing specific parameters to the backend service, the correctness of the URL is crucial.urlencodeFilter becomes a crucial tool to ensure that URL parameters are valid and secure.

Understanding the importance of URL encoding.

URL (Uniform Resource Locator) has a strict character specification. Some characters in the URL have special meanings, such as/used for path separation.?used for introducing query parameters,&Used to separate multiple query parameters,=Used to separate parameter names and parameter values. In addition, spaces, Chinese characters, non-ASCII characters, or certain punctuation marks are not allowed to appear directly in URLs.

When a URL parameter contains these special characters, if not processed, the browser or server may incorrectly parse this URL, causing the page to fail to load normally, or incomplete parameter passing, or even trigger security vulnerabilities. For example, searchTerm=安企CMS & GoLangThis parameter, if directly placed in the URL,&the symbol will be incorrectly parsed as a new parameter separator, leading toGoLangpartial loss.

The role of URL encoding (also known as percent encoding) is to convert these special characters into a URL-safe format. For example, a space will be encoded as%20,&will be encoded as%26Comma characters are also encoded as a series of percent signs followed by hexadecimal numbers.

In the AnQiCMS templateurlencodeFilter

The template engine of AnQiCMS providesurlencodeFilter, specifically used for percent-encoding the variable values in a URL. Its usage is very intuitive, just add|urlencode.

Basic syntax:

{{ 变量 | urlencode }}

This filter checks变量The content, and all characters that do not meet the URL specification should be converted to their percent-encoded forms, ensuring that the generated URL will not cause any issues during network transmission and parsing.

Actual application scenarios

Let's look at several specific examples to seeurlencodeHow does the filter work in the AnQiCMS template:

1. Dynamically generate search result links:Assuming your website has a search function, the keywords entered by users may contain spaces, Chinese characters, or special symbols.To ensure the validity of the search link, we need to encode the keywords.

   {# 假设用户输入的搜索关键词存储在变量 searchTerm 中 #}
   {% set searchTerm = "AnQiCMS 模板开发 & SEO" %}
   
   
   {# 使用 urlencode 过滤器对关键词进行编码 #}
   <a href="/search?q={{ searchTerm|urlencode }}">点击搜索：{{ searchTerm }}</a>
   
   
   {# 渲染后的 HTML 可能是这样的： #}
   {# <a href="/search?q=AnQiCMS%20%E6%A8%A1%E6%9D%BF%E5%BC%80%E5%8F%91%20%26%20SEO">点击搜索：AnQiCMS 模板开发 & SEO</a> #}
   

   In this example,searchTermSpaces, Chinese and&All symbols are correctly encoded, ensuring the integrity and accessibility of the URL.

2. Build a filter link with complex parameters:When you need to filter a list based on multiple conditions (such as category names, product attribute values), and these conditions may contain special characters,urlencodeit is also indispensable.

   {# 假设我们有一个分类名称变量 categoryName #}
   {% set categoryName = "产品系列 (新品)" %}
   {# 假设还有一个属性值变量 attributeValue #}
   {% set attributeValue = "金属 & 塑料" %}
   
   
   <a href="/products?category={{ categoryName|urlencode }}&attribute={{ attributeValue|urlencode }}">
       查看 "{{ categoryName }}" 下的 "{{ attributeValue }}" 产品
   </a>
   
   
   {# 渲染后的 HTML 可能是这样的： #}
   {# <a href="/products?category=%E4%BA%A7%E5%93%81%E7%B3%BB%E5%88%97%20%28%E6%96%B0%E5%93%81%29&attribute=%E9%87%91%E5%B1%9E%20%26%20%E5%A1%91%E6%96%99">查看 "产品系列 (新品)" 下的 "金属 & 塑料" 产品</a> #}
   

   Here,categoryandattributeParameter values containing brackets, spaces, and Chinese characters are handled correctly, ensuring independent transmission of parameters.&Symbols are also handled correctly, ensuring the independent transmission of parameters.

3. Reference external links with parameters:Sometimes we need to dynamically reference an external link in the AnQiCMS template, and this external link itself contains parameters, or we need to inject our own parameters into the URL of the external link.urlencodeCan help us ensure that these parameters are encoded correctly.

   {# 假设有一个动态生成的外部链接目标，本身可能包含查询参数 #}
   {% set externalLink = "https://www.example.com/callback?data=用户详情 & token=abc" %}
   
   
   {# 对整个外部链接（包括其参数）进行 urlencode，以确保作为另一个 URL 的参数时安全 #}
   <a href="/redirect?url={{ externalLink|urlencode }}">跳转到外部页面</a>
   

   In this scenario where 'URL contains URL', parameters of the outer URL should beurlencodecrucial.

iriencodeFilter: An important supplement

Excepturlencode, AnQiCMS also providesiriencodeFilter. Although both are related to URL encoding, their focus of use cases is slightly different, especially when handling.&symbols.

According to the document example,iriencodethe filter will&The symbol encoding is an HTML entity&, not URL percent-encoded%26. This makesiriencodeMore suitable for safely embedding URI strings (possibly dynamically generated) into HTML attributes (such as<a>TagshrefIn the 【en】attribute），to prevent the browser from misinterpreting it as HTML code or damaging the HTML structure.

iriencodesyntax and example:)

{{ 变量 | iriencode }}

{# 示例： #}
{% set dynamicUri = "?foo=AnQiCMS&bar=GoLang" %}
<a href="{{ dynamicUri|iriencode }}">链接</a>

{# 渲染后的 HTML 可能会是这样的： #}
{# <a href="?foo=AnQiCMS&amp;bar=GoLang">链接</a> #}

As you can see,&has been converted to)&. If in the URL'sActual query parametersare needed&As a delimiter, it should be usedurlencodeto ensure it is encoded as%26to ensure that the server correctly identifies the parameters. When the entire URI string needs to be safely displayed in the HTML environment (for example, as an attribute value and without the desire to&When breaking the HTML structure, `