edee.oneDocs
Edee.one · Dokumentace

Integrace pomocí moduleObject

Koncept slouží pro integraci mezi moduly pomocí volné vazby. Často vzniká požadavek, aby bylo v modulu možné omezeně pracovat s entitami jiného modulu, např. je přiřazovat jako související položky, nebo pouze zobrazovat v GUI.

Implementace poskytující strany

Modul, který se rozhodne poskytovat svoje objekty jiným modulům zajistí implementaci rozhraní com.fg.webapp.cps.v1.modules.integration.ModuleObjectDataProvider (nezaměňovat s ramjet data providery).

Je nutné zvolit dostatečně unikátní název typu objektu, doporučena je konvence "název modulu"/"typ entity" - pro inspiraci viz existující implementace.

Vrácený objekt je v minimalistické formě (id, název), může poskytovat další vlastnosti v dodatečné mapě.

Doporučené vlastnosti pro lepší integrovatelnost:

  • url - veřejné url objektu
  • lang - jazyk objektu
  • objectPath - drobečková navigace umístění objektu, odděleno entitou »
  • tags - seznam přiřazených štítků (resp. jejich systemId)

Pro kontrolu oprávnění (např. ve fulltextu, nebo pro obsahové bloky) je pak nutné doplnit

  • securityModule - id security modulu (hodnota jako se používá v security metadatech security/module)
  • securityIdentifier - id security objektu (hodnota jako se používá v security metadatech security/identifier)
  • securityIdentifierObject - dodatečně lze vracet přímo instanci SecurityIdentifier (hodnota jako se používá v security metadatech security/identifierObject)

Aby šel objekt otevřít v editoru administrace (viz Odkaz na editor objektu), doplňuje se

  • editorPage - selektor stránky editoru včetně parametrů, např. **/edee/metadata/fileEditor?fileId=12
  • editorModule - RamJet modul se stromem stránky editoru (např. edeeui), jen pokud editor není ve stromu administrace Edee

Preferované je implementovat včetně rozšíření pro podporu query - com.fg.webapp.cps.v1.modules.integration.query.ModuleObjectQuerySupport, pak lze plnohodnotně použít v UI.

Existující instance provideru v kontextu modulu jsou pro použití automaticky registrovány, není nutné řešit ručně.

Strana konzumující

Modul, který chce získavat cizí objekty pak využije servisní třídu com.fg.webapp.cps.v1.modules.integration.ModuleObjectService. Ta řeší optimalizované načítání objektů, lze získat i seznam poskytovaný více moduly najednou (volání na jednotlivé providery si třída řeší interně)

Pro práci s daty objektu modulu je vhodné nespoléhat na dostupnost konkrétních vlastností.

java
// ukázka volání pomocné metody pro získání Optional hodnoty s možností konverzefinal String lang = moduleObject.getData(DATA_LANG, String.class).orElse(null);

Odkaz na editor objektu

Libovolný objekt modulu lze otevřít v jeho editoru podle typové adresy přes navigátor:

kód
/adm/qf/<lang>/edeeui/editNavigator?objectType=<typ>&objectId=<id>

To je URL po resolvnutí. Uvnitř RamJetu (XML konfigurace, PageRedirectResolution) se na stejnou stránku odkazuje absolutním id **/edee/others/editNavigator (konstanta PageNavigateInterceptor.EDIT_NAVIGATOR). Navigátor dál přijímá i klasické parametry stránek (sourceId, pageId, systemId) - větev podle objectType/objectId se použije jen tehdy, když žádný z nich v požadavku není.

  • <lang> v cestě je jazyk rozhraní administrace - volí ho ten, kdo odkaz skládá, přesměrování ho zachová.
  • Volitelný parametr lang je jazyk entity (jako u systemId) - objekt vázaný na jazyk (stránka) se otevře vždy ve svém jazyce (lang v datech objektu), požadovaný lang platí jen pro objekty bez vlastního jazyka. Navigátor ho předá editoru sám.
  • Odkaz neskládat ručně - cestu i šablonu pro AI vrací com.fg.edee.integration.cps.editor.EditorLinks. Pro odkazy mimo administraci (MCP klienti, messengery, maily) je potřeba nastavit veřejnou URL administrace v properties edee.admin.publicUrl; bez ní se takové odkazy nenabízejí.

Co musí poskytující modul zajistit:

  • editor - vlastnost editorPage (a případně editorModule) v datech objektu, nebo implementace rozšíření com.fg.edee.integration.cps.editor.ModuleObjectEditorSupport na provideru, pokud editor závisí na uživateli (rozšíření má přednost před daty). Provider jazyk neřeší.
  • security data - securityModule s securityIdentifierObject nebo securityIdentifier (případně lang). Navigátor před přesměrováním ověří právo VIEW výhradně z nich; objekt bez nich se neotevře (fail closed), žádný fallback na id objektu není.

Neznámý typ, neexistující objekt, chyba provideru, chybějící právo i chybějící editor končí stejně - pageNotFound, aby odkaz sdílený mimo administraci neprozradil existenci objektu. Právo VIEW neznamená právo editace - to si hlídá editor sám.

Rozhodnutí viz ADR documentation/adr/edee-editor-navigation-by-object-address.md.

Aplikační události

Pro vybrané implementace jsou dostupné integrační aplikační události

jejich implementace zatím vznikají pouze při opodstatněném požadavku na integraci

Vazba na publikaci

Události svázané s životním cyklem objektu modulu, pomocí kterých mohou jiné module obecně reagovat na změny dostupnosti objektu.

  • ModuleObjectPublishedEvent - objekt se stal veřejně dostupným, případně použitelným pro integraci
  • ModuleObjectUnpublishedEvent - objekt není dále veřejně dostupný ani jinak smysluplně použitelný pro integraci

Publikace je zde chápána v obecnějším významu a tedy použitelná i pro objekty, které klasickou publikací ve smyslu redakčního obsahu neprocházejí. Dle typu objektu lze informovat obecně o dostupnosti pro integraci.

Vazba na provázání objektů

Události reagující na provázání objektů. Datový model pro uložení vazeb mezi objekty modulů je typicky obecný bez možnosti aplikace referenční integrity na úrovni databáze. Proto je vhodné mít možnost reagovat na vytvoření vazby aplikačně.

Události poskytují objectTypeSource a objectIdSource reprezentující zdrojový objekt, který ma k sobě navázané cílové objekty dostupné jako objectTypeTarget a objectIdTarget.

  • ModuleObjectAttachedEvent - akce navázání cílového objektu na zdrojový
  • ModuleObjectDetachedEvent - akce rozpojení cílového objektu se zdrojovým

Zdrojový objekt je tedy chápán jako nadřazený, cílový jak ten který je ke zdrojovému napojený

Ramjet

Dostupné komponenty pro použití v UI

  • com.fg.edee.integration.web.conversion.ModuleObjectConversionStrategy
  • com.fg.edee.integration.web.dataProvider.moduleObject.ModuleObjectRecordListingSource
  • com.fg.edee.integration.web.ui.widget.autocomplete.ModuleObjectAutocompletionDataProvider

Existující implementace

Typy označené editor lze otevřít přes navigátor.

  • edeeAssessment - schvalovací proces preview modulu
  • edeeComment - komentář edeecomment modulu
  • edeeContentBlock - obsahový blok (jako id objektu je použito sourceId) - editor
  • edeeFile - soubor z výchozího úložiště f.file - editor
  • edeePage - stránka (jako id objektu je použito sourceId) - editor
  • edeePageTree - uzel stromu stránek (jako id objektu je použito pageTreeId, lze dohledat i podle systemId v daném jazyce; shortcut je samostatný uzel, položka seznamu uzel nemá) - editor
  • edeeWeb - web - editor
  • edeeStorage - úložiště (jako id objektu je použit hash code textového id storage)
  • edeeTag - štítek - editor
  • edeeCategory - kategorie - editor
  • edeeUser - uživatel administrace
  • edeeLink - objekt odkazu link modulu
  • gaAccount - analytics modul - účet Google Analytics
  • gaProfile - analytics modul - profile Google Analytics
  • mailRecipientList - adresní list mail modulu
  • mailCampaign - kampaň mail modulu - editor
  • registeredUser - registrovaný uživatel
  • scramJetEdee - formulář scramjet modulu
  • eshopProduct - produkt eshop modulu
  • eshopCategory - kategorie produktů eshop modulu
  • eshopGroup - skupina produktů eshop modulu
  • eshopBrand - značka z eshop modulu

Existující vazby na události

  • modifikace souvisejícího objektu u obsahovému bloku emituje ModuleObjectAttachedEvent/ModuleObjectDetachedEvent událost na kterou reaguje edeelink modul pokud je cílový objekt typu edeeLink