How to use the `wordwrap` filter in the AnQiCMS custom content model field?

In website content operation, we often encounter situations where we need to display a large amount of text, such as product details, company profiles, activity rules, etc.These long texts can easily cause page layout chaos if not handled properly, affecting the user's reading experience.AnQiCMS is renowned for its flexible content model and powerful template system, providing a rich set of filters to help us finely control the display of content.wordwrapFilter is a practical tool for managing and optimizing the display of long text.

wordwrapWhat is the filter used for?

In simple terms,wordwrapThe filter is a feature that automatically breaks long text to specified lengths in the template.It will try to wrap at word boundaries rather than at any character, thus maintaining the semantic integrity of the text.When you want to display a piece of text on the front-end page and each line does not exceed a certain number of characters, you can use it.

This filter accepts a number as a parameter, which represents the maximum length of text per line that you wish to have. For example, if you set the length to 80,wordwrapIt will try to make the text about 80 characters wide per line.

Why apply it to the custom content model field?wordwrap?

One of AnQiCMS's core strengths is its很多时候，我们会在自定义内容模型中创建如“产品规格”、“详细描述”、“用户协议”等包含大量文本的字段。These fields may not have strict format restrictions when entered in the background, but when displayed on the front end, if the container width is limited or you want the content to be more readable, appropriate line breaks need to be handled.

• Improve readability:Long stretches of continuous text can make readers feel tired,wordwrapCan split text into shorter, more readable lines to improve readability.
• Optimize page layout:In responsive design or fixed-width containers, unhandled long text may overflow and destroy the beauty of the page.wordwrapIt can help text adapt to the container width and keep the page tidy.
• Unified content style:Through applying uniformly in the templatewordwrapThe filter can ensure that all long text fields are displayed visually consistently, enhancing the professionalism of the website.

Therefore, towordwrapThe filter is applied to the output of AnQiCMS custom content model fields, which is an effective means to optimize user experience and enhance the quality of content display.

How to applywordwrapFilter applied to AnQiCMS template?

In AnQiCMS template files, usewordwrapThe filter is very intuitive, its basic syntax is:{{ 变量名|wordwrap:长度 }}Here,变量名It is the content you get from the content model field.长度It is the maximum number of characters you want for each line of text.

Let us understand its application through a few specific examples:

1. Applied to custom long text field:Suppose you have a custom field named in some of your content models,product_descriptionEnglish for storing product detailed description. In the template of the document detail page, you can use it like thisarchiveDetailto get and apply the tagwordwrapFilter:

   {% archiveDetail productDesc with name="product_description" %}
   <p>{{ productDesc|wordwrap:70 }}</p>
   {% endarchiveDetail %}
   

   Here,productDescthe variable will carryproduct_descriptionthe content of the field, and throughwordwrap:70Keep each line length around 70 characters.

2. Applied to the built-in long text fields of the system:AnQiCMS also provides some built-in long text fields, such as the articles ofDescription(Summary) orContent(Content). If you only want to wrap the summary, you can write it like this:

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

   Here are thearchiveis the current document object,Descriptionis the summary field.

3. Combined with HTML display:It is worth noting that,wordwrapFilter is just inserting spaces in the text, but HTML browsers will collapse consecutive spaces by default and will not automatically recognize these spaces as line breaks. To truly display the line break effect, you need to wrap the processed text in<pre>Tags within, or combined with AnQiCMS providedlinebreaksbrThe filter converts newline characters to HTML's<br />Label.

   • Use<pre>Tags (preserving all whitespace and line breaks):

     {% archiveDetail productDesc with name="product_description" %}
     <pre>{{ productDesc|wordwrap:70 }}</pre>
     {% endarchiveDetail %}
     

     This method will preservewordwrapInsert all spaces and 'soft line breaks' generated by the filter.preTags will be displayed in monospaced font.

   • CombinelinebreaksbrFilter (which converts line breaks into<br />):If your text does not contain explicit line breaks, but onlywordwrapthe inserted spaces, you need to replace the spaces in the text with HTML line breaks. But sincewordwrapInserting is a normal space, usually we would combinelinebreaksbra filter, butlinebreaksbrit is to process the\nnewline characters in the original text.wordwrapIf you want to display the text after as multiline, you need towordwrapAfter that, replace the (space) in the content with\n, and then use linebreaksbr. But this is usually more complex,The simplest and recommended way is to use<pre>Label, or ensure that the content includes natural line breaks (return) when entered, and then apply to the content that includes natural line breakswordwrapafter that, uselinebreaksbr.

     If your original field content already includes newline characters, and you wantwordwrapjust to assist in adjusting the line length, then you can do it like this:

     {% archiveDetail productDesc with name="product_description" %}
     <p>{{ productDesc|wordwrap:70|linebreaksbr|safe }}</p>
     {% endarchiveDetail %}
     

     Here are thesafeThe filter is necessary because it tells the AnQiCMS template engine that this content is safe and does not need to be escaped as HTML entities.

UsewordwrapTip:

• Chinese and continuous text: wordwrapThe filter defaults to splitting text by spaces. For continuous Chinese text or ultra-long English words/URLs without spaces, it will not force a split in the middle, meaning that if a Chinese string or an ultra-long word exceeds the length you set,numberIt will still display on one line until it encounters the next space.
• Adjust the length: wordwrapofnumberThe parameter needs to be adjusted according to your actual page design (such as container width, font size).The line length is usually between 45 and 75 characters to achieve **reading experience**.
• WithtruncatecharsThe difference: wordwrapThe purpose is to "wrap", it will return the complete text content, just adjusted the line length.truncatechars(or}truncatewords）的目的 is “truncation”，it will use an ellipsis (...）to end the text. They have different functions and should be chosen according to the requirements.

In short,wordwrapFilter is a small but powerful tool in AnQiCMS template.Reasonably utilizing it can help us better display the long text fields in the content model, making your website exude a professional charm in the details and providing users with a more comfortable browsing experience.

---

Common Questions (FAQ)

1.wordwrapDoes the filter work for Chinese content? wordwrapThe filter is default based on word spacing for line breaks. For continuous Chinese text, since there is usually no space between Chinese characters,wordwrapIt will not force line breaks in the middle of Chinese sentences; it will treat it as a 'long word' and keep it on one line. Only when Chinese text contains English words or punctuation (usually accompanied by spaces),wordwrapThe purpose is to attempt line breaks at these positions.

2.wordwrapandtruncatecharsWhat are the differences between filters? wordwrapThe purpose is to 'wrap' a long text to a specified length, and it will outputthe complete text contentEnglish only. It is inserted with extra spaces to achieve a visual line break effect.truncatecharsThe purpose is to "truncate" text, it will use an ellipsis (...）to end the text,Only show part of the content. Choose which one depends on whether you want to display the content in full but limit the length of each line, or only display the summary part.

3. I used in the template:wordwrapFilter, but the text auto-wrap is not visible on the front-end page, why is that? wordwrapFilter simply inserts extra spaces in the text to create a 'soft line break' effect.However, HTML browsers will collapse consecutive spaces and do not treat ordinary spaces as newline characters.wordwrapeffect is visible on the page, you need to wrap the processed text content in<pre>tags, or inwordwrapAfter that, combinedlinebreaksbrFilterer, which will take the original text (if