Skip to content

Loading Resources

Jump to bottom
Andre Kless edited this page Nov 25, 2025 · 13 revisions

content is up-to-date for ccmjs v28.0.0

Introduction

The ccmjs framework provides a service for asynchronous loading of resources that can be used with ccm.load().

Examples:

const data = await ccm.load('data.json'); // {"foo":"bar"}

Load multiple resources:

const results = await ccm.load('data.json', 'hello.html'); // [{"foo","bar"}, "Hello, world!"]

Syntax

ccm.load( ...resources ) → Promise<any>

Parameters

  • ...resources — One or more resources to load (URL’s or resource objects).
    Resources may be individual entries or nested arrays to control parallel and sequential loading.

Returns

A Promise that

  • resolves when all resources load successfully
  • rejects when at least one resource fails
  • resolves/rejects with either a single value or an array of values/errors

Error Handling

If at least one resource fails, the Promise is rejected — but all resources are still attempted to be loaded. This means:

  • Successful resources appear normally in the result array.
  • Failed resources appear at their corresponding index as an Error object.
  • The Promise rejects with the entire result array, allowing detailed inspection.

Parallel and Sequential Loading

The parallel and sequential loading can be flexibly controlled as deep as desired. With each deeper array level you switch between parallel and sequential loading:

ccm.load(
  'hello.html',     // Array Level 0: Parallel
  [
    'style.css',    // Array Level 1: Sequential
    'image.png',
    [
      'data.json',  // Array Level 2: Parallel
      'script.js'
    ],
    'logo.gif'
  ],
  'picture.jpg'
);

The example loads the resources in the following timeline:

Resource Timeline
hello.html ******------------------
style.css ******------------------
image.png ------******------------
data.json ------------******------
script.js ------------******------
logo.gif ------------------******
picture.jpg ******------------------

Resource Objects

Instead of a string, a resource may also be passed as an object.

Example:

ccm.load({ url: 'script.js', type: 'module' });

Configurable Properties

Property Type Description Applies to resource types
url string Required. URL of the resource.
type string Explicit resource type: 'html', 'css', 'image', 'js', 'module', 'data', or 'xml'. If omitted, the type is inferred from the file extension. If the extension is unknown, 'data' is used.
context Element DOM context into which the resource will be loaded (default: <head>). css, js
attr object HTML attributes to apply to the generated <link>/<script> tag. css, js
params object HTTP GET/POST parameters to send. data

HTML Template Extraction (<ccm-template>)

ccm.load() supports a special mechanism for loading HTML files that contain embedded templates. If a loaded HTML file contains one or more tags, the content is automatically extracted and returned as a JavaScript object.

This allows you to bundle multiple HTML templates inside a single file and reference them by key.

Example:

<ccm-template key="header">
  <h1>Example Header</h1>
</ccm-template>

<ccm-template key="footer">
  <footer>...</footer>
</ccm-template>

When loading such a file, ccm.load() extracts the templates into an object:

const templates = await ccm.load('templates.html');

console.log(templates.header);  // "<h1>Example Header</h1>"
console.log(templates.footer);  // "<footer>...</footer>"

Shadow DOM Support

ccm.load() can load resources directly into a Shadow DOM. To do so, pass the shadow root as the context property of the resource object.

Example:

const host = document.createElement('div');
const root = host.attachShadow({ mode: 'open' });

ccm.load({
  url: 'styles.css',
  context: root      // the <link> element will be appended here
});

If you pass a ccmjs instance as context, the resource is automatically loaded into its shadow root.

const instance = await ccm.instance( 'ccm.quiz.js' );

ccm.load({
  url: 'styles.css',
  context: instance
});

Image Preloading

ccm.load() can be used to preload image files such as .jpg, .gif, .png, .svg, and others. Preloading ensures that an image is already available in the browser cache before it is needed in the webpage. This helps display images without delay.

Loading with Subresource Integrity (SRI)

ccm.load() supports loading CSS and JavaScript files with Subresource Integrity (SRI).

Example:

ccm.load({
  url: 'script.js',
  attr: {
    integrity: 'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=',
    crossorigin: 'anonymous'
  }
});

The <head> then contains:

<script src="script.js"
        integrity="sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="
        crossorigin="anonymous"></script>

ccm.load() also supports SRI when loading JavaScript modules:

const exports = await ccm.load({
  url: 'script.js',
  type: 'module',
  attr: {
    integrity: 'sha384-HUXdHqTt4miSLn4X4gaWsM8XlJuzTYeaIeI23MDnpjnUW2vRxWiDnG4XZBM49Vs9',
    crossorigin: 'anonymous'
  }
});

Behind the scenes, module files are first fetched and verified against the SRI hash. Only if the hash matches, the verified source code is executed as a module (via a Blob URL), without a second network request.

Loading Data

When loading data, ccm.load() internally calls the browser’s Fetch API. The value of resource.url becomes the fetch URL, and the remaining fields of the resource object are passed to fetch() as the init object.

Example transformation:

ccm.load({
  url: 'api/user',
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  params: { name: 'Mika' }
});

becomes:

fetch('api/user', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: '{"name":"Mika"}'
});

Loading XML

ccm.load() supports loading XML files. When the resource type is 'xml' (either detected from the file extension or set explicitly), the result is parsed as XML and returned as a DOM Document object.

Example:

const xml = await ccm.load( 'config.xml' );

console.log( xml instanceof Document );   // true
console.log( xml.querySelector('title')?.textContent );

ccm.load() uses fetch() internally, reads the response as text, and parses it via the browser’s XML parser (DOMParser). The resulting Document behaves like any other XML DOM document: elements can be queried, modified, and traversed.

Differentiation

Unlike fetch(), ccm.load() can be used as a CCM dependency.

Clone this wiki locally