Etap 13: Renderowanie składnika w ramce wstawkowej

Podobieństwa między składnikami zawartymi i niezawartymi w ramkach wstawkowych

Panel "Ustawienia"

Ponieważ panel "Ustawienia" jest zawsze na stronie umieszczany w ramce wstawkowej, kod panelu "Ustawienia" nie zmienia się bez względu na to, czy składnik używa czy nie używa ramki wstawkowej. Dla obu przypadków jest tworzony ten sam kod panelu "Ustawienia".

Sites SDK API

SDK API jest identyczny dla obu przypadków. Ten sam kod jest używany do uaktywniania wyzwalaczy, nasłuchiwania czynności oraz uzyskiwania i ustawiania wartości właściwości. Mimo że niektóre właściwości mogą nie mieć zastosowania w obu przypadkach (na przykład nie można ustawić właściwości "height" dla składnika, który nie używa ramki wstawkowej), to jednak API nie ulega zmianie. Z tego powodu można kopiować kod między tymi oboma typami składników — przykładowy kod, omawiany w tym samouczku, będzie działał w obu przypadkach.

Różnice między składnikami zawartymi i niezawartymi w ramkach wstawkowych

Struktura plików i zależności

<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

Pliki te pozwalają od razu uruchomić składnik w ramce wstawkowej na stronie. Główne różnice między tą strukturą a strukturą standardowego składnika lokalnego są następujące:

• Zależności JavaScript:

  • Uzyskuje się kompletną kopię tych plików, tak że składnik będzie działał. Pliki te są wymagane do uruchomienia przykładowego składnika w ramce wstawkowej. W zależności od własnych wymagań można dodawać i usuwać pliki do/z tego katalogu.

  • Ponieważ wszystkie pliki z katalogu assets składnika są wypychane do serwisu publicznego, gdy składnik jest publikowany, wszystko zawarte w katalogu js będzie dostępne zarówno w konstruktorze serwisów, jak i w środowisku wykonawczym.

  • Uwaga: Pliki te są tworzone w celu ułatwienia użytkowania. Zamiast tworzyć ich osobne dla każdego ze składników w ramkach wstawkowych, powinno się te pliki konsolidować w motywie lub w innej lokalizacji publicznej.

• render.html:

  • Jest to pełny dokument HTML w przeciwieństwie do pliku render.js dla składników standardowych, będącego modułem AMD.

Zarządzanie wysokością przez składnik

Jednym z problemów związanych z używaniem ramki wstawkowej jest zarządzanie jej wysokością. Jeśli nie zostanie to poprawnie zrobione, dla składnika na stronie pojawią się paski przewijania, co może być zjawiskiem niepożądanym.

W celu zarządzania wysokością ramki wstawkowej składnik musi poinformować stronę, jaka ma być wysokość ramki. W przypadku składników odległych mogą pojawić się problemy z obsługą różnych domen; trzeba wówczas — do zlecenia ustawienia wysokości ramki wstawkowej na wymaganą po wyrenderowaniu składnika na stronie — użyć funkcji komunikowania się z pakietu Sites SDK. Służy do tego API SitesSDK.setProperty('height', {wartość}). (zob. Oracle Content and Experience — SDK.)

Na przykład można utworzyć funkcję setHeight oraz niestandardową procedurę obsługi wiązania wywoływaną, gdy składnik zostanie wyrenderowany na stronie.

• Funkcja aktualizacji wysokości:

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

• Niestandardowa procedura obsługi wiązania Knockout, wywołująca funkcję setHeight, gdy składnik zostanie wyrenderowany na stronie lub zmienią się właściwości:

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

• Aktualizacja szablonu do wywoływania procedury obsługi wiązania:

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

Rejestracja wyzwalaczy i czynności

Podczas gdy rejestracja wyzwalaczy i czynności dla składników niebędących w ramkach wstawkowych jest zawarta w pliku appinfo.json, to w przypadku składników w ramkach wstawkowych sam składnik jest odpowiedzialny za dostarczenie tych informacji. Służą do tego następujące dwa API:

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

Oto przykład użycia tych 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;
    };

Dostęp do stylów w motywie

Składnik, ponieważ jest renderowany w ramce wstawkowej, nie ma dostępu do stylów zawartych w motywie. Sites SDK udostępnia interfejs API umożliwiający pobranie tych stylów, tak aby mogły one zostać zastosowane do elementów w ramce wstawkowej.

Zagadnienie to jest omówione dokładniej pod hasłem Etap 14: Używanie stylów niestandardowych, gdy składnik jest renderowany w ramce wstawkowej.

Mieszane użycie protokołów HTTPS i HTTP

Ponieważ Oracle Content Management używa protokołu HTTPS, wszystkie zasoby, do których występuje odwołanie na stronie, także muszą używać protokołu HTTPS. Zasoby zawierają bazowy plik .html, który jest renderowany w ramce wstawkowej wraz ze wszystkimi plikami, do których się on odwołuje.

Ten wymóg dotyczy głównie zasobów odległych, ale trzeba jednak pamiętać o tym ograniczeniu. Zasoby dla składników lokalnych używających ramek wstawkowych są udostępniane przez serwer Oracle Content Management, wskutek czego składniki te korzystają z właściwego protokołu.

Kontynuacja: Etap 14: Używanie stylów niestandardowych, gdy składnik jest renderowany w ramce wstawkowej.