The `wordwrap` filter: how to elegantly handle the automatic line break display of long text without truncating words?

In website content display, we often encounter layout problems with long text content.When a piece of text is too long and exceeds the container width, if it is not properly handled, it may cause layout disorder and a decline in reading experience.AnQiCMS (AnQiCMS) provides a very practical template filter -wordwrapIt can help us elegantly solve the automatic line break display of long text, and the key is that it maintains the integrity of words, avoiding truncation in the middle of words, thereby greatly enhancing the professionalism and readability of the content.

wordwrapWhat is a filter?

wordwrapA filter is a tool used to handle text auto-wrap.Its core function is to break long text into lines according to the specified character length.Different from simply forcing a line break by character count,wordwrapThe intelligence lies in its ability to prioritize the recognition of 'word' boundaries in text (usually spaces), ensuring that a complete word is not harshly broken in the middle, thus making the text after line breaks still natural and smooth.

How to usewordwrapFilter?

UsewordwrapThe filter is very intuitive, it accepts a parameter to define the maximum character length of each line of text.

The basic syntax format is as follows:

{{ 你的文本内容 | wordwrap:每行最大字符数 }}

Here, 你的文本内容is the string variable you want to perform line break processing on, and每行最大字符数This is a number that represents the approximate number of characters you want to display per line.

For example, if you have a variable segmentarchive.DescriptionContaining the document summary, and it is desired that it display about 20 characters per line, you can use it like this:

<p>
  {{ archive.Description | wordwrap:20 }}
</p>

If your content is a long English sentence, for example: ”Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.“, when appliedwordwrap:10It will try to break at the word boundary around the 10th character, the effect may be as follows:

Lorem ipsum
dolor sit
amet,
consectetur
adipisici
elit, sed
eiusmod
tempor
incidunt ut
labore et
dolore magna
aliqua. Ut
enim ad minim
veniam, quis
nostrud
exercitation

You can see that each newline occurs at the end of a word, not in the middle of a word.

Actual application scenario: maintain text elegance and layout neatness.

In AnQi CMS,wordwrapFilters can be applied to various scenarios to optimize user experience and website layout:

1. Document summary and abstract:On the article list page or search results page, the document's summary (archive.DescriptionIt often requires limiting length and beautiful line breaks. UsewordwrapIt can ensure that the introduction is displayed neatly within a limited width, while avoiding the reading障碍 brought by word truncation.
2. Sidebar or widget text block:The sidebar of a website usually has limited space, if it contains some descriptive text or announcements, usingwordwrapThese texts can better adapt to narrow layouts and avoid overflow.
3. Content generated dynamically:When the content of the website comes from user input or external data, its length is uncontrollable,wordwrapProvided an automated solution that ensures all text content is presented in a unified and standardized format.

If your content has gone throughwordwrapProcessed, the output needs to be in HTML format and retain line breaks, you can consider combininglinebreaksbra filter to convert line breaks to<br/>tags and usesafeThe filter ensures that HTML is parsed correctly:

<p>
  {{ archive.Description | wordwrap:30 | linebreaksbr | safe }}
</p>

Details to pay attention to.

• Line break of Chinese text: wordwrapThe filter is based on spaces to identify 'words' and perform line breaks. This means that for languages like Chinese, which are written continuously without using spaces to separate words,wordwrapThe filter will treat a continuous Chinese text as a "long word", so it will not automatically wrap within it. In this case, if you need to force the Chinese text to wrap, you may need to combine CSS styles (such asword-break: break-all;) or use other character-based truncation logic.
• Parameter flexibility: 每行最大字符数is a suggested value.wordwrapThe filter will try to break lines as close to this length as possible, but to maintain word integrity, the actual line length may be slightly shorter or longer than the set value.
• Combined with HTML tags: wordwrapThe filter operates on plain text content. If your text contains HTML tags, these tags themselves are also considered part of the text and may be counted as characters when wrapping at line breaks.If you need to process content that includes HTML tags in a similar way (for example, truncating while maintaining the integrity of the HTML structure), you may need to consider using other specialized HTML processors (such astruncatechars_htmlThis does not match withwordwrapThe word wrap logic is different.

MasterwordwrapA filter that helps us better control the display effect of website content, allowing long text to remain clear and beautiful across different layouts, thereby enhancing the overall user experience.

Frequently Asked Questions (FAQ)

1.wordwrapFilters and CSS ofword-breakWhat are the differences between the properties?

wordwrapFilters are inserted at template rendering time by modifying the string content itself to insert line breaks (usually\nIt enables text wrapping. It focuses more on changing the text structure at a logical level. While CSS aims to maintain word integrity,word-breakThe attribute is controlled by style on the browser side to display text.It does not change the original text content, it just adjusts how the browser displays text in the layout for line breaks.wordwrapwhile keeping the integrity of words.word-break: break-allForces a newline at any character to fit the layout, even if it truncates words.

2.wordwrapHow does the filter perform when processing text with HTML tags?

wordwrapThe filter will treat strings containing HTML tags as plain text. This means that it will<p>/<a>The tag characters are also counted, and line breaks are inserted at appropriate word boundaries (i.e., at spaces).It does not intelligently parse HTML structures and does not wrap lines within tags.Therefore, it is usually recommended to ensure that the content is plain text before automatic line breaking, or when usingwordwrapcombine them after that.safeandlinebreaksbrThe filter handles possible HTML tags to display them correctly.

3. Why does my Chinese content usewordwrapNo line break effect after the filter?

wordwrapThe filter mainly relies on spaces in the text to identify word boundaries and perform line breaks. Due to the characteristics of the Chinese language, words are usually not separated by spaces, which causes a continuous Chinese text to bewordwrapRegarded as an inseparable 'long word'. Therefore, it will not be automatically wrapped within this Chinese text.If you need to force a line break in a long Chinese text to fit the layout, you can consider using CSS.word-break: break-all;Property, or when processing on the back-end, use programming methods to insert zero-width spaces between Chinese words, etc., to assist in line breaks.