Edee pro vývojáře - začínáme
Edee pro vývojáře - začínáme
Vítejte v dokumentaci pro Edee.one, robustního content management systému postaveného na Java platformě.
Edee.one je speciálně navržen pro správu velkých a komplexních projektů, kde je důraz na efektivitu a spolehlivost. Jeho headless architektura vám umožní integrovat obsah snadno a flexibilně na jakoukoliv platformu.
Tato dokumentace je určena primárně pro vývojáře, kteří se chtějí seznámit s možnostmi a funkcionalitami platformy Edee.one, ať už pro účely vývoje, integrace nebo rozšíření existujících řešení.
Zkopírovat odkaz na sekciDocker
Než začneme, je potřeba nainstalovat Docker. Návod pro vaši platformu naleznete v dokumentaci k Dockeru.
Zkopírovat odkaz na sekciStart
Pro potřeby testování pro vývojáře je k dispozici docker image v Gitlab registry https://gitlab.edee.one/
Přístup do Gitlab Vám poskytne Vaše konktaktní osoba.
První kroky - login do registry a stažení docker image
1 > docker login docker-gitlab.edee.one2Username: <your-username>3Password: <your-password>4..5Login Succeeded6 7> docker pull docker-gitlab.edee.one/release/edee.one/edee_conf:latest8..9Status: Downloaded newer image for docker-gitlab.edee.one/release/edee.one/edee_conf:latest10docker-gitlab.edee.one/release/edee.one/edee_conf:latest
Založte projektovou složku
1 mkdir -p edeeheadless/dockera v ní pak soubor docker-compose.yml s obsahem
1 version: "3.7"2 3services:4 edee_conf:5 image: docker-gitlab.edee.one/release/edee.one/edee_conf:latest6 environment:7 TOMCAT_UID: ${TOMCAT_UID}8 TOMCAT_GID: ${TOMCAT_GID}9 WAIT_FOR_MYSQL: mysql:330610 EDEE_HOSTNAME: dev11 volumes:12 - ./volumes/edee-data:/mnt/data13 ports:14 - 127.0.0.1:8080:808015 mysql:16 image: mysql:8.0.3417 volumes:18 - ./volumes/mysql-data:/var/lib/mysql19 ports:20 - 127.0.0.1:3306:330621 environment:22 MYSQL_ROOT_PASSWORD: root23 MYSQL_DATABASE: edeeheadless24 MYSQL_USER: edeeheadless25 MYSQL_PASSWORD: gQat5aVeMY
Je vhodné připravit proměnné prostředí a složky pro data vytvořené aplikací
1 cd edeeheadless/docker2 3export TOMCAT_UID="$(id -u)"4export TOMCAT_GID="$(id -g)"5 6mkdir -p volumes/edee-data7mkdir -p volumes/mysql-data
Pro start Edee.one a databázového serveru pak stačí
1 > docker compose up2...3 4 ✔ Network edee-docker-test_default Created 0.1s 5 ✔ Container edee-docker-test-mysql-1 Created 0.3s 6 ✔ Container edee-docker-test-edee_conf-1 Created 7...8 9edee_conf-1 | 19-Feb-2024 09:35:23.208 INFO [main] org.apache.catalina.core.ApplicationContext.log No Spring WebApplicationInitializer types detected on classpath10edee_conf-1 | ### EDEE ### [11dc48e8] | 0ms | 20240219-093523 | Create new application with edee.one instance11edee_conf-1 | _ 12edee_conf-1 | .___._| |___.___. .___.___.___ 13edee_conf-1 | | -_| . | -_| -_|_| . | | -_|14edee_conf-1 | |___|___|___|___|_|___|_|_|___| 10.10.015edee_conf-1 | 16edee_conf-1 | ### EDEE ### [11dc48e8] | 18ms | 20240219-093523 | startWebApplication17edee_conf-1 | ### CPS ### 10.10.0 build 76483 machine 'dev' os 'Linux'18...19 20edee_conf-1 | 19-Feb-2024 09:36:24.657 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio2-0.0.0.0-8080"]21edee_conf-1 | 19-Feb-2024 09:36:24.662 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [65941] milliseconds22edee_conf-1 | INFO [EdeeONE_moduleExecutor_1][2024-02-19T09:36:37,443][com.fg.monitoring.prometheus.version.VersionInfoLogger]: edee_version_inventory: edee_one: 10.10.0
Aplikace zdetekuje prázdnou databázi a provede kompletní inicializaci. První start může trvat několik minut.
Zkopírovat odkaz na sekciAdministrační rozhraní
Po startu aplikace ověřte dostupnost administračního rozhraní na adrese http://localhost:8080/edee
Konfigurace systému pro potřeby seznámení je zjednodušená a nepožaduje přihlášení jménem a heslem. V produkčním nasazení je pak oprávnění samozřejmě vyžadováno. Lze konfiguračně vynutit i potřebu nastavení dvoufázové autentizace.
Po přihlášení se zobrazí úvodní obrazovka s dlaždicemi, které nabízejí rychlý přístup k dostupným funkcím a modulům. V pravé části obrazovky naleznete sekci "Aktivita", kde je seznam uživatelských událostí a případných požadavků na spolupráci od jiných uživatelů. V horní části se nachází hlavní menu, kde jsou dostupné klíčové části systému, jako správa obsahu, rozšíření a nastavení systému.
Dle konfigurace systému a povolené sadě modulů se v UI zobrazují další funkce. Součástí základní headless verze Edee.one není e-commerce část.
Základní nastavení Edee.one se provádí pomocí konfiguračních XML souborů. Uživatelské rozhraní je primárně určeno pro tvorbu vlastního obsahu. Detailní možnosti konfigurace a přizpůsobení systému jsou zdokumentovány dále.
Zkopírovat odkaz na sekciSpráva obsahu
Volba "Obsah" v menu reprezentuje část Edee.one určenou pro správu redakčního obsahu, tedy obsahu stránek. Je možné spravovat více webů. Každý web je tvořen stromem stránek, kde každý uzel může být jiným typem stránky.
Speciálním případem je seznam stránek. Ve stromu stránek je reprezentován jako jedna položka, ale na webu představuje více stránek. Typicky se jedná o seznam novinek, nicméně možností pro využití je více.
Klik na uzel v levém menu otevře editační formulář v pravé části, kde je pak možné pracovat s obsahem. U seznamů se zobrazí stránka s přehledem položek seznamu; editace jedné položky pak otevře editační formulář podobný tomu pro stránku. Podoba formuláře se může lišit dle potřeb typové stránky a lze ji modifikovat pro potřeby projektu, a to i do výrazně jiné podoby.
Veškeré změny v obsahu je nutné uložit, což lze provést pomocí tlačítka v horní liště formuláře. Uložení proběhne i po kliku na tlačítko "Zveřejnit" nebo "Náhled". Změny, které jsou uloženy, nejsou hned viditelné na spravovaném webu. K jejich zveřejnění je nutné spustit publikační proces.
Zkopírovat odkaz na sekciPublikace v headless režimu - stage
Edee.one rozlišuje mezi primární obsahovou databází a prostorem určeným pro publikovaný obsah, který se nazývá "stage".
Dokud uživatel v administraci nespustí publikaci, není obsah ve "stage" aktualizován a lze na něm bez obav pracovat. K dispozici je i tzv. "preview stage", kde je obsah synchronizován okamžitě po jeho změně.
Nový obsah je tedy možné libovolně měnit a testovat, aniž by byl viditelný na veřejném webu. Teprve finální verzi pak uživatel ve vhodnou dobu zveřejní. Obdobně je možné upravovat již jednou publikovaný obsah. Provedené změny nebudou na webu viditelne dokud neproběhne nová publikace. Pomocí náhledu lze kontrolovat stav obsahu před jeho publikací.
Databáze "stage" modulu je koncipována jako obecné úložiště pro objekty dostupné na webu. Objekty tak mají částečně obecné názvy atributů, které různé typy entit využívají dle svého použití. Podpora dostupných typů objektů se může lišit dle konfigurace modulu.
Důležité je rozlišovat různé identifikátory v rámci celé platformy. Jedna entita může být v různých částech systému dostupná pod různými identifikátory.
Zkopírovat odkaz na sekciTerminologie
Pro lepší orientaci následuje přehled základních entit v části platformy pro správu obsahu:
- Stránka - Reprezentace stránky, má vlastní URL a je vázaná na zdroj stránky.
- Zdroj stránky - Každá stránka má svá zdrojová data, obsahující texty a případně další atributy s možností rozšíření.
- Seznam a položka seznamu - Pro seznamy je pouze provedeno rozšíření; seznam i položka seznamu jsou speciální stránky. Jeden seznam může mít přiřazeno libovolné množství položek, a jak seznam, tak položky mají svůj zdroj stránky.
- Obsahový blok - Ke zdroji stránky lze navázat obsahové bloky, komponenty, které lze doplňovat do stránky.
- Web - Reprezentace jednoho webu, pod který spadá libovolné množství stránek.
- Prototyp - Specifikace typu entity (webu, stránky, nebo bloku) sdružující jeho vlastnosti a možnosti rozšíření.
Další entity
- Štítek - Pro potřeby kategorizace obsahu.
- Kategorie - Rozšíření možností vazeb, primárně mezi zdrojem stránky a dalšími entitami.
- Soubor - Binární soubor v úložišti souborů, reprezentující přílohy, ale i fotografie vložené např. jako motiv.
Reprezentace ve stage
Zjednodušeně se bavíme především o entitách:
- StageObject - Objekt publikovaný ve stage (stránka, obsahový blok, nebo soubor).
- StageRelated - Související položky přiřazené k publikovanému objektu.
- StageSource - Zdrojová data položky.
Objekty modulu
Pro potřeby integrace vazeb mezi různými entitami se používá koncept "module object". Ten každou entitu umožňuje odkazovat pomocí složeného klíče, který se skládá z identifikátoru objektu a typu objektu.
Zkopírovat odkaz na sekciIdentifikátory
Základní podoba identifikátorů je celé číslo použité jako primární klíč v databázi systému. Pojmenování následuje konvenci {{názevEntity}}Id. Například, pokud se objevuje tagId, je zřejmé, že se jedná o identifikátor štítku.
Přehled s vysvětlením:
- pageTreeId - Identifikátor uzlu navigace, tedy stránky. Tímto identifikátorem nelze adresovat položky seznamu, pouze stránky a seznamy.
- sourceId - ID zdroje stránky. Více stránek může používat stejný zdroj. Adresuje jak stránky, tak položky seznamu, ale pouze první stránku, pokud je stejný zdroj použit u více stránek.
- blockId - ID bloku stránky. Aktuálně platí, že jeden blok náleží právě jednomu zdroji stránky a mohou tvořit strom bloků. Ke zdroji jsou přímo navázány pouze bloky první úrovně.
- webId - Identifikátor webu a zároveň id kořenového uzlu stránek webu.
- webSystemId - Alternativní reprezentace ID webu, která zajistí stabilní řetezcový identifikátor (výchozí hodnota je ROOT). Řeší problém s různými databázovými ID v různých prostředích.
- systemId - Alternativní podoba pro pageTreeId, unikátní pouze v jednom jazyce. Konvence pro stránky je prefixovat hodnotu identifikátorem webu - tedy např. pro úvodní stránku hlavního webu se používá ROOT_HP.
Jako názvy parametrů v administračním rozhraní nebo API se dále používají:
- pageId - Obdoba pageTreeId, reprezentována jako řetězec, kde lze volitelně jako hodnotu použít přímo systemId, proto vyžaduje i specifikaci jazyka (lang).
- itemId - Obdoba sourceId, která se používá pro položky seznamu.
Pro realizaci volných vazeb mezi objekty se používá ukazatel přes "module object," který se skládá z:
- objectId - Celočíselný primární identifikátor objektu v modulu.
- objectType - Řetězcový typ objektu v modulu.
- categoryId - ID kategorie vazby - používá se pro rozšíření vazby na související položky.
- categorySystemId - Alternativní podoba pro categoryId, stabilní řetezcový identifikátor.
Ve vztahu se stage:
- stageObjectId - Identifikátor entity ve stage. Stejná entita může být ve stage vícekrát, ale měla by existovat pouze jedna reprezentace v jedné stage (např. jednou v primární a jednou v preview stage).
- stageId - Identifikátor stage, platí ze existuje alespoň primární stage.
- stageSystemId - Alternativní podoba pro stageId, výchozí hodnota pro produkční záznamy je PRIMARY a PREVIEW pokud je povolen náhledový režim.
Z pohledu unikátnosti:
- Pro sourceId (a tedy i itemId) a blockId platí, že se jedná o jednu řadu identifikátorů. To znamená, že neexistuje zdroj stránky a blok se stejným ID.
- Pro webId a pageTreeId (a tedy i pageId) platí, že se jedná o jednu řadu identifikátorů.
- Pro systemId, webSystemId a pageId je nutné použít složený klíč s lang - jinými slovy mohou existovat objekty se stejným system id v jiném jazyce.
- Pro moduleObject je nutné vždy používat složený klíč objectId a objectType - pouze objectId není napříč platformou unikátní.
Zkopírovat odkaz na sekciSystémové identifikátory - Stabilní klíče
Důvodem pro vznik stabilních klíčů (tedy všech identifikátorů obsahujících systemId) je potřeba odkazovat se na neměnné identifikátory objektů. V praxi jsou různá prostředí (vývoj, test, produkce) v různém stavu a nelze nikdy garantovat stejnou podobu databáze.
Pokud chceme v konfiguraci nebo integračním kódu odkazovat na konkrétní objekty, používáme pro ně symbolické názvy. Těmi jsou systémové identifikátory (systemId, webSystemId, tagSystemId, atd.).
Tyto identifikátory jsou vytvořeny podle konvence pro konstanty v Javě, tj. snake case s velkými písmeny. Maximální délka je 96 znaků, ale preferovány jsou kratší hodnoty.
Pro lepší předcházení kolizím u stránek je doporučeno používat prefixy, které identifikují web, tedy ${web.systemId}_${page.systemId} - například ROOT_HP, ROOT_CONTACT.
Zkopírovat odkaz na sekciDotazování pomocí query
Na úrovni API je často použitý Query Language (QL), který slouží pro efektivní filtraci záznamů.
Zkopírovat odkaz na sekciZákladní komponenty dotazu
Ve zkratce, každý dotaz se skládá z následujících částí:
- Filter - Podmínky rozhodující, které záznamy budou vráceny.
- Order - Specifikace pořadí záznamů.
- Hint - Dodatečné informace, například jaký objekt a s jakými daty má být vrácen, může obsahovat požadavek na stránkování.
Pro lepší představu několik ukázek dotazu s popisem
- eq(id,1) - záznam s ID 1
- and( eq(name,'Test'), eq(lang,cs) ) - záznam s názvem 'Test' v češtině
- and( eq(prototype,list), not(eq(sourceType,LIST)), relatedTags: hasAny(eq(systemId,web)) ) - záznamy, které nejsou seznamy a mají přiřazený štítek 'web'
Ukázky specifikace řazení
- desc(id) - řazení podle ID sestupně
- order(name,asc) - řazení podle názvu vzestupně
- desc(sourceType), asc(sectionSortOrder) - řazení podle typu sestupně a následně podle pořadí v sekci vzestupně
- desc(date), relatedTags: asc(systemId) - řazení podle data sestupně, pro jednotlivé záznamy pak seřadit štítky dle systémového identifikátoru vzestupně
Několik příkladu s použitím hintů
- paging(1,20) - vrátit prvních 20 záznamů
- bundle(allDefault,attr) - záznam načíst s výchozími daty doplněný o atributy
Zkopírovat odkaz na sekciREST API stage modulu
Jednotlivé moduly Edee.one vystavují vlastní REST API. Obdobně, jak se rozšiřuje nabídka v uživatelském rozhraní, tak se rozšiřuje i počet dostupných REST API. Pro headless přístup je primární API stage modulu.
REST API jsou dostupné na adrese /api/{název_modulu}. Pro přístup k těmto API budete potřebovat přihlašovací údaje k systému, které pak využijete pro autentizaci (tzv. Basic Auth).
Pro API je nutné vytvořit uživatele v administraci - v sekci Nastavení -> Oprávnění -> Uživatelé -> Nové. Pro použití REST API postačí vyplnit "Přihlašovací jméno" (např. apiuser) a "Heslo".
Stage modul poskytuje svoje API na adrese /api/stages/{stageSystemId}, nejpoužívanější je pak endpoint pro načtení stránkovaného seznamu objektů na adrese /api/stages/PRIMARY/objects.
Komponenty dotazy se v API předávají pomocí parametrů, primárně se jedná o:
- query - specifikace filtrační podmínky
- order - řazení vrácených záznamů
- pageSize a pageNumber - části hintu pro stránkování
- related, source, tree, attr - další hinty pro určení množství vrácených dat
Pro GET požadavky se jedná o URL parametry, pro POST požadavky pak o klíče v JSON objektu.
Zkopírovat odkaz na sekciUkázka použití
Pro otestování je možné použít curl pro vytvoření požadavku na hlavní stage.
1 curl http://localhost:8080/api/stages/PRIMARY -u "apiuser:your-password"Výsledkem pak bude
1 {2 "id" : 1,3 "stageType" : "PRODUCTION",4 "systemId" : "PRIMARY",5 "name" : "Default stage",6 "created" : "2024-01-02T09:36:19.000+00:00",7 "changed" : "2024-01-02T09:36:19.000+00:00",8 "createdBy" : "stageModule",9 "changedBy" : "stageModule"10}
Pokud je vše v pořádku, můžeme pokračovat s načtením seznamu objektů.
1 curl http://localhost:8080/api/stages/PRIMARY/objects -u "apiuser:your-password"Výsledkem bude objekt reprezentující stránkovaný seznam a jeden objekt typu edeeWeb. Další položky budou dostupné po publikaci stránek.
1 {2 "pageSize" : 20,3 "pageNumber" : 1,4 "totalNumberOfRecords" : 1,5 "lastPageNumber" : 1,6 "data" : [ {7 "id" : 1,8 "stageId" : 1,9 "objectId" : 1,10 "objectType" : "edeeWeb",11 "name" : "web 1",12 "sourceId" : 10001,13 "lang" : "cs",14 "webId" : 1,15 "webSystemId" : "ROOT",16 "pageTreeId" : 1,17 "pageTreeSortOrder" : 1,18 "sectionSortOrder" : 0.0,19 "systemId" : "ROOT",20 "dataType" : "sourceWeb",21 "sourceType" : "PAGE",22 "prototype" : "defaultWeb",23 "created" : "2024-02-19T09:35:47.000+00:00",24 "changed" : "2024-02-19T09:35:47.000+00:00",25 "url" : "http://localhost/cs"26 } ],27 "pageNumbersNavigation" : [ 1 ]28}
Doplněním parametru source=true získáme košatější objekty, které obsahují i zdrojová data.
1 curl http://localhost:8080/api/stages/PRIMARY/objects?source=true -u "apiuser:your-password"Zkopírovat odkaz na sekciPříklady dotazů
Pro rychlejší orientaci několik příkladů dotazů, které lze provést pomocí REST API stage modulu.
Všechny stránky - tedy stránky, seznamy stránek i položky seznamů
- GET /api/stages/PRIMARY/objects?query=eq(objectType,edeePage)
Stránky z konkrétního webu dle jeho systemId a jazyka
- GET /api/stages/PRIMARY/objects?query=and( eq(webSystemId,ROOT), eq(lang,cs), eq(objectType,edeePage) )
Stránky pouze vybraného prototypu s omezením na položky seznamu
- GET /api/stages/PRIMARY/objects?query=and( eq(prototype,listNews), eq(sourceType,ITEM), eq(objectType,edeePage) )
Řazení dle data poslední modifikace - seznam 50 naposledy modifikovaných stránek
- GET /api/stages/PRIMARY/objects?query=eq(objectType,edeepage)&order=desc(changed)&pageSize=50
Stránky z konkrétní sekce dle její systemId
- GET /api/stages/PRIMARY/objects?query=and( eq(objectType,edeePage), tree: hasAny(eq(systemId,'ROOT_CONTACTS')) )
Stránky s přiřazeným jedním ze štítků
- GET /api/stages/PRIMARY/objects?query=and( eq(objectType,edeePage), relatedTags: hasAny(in(systemId, 'WORKPLACE_NA', 'WORKPLACE_PHA')) )
Všechny obsahové bloky vybrané stránky seřazené dle pořadí v administraci
- GET /api/stages/PRIMARY/objects?query=and( eq(objectType,edeeContentBlock), eq(sourceId,10002) )&order=asc(sectionSortOrder)
Zkopírovat odkaz na sekciDalší dokumentace
Detailní informace o stage modulu jsou v samostatné části dokumentace.
- popis stage modulu včetně jeho objektového modelu
- dokumentace stage REST API
- specifikace Stage REST API pomocí OpenAPI