Theme Assets

assets/
├── css/                    50 stylesheets: default.css, theme.css, then one per surface
│   └── libs/               5 third party bundles: bootstrap-icons, fontawesome, fonts, prism, wcp-table
├── js/                     55 scripts: default.js, money.js, then one per surface
│   └── libs/               6 third party bundles: tom-select, intl-tel-input, jspdf, ...
├── images/                 27 entries, grouped: hero/, logo/, banks/, avatars/, addons/
├── videos/                 anything heavier than an image
├── favicon.svg             addressed like any other asset
└── component-showcase.html a live catalogue of the theme's own primitives

public function assetUrl(string $path = ''): string;

// $path  relative to the theme's assets/ directory. A leading slash is trimmed,
//        so 'css/default.css' and '/css/default.css' are the same request.
//        An empty string returns the assets directory itself.
//
// returns  {APP_URI}/templates/website/{Theme}/assets/{$path}
//          plus ?v={mtime} when the extension is css or js AND the file exists on disk.

<!-- Smarty: one named parameter, 'path' -->
<link rel="stylesheet" href="{asset path='css/balance.css'}">
<script src="{asset path='js/balance.js'}" defer></script>

<!-- Twig: one positional argument -->
<link rel="stylesheet" href="{{ asset('css/balance.css') }}">

<!-- Plain PHP theme, and any PHP outside a view -->
<link rel="stylesheet" href="<?= Theme::active()->assetUrl('css/balance.css') ?>">

<link rel="icon" type="image/svg+xml" href="{asset path='favicon.svg'}">

<!-- The query is the hash already present in bootstrap-icons.min.css's own src.
     Get it wrong and the browser fetches the font twice. -->
<link rel="preload" href="{asset path='css/libs/bootstrap-icons/fonts/bootstrap-icons.woff2'}?e34853135f9e39acf64315236852cd5a"
      as="font" type="font/woff2" crossorigin>

<link rel="stylesheet" href="{asset path='css/libs/bootstrap-icons/bootstrap-icons.min.css'}">
<link rel="stylesheet" href="{asset path='css/libs/fonts/urbanist.css'}">
<link rel="stylesheet" href="{asset path='css/theme.css'}">
<link rel="stylesheet" href="{asset path='css/default.css'}">
<link rel="stylesheet" href="{asset path='css/default-dark.css'}">

<!-- Loaded only where it is needed, decided by a variable, not by a second layout. -->
{if $is_client_area}<link rel="stylesheet" href="{asset path='css/client-nav.css'}">{/if}

<!-- Core scripts, before the page's own block. -->
<script src="{asset path='js/bootstrap.bundle.min.js'}" defer></script>
<script src="{asset path='js/money.js'}" defer></script>
<script src="{asset path='js/default.js'}" defer></script>

{extends file='layouts/default.tpl'}

{block name=head}
    <link rel="stylesheet" href="{asset path='css/account-settings.css'}">
    <link rel="stylesheet" href="{asset path='css/libs/wcp-table/table.css'}">
    <link rel="stylesheet" href="{asset path='css/balance.css'}">
{/block}

{block name=scripts}
    {* The library first, then the page script that uses it: same block, document order. *}
    <script src="{asset path='js/libs/wcp-table/table.js'}" defer></script>
    <script src="{asset path='js/balance.js'}" defer></script>
{/block}

{block name=content}
    {* ... *}
{/block}

// A hook point takes a string and prints it as is, so build the tag here and
// leave the layout alone. Same function, same version query.
Hook::add("ui:client.head.css", 1, function (): string {
    $href = Theme::active()->assetUrl('css/extra.css');

    return '<link rel="stylesheet" href="' . $href . '">';
});