This blog highlights the development process involved in building the first task of my GSoC project. The first task aims to enhance the flow of creating and placing modules in a menu.
Unlike the other projects, Core Enhancements strives to dive deep into the codebase and requires the developer to understand the working of existing Joomla! Core as a whole in order to enhance it. This was a challenging but interesting part that helped me develop the habit of comprehending the lines of code authored by previous developers and it was especially inspiring as this helped me learn more about the coding standards and think like an experienced Joomla contributor.
Placing Modules in Menu
The Pull Request for testing this feature can be found here: https://github.com/joomla/joomla-cms/pull/34743
The rudimentary step in planning a task is to research and find any scope for improvement. I focused my research on blogs and articles by the Joomla community to understand where the users need a UX upgrade and which parts are confusing. After referring to several forum posts and user discussions,
Based on my research, I found scope for improvement in the following:
- Reduce the number of times the user has to switch between the backend and frontend to see the positions.
- There is no direct way for the website admin to know where the module will be placed and how it will look. Ie. A preview is missing.
- Provision to directly add modules via frontend. This flow will be similar to the add modules button in the Backend that opens the add module modal.
- While Placing modules via Backend, a preview of the position is missing. This is especially needed for templates where the position names are not very intuitive.
Place Modules via Frontend
This task re-invents the conventional method of placing modules from the Backend Dashboard to an easier to visualize series of steps where the users can visit a particular page in the Frontend (while logged in to an admin account), and from there, they can select the menu (automatically determined based on the page) and position of the Module by means of buttons that reflect the output of where the module will be placed if the user proceeds to create it.
The Process of Placing Modules via Frontend is as follows:
- Enable Frontend Module Placement Plugin
- Visit Frontend and log in as Administrator (or any role that has permissions to create and edit Modules)
- You will find an 'Add Module' button. Click on this, and it will append ?pm=1 to the URL (i.e. Switch to the place modules view)
4. In the Place Modules view, you will be shown all positions and a Button: 'Add Module here' in each of these positions. This will give the user a preview of where each position points to.
5. On selecting any of the place modules buttons, the user is sent to the administrator dashboard where the user can select a module type.
6. Next, he reaches the Module's form page where the Position and Menu Assignment will be pre-filled, and the user can add a Title/Note, etc., and submit to save the module.
7. And now the module is successfully placed.
A video for the same can be found here: https://youtu.be/kToRkxx1G54
The actors behind this flow are:
- New Plugin
- Introduce a new system plugin plg_system_addmodulebutton for displaying the Add Module Button
- This button is present at the top of the <main> tag and looks similar to the frontend editing button.
- This button is only displayed when a user logs into the frontend using an account with Module Add/Edit Permissions.
- Pressing this button adds ?pm=1 as a GET parameter in the URL. This is similar to the ?tp=1 parameter that is used for displaying template positions.
- Place Module (?pm=1) View
- This view displays the current page will all possible template positions
- Each position will have a button corresponding to it. Users can use this button to select this position for placing the new module.
- These buttons (to select position) redirect the user to a backend page having a URL like administrator/index.php?option=com_modules&task=module.selectPosition&position=footer&menu=[id] . This URL has 3 parts:
- task=module.selectPosition is used to call the selectPosition Controller in com_modules/module
- &position=footer is used to pass the position as a GET param
- &menu=[id] is used to pass the menu id of the current page as a GET param where [id] is the menu id which would be an integer eg: &menu=101
- New Controller: /com_modules/Module/selectPosition
- Saves the Position and Menu ID, which is passed as a GET param in URL by the previous step in the User State,
- Redirects to Module Select View where user can select the Module Type
- After the Module Type has been chosen, these state items (Position and Menu ID) is used to pre-fill the Position Name and Menu ID
Preview Module Positions in Backend:
Editing Modules in the Backend Admin Panel turned out to be a little tricky for the user if the template positions were not easy to visualize or if the User was unaware of the layout of the template positions.
The old way for a user to get around this difficulty was:
- Visit the Add/Edit Site Modules Page
- Realize that you do not know the desired position name
- Visit the Global Configuration for Templates
- Enable Template Positions
- Visit Frontend
- Append ?tp=1 as a param in the Page's URL (Might not be easy for users who do not have a technical background)
- Remember the position name (Note: This view only shows active positions, so they cannot even know where inactive positions are. Inactive means those positions that do not have a module to show in it)
- Go back to the Admin Dashboard and select this position.
- Save the module
To simplify all this into a more effortless and efficient method, a new modal has been added to select the positions via their preview.
The Process is as follows:
- Visit the Add/Edit Site Modules Page
- In the Module form, you will see a button below the 'Position' dropdown. This button will show the frontend page with all positions in a Modal. Users can now select any position from the preview, and it will update the dropdown’s selection. This solves the issue of not knowing where each position place on the Frontend.
- Fill the remaining form.
- Save and Close
A video demonstrating the above can be found here: https://youtu.be/8tL9L1PSSMI
We were able to meet the planned deliverables for this task. Special thanks to my mentors: Christiane Maier-Stadtherr, Benjamin Trenkle, Niels Braczek, and special thanks to Richard Fath for their tremendously valuable guidance that massively helped me in accelerating the development process. With their mentorship, I was successful in completing the first iteration of this task by the 23rd of June, 2021.
As of today (17th of August, 2021), this PR is already in its testing phase, and I hope to see this feature in Joomla! Soon!