Création d'un composant web en utilisant Angular custom elements
Écrit le by T4D Admin
Composants web - à quoi bon?
Au début de ma carrière, j'ai principalement travaillé avec Joomla. Au cours de cette période, diverses demandes spéciales et nos propres idées ont commencés à émerger, ce qui a conduit au développement de nos propres modules personnalisés pour Joomla. Au fil des années, cependant, d'autres CMS tels que Contao et Wordpress ont rejoint notre portefeuille, ce qui a présente le problème suivant : le code de nos modules Joomla ne pouvait être que partiellement adopté pour les modules d'autres CMS. De plus, à chaque portage, un nouveau projet était ajouté, qui devait être maintenu. Et maintenant ?
C'est là que les composants Web viennent à la recousse. Ils sont indépendants de la plate-forme et pris en charge par tous les principaux navigateurs web, donc aucun traitement spécial n'est requis pour les CMS individuels et ce n'est qu'un seul projet qui nécessite maintenance! Par conséquent, la conversion du module en composant Web est une idée évidente.
Qu'est-que c'est, un composant Web?
Les composants Webs sont une technologie pour créer des élements réutilisables dont le code est exécuté en dehors du DOM principal. Les composants web sont réalisés grâce aux trois technologies suivantes:
Custom Elements
Les Custom Elements permettent aux développeurs de définir leurs propers balises HTML et leurs fonctionalités.
Shadow DOM (DOM fantôme)
Même si les composants Web sont bien intégrés dans le document principal, ils sont rendus effectivement dans leur propre DOM fantôme encapsulé, qui ne peut pas accèder le document principal.
HTML-Templates & Slots
Les HTML-templates peuvent être utilisés pour créer des modèles de balisage réutilisables, tandis que le contenu de ceux-ci peut être défini à l'aide des Named Slots.
Créer le projet Angular
Le premier pas est évidemment de créer le projet Angular avec la commande suivante:
ng new <Project-Name> --no-standalone
Bien qu'Angular supporte les composants Web hors de la boîte, les bilbiothèques réquises ne sont pas ajoutés pour un nouveau projet par défaut. Elles doivent être ajoutées par main avec la commande suivante:
npm i @angular/elements
Le projet est désormais prêt à être transformé en un composant Web.
Transformer le projet en composant Web
app.module.ts
On commence par modifier le fichier app.module.ts. La classe AppModule recevra la hook Angular DoBootstrap, et le constructeur ajoute un injecteur qui nous permet de définir notre Custom Element.
Le composant Web sera défini et rendu disponible dans le Bootstrap-Hook ngDoBootstrap ; la fonction createCustomElement, fidèle à son nom, crée un élément personnalisé à l'aide d'un composant Angular (l'AppComponent dans ce cas), tandis que la fonction customElements.define définit la balise HTML que nous utiliserons pour insérer notre composant Web dans un site Web. La dénomination de la balise HTML est soumise aux règles suivantes :
- Le premier caractère de la balise doit être une lettre minuscule (a-z).
- La balise doit inclure au moins un tiret (-).
- Le nom de la balise ne peut pas être une balise HTML existante.
- La balise ne peut pas contenir de caractères spéciaux. (=, @, $ etc.)
Le site webcomponents.guide fournit un outil pour vérifier la validité d'un nom de balise, ainsi que des explications plus détaillées sur les conventions de dénomination.
export class AppModule implements DoBootstrap {
constructor(readonly injector: Injector) {}
ngDoBootstrap() {
const webArticle = createCustomElement(AppComponent, {
injector: this.injector,
});
customElements.define('web-article', webArticle);
}
}Finalement, la ligne suivante doit être supprimée afin d'éviter l'erreur Angular NG05104 :
bootstrap: [AppComponent]
Mise à jour du fichier main.ts
Après avoir mis à jour le fichier app.module.ts, main.ts doit être modifié comme suit pour éviter l'erreur Angular NG0908, et nous sommes alors prêts à partir :
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import 'zone.js';
platformBrowserDynamic().bootstrapModule(AppModule)
.catch(err => console.error(err));Construir le composant Web
Afin de déployer le composant Web, il doit d’abord être construit à l’aide de la commande suivante:
ng build --output-hashing none
Notez l'option --output-hashing none
Vous pouvez aussi ajouter un build-script dans le fichier package.json afin d'éviter l'ajout de l'option à chaque mise à jour.
Le code généré peut être trouvé dans le fichier suivant:
<Project-folder>/dist/<Project-Name>/browser/main.js
Intégrer le composant Web
En général, un composant web peut être intégré dans un site web en suivant les trois pas suivants:
- Télécharger la fichier générer main.js.
- Ajouter le fichier main.js dans le Head du site web en utilisant la balise script.
- Ajouter la composant Web en utilisant la balise définie dans le fichier app.module.ts.
Selon le système, chacune de ces étapes est réalisée différemment.
HTML5
Incorporer un composant web dans un site web HTML5 simple est assez facile, il suffit d'ajouter la balise script dans la portion head du code HTML, avec son attribut src pointant vers l'emplacement du fichier main.js. Une fois ajouté, le composant peut être ajouté en utilisant la balise du composant:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Angular Social Feed</title>
<script src="web-article/dist/web-article/browser/main.js"></script>
</head>
<body>
<web-article></web-article>
</body>
</html>Contao
Afin d'utiliser les composants Web avec Contao, il faudra télécharger le main.js dans un fichier public en utilisant l'interface utilisateur. Le peut ensuite être ajouté à l'en-tête à l'aide du thème (Themes -> Page Layouts) avec l'option External Javascripts.
Une fois ces étapes terminées, le composant Web est disponible sur chaque page qui utilise le thème sélectionné et il peut être inséré à l'aide d'un élément de bloc HTML.
Lors de l'ajout du composant Web, assurez-vous d'utiliser le bloc HTML non filtré, car Contao a tendance à remplacer les crochets par des entités HTML, ce qui conduit à l'affichage de la balise sous forme de texte plutôt qu'à son rendu.
Joomla
Après avoir téléchargé le fichier main.js via FTP, il doit être ajouté à l'en-tête du modèle. Les modèles Joomla proposent généralement cette option dans les paramètres du modèle (Système - > Styles de modèle de site - > Modèle).
Si votre modèle ne propose pas cette option, vous pouvez ajouter le fichier en manipulant le fichier index.php de modèle. (System -> Site Templates -> Template).
Attention: N'utilisez cette méthode qu'en dernier recours. Il est fortement déconseillé de modifier les fichiers de base d'un modèle, car ces modifications peuvent être écrasées lors d'une mise à jour !
Après avoir ajouté le main.js à l'en-tête du modèle, le composant Web peut ensuite être inséré à l'aide d'un module personnalisé, par exemple.
Wordpress
L'utilisation de composants Web sur un site Wordpress est un peu plus délicate, car il faut les importer lors d'une étape supplémentaire. Tout d'abord, le fichier doit être téléchargé sur le chemin suivant:
<WP-DOSSIER-DE-BASE>/wp-content/themes/<THEME>/<DOSSIER_PERSONALISE/>
Après avoir téléchargé le fichier, un script d'importation doit être ajouté ; vous pouvez le faire dans le backend de Wordpress via Tools -> Theme File Editor. Sélectionnez le bon thème dans lequel vous avez téléchargé le fichier main.js à l'aide de la zone de liste déroulante dans le coin supérieur droit, puis ajoutez le code suivant au fichier functions.php :
function add_webcomponent()
{
wp_register_script( 'web-component-script', get_template_directory_uri() . '/web-component/main.js' );
wp_enqueue_script( 'web-component-script' );
}
add_action( 'wp_enqueue_scripts', 'add_webcomponent' );La fonction PHP add_webcomponent enregistre le nouveau script web-component-script, qui importe le fichier main.js dans le site wordpress, puis exécute ce script. La fonction sera exécutée après sa définition. Les noms add-webcomponent et web-component-script ont été choisis librement.
Après avoir ajouté la fonction, le composant Web peut être ajouté au site Wordpress en utilisant p.Ex. un bloc HTML personnalisé.