What is the practice of applying the `wordwrap` filter to the `archive.Content` field in AnQiCMS?

In AnQiCMS,archive.ContentThe field carries the core content of the website, usually containing detailed articles, product descriptions, and other rich text information.How to properly handle the layout of fields that may contain a large amount of text and images, especially for automatic line breaks, is crucial for improving the user reading experience.This article will discuss on AnQiCMS'sarchive.ContentField applicationwordwrapThe practice of the filter, helps content operators and template developers better utilize this feature.

UnderstandingwordwrapThe principle of the filter.

Firstly, we need to understandwordwrapBasic functions of the filter. In the AnQiCMS template system,wordwrapThe filter is used to automatically wrap long text at specified lengths. Its core mechanism is to identify thespacesas the line break delimiter. When the length of a line of text exceeds the preset value,wordwrapThe line break is performed at the nearest space to avoid the layout being broken by a long string.

Its basic usage syntax is relatively intuitive:{{ obj|wordwrap:number }}. Here,objIs the text variable to be processed,numberThe maximum number of characters per line that you wish.

However, it is especially important to note that,wordwrapIt depends on spaces as separators. This means it is significant for English and other languages that separate words with spaces.But for Chinese, Japanese and other languages that are written continuously without spaces between words, if a string of Chinese characters does not have spaces between them,wordwrapIt cannot be broken up in the middle and will still be considered a long word, which will limit its role in processing pure Chinese long texts. In this case, the CSS attribute may be more effective.word-breakoroverflow-wrapThe attribute may be more effective.

archive.ContentThe specificity of the field

AnQiCMS'archive.ContentThe field usually stores content that has been processed by a rich text editor, which means it often contains HTML tags such as<p>,<img>,<strong>,<a>even Markdown syntax, and is safely rendered onto the page to maintain its text structure.|safeFilter is safely rendered onto the page to maintain its text structure.

Becausearchive.Contentis rich text, and it iswordwrapThis plain text filter feature has caused a conflict.wordwrapThe filter was initially designed to handle plain text strings without HTML tags. If you directlywordwrapApplied to content containing HTML tagsarchive.ContentThe filter does not understand the meaning of HTML tags and may treat the tags themselves as ordinary characters for counting and truncation. This may result in:

1. HTML structure is damaged: A complete<div>or<img>Tags may be cut off in the middle, causing page display errors, even affecting the layout and functionality of the entire page.
2. Security risk: If the tag is incorrectly truncated, it may unexpectedly create an incomplete HTML structure, and in some extreme cases, it may even trigger security issues at the front-end rendering level.
3. Abnormal rendering effect: The expected layout effect cannot be achieved, instead, garbled or disordered formats appear.

Consideringarchive.ContentThese characteristics, apply directly to themwordwrapFilter, is usually not a recommended practice.

applywordwrapof the practice

Then, in AnQiCMS, under what scenarios should we consider usingwordwrapthe filter? The practice lies in ensuringwordwrapalways applied toPlain text contentNot including rich text with HTML structures.

1. Handle content summaries or custom plain text fields.If you need to extract a block of plain text from an article content to display as a summary and want the summary to automatically wrap to fit a narrow display area, then after extracting the plain text, usewordwrapIs appropriate. AnQiCMS usually providesarchive.DescriptionThe field is used as the article's summary or abstract. This field typically stores plain text (or at least is treated as short content that would be processed as plain text).

   Example: Break the article summary at 30 characters

   <p class="article-summary">{{ archive.Description|wordwrap:30 }}</p>
   

   Moreover, if we define additional, custom fields specifically for storing plain text in the content model (such as "Subtitle", "Abstract", etc.), and the content of these fields needs to be automatically wrapped, thenwordwrapthe filter can also be useful.

   Example: Perform line breaks for custom plain text fieldsSuppose you have a variable namedcustom_pure_textCustom field

   {% archiveDetail custom_pure_text with name="CustomPureText" %}
       <div class="custom-text">{{ custom_pure_text|wordwrap:40 }}</div>
   {% endarchiveDetail %}
   

2. Combine with CSS processingarchive.ContentLine break issueForarchive.ContentIt is because it contains HTML, the most recommended and robust solution for automatic line breaks is to use CSS styles.Modern browsers handle automatic line breaks for long words or long strings well without breaking the HTML structure.

   You can add the following rules in the website's CSS file, targeting the container that includesarchive.Contentor directly targetingarchive.Contentthe text elements inside:

   .article-content {
       word-wrap: break-word; /* 允许在单词内断行，兼容性较好 */
       overflow-wrap: break-word; /* 现代属性，与word-wrap功能相似 */
   }
   

   After setting this, whenarchive.ContentWhen there is a particularly long continuous text (whether Chinese or English), the browser will automatically break the line within the word or character without destroying the layout, thus keeping the page neat.

3. A Markdown rendered plain text snippet (complex scenario)Ifarchive.ContentIt is entered through a Markdown editor, and you need to deal with the HTML in the rendered output ofsome plain text snippetTo be processed (for example, to generate a plain text version with a fixed line width), you can first strip out the plain text from the rendered HTML, and then apply the text towordwrapThis is usually a high-level and specific scenario that does not belong to the scope of direct operation of frontend templates.

In summary, in AnQiCMS,wordwrapThe filter is an effective tool for automatically wrapping plain text content when dealing witharchive.Contentsuch rich text fields, we should avoid applying it directlywordwrapInstead, by extracting plain text or using CSS styles to achieve layout optimization.

Frequently Asked Questions (FAQ)

1. wordwrapIs the filter effective for Chinese content? wordwrapThe filter mainly relies on spaces in the text for line breaks. For languages like Chinese that are written continuously and do not separate words with spaces, if no explicit spaces are inserted in the Chinese text,wordwrapIt cannot be broken in the middle of the text. This means that its automatic line break effect on pure Chinese long text is very limited. For the layout of Chinese content, it is usually recommended to use CSS'sword-wrap: break-word;oroverflow-wrap: break-word;Property.

2. Why is it not recommended to use directly inarchive.Contentthe fieldwordwrap? archive.ContentThe field stores rich text (including HTML tags).wordwrapThe filter is a plain text processor that does not understand the structure of HTML tags.If applied directly to rich text, it may truncate part of the HTML tag, thereby breaking the HTML structure of the page, causing display errors, style chaos, and even functional anomalies.

3. exceptwordwrapWhat text length filterers does AnQiCMS provide?The AnQiCMS template engine provides various filters for handling text length, including:

   • truncatechars:number: Truncate strings by character count and add.... Specify the length including....
   • truncatewords:number: Truncate the string by word count and add at the end....
   • truncatechars_html:numberandtruncatewords_html:number: These two filters have similar functionstruncatecharsandtruncatewordsBut they are specifically designed to handle strings containing HTML, and they try to maintain the integrity of the HTML structure.