Tworzenie wtyczki dokumentacji (nieaktualne)

Widgety udostępniane użytkownikom mogą być wyposażone w pliki pomocy. Pliki te można umieścić w dowolnym miejscu, jednak aby zintegrować je z systemem pomocy, należy utworzyć wtyczkę dokumentacji.

1. Utwórz folder, w którym znajdować się będzie zawartość wtyczki, i nadaj mu nazwę zgodną z nazwą wtyczki. Nazwa wtyczki musi kończyć się łańcuchem .doc i musi obejmować numer wersji. Na przykład com.ibm.wbpm.bspace.main.doc_7.5.0.
   Wskazówka: numer wersji dobrze jest dodać na końcu nazwy folderu wtyczki, gdyż ułatwia to aktualizowanie wtyczki. Po napotkaniu wtyczek o takiej samej nazwie podstawowej system pomocy porównuje numery wersji i wyświetla wyłącznie zawartość wtyczki o najwyższym numerze wersji.
2. Utwórz plik plugin.xml, aby zdefiniować wtyczkę. Ustaw atrybuty elementów plugin i toc. W elemencie plugin atrybut name zawiera tekst wyświetlany przez system pomocy dla użytkownika. W elemencie toc atrybut file identyfikuje plik zawierający strukturę nawigacyjną.
   Definicja DTD elementów i atrybutów używanych w systemie pomocy jest następująca:

   <!ELEMENT plugin (extension*)>
   <!ATTLIST plugin
     name               CDATA #REQUIRED
     id                 CDATA #REQUIRED
     version            CDATA #REQUIRED 
   >
   
   <!ELEMENT extension ANY> 
   <!ATTLIST extension point              CDATA #REQUIRED 
    >

3. Utwórz plik nawigacyjny i nadaj mu odpowiednią nazwę. Nazwa pliku musi być zgodna z atrybutem file zawartym w pliku plugin.xml.
4. W pliku nawigacyjnym utwórz strukturę nawigacyjną przy użyciu elementów topic. Poniższy przykład jest częścią struktury nawigacyjnej wtyczki treści dotyczącej środowiska.

   <?xml version="1.0" encoding="utf-8"?>
   <?NLS TYPE="org.eclipse.help.toc"?>
   <!--  Copyright IBM Corporation 2011-->
   <toc label="Business Space oparty na technologii WebSphere" topic="concepts/bspace_concepts_main.html">
      <topic label="Przegląd produktu Business Space" href="concepts/bspace_concepts_main.html">
         <topic label="Obszary biznesowe" href="concepts/bspace_concepts_openbspace.html"/>
         <topic label="Widgety" href="concepts/bspace_concepts_widgets.html"/>
         <topic label="Przykłady modelowe" href="concepts/bspace_concepts_showcases.html"/>
      </topic>
   </toc>

5. Skopiuj pliki treści do tego samego folderu, w którym znajduje się plik plugin.xml i plik nawigacyjny.
6. Skompresuj pliki treści w pliku doc.zip. Nazwą pliku skompresowanego musi być doc.zip. System pomocy nie może odczytywać zawartości plików o innej nazwie.
7. Aby zapewnić obsługę dodatkowych języków, utwórz fragment NL. Fragment NL jest zestawem wtyczek zawierających przetłumaczone pliki odpowiadające plikom znajdującym się w podstawowym zestawie wtyczek.
   1. Utwórz folder fragmentu, zmień jego nazwę na zgodną z wtyczką dokumentacji i dopisz na końcu tej nazwy łańcuch .nl. Na przykład com.ibm.wbpm.bspace.main.doc.nl.
   2. Dodaj folder nl, a następnie dla każdego obsługiwanego języka utwórz podfolder zawierający kod danego języka.
   3. W każdym podfolderze utwórz przetłumaczoną wersję pliku nawigacyjnego i skompresuj przetłumaczone pliki treści do postaci pliku doc.zip. Jeśli w pliku doc.zip nie ma przetłumaczonego pliku, użytkownicy widzą domyślnie plik angielski.
   4. W katalogu głównym wtyczki fragmentu dodaj plik fragment.xml. Definicja DTD pliku fragment.xml jest następująca:

      <?xml encoding="US-ASCII"?> 
      <!ELEMENT fragment>
      <!ATTLIST fragment
        name                CDATA #REQUIRED
        id                  CDATA #REQUIRED
        version             CDATA #REQUIRED
        plugin-id           CDATA #REQUIRED
        plugin-version      CDATA #REQUIRED
      >

      Folder fragmentu NL zawiera plik fragment.xml oraz folder nl. W folderze nl znajduje się folder dla każdego obsługiwanego języka zawierający przetłumaczony plik spisu treści oraz plik doc.zip zawierający przetłumaczone pliki.
8. W przypadku aktualizowania istniejącej wtyczki dokumentacji, która nie ma dopisanego do nazwy numeru wersji, wyczyść pamięć podręczną pomocy.
   1. Zatrzymaj serwer.
   2. Usuń wyłącznie foldery znajdujące się w folderze katalog_główny_profilu\temp\nazwa_węzła\nazwa_serwera\BusinessSpaceHelpEAR\BusinessSpaceHelp.war\eclipse\configuration. Nie należy usuwać plików znajdujących się w tym folderze.
   3. Zrestartuj serwer.
9. Jeśli instalowana lub aktualizowana jest tylko wtyczka dokumentacji (czyli nie następuje instalacja ani aktualizacja widgetu):
   1. W wierszu komend przejdź do katalogu katalog_główny_profilu/bin lub katalog_główny_klastra/bin.
   2. Wprowadź komendę wsadmin.bat -conntype NONE, a następnie kolejną odpowiednią komendę:
      • W przypadku instalowania widgetów w środowisku autonomicznym:
        • Komenda w języku Jython:AdminTask.updateBusinessSpaceWidgets('{-nodeName węzeł -serverName serwer -helpplugins pełna_ścieżka}')
        • Komenda w języku Jacl: $AdminTask updateBusinessSpaceWidgets {-nodeName węzeł -serverName serwer -helpplugins pełna_ścieżka}
      • W przypadku instalowania widgetów w środowisku klastrowym:
        • Komenda w języku Jython: AdminTask.updateBusinessSpaceWidgets('{-clusterName klaster -helpplugins pełna_ścieżka}')
        • Komenda w języku Jacl: $AdminTask updateBusinessSpaceWidgets {-clusterName klaster -helpplugins pełna_ścieżka}
      Argument pełna_ścieżka określa nazwę i położenie utworzonej wtyczki dokumentacji.

      Informacje dotyczące komendy updateBusinessSpaceWidgets zawiera sekcja Komenda updateBusinessSpaceWidgets.

   3. Wprowadź komendę Exit.
   4. Zrestartuj serwer lub klaster.