How to协同使用`wordwrap`filter in AnQiCMS with other text processing filters (such as `linebreaks`)?

In the template design of AnQi CMS, we often encounter scenarios where we need to format long text content.Whether it is the main text of the article, product description, or user comments, the clear presentation of text directly affects the user experience.wordwrapandlinebreaks(or}linebreaksbrauto is two powerful tools for handling text line breaks and paragraph structures. They each have their own focus, but when used cleverly together, they can make your content display better structure and readability.

UnderstandingwordwrapFilter: Graceful line break for long text

wordwrapThe filter is mainly responsible for solving the line break problem of long text visually.When a piece of text is particularly long and does not have a natural line break, it may exceed the container boundary, causing the page layout to become disordered.wordwrapIts function is to automatically insert line breaks at word boundaries without splitting words, based on the length you specify.

For example, if you have a piece of English text and you want to display no more than 70 characters per line without breaking a word in half,wordwrapit comes into play:

{{ article.Content | wordwrap:70 }}

Here are the70This is the maximum number of characters per line. It is worth noting that,wordwrapIs "based on word" for line break.This means that for continuous text without natural space separation like Chinese, it will not insert line breaks between characters but treat an entire paragraph of Chinese as a 'word'. This may be different from the expected result when processing pure Chinese content.It mainly solves the problem of poor page layout due to long words in Western languages.

UnderstandinglinebreaksWithlinebreaksbrFilter: Build the HTML structure of the text

WithwordwrapPay attention to the visual line break differences,linebreaksandlinebreaksbrThe filter is more focused on converting existing line breaks in the text (usually produced by the user pressing the Enter key) into standard HTML structures.This is crucial for preserving the original format of user input and generating semantically meaningful HTML content.

• linebreaksThis filter will convert a single newline character in text to HTML tags<br/>labels, and will convert two or more consecutive newline characters to HTML tags<p>and</p>Label pair.It can automatically wrap plain text content into paragraphs and handle forced line breaks within paragraphs, which is very suitable for converting user input text with natural paragraph divisions into structured HTML.

  For example, the user entered some text in the background, which includes multiple paragraphs, usinglinebreaksYou can handle it like this:

  {{ user.Comment | linebreaks | safe }}
  

  Please note that an additional feature is used here:safethe filter. This is becauselinebreaksThe HTML tags will be generated, if the content comes from user input and we trust its safety, it needs to besafeTell the template engine not to escape these HTML tags so that the browser can render them correctly.

• linebreaksbrThis filter is simpler and more direct. It simply replaces all line breaks in the text with HTML's<br/>tags without generating<p>Label. When you do not need strict paragraph division, but just want to keep the independence of each line,linebreaksbrit will be a good choice.

  For example, a list of product features, each item on a new line, we just want them to be displayed with simple line breaks:

  {{ product.Features | linebreaksbr | safe }}
  

Collaborative use: balancing aesthetics and semantics

Now, let's discuss how towordwrapWithlinebreaks(or}linebreaksbrCombine them cleverly.Imagine you have a very long article with some user-input paragraph divisions, and you also want to have a uniform visual width limit for all the text on the screen to improve readability.

This is the first use of **practice**wordwrapThen limit the text width visually and use itlinebreaks(or}linebreaksbr) to handle the original line breaks in the text and convert them to HTML structure.

Why is the order important? Becausewordwrapnew line characters are inserted into the text to limit line width. Iflinebreaksis run first, it will convert the newline characters in the original text to<p>tags. After thatwordwrapThe newline characters inserted may not be correctly processed into HTML structure, or they may even break existing<p>tag structure. And ifwordwraprun first, the newline characters it inserts will belinebreaksIdentify and convert<br/>, and the newline character of the original paragraph is handled correctly.

Let's see an example of combined use:

{# 假设有一个名为 `long_article_content` 的变量，其中包含用户输入的段落和长句 #}
<div class="article-body">
    {{ long_article_content | wordwrap:80 | linebreaks | safe }}
</div>

In this example:

1. long_article_contentFirstly,wordwrap:80Process to ensure that each line (by word) does not exceed 80 characters. This will insert new line breaks in long sentences to ensure visual neatness.
2. Then, the processed text will be passed tolinebreaks. At this point, whether it iswordwrapthe newline characters inserted or the paragraph newline characters of the original user input, they will all belinebreaksconverted to the appropriate<p>or<br/>Label.
3. Finally,safeThe filter ensures that these generated HTML tags can be normally parsed and displayed by the browser.

Through this combination, we can ensure that long text content is presented with uniform line width on the page, enhancing the reading experience, while also respecting the original paragraph structure of the content to generate semantically meaningful HTML.

Summary

Anqi CMS'swordwrap/linebreaksandlinebreaksbrThe filter provides us with powerful text processing capabilities.wordwrapFocuses on the visual control of line width.linebreaksandlinebreaksbrThen focus on converting pure text line breaks to HTML structure. In practical applications, arrange the use of these filters according to specific needs, especially when puttingwordwrap置于linebreaksBefore, it could help us optimize the presentation of page content more effectively, providing visitors with a more comfortable and organized reading experience.

---

Common Questions (FAQ)

1.wordwrapWhy doesn't the filter wrap lines based on character length when processing Chinese content?

wordwrapThe filter is designed to wrap on a "word" basis. For English and other languages, spaces between words act as natural separators,wordwrapThis will use these spaces to insert line breaks. Chinese content is usually continuous characters without spaces separating them, thereforewordwrapIt treats a whole string of Chinese as a "big word", which prevents it from splitting and wrapping between Chinese characters. If you need to force the Chinese content to wrap at a certain length, you can consider using CSS'sword-break: break-all;orword-break: break-word;属性配合overflow-wrap，但这些是前端样式控制，与wordwrap过滤器在服务器端处理文本的机制不同。

2. 我应该在什么时候选择linebreakswhen to chooselinebreaksbr?

This mainly depends on the HTML structure you want the text to appear in.

• ChooselinebreaksWhen you want to convert a natural paragraph entered by the user (separated by two line breaks or empty lines) into standard HTML paragraph tags<p>and the single line breaks within the paragraph are converted into<br/>This is typically used for blog posts, comments, etc., where more semantic and structured text content is needed.
• ChooselinebreaksbrWhen you just need to simply convert all newline characters to HTML.<br/>Label, rather than generate<p>Label. This is applicable to address information, list item descriptions, simple short texts, etc., where you only want to retain inline line breaks but do not need strict paragraph semantics.

3. In using simultaneouslywordwrapandlinebreaksWhat is the correct order of filter application?

The correct order isFirst use:wordwrap, and then use linebreaks(or}linebreaksbr).{{ content_variable | wordwrap:80 | linebreaks | safe }}. This order ensureswordwrapFirstly, visually break the long line (insert a line break), thenlinebreaksand then these bywordwrapInsert line breaks and existing paragraph breaks in text to be converted to HTML tags. If the order is reversed,linebreakstext processing may be done too soon.<p>tags, causingwordwrapWhen encountering existing HTML structure during subsequent processing, it is unable to insert line breaks as expected, and may even damage the HTML structure.