Komponent specjalizowany - ExternalSection

Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach.

Właściwości komponentu

Właściwość Eximee Designer	Nazwa atrybutu w Źródle	Opis
Adresu URL zasobu	url	Umożliwia podanie adresu URL zasobu do osadzenia wewnątrz komponentu specjalizowanego.

Zewnętrzne źródło danych dla komponentu specjalizowanego

Zawartość komponentu specjalizowanego, poza podaniem URL do zasobu, może być dostarczana za pomocą zewnętrznego źródła danych typu SECTION. Procedura konfiguracji źródła danych jest opisana w rozdziale Przykład podpięcia w komponencie usługi.

ExternalSection w kanale GWT

Dla wszystkich ExternalSection tworzących DOM i wykorzystujących dawne klasy GWT należy:

• dla właściwego ostylowania:

  • nadać na tych elementach w Eximee Designerze klasę (styleName): legacy (np. w ExternalSection rysowany jest przycisk, znajduje się slider ostylowany po staremu)

  • lub dorzucić w samej ExternalSection na root elemencie klasę: legacy (przezroczysta dla starych formsów)

• nadać na elemencie w Eximee Designerze klasę: external-section-content (ExternalSection bez klasy external-section-content nie będą zajmowały miejsca na wniosku. Nie będą również powodowały dodania małego spacera rozdzielającego komponenty.)

W legacy nie wszystkie style są wspierane.

Z legacy będzie spójny z nowymi formsami (klasa potrafiąca ostylować część struktury wniosku).

Można dla starych ES oprócz dwóch wymienionych powyżej klas nadawać także nowe. Dla nowych można skorzystać z powyższych lub nadać nowe.

Ilustracja 1. Przykładowy wygląd komponentu w Eximee Designerze

Jeśli są wstawiane komponenty od teraz (bez użycia starych klas), można nadać dowolną (nową) klasę, jeśli korzysta się ze starych to trzeba dodać legacy.

Tworzenie usługi zwracającej treść ExternalSection w Java

Nowe ServiceProxy API (od wersji 0.63.0)

Parametry wejściowe:

• Wejściem jest obiekt typu ExternalSectionInput zawierający następujące pola:

  • params (dostęp przez metodę getParams()) - mapa parametrów zmapowanych do usługi na szablonie wniosku

  • targetApplication (dostęp przez metodę getTargetApplication()) - identyfikator kanału wywołującego usługę. Aktualne kanały:

    • "W4" - aplikacja webforms (stare webformsy GWT)

    • "ex-forms" - aplikacja ex-webforms (nowa aplikacja angularowa)

• Dodatkowo, w mapie parametrów zawsze przekazywany jest parametr "componentId" wskazujący identyfikator komponentu, na którym osadzona jest usługa

Parametry wyjściowe:

• Wyjściem jest obiekt ExternalSectionOutput zawierający następujące pola:

  • output (przekazywany również w jednoparametrowym konstruktorze) - wyjście usługi w języku HTML (w kodowaniu UTF-8)

package pl.consdata.eximee.examples;
  
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
  
import pl.consdata.iew.serviceproxy.api.exceptions.ServiceProxyException;
import pl.consdata.iew.serviceproxy.api.section.AbstractExternalSection;
import pl.consdata.iew.serviceproxy.api.section.ExternalSectionInput;
import pl.consdata.iew.serviceproxy.api.section.ExternalSectionOutput;
import pl.consdata.iew.serviceproxy.api.types.ServiceProxyField;
  
@Component
@Service(AbstractExternalSection.class)
public class NewApiExampleExternalSection extends AbstractExternalSection {
  
   public NewApiExampleExternalSection() {
      this.name = "NewApiExampleExternalSection";
      this.inputFields.add(new ServiceProxyField(ENTRY_PARAM));
   }
  
   @Override
   public ExternalSectionOutput callServiceForExternalSection(ExternalSectionInput externalSectionInput)
         throws ServiceProxyException {
      String param = getSingleValue(externalSectionInput.getParams(), ENTRY_PARAM, "wartość domyślna");
      if ("W4".equals(externalSectionInput.getTargetApplication())) {
         return new ExternalSectionOutput(String.format("<b>Webforms GWT</b><br><b>Parametr wejściowy:</b>%s<br>",
               param));
      } else if ("ex-forms".equals(externalSectionInput.getTargetApplication())) {
         return new ExternalSectionOutput(String.format("<b>EX-webforms</b><br><b>Parametr wejściowy:</b>%s<br>",
               param));
      } else {
         return new ExternalSectionOutput(String.format("<b>Kanał: %s</b><br><b>Parametr wejściowy:</b>%s<br>",
               externalSectionInput.getTargetApplication(),
               param));
      }
   }
  
   static final String ENTRY_PARAM = "parametrWejsciowy";
}

Stare ServiceProxy API (od wersji 0.63.0 oznaczone jako deprecated)

Parametry wejściowe:

• targetApplication (dostęp przez metodę getTargetApplication()) - identyfikator kanału wywołującego usługę. Aktualne kanały:

  • W4 - aplikacja webforms (stare webformsy GWT)

  • OTHER (od wersji 0.63.0 API) - każdy kanał inny niż W4

• params - mapa parametrów zmapowanych do usługi na szablonie wniosku

• dodatkowo, w mapie parametrów zawsze przekazywany jest parametr "componentId" wskazujący identyfikator komponentu, na którym osadzona jest usługa

Parametry wyjściowe:

• Wyjściem jest obiekt typu String, w którym znajduje się wyjście usługi w języku HTML (w kodowaniu UTF-8)

package pl.consdata.eximee.account.szkolenie;
  
import static org.apache.commons.lang3.StringUtils.EMPTY;
  
import java.util.List;
import java.util.Map;
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
  
import pl.consdata.iew.serviceproxy.api.exceptions.ServiceProxyException;
import pl.consdata.iew.serviceproxy.api.section.AbstractExternalSectionServiceProxy;
import pl.consdata.iew.serviceproxy.api.section.ExternalSectionTargetApplication;
import pl.consdata.iew.serviceproxy.api.types.ServiceProxyField;
  
@Component
@Service(AbstractExternalSectionServiceProxy.class)
public class ExampleExternalSection extends AbstractExternalSectionServiceProxy {
  
    public ExampleExternalSection() {
        this.name = "ExampleExternalSection";
        this.description = "ExampleExternalSection description";
        this.inputFields.add(new ServiceProxyField(INPUT_FIELD));
    }
  
    @Override
    public String callServiceForExternalSection(
            ExternalSectionTargetApplication targetApplication,
            Map<String, List<String>> params) throws ServiceProxyException {
        String input = getSingleValue(params, INPUT_FIELD, EMPTY);
        return String.format("<script>alert('%s')</script>", input);
    }
  
    private static final String INPUT_FIELD = "input";
  
}

Projektowanie komponentów specjalizowanych

Usługa zasilająca komponent specjalizowany może zwracać dwa rodzaje zawartości:

• Adres URL zasobu,

• Zawartość do osadzenia w prezentowanym wniosku.

Adres URL zasobu

Usługa zwracająca adres URL zasobu odpowiada jednowierszowym komunikatem postaci:

URL:adresUrlZasobu

Przykładowo:

URL:http://adres.serwera.obrazkow/zdjecie.png

Komponent specjalizowany zasilony adresem prezentuje statyczną zawartość.

Zawartość do osadzenia w prezentowanym wniosku

Treść zwrócona przez usługę zostanie osadzona bezpośrednio w prezentowanym wniosku. Komponent specjalizowany może przybierać postać:

• dokumentu HTML,

• skryptu JavaScript:

  • zapisane w tagach <script>...</script>

    • możliwe podanie wielu kolejnych tagów <script /> jeden po drugim

  • zapisane w tagach <script src="..." />

    • możliwe podanie wielu kolejnych tagów <script /> jeden po drugim

• kombinacji dokumentu HTML i tagów <script />.

Aplikacja eximee WebForms domyślnie dostarcza bibliotekę jQuery, którą można wykorzystać podczas projektowania komponentu specjalizowanego. Zewnętrzne biblioteki należy dostarczyć samodzielnie dodając odpowiednie tagi <script src="..." />.

Przygotowany komponent specjalizowany jest osadzany bezpośrednio w drzewie DOM prezentowanego wniosku, a w trakcie renderowania na wszystkich tagach <script />, wywoływana jest instrukcja eval.

Zapis wartości komponentu specjalizowanego

Komponent specjalizowany może stanowić bogatą aplikację napisaną w języku JavaScript, która może uaktualniać model wniosku o swoją wartość. W ten sposób, zapisana wartość jest uwzględniana podczas wyliczania warunków komponentów, aktualizacji komponentów zależnych, zasilania usług, zapisywania przy wysyłaniu wniosku itd.

W celu ustawienia wartości komponentu specjalizowanego należy wywołać globalną metodę dostarczaną przez aplikację eximee WebForms:

updateExternalSectionValue(IdentyfikatorKomponentSpecjalizowanego, NowaWartośćKomponentu);
updateExternalSectionValue(externalSection.attr('id'), 'newValue');

Konstrukcja externalSection.attr('id') oznacza, że na węźle drzewa DOM odpowiadającemu komponentowi specjalizowanemu ustawiony jest atrybut id = identyfikator komponentu specjalizowanego.

Jej wywołanie powoduje uaktualnienie modelu prezentowanego wniosku oraz powiadomienie o zmianach wszystkich komponentów zależnych od komponentu specjalizowanego.

Integracja na poziomie frontendu aplikacji

API komponentów specjalizowanych umożliwia między innymi integrację z aplikacją, w której osadzony jest wniosek (np. w przypadku kanału WWW osadzonego jako element portalu) na poziomie JavaScript. API dostarcza metod do odczytu oraz zapisu stanu komponentów na wniosku.

Pobranie wartości innego komponentu

W celu pobrania wartości innego komponentu należy ze skryptu ExternalSection wywołać funkcję getComponentValue("ID_KOMPONENTU_KTÓREGO_WARTOŚĆ_CHCEMY_ODCZYTAĆ"), np:

var textfieldValue = getComponentValue("GesTextField1");

Należy jednak mieć na uwadze następujące ograniczenia:

• Chcąc czytać zmienne sesyjne, muszą one mieć zaznaczoną właściwość "exposed",

• Można czytać jedynie model kliencki - tzn. komponenty z już odwiedzonych stron, potencjalnie niezwalidowane pola.

Ustawienie wartości innego komponentu ze skryptu

Wszystkie pola, które mogą być zmieniane przez kod komponentu specjalizowanego, muszą być dodane do parametru writableFields komponentu, który ustawiamy na wniosku w zakładce Źródło. Żądanie zmiany wartości komponentu nie ujętego w parametrze writableFields, zostanie zignorowane przez platformę.

W celu ustawienia wartości innym komponentom z javascriptu należy wywołać poniższą funkcję:

/**
 * @param externalSectionId - id externalSection, które będzie chciało zawołać setComponentValue
 * @param componentId - id komponentu, któremu chcemy ustawić nową wartość. Do każdego komponentu webformsy wysyłają go automatycznie pod kluczem componentId
 * @param newValue - nowa wartość dla tego komponentu
 */
setComponentValue(externalSectionId,componentId, newValue);

Do zbioru komponentów, którym możemy ustawić nową wartość, należą:

• GesTextField

• GesRadioGroup (ważne! aby ustawiać wartość, która jest w dziedzinie radiogrupy. W innym wypadku otrzymamy błąd na wniosku).

• GesCheckboxSection

• GesCheckbox

• GesTextArea

• GesStatementPopup

• Combobox (id itemu, który chcemy ustawić)

• Slider (wartość z odpowiedniego przedziału)

• StepSlider (wartość z odpowiedniego przedziału)

• PlusMinus (wartość z odpowiedniego przedziału)

• DatePicker (wartość Long)

Parametry funkcji setComponentValue to Stringi. Poniżej zamieszczono przykładowe wywołanie funkcji:

setComponentValue('GesComplexComponent1.GesExternalSection1','GesComplexComponent1.GesTextField3', 'aaaaaa');

Przekazywanie wartości do GesStatementPopup:

• wartość powinna być łańcuchem znaków zawierającym obiekt JSON o następującej strukturze: { MID_OŚWIADCZENIA1 : wartość, MID_OŚWIADCZENIA2 : wartość ... }

• wartość przekazana w obiekcie musi być typu boolean (true / false)

• zostaną zmienione jedynie w obiekcie

• przykładowe wywołanie:

  setComponentValue('GesComplexComponent1.GesExternalSection1','GesComplexComponent1.GesStatementPopup1', '{ "GesComplexComponent1.item1": true }')