Passo 13: Eseguire il rendering di un componente in un frame in linea

Similitudini tra i componenti che utilizzano un frame in linea e i componenti che non utilizzano un frame in linea

Pannello Impostazioni

Poiché il pannello Impostazioni viene sempre posizionato nella pagina in un frame in linea, il codice per il pannello Impostazioni non cambia indipendentemente dal fatto che il componente utilizzi o meno un frame in linea. Si creerà lo stesso codice del pannello Impostazioni per entrambi i casi d'uso.

API del kit Sites SDK

L'interfaccia API SDK è la stessa per entrambi i casi d'uso. Si utilizzerà lo stesso codice per richiamare i trigger, ascoltare le azioni nonché ottenere e impostare i valori delle proprietà. Sebbene alcune proprietà potrebbero non essere applicabili in entrambi i casi (ad esempio non è possibile impostare la proprietà "height" per un componente che non utilizza un frame in linea), l'interfaccia API non cambia. È quindi possibile copiare il codice tra questi due tipi di componenti e il codice di esempio illustrato in questa esercitazione funzionerà per entrambi i casi.

Differenze tra i componenti che utilizzano un frame in linea e i componenti che non utilizzano un frame in linea

Struttura di file e dipendenze

<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

Questi file vengono creati per consentire di eseguire immediatamente il componente in un frame in linea nella pagina. Di seguito vengono descritte le differenze principali tra questa struttura e la struttura di un componente locale standard.

• Dipendenze JavaScript:

  • Si ottiene una copia completa di questi file in modo che il componente possa essere eseguito. Questi file sono necessari per l'esecuzione del componente frame in linea di esempio. È possibile aggiungere e rimuovere il contenuto di questa directory in base alle esigenze.

  • Poiché viene eseguito il PUSH di tutti gli elementi della directory assets in un sito pubblico alla pubblicazione del componente, tutto il contenuto della directory js sarà disponibile sia in SiteBuilder che in runtime.

  • Nota: questi file vengono creati per semplificare l'utilizzo. Si consiglia di consolidare questi file nel tema o in un'altra posizione pubblica, anziché creare versioni separate dei file per ciascuno dei componenti che utilizzano frame in linea.

• render.html:

  • Si tratta di un documento HTML completo, a differenza del file render.js per i componenti standard, che è un modulo AMD.

Gestione di "Height" per il componente

Uno dei problemi riscontrati quando si usa un frame in linea è la gestione dell'altezza del frame in linea. Se si commette un errore, verranno visualizzate barre di scorrimento per il componente nella pagina, anche se non desiderate.

Per gestire l'altezza del frame in linea, il componente deve indicare alla pagina quanto desidera sia alto il frame in linea. Con i componenti remoti, potrebbero verificarsi problemi tra domini diversi, pertanto è necessario utilizzare la messaggistica del kit Sites SDK per chiedere alla pagina di impostare il frame in linea sull'altezza richiesta dopo la visualizzazione del componente nella pagina. A questo scopo si utilizza l'interfaccia API SitesSDK.setProperty('height', {value}). (Vedere Oracle Content and Experience SDK).

Ad esempio, creare la funzione setHeight e un handler di associazioni personalizzato per richiamarla una volta eseguito il rendering del componente nella pagina.

• Aggiornare la funzione height:

  // 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');
  };

• Handler di associazioni personalizzato Knockout per richiamare la funzione setHeight a ogni visualizzazione del componente nella pagina o modifica di proprietà:

  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();
   }
  };

• Aggiornamento del modello per richiamare l'handler di associazioni:

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

Registrazione dei trigger e delle azioni

Per i componenti non inseriti in frame in linea la registrazione dei trigger e delle azioni si trova nel file appinfo.json, mentre per i componenti che utilizzano un frame in linea è responsabilità del componente stesso fornire queste informazioni. Per questa operazione si utilizzano le due interfacce API seguenti:

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

Di seguito viene fornito un esempio dell'uso delle due interfacce 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;
    };

Accesso agli stili del tema

Poiché viene visualizzato in un frame in linea, il componente non ha accesso agli stili disponibili nel tema. Nel kit Sites SDK è disponibile un'interfaccia API che consente di recuperare gli stili in modo che possano essere applicati agli elementi contenuti nel frame in linea.

Questo argomento viene approfondito nel Passo 14: Utilizzare stili personalizzati quando il componente viene visualizzato in un frame in linea.

Uso del protocollo HTTPS e del protocollo HTTP

Poiché Oracle Content Management usa il protocollo HTTPS, anche tutte le risorse alle quali viene fatto riferimento nella pagina devono utilizzare il protocollo HTTPS. Le risorse includono il file .html di base di cui verrà eseguito il rendering nel frame in linea insieme a tutti i file ai quali fa riferimento.

Questo requisito per le risorse si applica soprattutto ai componenti remoti, ma è tuttavia necessario essere consapevoli di tale vincolo. Le risorse per i componenti locali che utilizzano frame in linea vengono fornite dal server di Oracle Content Management, pertanto questi componenti utilizzano già un protocollo corrispondente.

Continuare con l'argomento Passo 14: Utilizzare stili personalizzati quando il componente viene visualizzato in un frame in linea.