In the template development of Anqi CMS,urlizeFilter is undoubtedly a very practical tool, it can intelligently recognize URLs or email addresses in text and automatically convert them into clickable links<a>Tags. This is very beneficial for processing user submitted content or importing plain text content from external sources, providing better user experience and SEO-friendliness.

However, when usingurlizeAt times, some developers may encounter a confusing issue: why do the URLs in the original text, especially those with query parameters or special characters, become unreadable when converted to links?hrefThe special characters in the attribute value will be escaped by HTML entities, causing the link to not work normally or display abnormally? For example, the original should behttps://example.com/?param=值&other=更多The link, might becomehttps://example.com/?param=值&amp;other=更多of which&escaped to&amp;.

To solve this core problem, we need to understand deeplyurlizeA key parameter of a filter.The template engine of AnQi CMS, by default, escapes the output HTML content for security reasons to prevent potential XSS attacks.urlizeThe filter processes a URL, and if it is not given special instructions, it treats the URL string as part of plain text and considers special characters (such as&/"/'The English translation of 'auto' is 'English'.<a>TagshrefFor the 'auto' attribute, it often disrupts the structure and functionality of URLs.

The key to solving this problem lies inurlizeThe filter provides an optional booleantrue/false) parameter, specifically used to control the HTML entity escaping behavior of the URL string itself.

Core Solution: Useurlize:falseParameters

When we set the value of theurlizeFilter is related tofalseWhen used with parameters, we are explicitly telling the template engine to recognize URLs in the text and generate<a>then,Do notForhrefThe URL string in the attribute is escaped as HTML entities. This ensures that the URL retains its original form and ensures normal functionality.

At the same time, we also need to pay attention to a common misconception. Evenurlize:falsePrevented the escaping of the URL itself, the generated<a>Label (for example)<and>symbols) may still be escaped by the default template engine.&lt;and&gt;，causing the HTML code for the link to be displayed directly on the page instead of an clickable link. To make<a>tags be properly parsed and rendered by the browser, we need to use them in combination with|safeFilter.|safeThe filter tells the template engine that the marked content is “safe”, and does not need to be HTML-escaped; it can be output directly as HTML code.

Therefore, to ensure that the original URL is not escaped by HTML entities and is rendered correctly as a clickable link, the complete syntax is:

{{ 你的文本变量 | urlize:false | safe }}

Let's see the effect through a specific example:

Assume we have a text variablecontent_textIt contains:请访问我们的安企CMS教程：https://en.anqicms.com/docs?id=123&category=入门指南&lang=zh-CN

If we use only{{ content_text|urlize|safe }}(default)urlizebehavior, equivalent tourlize:true），生成的链接href属性可能包含转义的字符：<a href="https://en.anqicms.com/docs?id=123&amp;category=&#x5165;&#x95E8;&#x6307;&#x5357;&amp;lang=zh-CN" rel="nofollow">...</a>这样的链接在点击时，就可能因为参数被错误解析而无法跳转到预期页面。

而使用正确的urlize:falseParameters:{{ content_text | urlize:false | safe }}The following HTML code will be generated:<a href="https://en.anqicms.com/docs?id=123&category=入门指南&lang=zh-CN" rel="nofollow">请访问我们的安企CMS教程：https://en.anqicms.com/docs?id=123&category=入门指南&lang=zh-CN</a>At this time,hrefThe URL in the attribute maintains the original correct format, and the link function works normally.

When to chooseurlize:false?

In most cases, when you obtain content from a trusted data source (such as known valid links stored in a database, or links automatically generated by the system), and these links need to accurately preserve their query parameters or special characters, useurlize:falseIt is a wise choice. For example, the links in the article body after content collection, links used to jump to external APIs, or links containing dynamic tracking parameters, and so on.

而对于用户直接输入、未经严格验证的内容，保持 Englishurlize的默认行为（即 Englishurlize:true，Allow special characters within URLs to be escaped) will be safer, which can further reduce potential security risks, although this may affect the accuracy of links in some edge cases.In these scenarios, we tend to prioritize safety over the complete originality of the URL.

MasterurlizeThis parameter of the filter can help us control the presentation of website content more flexibly and accurately, ensuring that the links retain the integrity of the functions while also considering the safety and aesthetics of the page.

Common Questions (FAQ)

  1. urlizeandurlizetruncWhat is the difference? urlizeThe filter will convert URLs in the text to complete<a>labels, displaying the full URL text.urlizetruncbesides havingurlizeThe function of auto, in addition to the original function, can also specify an additional numeric parameter to truncate the displayed text length of the link. If the URL text exceeds the specified length, it will use an ellipsis (...This replaces the overflow part, which is very useful in limited display areas. For example,{{ some_url_text|urlizetrunc:20|safe }}.

  2. Why did I useurlize:falseBut the link is still not clickable, and the HTML code is displayed directly on the page?This is usually because you forget to add|safeFilter.urlize:falsethe parameter ensures that the URL itself is inhrefthe attribute is not escaped, but the entire<a>tag (including)</>HTML symbols) may still be automatically escaped by the template engine. Only by adding|safe，only then can the template engine be informed that this HTML snippet is safe and can be rendered directly as a clickable link.{{ 你的文本变量 | urlize:false | safe }}.

  3. urlizethe filter will automatically addrel="nofollow"attributes?Yes, according to the document description of Anqi CMS,urlizethe filter converts URLs in plain text into<a>when labelingrel="nofollow"Property.This is a beneficial SEO practice that helps avoid inadvertently passing the weight of the current page to external links, especially when dealing with user-generated content or unrelated links.