Etape 13 : affichage d'un composant dans un cadre incorporé

Similarités entre les composants affichés dans un cadre incorporé et les composants non affichés dans un cadre incorporé

Panneau des paramètres

Le panneau des paramètres étant toujours placé sur la page dans un cadre incorporé, son code ne change pas, peu importe si le composant utilise un cadre incorporé ou non. Dans les deux cas, vous créez le même code de panneau des paramètres.

API de kit SDK Sites

L'API de kit SDK est la même dans les deux cas d'emploi. Vous utilisez le même code pour activer les déclencheurs, écouter les actions, obtenir les valeurs de propriété et les définir. Même si certaines propriétés ne sont pas applicables dans les deux cas (par exemple, vous ne pouvez pas définir la propriété "height" pour un composant qui n'utilise pas de cadre incorporé), l'API reste la même. Par conséquent, vous pouvez copier le code entre ces deux types de composant et l'exemple de code présenté dans ce tutoriel fonctionne dans les deux cas.

Différences entre les composants affichés dans un cadre incorporé et les composants non affichés dans un cadre incorporé

Structure et dépendances des fichiers

<component name>
    assets
        css
            app-styles.css
        js
            jquery.mn.js
            knockout.mn.js
            sites.min.js
        render.html
        settings.html
    appinfo.json
    _folder_icon.jpg

Ces fichiers sont créés dans le but de vous permettre d'exécuter immédiatement votre composant dans un cadre incorporé sur la page. Les principales différences entre cette structure et celle d'un composant local standard sont les suivantes :

• Dépendances JavaScript :

  • Vous obtenez une copie complète de ces fichiers afin que votre composant puisse être exécuté. Ces fichiers sont requis pour que l'exemple de composant de cadre incorporé soit exécuté. Vous pouvez ajouter et enlever le contenu de ce répertoire en fonction de vos besoins.

  • L'ensemble du contenu du répertoire assets de votre composant est propagé vers un site public lorsque le composant est publié, tout le contenu du répertoire js est donc disponible à la fois dans le générateur de site et lors de l'exécution.

  • Remarque : ces fichiers sont créés pour faciliter l'utilisation. Vous devriez envisager de consolider ces fichiers dans le thème ou dans un autre emplacement public plutôt que d'en créer des versions séparées pour chaque composant de cadre incorporé.

• render.html :

  • Document HTML complet, contrairement au fichier render.js pour les composants standard, qui est un module AMD.

Gestion du composant "Height"

L'un des problèmes liés à l'utilisation d'un cadre incorporé réside dans la gestion de la hauteur du cadre incorporé lui-même. Si vous ne la gérez pas correctement, des barres de défilement peuvent apparaître pour le composant sur la page, que vous ne souhaitez pas forcément.

Afin de gérer la hauteur du cadre incorporé, le composant doit indiquer à la page la taille du cadre incorporé. Dans le cas de composants distants, vous pouvez rencontrer des problèmes interdomaines. Vous devez donc utiliser la messagerie de kit SDK Sites pour demander à la page de définir le cadre incorporé sur la hauteur requise une fois que le composant a été affiché sur la page. Pour ce faire, utilisez l'API SitesSDK.setProperty('height', {value}). (Reportez-vous à Kits SDK Oracle Content and Experience.)

Créez par exemple la fonction setHeight et un gestionnaire de liaisons personnalisées pour l'appeler lorsque le composant est affiché sur la page.

• Mettez à jour la fonction de hauteur :

  // set the height of the iFrame for this App
  self.setHeight = function () {
  // use the default calculation or supply your own height value as a second parameter
  SitesSDK.setProperty('height');
  };

• Gestionnaire de liaisons personnalisées Knockout pour appeler setHeight lorsque le composant est affiché sur la page ou lorsqu'une propriété est modifiée :

  ko.bindingHandlers.sampleAppSetAppHeight = {
    update: function (element, valueAccessor, allBindings, viewModel, bindingContext) {
      // create dependencies on any observables so this handler is called whenever it changes
      var imageWidth = viewModel.imageWidth(),
          imageUrl = viewModel.imageUrl(),
          titleText = viewModel.titleText(),
          userText = viewModel.userText();
  
    // re-size the iFrame in the Sites page now the template has rendered
    // Note: If you still see scrollbars in the iframe after this, it is likely that CSS styling in your app is the issue
    viewModel.setHeight();
   }
  };

• Mettez à jour le modèle pour appeler le gestionnaire de liaisons personnalisées :

  <div data-bind="sampleAppSetAppHeight: true"></div>

Inscription des déclencheurs et des actions

L'inscription des déclencheurs/actions pour les composants qui ne sont pas dans des cadres incorporés se trouve dans le fichier appinfo.json, tandis que pour les composants de cadre incorporé, c'est le composant lui-même qui fournit ces informations. Pour ce faire, employez ces deux API :

SitesSDK.subscribe('GET_ACTIONS', self.getAppActions);
SitesSDK.subscribe('GET_TRIGGERS', self.getAppTriggers);

Voici un exemple d'utilisation de ces API.

    // Register TRIGGERS meta-data
    SampleAppViewModel.prototype.getAppTriggers = function (args) {
      var triggers = [{
        "triggerName": "imageClicked",
        "triggerDescription": "Image clicked",
        "triggerPayload": [{
          "name": "payloadData",
          "displayName": "Trigger Payload Data"
        }]
      }];

      return triggers;
    };

    // Register ACTIONS meta-data
    SampleAppViewModel.prototype.getAppActions = function (args) {
      var actions = [{
        "actionName": "setImageWidth",
        "actionDescription": "Update the image width",
        "actionPayload": [{
          "name": "imageWidth",
          "description": "Image Width in pixels",
          "type": {
            "ojComponent": {
            "component": "ojInputText"
            }
          },
          "value": ""
        }]
      }];

      return actions;
    };

Accès aux styles de thème

Puisque le composant est affiché dans un cadre incorporé, il n'a pas accès aux styles disponibles dans le thème. Le kit SDK Sites fournit une API permettant d'extraire ces styles afin de pouvoir les appliquer aux éléments qui se trouvent dans le cadre incorporé.

Ce sujet est plus approfondi dans Etape 14 : utilisation de styles personnalisés lorsque le composant est affiché dans un cadre incorporé.

Protocole HTTPS mixte versus HTTP

Comme Oracle Content Management emploie le protocole HTTPS, toutes les ressources référencées sur la page doivent utiliser HTTPS. Les ressources comprennent le fichier .html de base qui sera affiché dans le cadre incorporé avec tous les autres fichiers qu'il référence.

Cette exigence concernant les ressources s'applique principalement aux composants distants. Vous devez toutefois connaître cette contrainte. Les ressources des composants locaux utilisant des cadres incorporés sont fournies par le serveur Oracle Content Management. Ces composants emploient donc déjà un protocole correspondant.

Passez à Etape 14 : utilisation de styles personnalisés lorsque le composant est affiché dans un cadre incorporé.