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

Managing and displaying content in AnQi CMS is a core operation, wherearchiveListLabels play a crucial role. They not only help us flexibly present lists of various documents such as articles, products, and more, but also seamlessly connect with pagination features to meet various complex content display needs.

Get to knowarchiveListTag: A powerful tool for content display

archiveListTags are the core tools used to obtain document lists in Anqi CMS templates. Whether we want to display the latest articles on the homepage, show specific products on the category page, or recommend related content on the article detail page,archiveListCan handle everything easily. Its strength lies in its rich parameters, allowing us to precisely control the filtering, sorting, and display of content.

archiveListCore capabilities and common parameters

UsearchiveListBasic syntax is{% archiveList 变量名称 with 参数 %}...{% endarchiveList %}The variable name is the name you have given to the document list you have obtained, and you can traverse it within the tags.Next, let's take a detailed look at some of its common parameters:

  1. Specify content model (moduleId)Aqin 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, andmoduleId="2"May represent a product model. This allows you to easily display different types of content on different pages.

  2. Filter by category (categoryId/excludeCategoryId)If you want to get documents under a specific category, you can usecategoryIdThe parameter supports a single ID or multiple IDs separated by commas. For example,categoryId="1,2,3"It will list the documents under the category with IDs 1, 2, 3. Conversely,excludeCategoryIdIt can help you exclude certain categories. If the page is already in a category,archiveListThe default is to read the current category ID, if you do not want to do so, you can explicitly set itcategoryId="0".

  3. Control the display quantity and offset (limit) limitThe parameter is used to control how many documents are displayed each time. If you only want to get the first 10 latest contents, you can setlimit="10".limitIt also supports the "offset mode", such aslimit="2,10"Indicates starting from the 3rd item, fetching 10 items (skipping the first 2).

  4. Flexible sorting method (order)The sorting methods of the content are various,orderThe parameters provide multiple choices:

    • order="id desc": Sort by document ID in reverse order, usually used to display the most recently published documents.
    • order="views desc": Sort by view count in reverse 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. utilize recommended attributes(flag/excludeFlag/showFlag)Aqin CMS allows you to set various recommended attributes for documents, such as headlines [h], recommendations [c], slides [f], and so on.flag="c"You can filter documents with the 'recommended' attribute.excludeFlagIt is used to exclude documents with specific properties. If you want to display the recommended properties of the document in the list item,showFlag=trueit will help you achieve that.

  6. Define the list type(type) typeThe parameter isarchiveListA key attribute that determines the working mode of the label:

    • type="list": Default mode, only according tolimitParameters to obtain a specified number of documents.
    • type="page": Pagination mode, commonly used on list pages, withpaginationUsing tags together to implement pagination display.
    • type="related": Related document mode, used on the document detail page to get other documents related to the current document. It can also be combinedlike="keywords"(Associate by keyword) orlike="relation"Further refine the association logic by manually setting the associated documents on the backend.

  7. Search keywords (q)Whentype="page"then,qThe parameter can be used to implement document search. You can explicitly set it.q="你的关键词"Or more intelligently,archiveListWill automatically read the query parameters named in the URL namedqAs the search keywords.

  8. Custom Filter ParameterThis 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 fieldsexYou can go throughurl?sex=男to filter documents with gender "male". This is usually used witharchiveFilterstags to build a complex filtering interface.

  9. multi-site data call(siteId)If you are using the multi-site management feature of Anqicms and need to call data from other sites, you cansiteIdspecify the target site ID with parameters.

  10. combine documents (combineId/combineFromId)This is a very interesting parameter, used to build the list of 'combined documents'.For example, on a travel website, you can combine two documents about 'Beijing' and 'Shanghai' to generate a title and link such as 'Travel route from Beijing to Shanghai'.combineIdUsed to attach a document after the current document,combineFromIdThen used to attach in front.

Actual application scenario: flexibly build content list

Understood these parameters, let's see how to flexibly apply them in actual projectsarchiveList.

Scenario one: Displaying a list of ordinary documents

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

{% 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"Assuming news belongs to the article model,limit="5"Limit the display to 5,order="id desc"Ensure it is the latest.

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 %}

This example shows,type="page"Turn on pagination mode,categoryId="10"Limited category,limit="10"indicating 10 items per page.q=urlParams.qwill automatically read the search keywords in the URL.paginationTags follow immediately, usingpagesvariables (byarchiveListIntype="page"Automatically provided to build a complete page navigation.show="5"Indicates that up to 5 middle page number buttons are displayed.

Scenario three: display related documents.

On the article detail page, we usually recommend some related content to increase 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 the quantity. If finer control is needed, you can addlike="keywords"orlike="relation"Parameter.

Scenario four: Mixed display of multiple categories and multiple 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 a loop toarchiveListretrieve the articles under it.

archiveListThe returned data structure (item)

InarchiveListwithin the tags, throughfor item in 变量名称looping, itemThe object contains rich information in the document, you can directly access{{ item.字段名 }}in the manner, for example:

  • item.Id：Document ID
  • item.Title：Document title
  • item.Link：Document link
  • item.Description: Document description
  • item.Thumb: Document thumbnail address
  • item.CreatedTime: The document creation timestamp (it is necessary to usestampToDateFilter formatting
  • item.Views: Document views
  • item.Flag: Document recommendation attributes (requiredshowFlag=true)
  • and all the fields customized in the background content model, for exampleitem.Author/item.Priceetc.

Summary

archiveListTags are one of the foundations of content operation and template development for Anqi CMS.By mastering its various parameters and flexible application scenarios, you can easily build powerful, user-friendly content display pages. Combined withpaginationsuch auxiliary tags, whether it is a simple list or a complex filtering and pagination, can be implemented efficiently.

Frequently Asked Questions (FAQ)

Q1:archiveListandcategoryListWhat are the differences between tags? How should I choose? A1: archiveListMainly used for gettingdocument (such as an article, product)list, which results in specific document items. AndcategoryListis used to getCategorylist, which results in category items. The key is what you want to display:

  • If you want to display "Latest Articles", "Hot Products", or "specific article lists under a category", usearchiveList.
  • If you want to display "All Product Categories", "News Category List", or "Navigation Menu with Subcategories", usecategoryListBoth are often used together, for example, in a loop of a category list, nesting onearchiveListto display the documents under the category, just like the example in the scene four of the article.

Q2: I have customized some fields in the content model, such as "author" and "source", how can I display them inarchiveListit? A2:When you passarchiveListAfter obtaining the document list, eachitemObjects will automatically include fields that you customize in the content model. You can use them directly as you would built-in fields. For example, if you customize theauthorField, it can be accessed directly in the loop{{ item.Author }}Display author information.

Q3: MyarchiveListuptype="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: archiveListsettingtype="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 by the tag matchesarchiveList(Whentype="page") Automatically generated insidepagesThe variable is consistent.
  3. The list does not have enough items on one page: