How to use the `wordwrap` filter in AnQiCMS along 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.No matter whether it is the main text of an article, product description, or user comments, the clear presentation of text directly affects user experience.AnQi CMS provides a variety of text processing filters, includingwordwrapandlinebreaks(orlinebreaksbrThese are two powerful tools for handling text line breaks and paragraph structures. They each have their focus, but when used cleverly together, they can make your content show better structure and readability.

UnderstandingwordwrapFilter: Elegant line break for long text

wordwrapThe filter is mainly responsible for solving the problem of line breaks in 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 paragraph of English text and you want to display it with a maximum of 70 characters per line without splitting a word in half, at this pointwordwrapit comes in handy:

{{ article.Content | wordwrap:70 }}

Here70It is the maximum number of characters per line. It is worth noting that,wordwrapThis is word-based wrapping. This means that for continuous text like Chinese, which does not have natural space separation, it does not insert line breaks between characters. Instead, it treats an entire paragraph as a 'word', which 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 breaks,linebreaksandlinebreaksbrThe filter is more focused on converting existing line breaks (usually generated when users press the Enter key) into standard HTML structure.This is crucial for retaining the original format of user input and generating semantically meaningful HTML content.

• linebreaksThis filter will convert a single newline character in text to HTML's<br/>tag, and will convert two or more consecutive newline characters to HTML's<p>and</p>A pair of tags. 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 contains multiple paragraphs, usinglinebreaksThis can be handled as follows:

  {{ user.Comment | linebreaks | safe }}
  

  Please note that an additionalsafefilter was used. This is becauselinebreaksIt will generate HTML tags, if the content comes from user input and we trust its safety, we need to usesafeTell 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 any<p>Label. When you do not need strict paragraph separation, but just want to retain the independence of each line,linebreaksbrit would be a good choice.

  For example, a product feature list, each item on a new line, we just want to display them in a simple new line:

  {{ product.Features | linebreaksbr | safe }}
  

Used collaboratively: balancing aesthetics and semantics

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

At this point, **the practice is to use firstwordwrapThen use visual text width limitation to uselinebreaks(orlinebreaksbr) to process the original line breaks in the text and convert them into HTML structure.

Why is the order important? BecausewordwrapNew line characters will be inserted into the text to limit the line width. IflinebreaksRun first, it will convert the line breaks in the original text to<p>tags. After thatwordwrapThe newline characters may not be properly processed into HTML structures, or they may break existing<p>tag structures. If run first, the newline characters it insertswordwrapwill be processed.linebreaksIdentify and convert to<br/>It is processed correctly with the original paragraph's line breaks.

Let's see an example of combining usage:

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

In this example:

1. long_article_contentFirstly, it passes throughwordwrap:80Process to make each line (by word) have no more than 80 characters. This will insert new line breaks in long sentences to ensure visual neatness.
2. Next, the processed text will be passed tolinebreaks. At this point, whether it iswordwrapa newline inserted or the paragraph newline entered by the user, all will belinebreaksconverted to the appropriate format<p>or<br/>.
3. Finally,safeThe filter ensures that these generated HTML tags can be normally parsed and displayed by the browser.

By this combination, we can ensure that the long text content is presented with a unified line width on the page, improving the reading experience, and can also respect the original paragraph structure of the content to generate semantically meaningful HTML.

Summary

Of Security CMSwordwrap/linebreaksandlinebreaksbrThe filter provides us with powerful text processing capabilities.wordwrapFocused on the visual line width control,linebreaksandlinebreaksbrFocuses on converting pure text line breaks into HTML structure. In practice, according to specific requirements, arrange the use order of these filters properly, especially when placingwordwrapinlinebreaksBefore, it could help us optimize the presentation of page content more effectively, providing visitors with a more comfortable and organized reading experience.

---

Frequently Asked Questions (FAQ)

1.wordwrapWhy does the filter not wrap lines by character length when processing Chinese content?

wordwrapThe filter is designed to wrap lines based on words. For languages like English, words are naturally separated by spaces.wordwrapIt uses these spaces to insert line breaks. Chinese content is usually continuous characters without spaces separating them, thereforewordwrapIt treats a continuous string of Chinese as a 'big word', which causes it not to split and wrap 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;attribute collaborationoverflow-wrap, but these are frontend style controls, andwordwrapThe filter handles text processing on the server side differently than.

2. When should I choose?linebreaksWhen to choose,linebreaksbr?

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

• SelectlinebreaksWhen you want to convert the natural paragraph entered by the user (separated by two newlines or empty lines) into a standard HTML paragraph tag<p>while a single newline within the paragraph is converted to<br/>This is commonly used in blog posts, comments, etc., where more semantic and structured text content is needed.
• SelectlinebreaksbrWhen you only need to simply convert all newline characters to HTML.<br/>Label, do not generate<p>Label. This is applicable to address information, list item descriptions, simple short texts, and so on. You only want to retain the inline line breaks but do not need strict paragraph semantics.

3. Using simultaneouslywordwrapandlinebreaksWhat is the correct order of applying filters?

The correct order isFirst usewordwrapuse first, and then uselinebreaks(orlinebreaksbr). For example:{{ content_variable | wordwrap:80 | linebreaks | safe }}. This order ensures thatwordwrapFirst, break the long line visually (insert a newline character), thenlinebreaksThen, take these bywordwrapInserting line breaks and paragraph breaks in the original text are unified into HTML tags. If the order is reversed,linebreaksit may be too early to process the text into<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.