How to use `categoryList` and `categoryDetail` tags to build and display category navigation and details?

In website content management, category navigation and detail pages are the core paths for users to browse the website and obtain information, as well as an important basis for search engines to understand the website structure.A clear and intuitive classification system can not only greatly improve the user experience, but also effectively help the website's SEO performance.For users of Anqi CMS, flexibly use the system providedcategoryListandcategoryDetailThese template tags can easily build powerful, beautiful, and practical category navigation and detail display.

1. Build flexible category navigation: Deepen your understanding.categoryListTag

categoryListThe tag is mainly used to obtain the classification list of a website. Whether you want to display the main classification at the top, build a multi-level classification tree in the sidebar, or display the child categories under a specific classification on the homepage, this tag can provide strong support.

1. Basic usage and core parameters of the tag

While usingcategoryListWhen labeling, we usually define a variable to receive the classification data obtained, for example{% categoryList categories with ... %}...{% endcategoryList %}. Among them,categoriesThis is an array object containing multiple categories of information, we can iterate through it to display each category.

Here are several commonly used and critical parameters that determine which categories you can obtain and how they are organized:

  • moduleId: Specify the content model.Your website may have various content types such as articles, products, etc., which are called 'content models' in AnQi CMS. ThroughmoduleId="1"(taking the article model as an example) ormoduleId="2"Specify the category of the content model you want to retrieve using the product model as an example.
  • parentId: Control the hierarchical relationshipThis is a key parameter for building hierarchical navigation.
    • WhenparentId="0"When, you will get all the top-level categories under the specified model. This is a common way to build the main navigation or first-level category list.
    • If you want to get all subcategories under a specific category, just need toparentIdto the parent category ofIDJust do it.
    • A very practical trick is, when you are on a category page (such as an article list page), if you want to get the sibling categories of the current category (i.e., other categories at the same level), you canparentIdis set to"parent". The system will automatically identify the parent category of the current category and return all its subcategories (including the current category itself).
  • limit: Limit the number of displayed items.If you only want to display a fixed number of categories, such as showing 5 popular categories on the homepage, you can uselimit="5". A more advanced usage islimit="2,10"This means to start from the second category and get 10 categories.
  • all: Get all categoriesIf you need to get all categories under a specified model, regardless of the hierarchy, you can useall=trueThis is very useful when building a full-site category map or for some special display.

2.categoryListApplication scenarios

  • Build the main navigation

    {% categoryList categories with moduleId="1" parentId="0" %}
    <ul class="main-nav">
        {% for item in categories %}
            <li {% if item.IsCurrent %}class="active"{% endif %}>
                <a href="{{ item.Link }}">{{ item.Title }}</a>
            </li>
        {% endfor %}
    </ul>
{% endcategoryList %}

    This code retrieves all top-level categories under the article model and generates a simple navigation list.item.IsCurrentCan help you determine whether the current category is the category of the page being visited by the user, thereby adding a highlight style.

  • Create multi-level nested sidebarWhen you need to display a complex classification structure, you can usecategoryListnested call:

    {% categoryList topCategories with moduleId="1" parentId="0" %}
    <ul class="sidebar-menu">
        {% for topCategory in topCategories %}
            <li>
                <a href="{{ topCategory.Link }}">{{ topCategory.Title }}</a>
                {% if topCategory.HasChildren %} {# 判断是否有子分类 #}
                    {% categoryList subCategories with parentId=topCategory.Id %}
                        <ul class="sub-menu">
                            {% for subCategory in subCategories %}
                                <li><a href="{{ subCategory.Link }}">{{ subCategory.Title }}</a></li>
                            {% endfor %}
                        </ul>
                    {% endcategoryList %}
                {% endif %}
            </li>
        {% endfor %}
    </ul>
{% endcategoryList %}

    HeretopCategory.HasChildrenIt is a very useful field that helps us determine whether the current category has subcategories, thereby deciding whether to continue nested callscategoryList.

  • Combined with the document list displayOn the homepage or content aggregation page, we often need to display a list of articles under different categories,categoryListand also work well witharchiveList(Document list tag)配合：

    {% categoryList featureCategories with moduleId="1" parentId="0" limit="3" %}
    <div class="category-section">
        {% for category in featureCategories %}
            <h3><a href="{{ category.Link }}">{{ category.Title }}</a></h3>
            <ul class="article-list">
                {% archiveList articles with categoryId=category.Id limit="5" %} {# 获取当前分类下的5篇文章 #}
                    {% for article in articles %}
                        <li><a href="{{ article.Link }}">{{ article.Title }}</a></li>
                    {% endfor %}
                {% endarchiveList %}
            </ul>
        {% endfor %}
    </div>
{% endcategoryList %}

IncategoryListthe loop,item(Category object) provides rich field information such asId(Category ID),Title(Category name),Link(Category link),Description(Category description),Logo(Thumbnail large image),Thumb(Thumbnail),HasChildren(Has subcategory),IsCurrent(Is current link) etc., all of which bring great flexibility to template development.

Details of the category display: MasteringcategoryDetailTag

When the user clicks the category navigation and enters the specific category page, we usually need to display the detailed information of the category, such as the introduction, Banner image, etc. At this time,categoryDetailThe label comes into play. It is used to obtain detailed data for a single category.

1. Basic usage and core parameters of the tag

categoryDetailLabels are usually used to directly output a specific field value of a category, such as{% categoryDetail with name="Title" %}.

  • idortoken: Specify categoryGenerally speaking, when you use in the category detail pagecategoryDetailit is not necessary to specifyidortokenThe system will intelligently recognize the category ID of the current page and automatically retrieve its details. But if you need to get information about a specific category on other pages (such as the article detail page), you can do so byid="10"(Specify the category ID as 10) ortoken="web-design"To explicitly specify the target category, use (category URL alias as web-design)
  • name: Get the specified fieldThis iscategoryDetailThe most important parameter, it determines which information of the category you want to obtain. Commonly usednameValues include:
    • Id: Category ID.
    • Title: Category title.
    • Link: Category link.
    • DescriptionCategory description, usually used for page TDK or category introduction.
    • ContentCategory details, can be edited in "Document Category" backend.
    • Logo: The Banner image or large thumbnail of the category.
    • Thumb: The small thumbnail of the category.
    • Images: The category Banner group image, which is an array and usually needs to be looped through.
    • ArchiveCountThe number of documents under this category.
    • And any fields you customize for the category in the "Content Model" backend.

2.categoryDetailApplication scenarios

  • Display the category name and description on the category page.

    <div class="category-header">
    <h1>{% categoryDetail with name="Title" %}</h1>
    <p>{% categoryDetail with name="Description" %}</p>
</div>

    This code will be displayed at the top of the category list page, showing the current category name and description, making it convenient for users to understand the theme of the current category.

  • Display the category Banner imageIf your category has uploaded a Banner image on the backend, it can be displayed at the top of the category page:

    {% categoryDetail categoryBanner with name="Logo" %}
{% if categoryBanner %}
    <div class="category-banner" style="background-image: url('{{ categoryBanner }}');">
        {# 可以叠加其他内容 #}
    </div>
{% endif %}

    Here we first assign theLogovalue of the field tocategoryBannerVariable, then check if the variable exists to avoid the situation where the image path is empty.

  • Used in breadcrumb navigation.On the article detail page, breadcrumb navigation usually needs to display the name and link of the article's category. At this time, even if we are not on the category page, we can also obtain the category details through the article'sCategoryIdto get the category details:

    {# 假设这里是文章详情页，并且文章对象名为 archive #}
{% breadcrumb crumbs %}
<ul>
    {% for item in crumbs %}
        <li><a href="{{item.Link}}">{{item.Name}}</a></li>
    {% endfor %}
</ul>
{% endbreadcrumb %}
{# 也可以直接获取文章所属分类的名称和链接 #}
<p>所属分类：<a href="{% categoryDetail with name='Link' id=archive.CategoryId %}">{% categoryDetail with name='Title' id=archive.CategoryId %}</a></p>

  • Invoke category custom fieldIf you have added custom fields for the category model in the background, such as "Category Leader" (manager)，you can use{% categoryDetail with name="manager" %}Call directly to display its value. If you need to loop through all custom fields, you can do it like this:

    {% categoryDetail extras with name="Extra" %}
{% for field in extras %}
    <div>{{ field.Name }}：{{ field.Value }}</div>
{% endfor %}

Third,categoryListwithcategoryDetailCollaboration and advancement

These tags are not isolated, they often work together in the development of actual templates and play a greater role.

A common scenario is when usingcategoryListWhen looping to output categories, eachitemIt already includes basic classification information (such asId/Title/Link). If you need to get more complex information that is notitemdirectly provided in the classification (such as classificationContentor some custom field), you cancategoryListthe loop, and throughcategoryDetailLabel and pass initem.IdTo get more complete classification details.

For example, in a category list, in addition to displaying the category name, you also want to display each category's thumbnail:

{% categoryList categories with moduleId="1" parentId="0" %}
    <ul class="category-grid">
        {% for category in categories %}
            <li>
                <a href="{{ category.Link }}">
                    <img src="{% categoryDetail with name='Thumb' id=category.Id %}" alt="{{ category.Title }}">
                    <h4>{{ category.Title }}</h4>
                    <p>{{ category.Description | truncatechars:50 }}</p>
                </a>
            </li>
        {% endfor %}
    </ul>
{% endcategoryList %}

here,{% categoryDetail with name='Thumb' id=category.Id %}ingeniously in the loop, for each categorycategoryobtained the corresponding thumbnail.

4. Practical Suggestions and Summary

  • Plan the classification structureBefore starting to develop the template, it is essential to plan clear categories and content models in the Anqi CMS backend, which will directly affect the way you call tags.
  • Optimize SEOMake reasonable use ofTitle/DescriptionAnd custom URL alias (token) Set attractive TDK information with keywords for each category, which helps search engines better index your category pages.
  • Keep the template conciseUse template inheritance (extends) and include (include) Function, modularize repeated code snippets (such as the submenu structure of the navigation menu), making the template structure clear and easy to maintain. For example, multi-level nested category navigation can be encapsulated into a macro (macroCall to avoid code redundancy.
  • Flexible field usageOther than the default: