How to avoid `categoryList` automatically reading the current page category ID and force it to only display top-level categories?

In the flexible content management world of Anqi CMS, template tags are the bridge between us and data interaction. Among them,categoryListTags are undoubtedly one of the core tools for building website navigation and content lists. However, experienced operators often encounter a scenario: when the website is on a specific category page, ...categoryListThe label reads the current category ID 'intelligently' and uses it as the context for data display.This is extremely convenient in many cases, such as displaying the subcategories or peer categories of the current category.

But imagine, your website needs a fixed top navigation bar that always displays the top-level categories of the website, regardless of which article or sub-category the user is currently browsing. At this point,categoryListThis 'intelligence' has反而 become a trouble.How can I make it 'let go of the burden', and force it to only display those categories at the top level?Today, let's delve into this issue and provide you with effective solutions.

categoryListThe 'Intelligence' and Predicament

Of Security CMScategoryListThe label was originally designed to allow template developers to easily build context-aware category lists. By default, if you call it on the category detail page or article detail page,categoryListWhen not explicitly specifiedcategoryIdThe parameter will default to using the category ID of the current page as a filter condition, which makes the list automatically adapt to the content of the current page and display related subcategories or同级categories.This behavior is efficient and convenient in most dynamic content display scenarios.

However, as mentioned earlier regarding the fixed main navigation requirement, or when it is necessary to display all top-level categories of a content model on a completely unrelated page (such as the homepage), this default behavior becomes inappropriate. We need a way to clearly indicatecategoryListPlease ignore the category ID on the current page, I only want the top-level category.

Revealing the solution: Enforce the specification of the top-level category

The Anqi CMS template tags provide enough flexibility to meet such needs. To achieve the goal of 'forcing only top-level categories to be displayed', we need to skillfully combine the use ofcategoryId/parentIdandmoduleIdThese three parameters.

1. categoryId="0": Sever the connection with the current page context. categoryListlabel'scategoryIdParameters, as the name implies, are used to specify which category of content to retrieve. When you explicitly set it to"0"This means that a clear instruction has been sent to the system:Please do not attempt to automatically obtain any category ID as a filtering condition from the current page environment!This effectively prevents it.categoryListThe default "smart" behavior.

2. parentId="0": Lock the target to the top-level category parentIdThe parameter is used to specify which parent category's subcategories to retrieve. Set it to"0"This means you are explicitly requesting those categories without parent categories, that is, the ones we usually refer to astop-level categories.

3. moduleId: This limits the scope of the categoryWhen you useparentId="0"When obtaining the top-level category, the system needs to know which content model (such as "article model" or "product model") you want to obtain the top-level category under.Because different content models may have their own independent classification systems.moduleIdParameters become an indispensable companion at this point. Provide the content model ID for the top-level category according to the actual situation (for example, the article model ID is usually 1, and the product model ID is usually 2).

Combine these three parameters and we can accurately indicatecategoryListlabels to achieve the effect we want.

Practice: step by step implementation

Let's go through a specific example to demonstrate how to operate. Suppose you want to always display all top-level categories under the 'Article Model' in the header navigation area of the website.

First, in your template file (for examplepartial/header.htmlorbase.htmlrefer toheadersection) you may see something similar to the defaultcategoryListcall method (if any):

{# 默认或不带参数的categoryList调用，可能受当前页面分类ID影响 #}
{% categoryList categories with moduleId="1" %}
    <ul>
        {% for item in categories %}
            <li><a href="{{item.Link}}">{{item.Title}}</a></li>
        {% endfor %}
    </ul>
{% endcategoryList %}

Modify it to force only display "Article Model" (assuming itsmoduleIdWith1) top-level category, you can modify it like this:

{# 强制显示文章模型的顶级分类，忽略当前页面上下文 #}
{% categoryList topLevelCategories with moduleId="1" parentId="0" categoryId="0" %}
    <nav class="main-navigation">
        <ul>
            {% for category in topLevelCategories %}
                <li><a href="{{category.Link}}">{{category.Title}}</a></li>
            {% endfor %}
        </ul>
    </nav>
{% endcategoryList %}

In the code above:

• topLevelCategoriesWe define the variable name for the top-level category list obtained, you can name it freely.
• moduleId="1"Specifically, we need to retrieve the classification of the article model. If your top-level category belongs to the product model, you may need tomoduleIdis set to2and so on.
• parentId="0"Make sure we only get the top-level categories that do not have a parent category.
• categoryId="0"It is crucial, it tellscategoryListTags should not automatically inherit the category ID of the current page, thus avoiding unnecessary context interference.

Through such a combination, regardless of which specific category of articles the user is currently visiting, even a single page or search results page, this code will consistently display all the top-level categories of the article model, achieving your fixed main navigation requirements.

Deep understanding: parameter matching and meaning

Understanding the matching of these parameters is crucial:

• categoryId="0"The function isDecoupling. It allowscategoryListWhen performing classification filtering, it no longer relies on the classification ID that may exist in the URL or page environment, but completely listens to other filtering conditions set in the tags.
• parentId="0"The function isFilter. It precisely filters out allParentIdThe classification 0, which is exactly the top-level classification we define in the website structure.
• moduleIdThe function isLimited range. Since the classifications under different models are independent,moduleIdTell the system which model's classification data should be filtered.

These three parameters work together to ensure thatcategoryListIn the absence of page context, it can still accurately find and display the top-level category list you expect.

Application scenario expansion

This technique of forcibly displaying the top-level category is not only applicable to the main navigation:

• The "All Columns" in the sidebar：On any page, the sidebar may need a fixed entry point to display all top-level categories of a content model.
• Home category entry：The homepage needs to display the entry of each content model, usually only displaying top-level categories.
• Footer navigation: The footer sometimes also includes some main category links, which are usually pointing to top-level categories.

Master this skill, and it will allow you to be more agile in the template development of Anqi CMS, building a more flexible and robust website structure.

Summary

Of Security CMScategoryListTags are default to have contextual awareness, but in scenarios where it is necessary to display the top-level categories fixedly, by settingcategoryIdandparentIdall to"0"and combiningmoduleIdSpecify the content model, and we can easily override its default behavior to achieve accurate classification list display.This not only improves the versatility of the template, but also brings greater freedom to the structural layout of the website.

Frequently Asked Questions (FAQ)

Q1:categoryListWhy does it default to reading the category ID of the current page? What are the benefits of this design?A1:categoryListThe default design of reading the current page category ID is to improve the flexibility and development efficiency of the template.In many cases, you may wish to display related subcategories or同级categories on the category page or article detail page (for example, when a user is browsing an article under the "News Center", the sidebar automatically displays "Domestic News", "International News", and so on).By automatically inheriting the current page's category ID, developers do not need to manually pass parameters on each page, the system can intelligently adjust the list content according to the context, greatly simplifying the implementation of dynamic navigation and content blocks.

Q2: Can I force the display of all subcategories under a specific parent category, while ignoring the current page ID?A2: Of course. You just need toparentIdSet the parameter to display the subcategory you want.Parent Category IDand at the same time.categoryId="0"Ignoring the current page context, along with.moduleIdTo limit the content model. For example, to display ID as.5The parent category's all subcategories (article model), you can write it as: {% categoryList subCategories with moduleId="1" parentId="5" categoryId="0" %}.

Q3: How can I display the categories of a specific content model without forcing them to be top-level categories, or do I need them to be nested multi-levels?A3: If you want to limit the content model of the category but not restrict its hierarchy, and wish to retain the feature of multi-level nesting, you only need to specifymoduleIdthe parameter, and it can be omittedparentIdandcategoryId="0"For example, to get the "product model" (assumingmoduleId="2") all categories (including nested levels), you can call it like this:{% categoryList productCategories with moduleId="2" %}Then, you can useforin a loopitem.HasChildrenand recursioncategoryListBuild a multi-level nested menu.