Akeneo ikona technologiiWprowadzenie do tworzenia modułów frontendowych w Akeneo PIM

Wprowadzenie do tworzenia modułów frontendowych w Akeneo PIM

Modyfikacja istniejących funkcjonalności i tworzenie nowych to często bardzo złożony temat. Aby móc swobodnie poruszać się w tym obszarze, musimy najpierw zapoznać się z kilkoma technicznymi aspektami, które ułatwią nam dalszą pracę i zminimalizują ryzyko wystąpienia potencjalnych problemów.

Nie jesteś pewny, jak stworzyć nowe bundle w Symfony, jak stworzyć lub nadpisać moduły oparte o JS? Jak znaleźć moduły w plikach źródłowych Akeneo? Jakie są podstawowe komendy, potrzebne do przebudowania frontendu w wersjach 4.0/5.0 i do uruchomienia domyślnego watchera w webpacku? Podpowiadamy!


Przeczytaj również inne artykuły z cyklu:


Tworzenie nowych bundli z modułem JS

Przed rozpoczęciem prac należy zainstalować Akeneo. Nie będziemy omawiać samego procesu instalacji, ponieważ są różne sposoby i – w zależności od wybranej metody – cała procedura będzie przebiegać nieco inaczej. Odsyłamy w tym momencie do dokumentacji.

Zakładamy, że Akeneo zostało już zainstalowane. W folderze głównym można zobaczyć następującą strukturę plików:

File structure 1a

Wszystkich naszych zmian będziemy dokonywać w folderze "src". W ramach przyjętych przez nas praktyk zmiany będą przechowywane w folderze "Macopedia", od nazwy naszej firmy (lub czasem od nazwy projektu).

Zajmiemy się teraz stworzeniem nowego bundla dla wybranego zbioru funkcjonalności. Nazwijmy go "Product". Jak sama nazwa wskazuje, tutaj będą się znajdować zmiany dotyczące produktów. Pomaga nam też podzielić moduły ze względu na zastosowanie. Folder "Product" zakładamy w folderze "Macopedia":

File structure 2

Musimy dodać plik ".php", postępując dalej zgodnie z konwencją Symfony. Nadajemy mu nazwę "MacopediaProductBundle". Zwróć uwagę, że plik kończy się członem "Bundle". To konieczne, by możliwa była jego identyfikacji przez Symfony.

Umieść ten plik w następującej ścieżce:

"src/Macopedia/Product/Infrastructure/Symfony/MacopediaProductBundle.php"

File structure 7

Sam plik ma bardzo prostą budowę:

Kolejnym krokiem będzie zarejestrowanie naszego bundla w konfiguracji Symfony. Szukamy pliku "config/bundles.php" i załączamy stworzony przez nas bundle:

File structure 3a
 ['all' => true],
];?>

Po tych zabiegach możemy jeszcze usunąć cache "rm -rf var/cache" oraz wykonać komendę "composer install".

W tym momencie powinniśmy mieć możliwość pracy w naszym bundlu. Więcej informacji na temat dodawania bundli znajdziesz w dokumentacji Symfony.

Gdzie umieszczamy nowe pliki odpowiadające za frontend?

Dowiedziałeś się już, że wszystkie nadpisywane i tworzone pliki są gromadzone w folderze "src". Mając tę wiedzę oraz informację z poprzedniego rozdziału, najwyższy czas wyjaśnić Ci, jaką dokładnie strukturę powinien mieć bundle, aby można było umieścić w nim pliki JavaScript.

W katalogu "Symfony" przygotowujemy dodatkowy katalog "Resources", w nim katalog "public" i w dalszej kolejności jeszcze folder "js". Pamiętaj, aby działać według dokumentacji Symfony:

File structure 4

Do tego należy też przygotować "config", a w nim plik "requirejs.yml". W folderze "config" będą dodawane przez RequireJS pliki JavaScript:

File structure 5

Jak wiemy z poprzednich rozdziałów, tak rejestrujemy moduł dla RequireJS:

config:
 paths:
   file-key: macopediaproduct/js/product/file

To przykład dodania naszego pliku "file.js", który teraz będzie dostępny po kluczu "file-key".

Podstawowe komendy potrzebne do przebudowania frontendu

Zmiany w plikach .yml (jak powyżej) wymagają przebudowy frontendu z wykorzystaniem komendy "make front" (Akeneo 4.0), a od wersji 5.0 – "make upgrade-front". Przy wykonywaniu komendy przebudowującej warstwę frontendową należy wyłączyć watcher, a po zakończeniu procesu ponownie go włączyć. 

Domyślny webpackowy watcher monitorujący zmiany w projektach Akeneo jest wywoływany przez komendę "yarn run webpack-dev --watch".

Jak znaleźć szukany moduł?

Chcąc zmodyfikować istniejącą funkcjonalność Akeneo, musisz nadpisać oryginalny moduł JS własnym modułem. W tym celu należy najpierw odszukać w plikach źródłowych Akeneo pierwotny plik oraz sprawdzić, jak jest zarejestrowany w RequireJS.

Pliki źródłowe Akeneo w naszym projekcie zlokalizujemy tutaj:

File structure 6a

Omówmy teraz krok po kroku, jak znaleźć plik po kluczu z RequireJS. Będzie to bardzo przydatne w kolejnym poście, gdzie przedstawimy proces nadpisywania modułu. Dlatego wyobraźmy sobie, że chcemy odszukać plik, który jest dostępny po kluczu "pim/form-modal".

W głównym pliku RequireJS znajdującym się w plikach źródłowych Akeneo mamy następującą sytuację:

pim/form-modal:                     pimui/js/form/form-modal

Link do pliku:

https://github.com/akeneo/pim-community-dev/blob/master/src/Akeneo/Platform/Bundle/UIBundle/Resources/config/requirejs.yml

Podana ścieżka do niego to "pimui/js/form/form-modal", jednak próbując znaleźć plik dokładnie o takiej ścieżce, przekonasz się, że nie istnieje. Nie jest to bowiem dokładna ścieżka do pliku i zawiera aliasy. Spróbujmy zatem rozłożyć na czynniki pierwsze podaną ścieżkę i odnaleźć szukany moduł.

Pierwszy człon “pimui” odnosi się do ścieżki poniżej i pochodzi od nazwy bundla w Symfony:

pim-community-dev/src/Akeneo/Platform/Bundle/UIBundle

Ten folder możesz znaleźć w plikach źródłowych Akeneo na Githubie.

Dalej mamy "/js/", który mówi nam, że chodzi o plik JavaScript. W pierwszej części artykułu wspominamy, że w aplikacjach opartych na Symfony pliki JavaScript znajdują się w folderze "Resources", a następnie "public", w którym zawartych jest kilka folderów:

GitHub Akeneo files 1a

pim-community-dev/tree/master/src/Akeneo/Platform/Bundle/UIBundle/Resources/public

Chodzi nam o plik JavaScript, więc wybieramy folder "js". 

Zapamiętaj! Wszystkie pliki TypeScript, JavaScript czy komponenty napisane w React gromadzimy właśnie w folderze "js". Jeśli w przyszłości planujesz np. dodać style CSS, możesz stworzyć w tym miejscu folder "Style".

Znamy już dość spory kawałek ścieżki:

pim-community-dev/tree/master/src/Akeneo/Platform/Bundle/UIBundle/Resources/public/js

Patrząc na ścieżkę z RequireJS, kolejnym elementem jest "form/form-modal".

Powinniśmy więc znaleźć folder "form", gdzie będą zamieszczone różne pliki związane z formularzami:

pim-community-dev/tree/master/src/Akeneo/Platform/Bundle/UIBundle/Resources/public/js/form

W folderze "form" ostatecznie trafiamy na plik "form-modal.js":

GitHub Akeneo files 2

Skoro zgromadziliśmy już najważniejsze informacje na temat tego, jak stworzyć nowego bundla, a także jak znaleźć moduły w plikach źródłowych Akeneo, jesteśmy gotowi zająć się konkretnym zadaniem. Na pierwszy ogień bierzemy nadpisywanie modułu zbudowanego za pomocą RequireJS.