Why didn't the homepage Banner display even though I used the `bannerList` tag in the template?

In the operation practice of AnQi CMS, sometimes you may encounter a problem that is really a headache: even though you have already used it in the template,bannerListLabel, but the banner image on the homepage is reluctant to appear.This is like a meticulously prepared opening animation, but it stutters at the critical moment.As an experienced website operations expert, I am well aware of this trouble. Today, let's work together to unravel the issues, starting from the template mechanism and content management strategy of Anqi CMS, find the root cause, and treat the symptoms accordingly.

First of all, we need to make it clear that,bannerListThe label is a powerful and commonly used feature built into Anqi CMS, which is specifically used to extract and display the list of website Banner images from the background.When it does not work as expected, it is usually not a problem with the label itself, but rather a deviation in its usage environment, background configuration, or data status.

一、Template Basics and Syntax Review: Start from the Source

Let's start by checking the template file itself, which is the most direct and the most likely to have errors.

  1. Are the tag syntax and spelling correct?The template engine of Anqi CMS is similar to Django syntax and is very sensitive to the format and case of tags.bannerListTags must start with{% bannerList banners %}in this format, wherebannerListLabel name must not have any spelling errors, andcase must be strictly matched. If you mistakenly writeBannerList/bannerlist, or if you have used{{ }}Instead{% %}It will be ignored by the template engine if wrapped. Similarly, when referencing variables within a loop, also make sure thatbannersthe variable name isforthe same as the variable name in the loop (such asitem), for example{{ item.Logo }}.

  2. Is the label placed in the correct home page template file?The home page banner should naturally be in the home page template. Anqi CMS usually names the home page template asindex.htmlorindex/index.htmlIt depends on the organization mode of the template theme you are using. Please make sure that you willbannerListThe label is embedded in the template file that is actually used to render the homepage. If you place it in a non-homepage template, you naturally won't see the effect on the homepage.

  3. Template file encoding is UTF-8?Although this usually does not directly cause the label to not display, incorrect encoding may cause other rendering issues, interfering with normal debugging.AutoCMS requires all template files to be encoded in UTF-8, ensuring that your template files have not silently changed encoding format due to the editor settings.

  4. Does it have?emptyBlock or conditional judgment prevents display? bannerListLabels are usually used withforLoop combined use, for example:

    {% bannerList banners %}
    {% for item in banners %}
        <a href="{{item.Link}}" target="_blank">
            <img src="{{item.Logo}}" alt="{{item.Alt}}" />
            <h5>{{item.Title}}</h5>
        </a>
    {% empty %}
        <!-- 如果没有Banner，这里的内容会显示 -->
        <p>首页暂无Banner图片。</p>
    {% endfor %}
{% endbannerList %}

    If your backend is indeed not configured with any Banner, then{% empty %}the content within the block will be rendered. If your template does not have{% empty %}the block, andbannersthe variable is empty, then the entireforThe loop area will have no output, as if the tags are not active. Therefore, checkbannersif the variable is truly empty or if there are any externalifcondition judgments (such as{% if banners %}）Prevented the rendering of the entire Banner area.

II. Back-end configuration and data level: Content is king.

If the template syntax and placement are correct, the problem is likely in the background content configuration.

  1. The most core check: Have you added a Banner image in the background?This might sound somewhat basic, but it is the most commonly overlooked step.The Banner management of AnQi CMS is usually located under the "Page Resources" or "Content Management" module.Please log in to the backend, confirm that you have uploaded the Banner image, and filled in the corresponding link, title, and description information.If the background list is empty, the front-end naturally has no image to display.

  2. Banner group name (typeDoes the parameter match?) bannerListA very important parameter is supported by the tag:type.It allows you to set different groups for Banner images, such as "SlidesbannerListWhen labeling, it must also go throughtype="幻灯"Such a form is used to specify the call of the Banner under this group. For example:

    {% bannerList banners with type="幻灯" %}
    {# ... 循环显示幻灯组的Banner ... #}
{% endbannerList %}

    If there is a Banner on the back end, buttypethe parameter settings are incorrect, or the template does not use it at alltypeParameter, while the background Banner is exactly groupedtypeDefault isdefaultGrouping), then the Banner cannot be displayed. Please check the Banner grouping in the background and ensure that the template is corresponding.typeparameters are matched.

  3. In the multi-site modesiteIdIs it correct?auto CMS supports multi-site management. If you have enabled the multi-site feature and configured multiple sites in the background,bannerListtags also provide asiteIdParameters are used to specify which site's Banner data is called.By default, it will try to retrieve the Banner of the current site.siteIdParsing error, it may cause the Banner not to display. In this case, you can try to specify it explicitly in the tagsiteId="你的站点ID"to debug.

  4. Is the Banner image itself valid?Is the image link still valid even if the Banner is configured?Is the image uploaded on the backend saved successfully?Is the image path correct?bannerListThe label may have output HTML structure normally, but the image cannot be loaded, and it still appears as "not displayed" to the naked eye. At this point, it is necessary to check the image element'ssrcproperties.

三、Cache and Environmental Factors: Refresh and the world will change

Sometimes, both the code and data are correct, but stubborn cache may become an obstacle to seeing the latest changes.

  1. Auto CMS System Cache CleanupAuto CMS has a powerful caching mechanism to enhance website performance.When you modify background data or template files, the system cache may not be updated immediately, resulting in the front-end still displaying the old status.System Cache Cleanup.

  2. Browser Cache Force RefreshThis is the simplest but also the most easily overlooked step. Your browser may cache old page content. Try refreshing in your browser.Force refresh(通常是Ctrl+F5或Cmd+Shift+R)，以确保加载的是服务器上最新的页面。

Four、Advanced Debugging Techniques: Let the problems nowhere to hide.

If the above steps do not solve the problem, we need to explore more deeply.

  1. UtilizedumpFilter CheckbannersVariable ContentThe template engine of Anqi CMS provides a powerfuldumpFilter, helps you directly output the detailed structure and content of any variable on the front-end. Find it in your template:bannerListnear the tag, temporarily add a line of code:
    
{% bannerList banners %}
    {{ banners|dump }}
    {# ... 原始的for循环代码 ... #}
{% endbannerList %}
    or more directly, output anywhere in the template{{ banners|dump }}(ifbannersavailable in the global context). Check the page output after rendering the pagedumpResult:
    • if displayed[]或similar empty array structure, indicatesbannerListThe label works normally, but no matching Banner data is extracted from the background. At this point, focus on checking the background configuration, especially the group name (type).
    • If an array of objects is displayed{}indicating the structure