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

In AnQiCMS template development, building dynamic URLs is a common requirement.The correctness of the URL is crucial whether it links to the search results page, the filter list, or passes specific parameters to the backend service.urlencodeThe filter has become a key 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 have special meanings in URLs, such as/used for path separation,?used to introduce query parameters,&Used to separate multiple query parameters,=Used to separate parameter names and parameter values. In addition, spaces, Chinese characters, and other non-ASCII characters, or certain punctuation marks are not allowed to appear directly in URLs.

When a URL parameter contains these special characters, if it is not processed, the browser or server may incorrectly parse this URL, causing the page to load abnormally, or the parameter to be passed incompletely, or even trigger a security vulnerability. For example,searchTerm=安企CMS & GoLangThis parameter, if directly placed in the URL,&the symbol will be incorrectly parsed as a new parameter separator, causingGoLangpartial loss.

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

AnQiCMS template inurlencodeFilter

AnQiCMS provides a template engine that offersurlencodeA filter specifically used for percent-encoding the values of variables in a URL. Its usage is very intuitive, just add it after the variable that needs to be encoded|urlencodeJust do it.

Basic syntax:

{{ 变量 | urlencode }}

This filter will check变量The content, and all characters that do not conform to URL specifications should be converted to their percent-encoded forms to ensure that the generated URL does not cause any issues during network transmission and parsing.

Application scenarios in practice

Let's look at some specific examples to see.urlencodeHow does the filter work in the AnQiCMS template:

1. Dynamically generate search results 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,searchTermincluding spaces, Chinese and&The symbols are correctly encoded, ensuring the completeness 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 indispensable as well.

   {# 假设我们有一个分类名称变量 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,categoryandattributeParameters inside the brackets, spaces, and Chinese characters and&symbols have been properly processed, ensuring the independent transmission of parameters.

3. Refer to an external link with parameters:Sometimes we need to dynamically reference an external link in the AnQiCMS template, and this external link itself may have parameters, or we may need to inject our own parameters into the URL of the external link.urlencodeIt can 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 the scenario of "URL within URL", the parameters of the outer URL are processed.urlencodevital.

iriencodeFilter: An important supplement.

excepturlencode，AnQiCMS also providesiriencodea filter. Although both are related to URL encoding, their focus of use is somewhat different, especially when dealing with&symbols, their performance is different.

According to the document example,iriencodeThe filter will also treat&the symbol is encoded as an HTML entity&, not the URL percent-encoded version of,%26. This makesiriencodeMore suitable for securely embedding URI strings (possibly dynamically generated) into HTML attributes such as<a>label'shrefProperties in, to prevent the browser from misinterpreting it as HTML code or destroying the HTML structure.

iriencodeThe syntax with examples:

{{ 变量 | 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,&was converted to&. If in the URL'sActual query parametersIs needed&As a delimiter, then it should be usedurlencodeTo ensure that it is encoded as%26So that the server can correctly identify the parameters. When it is necessary to safely display the entire URI string in an HTML environment (such as an attribute value, and not hoping&Destroying the HTML structure