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 detailed introduction, company profile, event rules description, etc.These long texts, if not handled properly, can easily lead to page layout confusion and affect the user's reading experience.AnQiCMS is known for its flexible content model and powerful template system, providing a rich set of filters to help us finely control the display of content. Among them,wordwrapThe filter is a practical tool for managing and optimizing the display of long text.

wordwrapWhat does the filter do?

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

This filter accepts a number as a parameter, which represents the maximum length of each line of text. For example, if you set the length to 80,wordwrapTry to make each line of text about 80 characters wide.

Why apply in the custom content model fieldwordwrap?

One of the core strengths of AnQiCMS is its 'flexible content model', which allows us to customize various fields according to business needs.Most of the time, we create fields such as 'Product Specifications', 'Detailed Description', 'User Agreement', etc. in customized content models that contain a large amount of text.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, you need to perform appropriate line breaks.

• To improve readability:Long continuous text can make readers feel tired,wordwrapCan break text into shorter, more readable lines, thereby improving the readability of the content.
• Optimize page layout:In responsive design or fixed-width containers, unhandled long text may overflow and破坏 the page aesthetics.wordwrapCan help text adapt to the container width, maintain the page neat.
• Unified content style:Apply uniformly in the templatewordwrapThe filter ensures that all long text fields maintain a consistent display style visually, enhancing the professionalism of the website.

Therefore, we willwordwrapThe filter is applied to the output of AnQiCMS custom content model fields, which is an effective means of optimizing user experience and improving the quality of content display.

how to convertwordwrapFilter is applied to the AnQiCMS template?

In the 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,长度Is the maximum number of characters per line you wish.

Let us understand its application through a few specific examples:

1. Applied to custom long text fields:Assuming your content model has a custom field namedproduct_descriptionused to store product details. In the template of the document detail page, you can use it like thisarchiveDetailLabel to retrieve and applywordwrapFilter:

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

   here,productDescThe variable will carryproduct_descriptionThe content of the field, and throughwordwrap:70Control the length of each line to about 70 characters.

2. Applied to the system's built-in long text field:AnQiCMS also provides some built-in long text fields, such as theDescription(Summary) orContent(Content). If you only want to wrap the summary for line breaks, you can write it like this:

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

   HerearchiveIt is the current document object,DescriptionIt is the简介field.

3. Combined with HTML display:It should be noted that,wordwrapThe filter merely inserted spaces into the text, but HTML browsers default to collapsing consecutive spaces and do not automatically recognize these spaces as line breaks. To truly display the line breaks, you need to wrap the processed text in<pre>Tags within, or combined with the AnQiCMS providedlinebreaksbrThe filter will convert line breaks to HTML<br />.

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

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

     This method will retainwordwrapAll spaces and soft line breaks generated by the filter, butpreLabels will be displayed in monospaced font.

   • CombinelinebreaksbrThe filter (which converts line breaks into<br />):If your text does not contain explicit line breaks, but onlywordwrapspaces inserted, you need to replace the spaces in the text with HTML line breaks. But sincewordwrapThe space inserted is a common space, usually we would combinelinebreaksbra filter, butlinebreaksbrit is to process换行符。更通用的做法是，如果你希望将`wordwrap`后的文本显示成多行，需要在`wordwrap`之后将内容中的` `(空格) 替换为use first, and then uselinebreaksbr. This is usually quite complex,The simplest and recommended way to use<pre>Label, or make sure the content includes natural line breaks (return) when entering, and then apply the content that includes natural line breaks directlywordwrapAfter that, use itlinebreaksbr.

     If your original field content already contains line breaks and you wantwordwrapThen you can do it like this:

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

     HeresafeThe filter is necessary because it tells the AnQiCMS template engine that this content is safe and does not require HTML entity escaping.

Usewordwraptip:

• Chinese and continuous text: wordwrapThe filter, by default, wraps lines based on spaces between words. For continuous Chinese text or very long English words/URLs without spaces, it will not force a break in the middle, which means that if a Chinese string or a very long word exceeds the length you setnumberIt will still display on one line until the next space is encountered.
• Adjust the length: wordwrapofnumberThe parameters need to be adjusted according to your actual page design (such as container width, font size).The line length is typically between 45 to 75 characters to achieve** a good reading experience.
• withtruncatecharsThe difference is: wordwrapThe purpose is to 'wrap', it will return the complete text content, but only adjust the line length.truncatechars(ortruncatewordsThe purpose is to truncate, it will use an ellipsis when reaching the specified length...Both have different functions, choose according to your needs

In summary,wordwrapThe filter is a small but powerful tool in the AnQiCMS template.Reasonably using it can help us better display the long text field in the content model, making your website exude a professional charm in the details and provide a more comfortable browsing experience.

---

Frequently Asked Questions (FAQ)

1.wordwrapDoes the filter work on Chinese content? wordwrapThe filter is default to be based on spaces between words. For continuous Chinese text, as Chinese characters are usually not separated by spaces,wordwrapThe Chinese sentence will not be forced to break in the middle, it will treat it as a 'long word' and keep it on one line. Only when the Chinese text contains English words or punctuation symbols (usually accompanied by spaces),wordwrapWill try to break lines at these positions.

2.wordwrapandtruncatecharsWhat are the differences between filters? wordwrapThe purpose is to break a long text at a specified length, it will outputthe complete text contentJust inserted extra spaces, to achieve a visual line break effect.truncatecharsThe purpose is to "truncate" text, which will use an ellipsis after reaching a specified number of characters....End text here,Display only part of the contentChoose which one depends on whether you want to display the entire content while limiting the length of each line, or to display only the summary part.

3. I used in the templatewordwrapFilter, but why doesn't the text wrap automatically on the front-end page? wordwrapThe filter simply inserts extra spaces into the text to create a 'soft line break' effect.However, web browsers default to collapsing consecutive spaces and not treating normal spaces as newline characters. To makewordwrapeffect is visible on the page, you need to wrap the processed text content in<pre>tags, or inwordwrapAfter, combinelinebreaksbrFilter, to extract from the original text (if