A template package is a single .trucms.zip file that carries a website template or a library layout together with every picture, stylesheet and font it uses. Use packages to move a design between TruCMS sites or to receive one from a designer.
The Import package dialog on the Website Templates screen. Choose a .trucms.zip file, then check it before anything is imported.
| Package type | Contains | Export from | Import on |
|---|---|---|---|
| Website template | A whole site: pages, menus, blog posts, footer, theme options, site identity and the files they use. | The export icon on a card in Website Templates. | The Import package button on Website Templates. |
| Template Library layout | One section or one full-page layout, with its styles and files. | The export icon on a card in Template Library. | The Import package button on Template Library. |
aperture.trucms.zip.Every local file the template uses — images, SVG artwork, stylesheets, scripts, fonts, video and audio, JSON data — is copied into the package and referred to by a portable reference, never by an address or a media number from your own site. That is what lets the package work on any installation.
If a file cannot be included, the export still completes when possible and the later check lists it as a warning (a file that was missing, of an unsupported type, too large, or that failed the safety check). When the template is too large for a single package, or a file it depends on cannot be included, the export is refused with an explanation instead.
Premium layouts
A premium layout cannot be exported without an Extended License, because a package would hand out the layout’s markup.
.trucms.zip file (up to 50 MB).| Section | What it tells you |
|---|---|
| Detected | The kind of package (Website template, Section layout or Full-page layout) and where it will appear (Appearance → Website Templates, or Appearance → Template Library). |
| Contents | For a website template: how many pages, blog posts and menus. A Premium layout note appears for layouts that stay locked without an Extended License. |
| Files | How many files are included in the package, which are external (hosted on another website) and which are inline (embedded as data URIs, inline SVG or inline scripts). Packaged files are listed by kind: images, SVG, CSS, JavaScript, fonts, video, audio, data and other. |
| Modules | If the template needs Booking or TruCommerce and the module is not enabled, you are told. You can still import the package; applying the template needs the module. |
| Please note | Warnings that do not stop the import, for example a setting or theme option that is not allowed and will be ignored, inline scripts that will run on your pages, or a layout made for a different theme. |
Some templates refer to pictures or fonts hosted on other websites. Choose how to treat them:
| Option | Effect |
|---|---|
| Download and store them on this site | The template no longer depends on other sites. TruCMS downloads each external file, checks it, and stores it with your uploads. Files that cannot be downloaded keep their original link, and the result tells you how many. |
| Keep the links to the external sites | Nothing is downloaded. The template keeps loading those files from where they are hosted, which means it stops working correctly if the other site removes them. |
If your site already has a template with the same key or a layout with the same identity or name, the dialog explains the conflict, including the installed and package versions, and asks how to proceed:
| Option | Effect |
|---|---|
| Import as a new copy (recommended) | Nothing that exists is changed. The imported item gets its own name. |
| Replace the existing one | The existing item’s content is overwritten with the package. Pages already created from it keep their files. You must tick a confirmation. Built-in templates that ship with TruCMS cannot be replaced. |
A package is treated as untrusted input. Before and during import TruCMS enforces the following.
| Check | What it protects against |
|---|---|
| Valid, complete archive | Corrupt zip files, empty packages, duplicate entries and files that do not belong to the package are refused. |
| Size and compression limits | Packages are limited to 50 MB when uploading, 1,500 files, and 150 MB once unpacked. A file compressed suspiciously well (a “zip bomb”) is refused, and a single file cannot exceed 10 MB. |
| Safe file names | Entries with unsafe paths, special files or names that could escape the package folder are refused. |
| Checksums | The template data and every file carry a checksum. A package that was changed after it was exported is refused. |
| Format version | A package made by a newer TruCMS than yours asks you to update first; very old formats are upgraded automatically or refused if no longer supported. |
| No server code | A package may never contain page templates or program code. Any content that does is refused outright. |
| Allow-lists | Only an approved set of site settings, theme options and demo-data seeders can be applied by a package. Anything else is ignored and reported as a warning. |
| File validation | Each file must really be what its name says (for example an image that is not an image is refused) and pass a safety check. Files that fail are refused, or left out of an export with a warning. |
| External download rules | Downloads use web addresses on ports 80 and 443 only, follow at most 3 redirects, time out after 20 seconds, never reach private or internal network addresses, and are capped at 150 files and 100 MB in total. |
| Throttling | Checking and importing are limited to 20 requests per minute per user. |
| Short-lived staging | An uploaded package waits in private storage between Check package and Import for one hour; if you wait longer you are asked to upload it again. |
Only import packages you trust
Packages cannot contain server code, but a layout can contain scripts that run in your visitors’ browsers. The check reports how many inline scripts a package contains. Import packages only from sources you trust, as you would any theme or plugin.
| Message | What to do |
|---|---|
| This is a … package. Import it from … instead. | You used the wrong screen. Use Website Templates for sites and Template Library for layouts. |
| The PHP zip extension is not installed on this server. | Ask your host to enable the PHP zip extension. See System Requirements. |
| The uploaded file is missing or larger than allowed. | The file is above 50 MB or was not selected. Remove unused media from the source template and export again. |
| The uploaded package is no longer available. | The one-hour staging time passed. Upload and check the package again. |
| This package was made by a newer version of TruCMS. | Update TruCMS first (see Updating TruCMS), then retry. |
| The package was changed after it was exported. | The file is damaged or was edited. Obtain a fresh copy from the source. |
| … contains template or PHP code, which is never allowed in a package. | The package is refused for safety. Do not try to bypass it; ask the author for a clean export. |
| The package could not be imported. Nothing was changed. | Check the application log; the import is all-or-nothing, so your site is unchanged. |
Website Templates · Template Library · Updating TruCMS · Roles & Permissions