Vlastní widget Tisk pro ArcGIS Experience Builder
Začátkem roku 2020 přišla první verze dlouho očekávané aplikace ArcGIS Experience Builder (ExB), prostředí, pro tvorbu vlastních webových aplikací bez nutnosti programování. Přestože aplikace přináší mnoho nového (flexibilní a responzivní layout, ArcGIS JS API 4.x, 2D/3D, …), první verze ExB, ve srovnání s „vyzrálou“ aplikací ArcGIS Web AppBuilder (WAB), zatím zaostává ve funkcionalitě. Je to sice jenom otázka času, kdy Esri implementuje funkcionalitu WAB i do ExB, my se však podíváme na to, jak funkcionalitu ExB rozšířit již dnes. Využijeme k tomu verzi ExB určenou pro programátory.
Nebojte, nebudeme zde skutečně programovat. Pouze si vysvětlíme základní koncepty a nainstalujeme si prostředí, ve kterém můžete začít programovat vlastní widgety později
Co k tomu budeme potřebovat?
Aplikaci ArcGIS Experience Builder (Developer Edition), kterou si můžeme stáhnout zde. Poté postupujeme podle návodu k instalaci, který je podrobně popsán v dokumentaci.
Instalace ExB je v dokumentaci rozdělena na dvě části:
- client (služba pro vývoj widgetů) – zajišťuje kompilaci/transpilaci zdrojových kódů widgetů do produkční formy, pomocí nástroje Webpack.
- server (služba pro provoz ExB) – zajišťuje dostupnost ExB na adrese https://localhost:3001 při konfiguraci aplikací.
U konce každé části je uvedeno, že máme použít příkaz npm ci (tím nainstalujeme potřebné knihovny pro danou službu) a pak npm start (tím spustíme danou službu). Instalaci knihoven udělejte pro obě služby (client a server), spuštění pak pouze pro službu server (službu client budeme spouštět později).
Pozn. Příkazem npm start se spustí odpovídají služba a příkazový řádek zůstane zablokován. Po jeho zavření (nebo Ctrl+C) bychom spuštěnou službu ukončili. Proto ponechte příkazový řádek se spuštěnou službou server otevřen.
Po správné instalaci bychom měli být schopni spustit ExB na svém počítači, ve webovém prohlížeči, na adrese https://localhost:3001. Je tomu jinak? Napište do komentářů pod článkem.
Po spuštění ExB nás aplikace vyzve, abychom zadali URL adresu portálu (ArcGIS Online, nebo ArcGIS Enterprise) a také ID aplikace (toto bychom měli znát, pokud jsme prošli instalací ExB dle dokumentace). Po přihlášení se do portálu je ExB připraven.
Pozn. Propojení ExB s portálem nám umožní, abychom při konfiguraci aplikací mohli využít dostupný obsah portálu v podobě webových map a mapových vrstev (dat) a dalších služeb, které portál nabízí.
ArcGIS Experience Builder (Developer Edition) nám umožňuje rozšířit funkcionalitu aplikací ExB o vlastní widgety. Přestože je ExB stavěn na základech ArcGIS API for JavaScript 4.x, které samo obsahuje řadu widgetů, tyto widgety mají odlišné API než ExB widgety a nejsou v prostředí ExB automaticky dostupné. Neznamená to však, že bychom je v ExB využít nemohli. Proto se teď zaměříme na to, jak dostat widget ArcGIS JS API do prostředí ExB. Konkrétně se bude jednat o widget Print, který v ExB zatím chybí.
Co budeme potřebovat dál?
Pokud nemáme, nainstalujeme si aplikaci Visual Studio Code, ve které můžeme prozkoumávat zdrojové kódy widgetu a taky vyvíjet widgety vlastní. Mohli bychom použít i libovolný textový editor, připravili bychom se ale o komfort, který VS Code nabízí (podpora TypeScript, IntelliSense, …) a to určitě nechceme.
Abychom nezačínali od nuly, začneme od konce a do prostředí ExB si vložíme již hotový widget Print, kterého projekt je připraven v prostředí GitHub, zde. Buď si jej stáhneme v ZIP a obsah archivu umístíme do adresáře <exb>\client\your-extensions\widgets\exb-widget-print, nebo použijeme nástroj Git a po jeho instalaci zavoláme z příkazové řádky, s umístěním v adresáři <exb>\client\your-extensions\widgets\, příkaz git clone https://github.com/mvrtich/exb-widget-print.git. Výsledkem by měl být adresář <exb>\client\your-extensions\widgets\exb-widget-print, který obsahuje adresář src a soubory manifest.json, config.json a další.
Teď spustíme aplikaci VS Code a otevřeme (File>Open Folder) adresář <exb>\client\. Následně zobrazíme příkazový řádek (View>Terminal) a zavoláme v něm příkaz npm start. Tento příkaz, jak již víme, spustí ExB službu client (webpack), která zkompiluje zdrojové kódy našich widgetů a zůstane běžet a monitorovat další změny. Jakákoliv změna zdrojových kódů widgetů vyvolá jejich re-kompilaci. Protože se budeme zaměřovat spíš na porozumění konceptů než psaní vlastního kódu, můžeme příkaz po dokončení kompilace ukončit (Ctrl+C).
Za předpokladu, že nám pořád běží příkazový řádek se spuštěnou ExB službou server, měli bychom být schopni náš nový widget Print použít při tvorbě vlastní aplikace.
V prostředí ExB, na adrese https://localhost:3001, si vytvoříme nový projekt (Vytvořit nový) a použijeme např. šablonu Skládací. V aplikaci pak widget mapy propojíme s nějakou webovou mapou z portálu, ke kterému jsme v ExB připojeni (označit widget mapy a v pravé části pak Vybrat mapu). V pravé horní části aplikace pak vložíme náš nový widget Tisk pomocí tlačítka plus (+). Označením přidané ikony widgetu Tisk v aplikaci se v pravé části ExB zpřístupní UI pro konfiguraci widgetu. Náš widget Tisk potřebuje nastavit propojení s mapou (Widget mapy) a volitelně pak URL tiskové služby (ve výchozím nastavení je použita tisková služba portálu, ke kterému jsme v ExB připojeni). Po propojení s mapou by měl být widget Tisk funkční. Můžeme si to ověřit přepnutím ExB do režimu Živé zobrazení (nahoře), kdy budeme moct s konfigurovanou aplikací interagovat.
Kdybychom chtěli výslednou aplikaci zpřístupnit uživatelům, je třeba aplikaci nasadit na produkční webový server. Postup je uveden v dokumentaci.
Jak asi již tušíme, ExB očekává naše vlastní widgety v adresáři <exb>\client\your-extensions\widgets. Každý widget je reprezentován samostatným adresářem, kterého název nesmí obsahovat mezery a má danou strukturu.
Pozn. Vytvoření základní struktury nového ExB widgetu nám může usnadnit nástroj @arcgis/cli.
A z čeho se skládá náš ExB widget Tisk?
- <exb-widget-print>\manifest.json – takový rodný list widgetu. Je zde uveden název widgetu (musí být stejný jako název adresáře widgetu), verze ExB a další informace. Pro náš widget Tisk je důležité, že je zde uvedena závislost na knihovně „jimu-arcgis“. ExB tak zajistí, že náš widget bude mít po spuštění dostupné moduly ArcGIS API for JavaScript, ze kterých čerpá funkcionalitu. Více informací zde.
- <exb-widget-print>\icon.svg – ikona widgetu zobrazena v prostředí ExB.
- <exb-widget-print>\config.json – výchozí hodnoty konfigurace widgetu. V našem případě je zde pouze atribut printServiceUrl, který je prázdný. Proto se při konfiguraci widgetu v ExB zobrazuje ve výchozím stavu prázdné textové pole a widget je naprogramován tak, aby v takovém případě použil výchozí tiskovou službu portálu.
- <exb-widget-print>\src\config.ts – definice datových typů konfigurace widgetu. Musí odpovídat tomu, co je uvedeno v souboru config.json. V našem případě je zde řečeno, že atribut printServiceUrl je typu string.
- <exb-widget-print>\src\setting\setting.tsx – zdrojové kódy konfigurace widgetu (to, co vidí tvůrce aplikace, při konfiguraci widgetu v prostředí ExB).
- <exb-widget-print>\src\runtime\widget.tsx – zdrojové kódy widgetu (to, co vidí uživatel, při použití widgetu ve výsledné aplikaci).
ArcGIS Experience Builder je naprogramován v jazyce TypeScript a pro implementaci widgetů využívá React a další technologie. Proto je i náš widget naprogramován v jazyce TypeScript a jedná se prakticky o React komponentu (widget.tsx). Volitelně pak může obsahovat další React komponentu (setting.tsx), která slouží jako UI pro konfiguraci widgetu v prostředí ExB. Samotný ExB nabízí také vlastní knihovnu, Jimu. Ta obsahuje řadu modulů usnadňujících tvorbu UI vlastních widgetů, integraci na ostatní widgety a mnoho dalšího.
Náš widget Tisk je tedy React komponenta, která "obaluje" widget Tisk z ArcGIS JS API. ExB naší React komponentě zajišťuje mnoho schopností, jako je lokalizace, konfigurace, layout a tematizace, ale také propojení na datové zdroje a další komponenty v aplikaci. Toho naše komponenta využívá a po propojení s widgetem Mapa v rámci konfigurace, tuto mapu použije pro konfiguraci widgetu Tisk z ArcGIS JS API. Tento widget pak umístí na odpovídající HTML element pro vyrenderování. O zbytek se stará widget Tisk z ArcGIS JS API.
Veškeré widgety z ArcGIS JS API mají oddělenou aplikační logiku (ViewModel) od UI (View). Kdybychom chtěli, aby náš ExB widget Tisk vypadal zcela jinak než widget Tisk z ArcGIS JS API, ale funkčně nám vyhovoval, můžeme v rámci ExB widgetu využít pouze PrintViewModel a vlastní UI řešit v naší React komponentě. Je toho tolik, co nám může knihovna ArcGIS JS API 4.x při implementaci vlastních ExB widgetů nabídnout.
Více informací o psaní vlastních widgetů pro ArcGIS Experience Builder lze najít v dokumentaci. Najdeme zde i řadu ukázek widgetů, které představují různé možnosti implementace vlastní funkcionality a začínají se objevovat i tutoriály na webu ArcGIS for Developers.
Happy Widgeting!