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:
- Akeneo PIM UI – Kompletny przewodnik dla Frontend Developerów
- Co powinieneś wiedzieć o strukturze modułów w Akeneo PIM opartych o RequireJS?
- Jak nadpisać moduł oparty o RequireJS?
- Jak rozszerzyć istniejące moduły oparte o RequireJS?
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:
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":
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"
Sam plik ma bardzo prostą budowę:
<?php namespace Macopedia\Product\Infrastructure\Symfony;
use Symfony\Component\HttpKernel\Bundle\Bundle;
class MacopediaProductBundle extends Bundle
{
}?>Kolejnym krokiem będzie zarejestrowanie naszego bundla w konfiguracji Symfony. Szukamy pliku "config/bundles.php" i załączamy stworzony przez nas bundle:
<?php return [
\Macopedia\Product\Infrastructure\Symfony\MacopediaProductBundle::class => ['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:
Do tego należy też przygotować "config", a w nim plik "requirejs.yml". W folderze "config" będą dodawane przez RequireJS pliki JavaScript:
Jak wiemy z poprzednich rozdziałów, tak rejestrujemy moduł dla RequireJS:
config:
paths:
file-key: macopediaproduct/js/product/fileTo 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:
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-modalLink do pliku:
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:
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":
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.