assets-externos.php library

Path in the Gestor bibliotecas/assets-externos.php

Every third-party JavaScript and CSS file the Gestor uses goes through a single registry, with a pinned version. A module does not write the tag: it calls assets_externos_incluir('codemirror').

The file is served from gestor/assets/vendor/<library>/<version>/ when it exists, and from the registry's CDN when it does not. That way the visitor's IP does not go to third-party CDNs, and a new npm release does not reach production without review.

Registered libraries

New installations already ship the files in gestor/assets/vendor/. To download what is missing (or a new version after changing the registry):

c2f assets:vendor [--lib=codemirror] [--listar] [--forcar]

A library's arquivos entry lists what is downloaded but does not become a tag (the fonts the CSS requests by relative path). Without them, served from disk, Fomantic loses its icons.

Usage

gestor_incluir_biblioteca('assets-externos');
assets_externos_incluir('sortablejs');                  // false if the name is not registered
$tags = assets_externos_tags('quill', $vendorPath, $vendorUrl);   // ['css' => [...], 'js' => [...]]
$map  = assets_externos_urls_js(['codemirror']);        // library => file => URL, for JavaScript

assets_externos_urls_js() exists for code that builds tags in the browser (the preview iframes and the edit bar): it gets the same URLs, without knowing versions or hosts.

Pitfalls

• The fallback to the CDN is silent: a file missing from vendor/ is served from the CDN without warning. After changing a version, run c2f assets:vendor.

• assets_externos_incluir() adds the CSS tags through gestor_pagina_css_incluir($tag), which pushes them onto the end-of-page JavaScript queue (gestor.php). The CSS works, but loads after the content.

• The local URL uses url-raiz, which includes the language prefix when it is in the URL.

Internal helpers (used by the functions above; rarely called directly): assets_externos_registro(), assets_externos_url(), assets_externos_urls_map().

Functions

assets_externos_registro(): array<string, array{versao: string, cdn: string, css: list<string>, js: list<string>}>

assets_externos_url(array $lib, string $nome, string $arquivo, string $vendorFisico, string $vendorPublico): string

assets_externos_tags(string $nome, string $vendorFisico = '', string $vendorPublico = ''): array{css: list<string>, js: list<string>}

assets_externos_urls_map(list<string> $nomes = Array(), string $vendorFisico = '', string $vendorPublico = ''): array<string, array<string, string>>

assets_externos_urls_js(list<string> $nomes = Array()): array<string, array<string, string>>

assets_externos_incluir(string $nome): bool