During the operation of AnQiCMS website, we often encounter scenarios where we need to display a large amount of text content, such as the main text of the article detail page, the detailed description of product introduction, or the long introduction on the category page.These long texts, if not handled properly, may cause page layout to become disordered and affect the user's reading experience.Fortunately, the powerful template engine of AnQiCMS provides various flexible ways to manage and display these long texts, including automatic line breaks and content truncation.
AnQiCMS's template system borrowed the syntax of Django template engine, allowing us to output variables through double curly braces{{变量}}and output variables by using single curly braces with a percentage sign{% 标签 %}Use various logical controls and filters. The core of displaying long text lies in the reasonable use of the built-in "Filters" function.
Core solution:wordwrapFilter
When we need to allow a long text content to wrap at a certain width instead of simply overflowing the container,wordwrapThe filter can be put to use. It will intelligently wrap lines at the spaces in the text according to the specified character length.
For example, if you want to wrap a paragraph of text at about 50 characters:
{{ archive.Description|wordwrap:50 }}
Here50That is the maximum number of characters you want to display per line.wordwrapThe filter will try to find the nearest space for line break without breaking words.
It is worth noting that for continuous Chinese text,wordwrapThe filter may not automatically wrap at each character like English, because it mainly relies on spaces between words. If your Chinese content does not have spaces and you want to implement a hard return, you may need to combine CSS styles such asword-break: break-all;oroverflow-wrap: break-word;Help to achieve the expected effect.
CombinelinebreaksandlinebreaksbrFilter
Most of the time, the content we input from the backend editor may already contain newline characters (such as those generated by the enter key).If the content is output directly, the HTML browser will render multiple spaces and line breaks as a single space.To make the newline input from the backend display correctly on the front end, we can uselinebreaksorlinebreaksbrfilter.
linebreaksThe filter will convert a single newline character in the text to.<br/>Tags, while two consecutive newline characters will be converted to.<p>...</p>Paragraph wrapped in tags.linebreaksbrThe filter is simpler, it will directly convert all newline characters to<br/>.
usually, to ensure that HTML tags (such as bold, images generated by backend editors, etc.) in the content are not escaped, and can also handle line breaks, we will use these filters andsafeFilter combined use.safeThe filter tells the template engine that this content is safe HTML and does not need to be automatically escaped.
For example, to display the full text of an article:
{% archiveDetail articleContent with name="Content" %}
{{ articleContent|wordwrap:80|linebreaks|safe }}
In this example,articleContentFirstly, it passes throughwordwrap:80The filter processes, attempting to wrap at around 80 characters; then,linebreaksThe filter converts the original line breaks in the text to HTML paragraphs or line break tags; finally,safeThe filter ensures that all HTML tags are correctly parsed and displayed by the browser, rather than being output as plain text.
An alternative to truncating long text:truncatecharswithtruncatewordsFilter
In some design scenarios, we may not want to fully expand the long text, but only display part of the content, and add an ellipsis at the end to keep the page simple or guide the user to click to view more. AnQiCMS providestruncatecharsandtruncatewordsA series of filters to implement text truncation.
truncatechars:NTruncate by character count, N is the total number of characters (including ellipsis).truncatewords:NTruncate by word count, N is the total number of words (including ellipsis).
These filters have corresponding_htmlversions such astruncatechars_htmlandtruncatewords_htmlWhen truncating content that contains HTML tags, they attempt to maintain the integrity of the HTML structure to avoid generating invalid code.
For example, display the article summary, keeping only the first 100 characters:
{{ archive.Description|truncatechars:100 }}
If the summary content may contain HTML tags, to avoid truncation causing tags to not close properly, you can use:
{{ archive.Description|truncatechars_html:100|safe }}
Similarly,|safeThe filter is also indispensable here to ensure that the truncated HTML content is rendered correctly.
Summary
AnQiCMS's template engine provides a very flexible and powerful tool for managing the display of long text. Whether it is throughwordwrapfilter to implement automatic text wrapping, or throughlinebreaksThe filter retains the original paragraphs and line breaks, or usestruncatecharsandtruncatewordsThe filter elegantly truncates text, which can help us better optimize the content display of the website and improve the user experience.In practical applications, flexibly combining these filters with appropriate CSS styles can meet the vast majority of long text processing needs.
Frequently Asked Questions (FAQ)
Q1: Why did I usewordwrapThe filter, but the Chinese content does not line break as expected?
A1:wordwrapThe filter mainly splits lines based on spaces between words.For continuous Chinese text, due to the lack of natural word separators, it may not automatically insert line breaks after a specified number of characters.If you want to implement a hard return for Chinese text, you can try to add it in the CSS for the element containing the textword-break: break-all;oroverflow-wrap: break-word;A property that allows the browser to force a line break at any character when necessary.
Q2: How can I display long text containing HTML tags (such as images, bold text, etc.) without them being escaped into plain text?
A2: The AnQiCMS template engine defaults to escaping HTML entities in output variables for security, to prevent cross-site scripting (XSS) attacks. If your text content is valid HTML and you want the browser to parse and display it, you need to add it at the end of the variable output.|safea filter. For example:{{ archive.Content|linebreaks|safe }}.
Q3: How can I display the first N characters (or words) of a long text without automatic wrapping?
A3: In this case, you should use the truncation filter instead of the newline filter.truncatechars:NText can be truncated by character count,truncatewords:NTruncate by word count. If the content may contain HTML tags, please use the corresponding_htmlversion (such astruncatechars_html:N), to ensure the integrity of the truncated HTML structure, and it also needs to be combined with|safeA filter to prevent HTML tags from being escaped.