When building a website with AnQiCMS, the design of the template and the effective reference of static resources are the key links to ensure website performance and maintenance convenience.The loading speed and user experience of a website largely depend on whether its CSS styles, JavaScript scripts, and image resources can be efficiently transmitted to the visitor.AnQiCMS provides a clear and practical mechanism to handle these external static resources, allowing us to focus more on content creation rather than tedious technical details.
AnQiCMS adheres to a set of clear conventions in static resource management: all template files are stored in a centralized directory under the root./templateIn the folder, while the style sheets (CSS), JavaScript scripts (JS), and images, etc., related to these templates are placed uniformly./public/static/In the directory.This separation structure not only keeps the project directory in order, but more importantly, it provides the foundation for dynamic resource referencing.Following such a directory specification can greatly simplify the development process and help with team collaboration.
The core of referencing static resources lies in using the AnQiCMS provided{% system with name="TemplateUrl" %}Label.This tag can dynamically obtain the base path of the static resources of the current template, avoiding the potential problems caused by hardcoding absolute paths or relative paths in the code.Imagine if your website needs to change themes or be deployed to a different domain, hard-coded paths would mean a lot of modification work.TemplateUrlThese paths will be automatically adjusted according to the system configuration, greatly enhancing the flexibility and maintainability of the template.
CSS file reference
When we need to introduce a stylesheet for the website, we can place the CSS file in/public/static/css/the directory. In the template's<head>section, we can refer to it like this:
<link href="{% system with name="TemplateUrl" %}/css/style.css" rel="stylesheet">
TemplateUrlWill automatically be parsed as similarhttp://yourdomain.com/static/or/static/path, thus correctly loadingstyle.cssfile. This method ensures that the stylesheet can be loaded accurately and correctly in any deployment environment.
JavaScript file reference
Similarly, JavaScript script files are usually stored in/public/static/js/directory. When referencing in the template, they are generally placed in<body>The bottom of the label to avoid blocking page rendering:
<script src="{% system with name="TemplateUrl" %}/js/main.js"></script>
In addition to local JS files, AnQiCMS also supports direct referencing of external CDN resources, which is very convenient when introducing commonly used libraries such as jQuery, Bootstrap, etc. It can take advantage of the global distribution advantage of CDNs to accelerate resource loading. For example, when supporting mathematical formulas or flowcharts in Markdown content, you may be inbase.htmlIntroducing CDN libraries such as MathJax or Mermaid:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
This method is a direct reference, no need to go throughTemplateUrl.
Image resource reference
The reference to image resources is more diverse. For images that are part of the template design, such as logos, background images, or UI icons, we can place them in/public/static/images/In the directory, and throughTemplateUrlto refer:
<img src="{% system with name="TemplateUrl" %}/images/logo.png" alt="网站Logo">
As for the content images uploaded by users through the backend editor, AnQiCMS will store them in/uploadsIn the directory. The paths of these images are usually stored directly in the database, and the complete path can be used directly when referencing. For example, the images in the article details:
<img src="{{archive.Logo}}" alt="{{archive.Title}}" />
AnQiCMS also provides practicalthumbFilter used to automatically generate thumbnail images for pictures.This is crucial for responsive design and page loading speed.
<img src="{{ item.Logo|thumb }}" alt="{{item.Alt}}" />
This filter will automatically process images according to the thumbnail rules set in the background and return the URL of the thumbnail, greatly simplifying the development work for adapting images to different display sizes.
Practical Skills and **Practice
To further improve the efficiency of static resource references and website performance, it is recommended that you:
- Maintain a clear directory structure:In
/public/static/Create such directories under:css/js/imagesSub-folders should be created, and independent static resource directories should be established under each template theme (for example), for easy management and theme switching./public/static/default/css), for easy management and theme switching. - Utilize the image processing feature of AnQiCMS:Fully utilize the image auto-compression, WebP format conversion, thumbnail generation, and other functions provided in the "Content Settings" of the background. These built-in tools can significantly reduce the size of image files, thereby speeding up page loading and automatically apply
thumbFilter. - Use CDN reasonably:For general libraries with low update frequency (such as fonts, icon libraries, commonly used JS frameworks), it is recommended to use public CDNs to reduce server load and improve global access speed.
- Note the cache strategy: Although AnQiCMS may have already handled some cache optimization on the backend, in actual deployment, configuring reasonable HTTP cache headers through a web server (such as Nginx) or adding version numbers/hashes to the names of static resource files (for example
style.css?v=20231027It can effectively utilize browser caching and reduce unnecessary requests.
By understanding and utilizing the features and conventions provided by AnQiCMS, we can manage the external static resources of the website more efficiently, building a website with excellent performance and easy maintenance.
Common Questions (FAQ)
1. Why does my CSS or JS file show a 404 error in the browser?
This is usually due to an incorrect path reference. Please first check if your CSS or JS files are placed correctly in/public/static/the corresponding subfolder under the directory (for example/public/static/css/style.css）。Next，confirm whether you have used the tag to build the path in the template, for example{% system with name="TemplateUrl" %}标签来构建路径，例如<link href="{% system with name="TemplateUrl" %}/css/style.css" rel="stylesheet">When manually entering a path, even a tiny spelling mistake can cause the resource to fail to load.
How can I ensure that the images I upload also load efficiently, such as generating thumbnails or converting to WebP format?
AnQiCMS provides powerful image processing features in the "Content Settings" section of the backend.You can enable 'Whether to start Webp image format' to automatically convert uploaded JPG/PNG images to more efficient WebP format; turn on 'Whether to automatically compress large images' and set a specific width to optimize image size.{{ item.Logo|thumb }}SuchthumbFilter, AnQiCMS will automatically generate and provide optimized thumbnails for you.
3. If my static resources are not in/public/static/the directory, can I still refer to them?
Theoretically, it can be referenced through some advanced configurations (such as the reverse proxy rules of a web server), but this does not comply with AnQiCMS's recommended practices. To maintain the clarity of the website structure, ease of maintenance, and to make full use of AnQiCMS's built-in optimization mechanisms, it is strongly recommended that you place all static resources related to templates uniformly./public/static/This can avoid unnecessary configuration complexity and ensure that the system can dynamically and efficiently manage these resources.