How to use the `archiveList` tag to flexibly build various document lists and pagination display in the Safe CMS?

Manage and display content in AnQi CMS is a core operation, wherearchiveListLabels play a crucial role.It can not only help us flexibly present lists of various documents such as articles, products, etc., but also seamlessly connect with the pagination feature to meet various complex content display needs.

KnowarchiveListTags: a powerful tool for content display

archiveListLabels are the core tools used in AnQi CMS templates to retrieve document lists. Whether we want to display the latest articles on the homepage, show specific products on category pages, or recommend related content on article detail pages,archiveListIt can easily handle everything. Its strength lies in its rich parameters, allowing us to accurately control the filtering, sorting, and display methods of the content.

archiveListCore capabilities and common parameters

UsearchiveListBasic syntax is{% archiveList 变量名称 with 参数 %}...{% endarchiveList %}.The name of the variable is the custom name you give to the document list obtained, and you can traverse it within the tags using this name.

  1. Specify the content model (moduleId)The auto CMS supports flexible content models, such as articles, products, etc. ThroughmoduleIdparameters, you can specify which model's documents you want to retrieve. For example,moduleId="1"may represent the article model, whilemoduleId="2"This may represent a product model. This allows you to easily display different types of content on different pages.

  2. Filter by category (categoryId/excludeCategoryId)You can use this to retrieve documents under a specific category.categoryIdParameter, supports a single ID or multiple IDs separated by commas. For example,categoryId="1,2,3"will list the documents under the categories with IDs 1, 2, 3. Conversely,excludeCategoryIdIt can help you exclude certain categories. If the page itself is under a certain category,archiveListThe default is to read the current category ID, if you do not want to do this, you can explicitly set it.categoryId="0".

  3. 控制显示数量与偏移（English）limit) limit参数用于控制每次调用显示多少条文档。如果你只想获取前10条最新内容，可以设置Englishlimit="10".limit还支持“偏移模式”，比如Englishlimit="2,10"Represents starting from the 3rd content, getting 10 pieces of data (skipping the first 2).

  4. Flexible sorting methods (order)There are many ways to sort the content,orderThe parameters provide you with many choices:

    • order="id desc"：By document ID in descending order, usually used to display the latest documents.
    • order="views desc"：By views in descending order, used to showcase popular content.
    • order="sort desc"：Sort by the custom sorting field in reverse order. By default, if not specifiedorder，the system will use custom sorting.

  5. using the recommended attributes (flag/excludeFlag/showFlag)English CMS allows you to set various recommended attributes for documents, such as headline [h], recommended [c], slideshow [f], and so on.flag="c"You can filter documents with the 'recommended' attribute.excludeFlagThen it is used to exclude documents with specific properties. If you want to display the recommended properties of the document in the list items,showFlag=trueit will help you achieve it.

  6. define the list type(type) typeParameter isarchiveListEnglish of a key attribute, it determines the working mode of the label:.

    • type="list"English: Default mode, only according to.limitEnglish of parameters to obtain the specified number of documents.
    • type="page"English: Pagination mode, often used on list pages, withpaginationTags are used together to achieve pagination display.
    • type="related": Related document mode, used on the document detail page to obtain other documents related to the current document. It can also be combined withlike="keywords"(Associated by keywords) orlike="relation"Further refine the association logic by associating documents manually set in the background."),

  7. search keywords (q)Whentype="page"whenqThe parameter can be used to implement document search. You can explicitly setq="你的关键词"or even more intelligently,archiveListwill automatically read the query parameter namedqfrom the URL as the search keyword.

  8. Custom filter parametersThis is an advanced feature, if your content model defines custom fields and sets them as filterable, then these fields can be used as filter conditions in the form of URL query parameters. For example, if there is a custom fieldsex，you can accessurl?sex=男Filter documents with gender 'Male'.archiveFiltersUsed together with tags to build complex filtering interfaces.

  9. Multi-site data call (siteId)If you are using the multi-site management feature of Anqin CMS and need to call data from other sites, you can do so bysiteIdspecifying the target site ID as a parameter.

  10. combining documents (combineId/combineFromId)This is a very interesting parameter used to build the list of 'composite documents'.For example, on travel websites, you can combine documents such as 'Beijing' and 'Shanghai' to generate titles and links like 'Travel route from Beijing to Shanghai'.combineIdUsed to append a document to the current documentcombineFromIdUsed to prepend a document.

Actual application scenarios: Flexible construction of content lists

Understood these parameters, let's take a look at how to flexibly apply them in actual projectsarchiveList.

Scenario one: Displaying a list of ordinary documents

Assume you want to display the latest 5 news articles on the homepage of the website.

{% archiveList latestNews with moduleId="1" limit="5" order="id desc" %}
    {% for item in latestNews %}
        <div class="news-item">
            <a href="{{ item.Link }}">{{ item.Title }}</a>
            <span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
        </div>
    {% endfor %}
{% endarchiveList %}

Here,latestNewsis our variable name,moduleId="1"Suppose the news belongs to the article model,limit="5"Limit the display to 5,order="id desc"Ensure that it is the most recent.

Scene two: Build a document list with pagination

On the category page or search results page, we often need to display a large amount of content in pagination. At this timetype="page"andpaginationTags are **partners.

{% archiveList archives with type="page" moduleId="1" categoryId="10" limit="10" q=urlParams.q %}
    {% for item in archives %}
        <div class="article-summary">
            <a href="{{ item.Link }}">
                <h3>{{ item.Title }}</h3>
                {% if item.Thumb %}<img src="{{ item.Thumb }}" alt="{{ item.Title }}">{% endif %}
                <p>{{ item.Description|truncatechars:100 }}</p>
            </a>
            <small>发布于 {{ stampToDate(item.CreatedTime, "2006-01-02") }} | 浏览量：{{ item.Views }}</small>
        </div>
    {% empty %}
        <p>抱歉，当前分类下没有找到任何内容。</p>
    {% endfor %}

    {# 分页代码 #}
    <div class="pagination-container">
        {% pagination pages with show="5" %}
            <a class="first-page {% if pages.FirstPage.IsCurrent %}active{% endif %}" href="{{ pages.FirstPage.Link }}">首页</a>
            {% if pages.PrevPage %}<a class="prev-page" href="{{ pages.PrevPage.Link }}">上一页</a>{% endif %}
            {% for pageItem in pages.Pages %}
                <a class="page-number {% if pageItem.IsCurrent %}active{% endif %}" href="{{ pageItem.Link }}">{{ pageItem.Name }}</a>
            {% endfor %}
            {% if pages.NextPage %}<a class="next-page" href="{{ pages.NextPage.Link }}">下一页</a>{% endif %}
            <a class="last-page {% if pages.LastPage.IsCurrent %}active{% endif %}" href="{{ pages.LastPage.Link }}">尾页</a>
        {% endpagination %}
    </div>
{% endarchiveList %}

In this example,type="page"Turn on pagination mode,categoryId="10"Limited category,limit="10"Means 10 items per page.q=urlParams.qIt will automatically read the search keywords in the URL.paginationTags follow immediately, utilizingpagesVariables (byarchiveListIntype="page"The page number navigation is automatically provided to construct a complete page navigation.show="5"It indicates that up to 5 middle page number buttons are displayed.

Scenario three: display related documents

In the article detail page, we usually recommend some related content to improve user stickiness.

{% archiveList relatedArticles with type="related" limit="6" %}
    {% if relatedArticles %}
    <h4>相关推荐</h4>
    <ul class="related-list">
        {% for item in relatedArticles %}
            <li><a href="{{ item.Link }}">{{ item.Title }}</a></li>
        {% endfor %}
    </ul>
    {% endif %}
{% endarchiveList %}

Heretype="related"Let the system automatically find related content based on the current document.limit="6"Limit quantity. If finer control is needed, you can addlike="keywords"orlike="relation"Parameter.

Scenario four: Mixed display of multiple classifications and models

Sometimes, you may need to loop multiple categories on the same page and display their documents under each category.

{% categoryList categories with moduleId="1" parentId="0" %}
    {% for category in categories %}
        <section>
            <h2><a href="{{ category.Link }}">{{ category.Title }}</a></h2>
            <ul>
                {% archiveList articlesInCategory with type="list" categoryId=category.Id limit="5" %}
                    {% for article in articlesInCategory %}
                        <li><a href="{{ article.Link }}">{{ article.Title }}</a></li>
                    {% empty %}
                        <li>该分类暂无文章。</li>
                    {% endfor %}
                {% endarchiveList %}
            </ul>
        </section>
    {% endfor %}
{% endcategoryList %}

In this example, we first usecategoryListGet the top-level category and then use it in the loop for each category.archiveListTo get the articles under it.

archiveListThe data structure returned (item)

InarchiveListInside the tag, byfor item in 变量名称the loop,itemThe object contains rich information about the document, you can directly access it by{{ item.字段名 }}method, for example:

  • item.Id: Document ID
  • item.Title: Document Title
  • item.Link: Document Link
  • item.Description：Document Description
  • item.Thumb：The document thumbnail address
  • item.CreatedTime: Document creation timestamp (it needs to be used)stampToDateFilter formatting)
  • item.Views：Document Views
  • item.Flag：Document recommendation attributes (required)showFlag=true)
  • and all custom fields in the background content model, such asitem.Author/item.Priceetc.

Summary

archiveListLabels are one of the foundations of Safe CMS content operation and template development.By mastering its various parameters and flexibly applying them to different scenarios, you can easily build powerful and user-friendly content display pages.paginationetc. auxiliary tags, whether it is a simple list or a complex filtering pagination, can be implemented efficiently.

Common Questions (FAQ)

Q1:archiveListandcategoryListWhat are the differences between tags? How should I choose? A1: archiveListMainly used for obtainingdocuments (such as articles, products)list, and its result is a specific document item.categoryListis used to obtainCategoryThe list, its result is a classification item. The key choice is what you want to display:

  • If you want to display "Latest ArticlesarchiveList.
  • If you want to display "All Product Categories", "News Category List", or "Navigation Menu with Subcategories", usecategoryListEnglish. Both are often used together, for example, in a loop of a category list, nested aarchiveListto display the documents under the category, just like the scenario 4 example in the article.

Q2: I have customized some fields in the content model, such as “author” and “source”, how can I display them?archiveListHow to show them in the middle? A2:当你通过archiveListGet document list after,itemObjects will automatically include the fields you customize in the content model. You can use them directly as you would with built-in fields. For example, if you customizeauthorField, you can access it directly in the loop{{ item.Author }}Show author information.

Q3: MyarchiveListSettype="page", but the pagination navigation (pagination) is not displayed or displayed incorrectly, what could be the reason? A3:This situation usually occurs for the following reasons:

  1. Forgot to callpaginationTags: archiveListSettype="page"After that, only pagination data will be prepared, and you need to call it separately in{% endarchiveList %}after{% pagination pages with show="5" %}...{% endpagination %}to render the pagination navigation.
  2. pagesThe variable was not passed correctly:EnsurepaginationThe variable name used in the label isarchiveList(when)type="page") Automatically generated insidepagesThe variable is consistent.
  3. The list content is insufficient for one page: