In AnQiCMS,archive.ContentThe field carries the core content of the website, usually including article details, product descriptions, and other rich text information.For these fields that may contain a large amount of text and images, etc., how to properly handle their layout, especially the automatic line break of text, is crucial for improving the user reading experience.archive.Contentto thewordwrapThe**practice of filters, helps content operators and template developers better utilize this feature.

UnderstandingwordwrapThe working principle of the filter

Firstly, we need to understandwordwrapThe basic function of the filter. In the AnQiCMS template system,wordwrapThe filter is used to wrap long text automatically according to the specified length. Its core mechanism is to identify the text inspacesAs a line break delimiter. When the length of a line of text exceeds the preset value,wordwrapit will break at the nearest space to avoid the layout being broken by long strings.

The basic syntax is relatively intuitive:{{ obj|wordwrap:number }}Here,objIs the text variable to be processed,numberWhich is the maximum number of characters per line of text you want.

However, it should be especially noted that,wordwrapDepends on space as a separator.This means it is significant for languages such as English that are separated by spaces.wordwrapThis will not be split in the middle, and it will still be considered as a long word, which will limit its role in processing pure Chinese long text. In this case, the CSSword-breakoroverflow-wrapproperty may be more effective.

archive.ContentThe specificity of the field

AnQiCMSarchive.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>English）even Markdown syntax, and through|safefilter safely renders to the page to maintain its text structure.

Because it isarchive.Contentis rich text, which is withwordwrapThis pure text filter feature has caused a conflict.wordwrapThe filter was initially designed to handle plain text strings without HTML tags. If you directlywordwrapApplied to entries containing HTML tagsarchive.ContentThe filter will not understand the meaning of HTML tags and may treat the tags themselves as ordinary characters for counting and truncation. This may lead to:

  1. HTML structure is damaged: a complete<div>or<img>tag may be cut off in the middle, causing the page to display incorrectly, even affecting the layout and function of the entire page.
  2. Security risksIf 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. Rendering effect abnormalThe expected layout effect cannot be achieved, instead, garbled text or chaotic formatting appears.

Consideringarchive.Contentof these characteristics, apply directly to itwordwrapFilter, usually not a recommended practice.

Applywordwrapof the practice

Then, in AnQiCMS, we should consider using it under which scenarioswordwrapFilter? **Practice is in ensuring that**wordwrapalways be appliedPlain text content, rather than rich text with HTML structure.

  1. handle content summaries or custom plain text fieldsIf you need to extract a plain text segment from the article content as a summary for display, and you want this summary to automatically wrap to fit a narrow display area, then after extracting the plain text, usewordwrapIs suitable. AnQiCMS usually providesarchive.DescriptionField as the introduction or summary of the article. This field usually stores plain text (or at least is treated as plain text for brief content).

    Example: Break the article summary into lines at 30 characters

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

    In addition, if we define additional, custom fields specifically used for storing plain text in the content model (such as "subheadingwordwrapfilters can also be used.

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

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

  2. Combined with CSS processingarchive.ContentLine break issuesForarchive.ContentIt is because it contains HTML, the most recommended and robust automatic line break solution 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 rule in the CSS file of the website, affecting the container that includesarchive.Contentor directly affectingarchive.Contentthe text elements inside:

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

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

  3. The text fragment rendered from Markdown (complex scenario)Ifarchive.ContentIt is entered through the Markdown editor, and you need to handle the HTML renderedSome plain text snippetTo process (for example, to generate a plain text, fixed-width printing version), you can first strip out the plain text from the rendered HTML programmatically, and then apply to this plain textwordwrap. But this is usually a high-level and specific scenario, not belonging to the direct operation scope of conventional front-end templates.

In summary, in AnQiCMS,wordwrapFilter is an effective tool for automatically wrapping plain text content. In the face ofarchive.ContentWhen dealing with rich text fields, we should avoid applying them directlywordwrap，Switching to extracting plain text or utilizing CSS styles for layout optimization purposes.

Common Questions (FAQ)

  1. wordwrapIs the filter effective for Chinese content? wordwrapThe filter mainly relies on spaces in the text for line breaks. For languages such as Chinese, which are written continuously without spaces to separate words, if no explicit spaces are inserted in the Chinese text,wordwrapThis will not break in the middle of text. This means that its automatic line break feature is very limited for long Chinese text. For typesetting Chinese content, it is usually recommended to use CSS'sword-wrap: break-word;oroverflow-wrap: break-word;properties.

  2. Why is it not recommended to store directly onarchive.Contentthe field?wordwrap? archive.ContentThe field stores rich text (including HTML tags).wordwrapFilter 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 tags, thereby destroying the HTML structure of the page, leading to display errors, chaotic styles, and even abnormal functionality.

  3. ExceptwordwrapWhat text length filter options does AnQiCMS provide?AnQiCMS template engine provides various text length filter processors, including commonly used ones:

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