Editor schématu bodu rozšíření

Editor schématu bodu rozšíření je možné otevřít dvěma způsoby: jako spoluprodukt při vytvoření nového bodu rozšíření nebo otevřením stávajícího schématu bodu rozšíření.  Podle konvencí mají nová schémata stejný název jako ID bodu rozšíření s příponou souboru .exsd. Jsou umístěna v adresáři schéma v adresářovém stromě v modulu plug-in.  

Po vytvoření nového bodu rozšíření v prostředí PDE je vytvořen také soubor původního schématu a otevře se editor schématu pro úpravy. Schéma můžete definovat okamžitě, nebo jej zavřít a definovat později. Vytvoření úplného schématu bodu rozšíření umožňuje prostředí PDE nabídnout automatizovanou pomoc uživatelům bodu rozšíření.

Editor schématu bodu rozšíření prostředí PDE je založeno na stejných konceptech jako editor manifestu modulu plug-in.  Obsahuje dvě formulářové stránky a jednu stránku zdroje.  Vzhledem k tomu, že schéma XML obsahuje komentáře a v podobě zdroje je obtížně čitelné, měli byste provádět úpravy především na formulářových stránkách.  Stránka zdroje je užitečná pro čtení výsledného zdrojového kódu.

Příklad: Vytvoření schématu pro bod rozšíření "Ukázkové syntaktické analyzátory"

Bod rozšíření "Ukázkové syntaktické analyzátory" a původní schéma již byly vytvořeny dříve. Nyní otevřete schéma v projektové složce schéma a poklepejte na soubor parsers.exsd.  Otevře se editor schématu.

Cílem je:

  1. Definovat platné prvky a atributy XML bodu rozšíření.
  2. Definovat gramatiku (model obsahu).
  3. Poskytnout úseky dokumentace, které budou sloučeny do referenčního dokumentu.

Každé schéma bodu rozšíření začíná deklarací prvku "rozšíření".  Přidáte nový prvek XML s názvem "syntaktický analyzátor".

  1. Klepněte na tlačítko Nový prvek v části Prvky bodů rozšíření.
  2. Přesuňte se do pohledu Vlastnosti a změňte název prvku z "Nový_prvek" na název "syntaktický analyzátor".
  3. Nový prvek ponechejte vybraný a klepněte na tlačítko Nový atribut. Vytvoří se podřízený "nový_atribut". Na listě vlastností změňte jeho název na "ID" a použití na "povinné".
  4. V listě vlastností klepněte na tlačítko "Klonovat tento atribut", které se nachází na lokálním panelu nástrojů. Vytvoří se kopie atributu.  Toto tlačítko je užitečné, protože umožňuje uživatelům rychle definovat všechny atributy, aniž by museli opustit list vlastností.
  5. Změňte název nového atributu na "název".
  6. Znovu naklonujte atribut. Tentokrát změňte název na "třída" . Tento atribut bude představovat úplný název třídy Java, který musí implementovat konkrétní rozhraní prostředí Java. Tento atribut je třeba zadat, aby ho prostředí PDE mohlo později využívat. Změňte druh z "řetězce" na "java".  Nastavte vlastnost basedOn na com.ukazka.xyz.IParser.  (Toto rozhraní ještě neexistuje, ale bude vytvořeno později.)

Editor schématu by měl dosud vypadat takto:

Editor schématu bodu rozšíření - Stránka Definice

Nyní přidáme další atribut, který přebírá hodnoty z krátkého seznamu voleb.  To znamená, že je třeba vytvořit omezení výčtu základního typu řetězec.  Také nastavíte výchozí hodnotu atributu.

  1. Prvek "syntaktický analyzátor" ponechejte vybraný a klepněte na tlačítko  Nový atribut. Změňte jeho název v listu vlastností na "režim".
  2. Klepněte na buňku hodnoty vlastnosti "omezení" a zobrazte dialogové okno omezení. 
  3. Změňte typ omezení z "žádné" na "výčet".
  4. Přidejte následující tři volby: "nikdy", "vždy" a "ruční" . (Jedná se o tři hypotetické režimy pro rozšíření syntaktického analyzátoru.)

Dialogové okno omezení by mělo vypadat takto:

Dialogové okno omezení typu

Po zavření dialogového okna změňte atribut "použití" na hodnotu "výchozí" a "hodnotu" atributu na "vždy".  Tím nastavíte výchozí hodnotu.  Všimněte si, že stavový řádek zobrazuje při zadávání hodnoty chybovou zprávu, protože omezuje platné hodnoty na tyto tři volby výčtu. Jakmile dokončíte zadávání, měla by chybová zprávy zmizet, protože "vždy" je platná hodnota.

Po nadefinování všech prvků a atributů je třeba definovat gramatiku. Cílem je nadefinovat prvek "rozšíření" tak, aby mohl obsahovat libovolný počet podřízených prvků "syntaktický analyzátor". 

  1. Vyberte prvek "rozšíření". Počáteční model obsahu zobrazuje prázdný kompozitor posloupnosti.
  2. Vyberte kompozitor posloupnosti a z rozevírací nabídky vyberte položky Nový->Odkaz->syntaktický analyzátor. Do kompozitoru posloupnosti se přidá odkaz na syntaktický analyzátor.
  3. Výchozí kardinalita odkazů je [1,1], což znamená, že může existovat přesně jeden prvek "syntaktický analyzátor". To neodpovídá zcela požadavkům. Vyberte odkaz "syntaktický analyzátor" a změňte hodnotu maximální_počet_výskytů na "nesvázáno".

Po definování gramatiky zobrazuje přibližný odhad DTD v gramatické části, jak bude vypadat gramatika vybraného prvku v DTD.  Tyto informace jsou určeny vývojářům, kteří pracují s definicemi DTD raději než se schématy XML.

Editor schématu bodu rozšíření - Gramatika prvku

Po nadefinování platných prvků, atributů a gramatiky je třeba zadat informace o bodu rozšíření. Existují dva typy úseků dokumentace schématu:

První typ úseku je uveden na stránce Definice v manifestu schématu. Při výběru prvků a atributů k nim můžete přidat krátký popis v části "Popis". Očekávaný formát je přímý kód HTML (jako u dokumentace Javadoc) a text bude do konečného referenčního dokumentu zkopírován tak, jak je.

  1. Vyberte atribut "id" prvku "syntaktický analyzátor" a v editoru Popis zadejte následující informace:
    Jedinečný název, který bude použit k odkazování na tento syntaktický analyzátor.
  2. Vyberte atribut "název" a přidejte následující text:
    Přeložitelný název, který bude použit pro znázornění tohoto syntaktického analyzátoru v uživatelském rozhraní.
  3. Vyberte atribut "třída" a přidejte následující text (všimněte si značek HTML):
    Úplný název třídy Java, která implementuje rozhraní <samp>com.example.xyz.IParser</samp>.
  4. Vyberte atribut "režim" a zadejte následující informace:
    Nepovinný příznak, který označuje, jak často se spouští tato instance syntaktického analyzátoru (výchozí je <samp>always</samp>).

Krátký textový popis samotného bodu rozšíření není třeba uvádět. Chcete-li popis zadat, je třeba přepnout na stránku Dokumentace:

  1. Nyní by měla být zobrazena karta "Přehled". V textovém editoru přidejte následující text:

    Tento bod rozšíření slouží k zapojení dalších syntaktických analyzátorů. Syntaktické analyzátory nejsou ve skutečnosti funkční - jsou použity pouze jako příklad schématu bodu rozšíření.

    Klepněte na tlačítko Použít.
  2. Klepněte na kartu "Příklady" a zadejte následující text:

    Následuje příklad užití bodu rozšíření:

       <p>
       <pre>
          <extension point="com.example.xyz.parsers">
             <parser
                id="com.example.xyz.parser1"
                name="Sample Parser 1"
                class="com.example.xyz.SampleParser1">
          </parser>
          </extension>
       </pre>
       </p>
    

    Klepněte na tlačítko Použít.

  3. Vyberte kartu "Informace rozhraní API" a zadejte následující text:

    Moduly plug-in, které mají rozšířit tento bod rozšíření, musí implementovat rozhraní <samp>com.ukazka.xyz.IParser</samp>.

    Klepněte na tlačítko Použít.
  4. Vyberte kartu "Dodaná implementace" a zadejte následující text:

    Modul plug-in XYZ poskytuje výchozí implementaci syntaktického analyzátoru.

    Klepněte na tlačítko Použít.
Poznámka: Při poskytování příkladů je třeba vzít v potaz zvláštní okolnosti. Obvykle prostředí PDE považuje text za přímý kód HTML a nebere ohled na nový řádek a mezeru větší než jeden znak (tj. přehlížené neviditelné znaky). To je v pořádku u běžného textu, ale nesmírně obtěžující v ukázkách, kdy je třeba text zformátovat pomocí tabulátoru a svislého zarovnání, aby ukázka vypadala dobře. Prostředí PDE nabízí pro tuto situaci řešení: jakmile zjistí značku HTML <pre>, přebere obsah až po značku </pre> tak, jak je (zachová všechny znaky bez úprav). Díky tomu je možné poskytnout ukázku v takové podobě, v jaké je uvedena výše, a spolehnout se na to, že bude vypadat stejně dobře i v konečném referenčním dokumentu.

Možná jste si již všimli, že postupně, jak vytváříte dokumentaci, je čím dál více prvků v pohledu Osnova v editoru překryto obrázkem "pera". Tento malý indikátor označuje, že k danému prvku je přidružen text. Tímto způsobem můžete rychle zjistit, zda někde v dokumentu nechybí část dokumentace.

Osnova editoru schématu bodu rozšíření

Po dokončení dokumentace můžete obrátit pozornost k referenční dokumentaci. Existují dva způsoby. Po celou dobu práce můžete zobrazit náhled referenčního dokumentu tak, že vyberete položku Zobrazit náhled referenčního dokumentu z rozevírací nabídky. Také můžete nastavit předvolby prostředí PDE (Předvolby>Vývoj modulu plug-in>Kompilátory - na kartě Schéma) pro automatické vytvoření referenční dokumentace při každé změně souboru schématu. Bez ohledu na metodu, kterou zvolíte, bude výsledný dokument ukázky vypadat takto.