Room

Room-Suspense

Room-Suspense est un composant basé sur Room permettant d’afficher un contenu temporaire en attendant que ses composants enfants soient tous chargés.

Room-Suspense est disponible sous la forme d’un module ECMAScript 6 (une version non ECMAScript est également disponible) qui comme Room, ne nécessite pas de système de construction (build tools). Room-Suspense est donc utilisable directement dans un navigateur Web.

Room-Suspense ne fonctionne qu’à partir de la version 1.1.0 de Room.

Installation

Room-Suspense est disponible sur :

• GitHub : https://github.com/GreenerSoft/Room-Suspense
• NPM : https://www.npmjs.com/package/room-suspense
• jsDelivr : https://www.jsdelivr.com/package/npm/room-suspense

Vous pouvez aussi auto-héberger Room-Suspense en téléchargeant l’un des fichiers suivants :

Le référencement du fichier dans vos pages dépend de la version que vous voulez utiliser.

Version ESM

Une carte d’importation est obligatoire en version ESM à minima pour indiquer où est le module Room. Vous pouvez donc y ajouter une entrée pour indiquer où est aussi le module Room-Suspense.

Vous trouverez un exemple de carte d’importation dans le fichier index.html de notre dépôt Room-Test. Il contient par ailleurs plusieurs exemples d’utilisation de Room-Suspense.

Version non ESM

En version non ESM, vous devez avoir un élément <script> dans votre page HTML après celui pour Room.

Vous avez alors un objet RoomSuspense attaché à l’objet principal window qui permet d’appeler la fonction retournant le composant (RoomSuspense.Suspense()).

Une autre solution plus simple consiste à utiliser l’affection par décomposition :

const {Suspense} = RoomSuspense;

Vous pouvez alors appeler directement la fonction Suspense() sans préfixer avec RoomSuspense..

Fonction

Room-Suspense exporte une seule fonction Suspense() qui retourne le composant.

La signature de la fonction est :

Suspense({fallback}, ...children)

Le premier paramètre est requis et doit être un objet qui peut contenir la propriété optionnelle fallback ou être vide ({}).

La valeur de la propriété fallback est retournée par la fonction et représente un élément qui va temporairement être inséré dans le DOM et remplacé par les contenus des éléments enfants quand ils seront tous disponibles.

Si la propriété fallback n’est pas définie, à la valeur null ou undefined, alors la fonction Suspense() utile un noeud Text vide en remplacement. C’est le cas également si la valeur de la propriété est une chaîne de caractères en utilisant cette chaîne comme valeur du noeud.

Si la valeur de la propriété fallback est une instance de la classe Element (HTMLElement, SVGElement, etc.) il est alors utilisé directement.

Le paramètre children représente les composants enfants dont les contenus vont remplacer l’élément temporaire quand ils seront tous disponibles.

Il faut qu’au moins un des enfants soit une promesse JavaScript sinon l’élément temporaire est remplacé immédiatement. Et s’il n’y pas d’enfants, l’élément temporaire est supprimé immédiatement du DOM.

Les promesses doivent toutes être tenues (une alternative doit être donnée en cas de rejet) sinon l’élément temporaire n’est jamais remplacé.

Une fonction asynchrone JavaScript retourne une promesse, donc son appel peut être utilisé comme élément enfant.

Les contenus des enfants peuvent être de tous les types supportés par la fonction append() de Room (chaînes de caractères, éléments HTML, fonctions etc.). Les contenus peuvent donc aussi être un composant Suspense, l’imbrication est possible.

La fonction Suspense() ne peut pas être utilisée comme résultat d’une fonction réactive de Room, il faut inclure le résultat de la fonction dans un élément HTML pour que cela fonctionne.

Exemple

Dans cette exemple simple, un élément <img> est ajouté dans un container après un délai de 2 secondes et un bouton permet de recommencer l’opération.

Ceci est réalisé par le code suivant :

function SuspenseExample() {
	const {div, button, img} = elements();
	const loadImage = async (src, alt, delay) => {
		return await new Promise(resolve => {
			setTimeout(() => resolve(img({src, alt})), delay);
		});
	};
	const container = div();
	const loadContainer = () => {
		container.textContent = "";
		return append(container, Suspense({fallback: BounceLoader()},
			loadImage("/img/css/room.svg", "Logo Room", 2000)
		));
	};
	return [
		loadContainer(),
		button({class: "defaultButton", onClick: loadContainer}, "Recharger")
	];
}

La fonction loadImage() est asynchrone, elle retourne une promesse qui une fois résolue, retourne l’élément <img>. Elle est utilisée comme enfant du composant Suspense qui est ajouté dans le container par la fonction loadContainer(). Une valeur est donnée à la propriété fallback par la fonction BounceLoader() ce qui permet de voir pendant les 2 secondes d’attente, 3 petites billes animées (par CSS).

Plus d’exemples sont disponibles dans notre dépôt Room-Test.