How to debug the issue of the `wordwrap` filter not working in AnQiCMS?

In AnQiCMS template development,wordwrapThe filter is a very practical feature that helps us control the display of long text, avoid content overflow, and improve the readability of the page.However, sometimes we may find that it does not work as expected, resulting in the text not automatically wrapping.Encountering this situation, do not rush, it is usually due to awordwrapThe deviation in understanding the working principle or improper use caused.

Understandingwordwrapworking principle

Firstly, we need to clarify the AnQiCMS template system.wordwrapThe design goals and core mechanisms of the filter. According to the official documentation,wordwrapThe filter automatically wraps strings at the specified length. But its key point lies in,wordwrapIsIdentify "words" by spacesThis means it will only try to insert line breaks between words, without arbitrarily truncating words internally.

This point is being processedContinuous text without spaces, especially important when it comes to Chinese text. For a continuous string of Chinese characters,wordwrapIt will be regarded as an indivisible "word". Therefore, even if the length of this string of Chinese exceeds the line break value you set, wordwrapIt will not insert line breaks in it, because its design logic is to maintain the integrity of the "word".

For example, if you have{{ "中文长文本一段很长很长"|wordwrap:5 }}such code, because there are no spaces between Chinese characters,wordwrapThis will be consideredOneLong word, so it will not be wrapped in a new line.

wordwrapCommon reasons and solutions for the filter not working

UnderstoodwordwrapAfter understanding the working principle, we can target several common problems and treat them accordingly.

1. Chinese or other continuous text without spaces cannot be wrapped.

This is the most common case, especially on Chinese websites. As mentioned before,wordwrapContinuous text without spaces is treated as a single 'word', so no line breaks are made within it.

Solution:

• Using CSS for forced line breaks:For purely display effects, the most recommended way is to use CSS properties to handle. You can apply this to HTML elements containing long text.word-break: break-all;oroverflow-wrap: break-word;.

  • word-break: break-all;It will force a newline at any character, even within Chinese or English words.
  • overflow-wrap: break-word;(or compatible with old browsers)word-wrap: break-word;It will try to break lines at word boundaries, only when a word is too long and overflows.For Chinese, it is usually considered as a line break point between each Chinese character. Apply these CSS rules to your text container, usually it solves the visual line break problem without modifying the backend logic.

• Content preprocessing:If you want to introduce line breaks when storing content, you may need to consider preprocessing long Chinese paragraphs at the content publishing or editing stage, manually inserting some invisible line breaks or inserting a zero-width space between each Chinese character.This will increase the complexity of content processing.

2. The filter has been added, but the page did not display line breaks

You may have used it correctlywordwrapThe filter, and also found the text existing when viewing the page source code\nLine break, but the actual line break is still not visible in the browser.

Solution:

wordwrapThe filter inserts in the string isText line break(\n), not the HTML's<br/>Tag. A standard HTML renderer typically merges multiple whitespace characters (including\n) into a single space, therefore\nwhitespace in ordinary HTML elements will not be rendered as visible line breaks.

• CombinelinebreaksbrFilter:AnQiCMS provideslinebreaksbrFilter that can convert text\nto HTML<br/>tags. You can use these two filters in series:

  {{ your_long_text_variable|wordwrap:20|linebreaksbr|safe }}
  

  Please note that due tolinebreaksbrIt will generate HTML tags, so be sure to add them afterwards|safeA filter to prevent HTML from being escaped and unable to display correctly.

• Use<pre>Tags:If your content is suitable for display as preformatted text (preserving all whitespace and line breaks), you can directly place the processedwordwrapvariable into<pre>tags:

  <pre>{{ your_long_text_variable|wordwrap:20 }}</pre>
  

  In this case,<pre>tags will be automatically processed\nFor a visible line break, you do not need to add|safe.

3. Incorrect parameter settings or variable type

wordwrapThe filter requires an integer as its line break length parameter. If the parameter passed is not a valid number, or if you try to use a non-string type variablewordwrapThe filter may not work properly.

Solution:

• Check the parameter value:Ensure that the parameter passed towordwrapis an explicit number, for examplewordwrap:20. Avoid using undefined variables or strings as parameters.
• Confirm variable type: wordwrapIt aims to handle strings. If your variable is a number, boolean, or other non-string type, consider converting it to a string before processing, or confirming that the variable indeed contains text that can be processed.
• Use|dumpDebug:If you are unsure of the content and type of the variable, you can temporarily use a template to|dumpfilter to output variable details, such as{{ your_variable|dump }}This helps you understand its true state.

Troubleshooting steps

When you encounterwordwrapWhen the filter is not working, you can check the troubleshooting steps as follows:

1. Check the spelling and grammar of the filter:Ensurewordwrap:numberThe syntax is correct, no missing or incorrect numeric parameters.
2. View the page source:After rendering the page, check the page source code in the browser's developer tools. Look for the target text to see if it already has\nLine feed **enter.
   • If there is\nExplainwordwrapIt has taken effect, the problem is in the HTML rendering (refer to "Question Two").
   • If not\nContinue to the next step.
3. Confirm the text content:Check if your text contains spaces. If the text is a continuous string of Chinese or other long strings without spaces, thenwordwrapit will not take effect (refer to “Question One”).
4. Test Simplified Code:Create a simple test page, including only the variables you want to handle andwordwrapa filter to exclude other CSS or JS interference, isolating the problem.
   • For example:{{ "This is a long sentence that needs to be wrapped."|wordwrap:10|linebreaksbr|safe }}
   • Test Chinese again:{{ "这是一个很长很长的中文句子需要换行显示。"|wordwrap:10|linebreaksbr|safe }}
5. Use|dumpDebug:Confirm variableyour_long_text_variableThe actual content and type:{{ your_long_text_variable|dump }}.

Summary

wordwrapThe filter is a useful tool in AnQiCMS, but it is not万能.Especially for the default behavior of Chinese text and HTML rendering, we need to pay special attention.By understanding its working principle, and combining with CSS orlinebreaksbrWith the filter, you can effectively solvewordwrapThe issue is not yet effective, allowing your AnQiCMS website content to be presented in a more beautiful and readable way.

Frequently Asked Questions (FAQ)

Q1:wordwrapCan the filter recognize and protect HTML tags? A1:No.wordwrapThe filter processes plain text strings,