When building dynamic links in the AnQiCMS template, we often need to pass variables as query parameters in the URL.For example, a search results page may need to pass the user's search term as a parameter; a category filter page may need to include the selected category ID or multiple filter conditions.&/?/=///#They have specific meanings in URLs.If these special characters are not processed, the browser or server may not be able to correctly parse the URL, resulting in page errors, data loss, or functional anomalies.

Understand the risks posed by special characters

In the query parameters of the URL (usually in?after), key-value pairs are separated by&separated, and keys and values are connected by=. If your parameter value already contains&or=For example, the search term is "AnQiCMS & Go language", it is directly concatenated intosearch?query=AnQiCMS & Go语言The browser will parse it as two parameters:query=AnQiCMSand an empty parameterGo语言causing the search results to be inaccurate. Similarly, spaces in URLs are not allowed and usually need to be replaced.#It has a special meaning, it represents a URL fragment identifier, and the browser will not send#the content after it to the server, but it is used for client-side page navigation.

To avoid these potential conflicts, we need to URL-encode the values of the query parameters. URL encoding is a method of converting unsafe characters in a URL to percentage signs (%The method of following with two hexadecimal numbers, for example, spaces will be encoded as%20,&Will be encoded as%26. No matter how complex the parameter value is, it can be safely and accurately transmitted and correctly decoded by the server.

AnQiCMS solution:urlencodeFilter

AnQiCMS template system providesurlencodeA filter that can easily encode strings for URL. This filter is simple and practical, helping you convert dynamic content into safe URL query parameter values.

urlencodeHow to use the filter

In AnQiCMS template,urlencodeThe basic syntax of the filter is very intuitive:

{{ 您的变量 | urlencode }}

You only need to put the variables or strings you need to encode inside double curly braces, and the pipe symbol|then addurlencodeJust do it.

Below, we will demonstrate through several common scenariosurlencodeThe actual application of filters:

  1. Building Dynamic Search Query URLAssuming your website has a search function, the search term entered by the user is stored in a variable namedquery_stringand you need to use it asqThe parameter is passed to the search results page:

    {# 未编码的错误示例（可能导致问题） #}
<a href="/search?q={{ query_string }}">搜索</a>


{# 使用urlencode进行编码的正确示例 #}
<a href="/search?q={{ query_string | urlencode }}">搜索</a>

    Ifquery_stringThe value is "AnQi CMS & Go Language", afterurlencodeprocessing, the link will become:/search?q=%E5%AE%89%E4%BC%81CMS%20%26%20Go%E8%AF%AD%E8%A8%80This way, the entire search term can be passed to the server completely and correctly.

  2. Add custom parameters to the existing URL.Sometimes, you may need to add new query parameters to an existing URL, for example, when a user clicks on a filter condition in a category list page, you need to add the filter value to the current URL while retaining the original search term:

    {# 假设urlParams.q中含有用户搜索词，且可能包含特殊字符 #}
{# 构建一个筛选链接，同时保留原搜索词 #}
<a href="/category/filter?type=new&q={{ urlParams.q | urlencode }}">查看最新内容</a>

    In this example,urlParams.qMay come from the URL itself (AnQiCMS will automatically parse the URL parameters tourlParamsthe variable), it may already contain unencoded special characters. Apply tourlencodeEnsure it can safely be used as the query parameter value for the new link.

  3. Build a link with complex parameters in the loopAssuming you are displaying a series of products, each product has a name containing special characters, you need to pass the product name to a detail page or comment page:

    {% archiveList products with type="list" limit="5" %}
    {% for product in products %}
        <p>
            <a href="/product/detail?name={{ product.Title | urlencode }}">查看产品：{{ product.Title }}</a>
        </p>
    {% endfor %}
{% endarchiveList %}

    here,product.TitleIs a product title, may contain spaces,&etc. PassedurlencodeFilter, each product title can be correctly embedded in the URL, ensuring the validity of the link.

When to use and precautions

  • Encode the 'value' of query parameters only: urlencodeThe filter is only used to process the 'value' part of the query parameters in the URL. Parameter name (such asq/type) and URL path (such as/search//product/detailParentheses are usually not encoded because they should comply with URL specifications.
  • Avoid duplicate encoding:AnQiCMS generates some built-in links, for example, throughitem.LinkThe link obtained by the attribute or the pagination labelpaginationWhen generating a link, it is usually already automatically handled by URL encoding to ensure the validity of the link. Therefore, generally speaking, you do not need to encode these links provided by AnQiCMSLinkUse the variable againurlencodeRepeating encoding will cause the URL to fail (for example%20becomes%2520）。Please actively use it when manually concatenating or constructing query parameter values for URLsurlencode.
  • Ensure data integrity:It is a crucial step to URL-encode dynamic data containing special characters to ensure data integrity and the normal operation of website functions.It avoids data truncation or misinterpretation caused by URL parsing errors.

By skillfully utilizing the AnQiCMS providedurlencodeFilter, you can easily build robust and reliable dynamic URLs to ensure that users can access the content they need accurately with every click on the website, thereby enhancing user experience and website stability.

Frequently Asked Questions (FAQ)

Q1: In AnQiCMS template, suchitem.Linkhave the built-in link attributes already been URL encoded?

A1:Yes, AnQiCMS as a mature content management system is in the process of generatingitem.Link(such as documents, categories, tags, etc.) andpages.Link(such as pagination links) built-in link attributes, the URL encoding is usually pre-processed to ensure that they can be safely parsed and redirected in the browser. Therefore, you usually do not need to re-encode the complete link variables provided by AnQiCMS.urlencodefilter.urlencodeUsed for manually constructing URLs and embedding custom query parameter values that may contain special characters.

Q2: Can URL encoding affect a website's SEO performance?

A2:It won't, but it will have a positive impact.Correct URL encoding ensures that your website link structure is clear and stable, avoiding URL parsing errors caused by special characters, thereby reducing dead links and 404 errors.The search engine crawler can correctly fetch and understand the encoded URL, which helps your website content be better indexed and ranked.Avoiding special characters from being unencoded in URLs is one SEO-friendly practice.

Q3: Do I need to URL encode all the content in the URL?

A3:No. You usually only need to URL encode the query parameters in the URL.ValuePerform URL encoding. The protocol of the URL (http://orhttps://), domain name (www.example.com), and path (/category/articles}