How to use the `categoryList` tag to build a multi-level category navigation or display category lists in the content area?

In Anqi CMS, properly organizing website content categories is an important factor in improving user experience and website maintainability. Whether it is to build a clear multi-level navigation menu to help users quickly locate information, or to skillfully display different categories of content in the page content area,categoryListTags are the core tools for implementing these functions.

Core tags:categoryListIntroduction

categoryListThe tag is used in the Anqi CMS template engine to retrieve the list of website categories.It is very flexible and can retrieve the classification of specific content models, the sub-classifications under specific parent classifications, and even all classifications of the entire website according to your needs.

The basic structure of using it is like this:{% categoryList categories with moduleId="1" parentId="0" %} ... {% endcategoryList %}

Let's break down the key parameters of this tag:

• moduleId: Anqi CMS supports multiple content models, such as you may have article models (usually ID 1), product models (usually ID 2), and so on.moduleIdThe parameter is used to specify which content model category you want to retrieve. For example,moduleId="1"It will retrieve article categories,moduleId="2"It will retrieve product categories.
• parentId: This is the key to controlling the hierarchical relationship of categories.
  • If you want to gettop-level categoriescan be set toparentId="0".
  • If you are looping a category, and you want to get its directsubcategoriesthen you can omitparentIdparameter,categoryListThe tag reads the current loop category ID as the parent ID intelligently.
  • If you want to get the current category'ssibling categorycan be set toparentId="parent".
• limit: If you only want to display a specific number of categories, you can uselimitParameters to limit the number of returned items, such aslimit="10". You can even setlimit="2,10"to indicate starting from the second category and retrieving 10 categories.
• siteId: When you use the multi-site feature, you can go throughsiteIdSpecify the category data to be retrieved under a specific site. This parameter can usually be ignored.

WhencategoryListAfter the tag is executed, it will return a namedcategories(You can also customize this variable name) array. When you useforloop through this array, eachitemrepresents a category, which contains rich properties, such as:

• item.IdUnique ID of the category.
• item.Title: Category name.
• item.LinkCategory link address, can be used directly<a>label'shrefProperty.
• item.DescriptionCategory Introduction.
• item.LogoCategory logo image address.
• item.ThumbCategory thumbnail image address.
• item.HasChildrenA boolean value used to determine whether the current category has subcategories, which is very useful when building a multi-level menu.
• item.IsCurrentA boolean value indicating whether the current category is the category of the page being accessed by the user, often used for navigation highlighting.
• item.ArchiveCountThe number of documents under the current category (excluding subcategories).

Build multi-level classification navigation: allow users to find the direction at a glance

A well-structured website navigation is like a map, which can help users find their destination quickly. UsecategoryListLabel, you can easily build a complex navigation structure from a top-level menu to multi-level dropdown menus.

We usually start by obtaining the top-level category, which serves as the first level of our navigation menu.

{# 假设我们正在构建一个文章分类的导航菜单，文章模型ID为1 #}
<ul class="main-nav">
    {% categoryList topCategories with moduleId="1" parentId="0" %}
    {% for item in topCategories %}
    <li class="nav-item {% if item.IsCurrent %}active{% endif %}">
        <a href="{{ item.Link }}">{{ item.Title }}</a>
        {# 检查当前分类是否有子分类，如果有，则渲染子菜单 #}
        {% if item.HasChildren %}
        <ul class="sub-nav">
            {# 再次调用 categoryList，此时 parentId 留空，它会自动获取当前 item.Id 的子分类 #}
            {% categoryList subCategories %}
            {% for subItem in subCategories %}
            <li class="sub-nav-item {% if subItem.IsCurrent %}active{% endif %}">
                <a href="{{ subItem.Link }}">{{ subItem.Title }}</a>
                {# 您可以继续在这里嵌套，以构建三级甚至更多级别的菜单 #}
                {% if subItem.HasChildren %}
                <ul class="sub-sub-nav">
                    {% categoryList subSubCategories %}
                    {% for subSubItem in subSubCategories %}
                    <li class="sub-sub-nav-item {% if subSubItem.IsCurrent %}active{% endif %}">
                        <a href="{{ subSubItem.Link }}">{{ subSubItem.Title }}</a>
                    </li>
                    {% endfor %}
                    {% endcategoryList %}
                </ul>
                {% endif %}
            </li>
            {% endfor %}
            {% endcategoryList %}
        </ul>
        {% endif %}
    </li>
    {% endfor %}
    {% endcategoryList %}
</ul>

This code demonstrates how to use nestingcategoryListtags to build multi-level navigation. The key is the internalcategoryListIt will be based on the external loopitem.IdAutomatically obtain its subcategory, anditem.HasChildrenIt is responsible for determining whether the submenu structure needs to be rendered. At the same time,item.IsCurrentIt can help you add a category for the current visit.activeClass, implement navigation highlighting effect.

Display the category list in the content area: enrich the page content.

categoryListLabels are not just used for navigation; they also play an important role in the main content area of a page, such as displaying the 'Hot Categories' on the homepage or a specific module's classification content block.

For example, on the homepage of the website, we may want to display the two main categories of "Articles" and "Products", and show several of the latest articles or products under each category. This requires thatcategoryListwitharchiveList(Document list tag) combined for use.

{# 假设文章模型ID为1，产品模型ID为2 #}
<div class="content-sections">
    {# 获取顶级文章分类 #}
    {% categoryList articleCategories with moduleId="1" parentId="0" limit="3" %}
    <section class="section-block">
        <h2>最新文章</h2>
        <div class="category-grid">
            {% for cat in articleCategories %}
            <div class="category-card">
                <h3><a href="{{ cat.Link }}">{{ cat.Title }}</a></h3>
                <p>{{ cat.Description|truncatechars:80 }}</p> {# 截取分类描述，限制字符数 #}
                <ul class="article-list">
                    {# 在每个分类下获取最新的3篇文章 #}
                    {% archiveList articles with categoryId=cat.Id limit="3" order="id desc" %}
                    {% for article in articles %}
                    <li><a href="{{ article.Link }}">{{ article.Title }}</a></li>
                    {% endfor %}
                    {% endarchiveList %}
                </ul>
            </div>
            {% endfor %}
        </div>
    </section>
    {% endcategoryList %}

    {# 获取顶级产品分类 #}
    {% categoryList productCategories with moduleId="2" parentId="0" limit="3" %}
    <section class="section-block">
        <h2>热门产品</h2>
        <div class="category-grid">
            {% for cat in productCategories %}
            <div class="category-card">
                <h3><a href="{{ cat.Link }}">{{ cat.Title }}</a></h3>
                <img src="{{ cat.Thumb }}" alt="{{ cat.Title }}" class="category-thumb">
                <ul class="product-list">
                    {# 在每个分类下获取最新的4个产品 #}
                    {% archiveList products with categoryId=cat.Id limit="4" order="id desc" %}
                    {% for product in products %}
                    <li><a href="{{ product.Link }}">{{ product.Title }}</a></li>
                    {% endfor %}
                    {% endarchiveList %}
                </ul>
            </div>
            {% endfor %}
        </div>
    </section>
    {% endcategoryList %}
</div>

This code demonstrates how to iterate over several top-level categories and then, within each category, to usearchiveListLabel to retrieve the specific articles or products under the category. This allows users to view rich and categorized content without leaving the current page.

Practical skills and precautions

• moduleIdimportanceAlways remember to specify the correct content type (article, product, etc.) that you want to obtainmoduleIdto avoid getting incorrect categorized data.
• limitthe flexible applicationWhether it is in the navigation or content area,limitParameters can help you control the number of displays to avoid the page from being too bulky.
• item.IsCurrentHighlight implementationIn the navigation menu, make use ofitem.IsCurrentThis boolean value can easily add a CSS class to the category being accessed by the current user, highlighting it to enhance the user experience.
• **Style with