How to efficiently refer to external static resources (CSS, JS, images) in AnQiCMS template files?
When building a website with AnQiCMS, the design of the template and the effective reference to static resources are key to ensuring website performance and maintenance convenience.The loading speed and user experience of a website largely depend on whether its CSS style, JavaScript script, and image resources can be efficiently transmitted to the visitor.AnQiCMS provides a clear and practical mechanism for handling these external static resources, allowing us to focus more on content creation rather than tedious technical details.
AnQiCMS follows a clear convention in static resource management: all template files are stored in the root directory./templateIn the folder, and the style sheets (CSS), JavaScript scripts (JS), and static resources such as images related to these templates are placed uniformly in/public/static/Under the directory. This separation structure not only makes the project directory well-organized, but more importantly, it provides a foundation for dynamic resource referencing.Follow 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" %}The tag can dynamically obtain the base path of the static resources of the current template, thus avoiding potential problems caused by hardcoding absolute 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. And withTemplateUrlThese 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 a website, we can place the CSS file in/public/static/css/the directory. In the template's<head>section, we can reference it like this:
<link href="{% system with name="TemplateUrl" %}/css/style.css" rel="stylesheet">
TemplateUrlIt will automatically parse similarhttp://yourdomain.com/static/or/static/paths, thus loading correctlystyle.cssfiles. This method ensures that the stylesheet can be loaded accurately and correctly under any deployment environment.
JavaScript file reference
Similarly, JavaScript script files are usually stored in/public/static/js/directory. When referencing in a 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 and Bootstrap. You can take advantage of the global distribution advantage of CDN to accelerate resource loading. For example, when supporting mathematical formulas or flowcharts in Markdown content, you may be inbase.htmlInclude 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">
And for the images uploaded by users through the backend editor, AnQiCMS will store them in/uploadsUnder the directory. The paths of these images are usually stored directly in the database, and their complete paths can be used directly when referenced. For example, the images in the article details:
<img src="{{archive.Logo}}" alt="{{archive.Title}}" />
AnQiCMS also provides practicalthumbA filter used to automatically generate thumbnails for images. This is crucial for responsive design and improving page loading speed.When you need to display a thumbnail version of the image, you can use it like this:
<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 of adapting images to different display sizes.
War tactics and **practice
In order 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 as under the directory,css/js/imagesSub-folders should be created, and an independent static resource directory should be established under each template theme (for example/public/static/default/css), so that it is convenient for management and theme switching. - Using AnQiCMS image processing feature:Fully utilize the image auto-compression, WebP format conversion, thumbnail generation, and other built-in tools 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 applying them
thumbfilter. - Reasonably utilize CDN:For general and low-frequency update libraries (such as fonts, icon libraries, and commonly used JS frameworks), it is recommended to use public CDNs to alleviate server pressure and improve global access speed.
- Pay attention to the cache strategy:Although AnQiCMS may have already handled some cache optimization on the backend, in actual deployment, it is necessary to configure reasonable HTTP cache headers through a web server (such as Nginx) or add version numbers/hashes to the filenames of static resource files (such as
style.css?v=20231027It can effectively utilize browser cache, reducing unnecessary requests.
By understanding and applying the features and conventions provided by AnQiCMS, we can manage the external static resources of the website more efficiently, and build a website with excellent performance and easy maintenance.
Frequently Asked Questions (FAQ)
1. Why is my CSS or JS file showing 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）。其次，确认在模板中引用时，您是否使用了{% system with name="TemplateUrl" %}标签来构建路径，例如<link href="{% system with name="TemplateUrl" %}/css/style.css" rel="stylesheet">When entering the path manually, a small spelling mistake may also cause the resource to fail to load.
How can I ensure that the images I upload also load efficiently, such as by creating thumbnails or converting to WebP format?
AnQiCMS provides powerful image processing features in the background "Content Settings".You can enable 'whether to start Webp image format' to automatically convert uploaded JPG/PNG images to more efficient WebP format;Turn on "Auto-compress large images" and set a specified width to optimize image size.Display these images in the template, and use{{ item.Logo|thumb }}such as this.thumbFilter, AnQiCMS will automatically generate and provide optimized thumbnails for you.
3. If my static resources are not/public/static/in the directory, can I still reference them?
In theory, it is possible to reference it through some advanced configurations (such as the reverse proxy rules of the web server), but this does not comply with the recommended practice of AnQiCMS. To maintain the clarity of the website structure, ease of maintenance, and make full use of the built-in optimization mechanisms of AnQiCMS, it is strongly recommended that you place all static resources related to the templates in a unified location./public/static/Under the directory. This can avoid unnecessary configuration complexity and ensure that the system can dynamically and efficiently manage these resources.