Modification of existing functionalities and creating new ones is often a complex issue. In order to better understand the topic, you should start by becoming familiar with a few general technical aspects which will make your work easier and minimize the risk of potential problems.
Are you not sure how to create new bundles in Symfony, how to create or override JS modules? How to find modules in Akeneo source files? What are the basic commands to rebuild the frontend in versions 4.0/5.0? What commands do you need to run a default webpack watcher? We’re giving you some hints!
My blog post series provides some context and explanation of the principles used to build UI in the PIM. Check the other articles:
- Akeneo PIM UI – Complete Guide for Frontend Developers
- What should you know about the structure of RequireJS modules in Akeneo PIM?
- How to override a RequireJS module?
- How to extend existing modules based on RequireJS?
- How to share information between frontend components in Akeneo PIM with mediator pattern?
- How to use custom labels in Akeneo UI, translate components, or replace default strings?
- What is UserContext in Akeneo PIM & How to access and modify user properties from JavaScript?
How do you create a new bundle with a JS module?
Before you start your work, installing Akeneo PIM is necessary. We won’t discuss the installation process itself as there are various ways and specific steps need to be followed (depending on the chosen method). You should have a look at the documentation.
We assume that Akeneo has been installed. You can see the following file structure in the main folder:
All the adjustments will be made in the "src" folder. With the practices we’ve adopted, the changes will be stored in a folder called "Macopedia", the name coming from our company name (or sometimes from the name of a project).
Now, we will create a new bundle for a given set of functionalities. Let’s call it "Product". As the name indicates, it will contain changes related to products. It also helps us divide modules with regard to their role. The "Product" folder is set up in "Macopedia":
We have to add the ".php" file following the Symfony convention. We call it "MacopediaProductBundle". Pay attention to the fact that the file ends with "Bundle". It is vital for Symfony to identify it.
Put this file in the following path:
"src/Macopedia/Product/Infrastructure/Symfony/MacopediaProductBundle.php"
The file itself has a very simple structure:
<?php namespace Macopedia\Product\Infrastructure\Symfony;
use Symfony\Component\HttpKernel\Bundle\Bundle;
class MacopediaProductBundle extends Bundle
{
}?>The next step is to register our bundle in the Symfony configuration. We are searching for "config/bundles.php" and adding an entry for the newly created bundle:
<?php return [
\Macopedia\Product\Infrastructure\Symfony\MacopediaProductBundle::class => ['all' => true],
];?>After all these steps, we can delete the cache "rm -rf var/cache" and run the "composer install" command.
Right now we should be able to work on our bundle. More information on adding bundles can be found in the Symfony documentation.
Where do you put new files responsible for the frontend?
You've already found out that all of the overridden and created files are gathered in "src". Knowing that and having the information from the previous blog post, it’s high time to explain what the exact structure of a bundle should be so that it is possible to place JavaScript files in it.
We need to prepare an extra catalogue "Resources" in "Symfony", the next catalogue "public" inside it and then the "js" folder. Remember to act in accordance with the Symfony documentation:
You should also prepare "config", and then "requirejs.yml". JavaScript files will be added to "config" by RequireJS:
As we know from previous chapters, this is how we register a module for RequireJS:
config:
paths:
file-key: macopediaproduct/js/product/fileThis is an example of adding the file "file.js" which will be accessible by "file-key".
Basic commands necessary to rebuild the frontend
Changes in .yml files (as above) require rebuilding of the frontend using the "make front" command (Akeneo 4.0), and from version 5.0 – "make upgrade-front". While running the command to rebuild the frontend layer, you have to turn off a watcher and turn it on again after completing the process.
The default webpack watcher monitoring changes in Akeneo projects is started by the "yarn run webpack-dev --watch" command.
How do you find the module you are looking for?
In order to modify the existing Akeneo functionality, you have to override the original JS module with your own. To do that you must first find an original file in source files of Akeneo and check how it is registered in RequireJS.
The Akeneo source files are located here:
Now, we will discuss step by step how to find a file by the RequireJS key. It will be very useful in the next post where we will present the process of overriding the module. Therefore, let’s imagine that we want to find a file which is accessible by the "pim/form-modal" key.
We can see the following line in the main file of RequireJS located in the Akeneo source files:
pim/form-modal: pimui/js/form/form-modalThe link to the file:
The path given is "pimui/js/form/form-modal", however when trying to find the file with exactly that path, you will find out that it doesn’t exist. This is because it is not the exact path to the file as it contains aliases. Let’s then try to break down the path and find the proper module.
The first part "pimui" refers to the path below and it comes from the name of the Symfony bundle:
pim-community-dev/src/Akeneo/Platform/Bundle/UIBundle
This folder can be found in the Akeneo source files on Github.
Further you can see "/js/" which tells us that it is about JavaScript. In the first part of the article we mentioned that in applications based on Symfony, JavaScript files are placed in "Resources" and next in "public" which includes several folders:
pim-community-dev/tree/master/src/Akeneo/Platform/Bundle/UIBundle/Resources/public
We're talking about the JavaScript file, so we’re going to choose the "js" folder.
Remember! All TypeScript and JavaScript files or components written in React should be placed in the "js" folder. If you’re planning e.g. to add CSS style in the future, you can create the "Style" folder here.
We already know quite a big part of the path:
pim-community-dev/tree/master/src/Akeneo/Platform/Bundle/UIBundle/Resources/public/js
Looking at the path with RequireJS, the next element is "form/form-modal".
We should then find the "form" folder where various files related to the forms will be placed:
pim-community-dev/tree/master/src/Akeneo/Platform/Bundle/UIBundle/Resources/public/js/form
Finally we come across the "form-modal.js" file in the "form" folder:
As we’ve already collected the most significant information on how to create a new bundle and find modules in the Akeneo source files, we’re ready to take up a specific task. Overriding a RequireJS module will be discussed in the next blog post.