In AnQiCMS template development,wordwrapFilter is a very practical feature, which helps us control the display of long text, avoid content overflow, and improve the readability of the page.However, we may find that it does not work as expected, resulting in the text not being automatically wrapped.wordwrapUnderstanding deviation or improper use of the working principle.

Understandingwordwrapworking principle

Firstly, we need to clarify the AnQiCMS template systemwordwrapThe design goals and core mechanisms of the filter. According to the official documentation,wordwrapThe filter will automatically wrap strings at the specified length. But the key point is,wordwrapYesIdentify 'words' by spacesmeans that it will only try to insert line breaks between words, and will not arbitrarily truncate words within them.

is also important in handlingEnglish text without spaces, especially important for continuous Chinese textFor a continuous stretch of Chinese characters,wordwrapIt will treat it as an indivisible 'word'. Therefore, even if the length of this Chinese string exceeds the line break value you set,wordwrap也不会在其中插入换行符，因为它的设计逻辑是保持“单词”的完整性。

例如，如果您有{{ "中文长文本一段很长很长"|wordwrap:5 }}这样的代码，由于中文之间没有空格，wordwrapIt would consider thisAnA long word, thus it will not break it into a new line.

wordwrapCommon reasons and solutions for the filter not working

Understoodwordwrap的工作原理后，we can then target several common problems with specific remedies.

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

This is the most common case, especially on Chinese websites. As mentioned before,wordwrapTreats continuous text without spaces as a single "word", and therefore does not break it within.

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 CSS properties to HTML elements containing long text.word-break: break-all;oroverflow-wrap: break-word;.

    • word-break: break-all;Forces a line break at any character, even within Chinese or English words.
    • overflow-wrap: break-word;(or compatible with old browsers)word-wrap: break-word;）Then it will attempt to break the line at word boundaries, only when a word is too long to fit that it will break within the word.For Chinese, it is usually considered as a breakable point between each Chinese character.Apply these CSS rules to your text container, which usually resolves visual line break issues without modifying the backend logic.

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

2. The filter has been added, but the line break effect is not displayed on the page.

You may have already correctly usedwordwrapthe filter, and also found the text exists in the page source code\n(newline), but the actual newline is still not visible in the browser.)

Solution:

wordwrapFilter inserts into the string isa line break in text (\n)instead of HTML's<br/>tags. Standard HTML renderers typically treat multiple whitespace characters (including\nMerge into a single space, therefore\nIt will not be rendered as a visible newline in standard HTML elements.

  • CombinelinebreaksbrFilter:AnQiCMS provideslinebreaksbrFilter, which can extract text from\nConverted to HTML,<br/>Label. 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 make sure to add|safefilters to prevent HTML from being escaped and displayed incorrectly.

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

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

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

3. Incorrect parameter settings or variable type mismatch

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

Solution:

  • Check the parameter value:Make sure to pass:wordwrapThe parameter is a clear number, for examplewordwrap:20. Avoid using undefined variables or strings as parameters.
  • Confirm the variable type: wordwrapIntended to handle strings.If your variable is a number, boolean, or other non-string type, consider converting it to a string before processing, or confirm that the variable indeed contains text that can be processed.
  • Use|dumpPerform debugging:If unsure of the content and type of a variable, you can temporarily use|dumpa filter to output the detailed information of the variable, such as{{ your_variable|dump }}which will help you understand its real state.

Troubleshooting Steps

When you encounterwordwrapWhen the filter does not work, you can troubleshoot as follows:

  1. Check the spelling and grammar of the filter:Ensurewordwrap:numberThe grammar is correct, and there are no missing or incorrect numeric parameters.
  2. View the page source code:Render the page and check the page source in the browser developer tools. Find the target text and see if it already has\na newline character**enter**.
    • If there is\n，“it meanswordwrapThe status has been activated, the problem is with 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,wordwrapit will not take effect (refer to “Question 1”).
  4. Test simplified code:Create a simple test page that only contains the variables you want to handle.wordwrapFilter out other CSS or JS interference and isolate 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 the variableyour_long_text_variableEnglish actual content and type:{{ your_long_text_variable|dump }}.

Summary

wordwrapThe filter is a useful tool in AnQiCMS, but it is not all-powerful.Especially for Chinese text and the default behavior of HTML rendering, we need to pay extra attention.linebreaksbrWith the filter, you can effectively solve English issueswordwrapUn生效的问题，让您的AnQiCMS网站内容以更美观、更易读的方式呈现。

Common Questions (FAQ)

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