Build tools for PMA v5

[adorade]

@williamdes
Thanks for giving my BooDark theme as an example. In the following days I will update the theme, something minor, and I will also update the build tools. My theme is based on the Bootstrap theme, not pmahomme. Supports PMA v5.2 with Bootstrap v5.2.3.

Helpful for those who want to build a new theme, continued from #104

Keep in touch! 💪

[adorade]

Folder Structure

YourTheme theme must respect the folders structure of phpMyAdmin.

├── node_modules
├── themes
│   └── YourTheme
│       ├── css/
│       ├── img/
│       ├── jquery/
│       ├── scss/
│       ├── screen.png
│       └── theme.json
├── package.json
└── yarn.lock

Dependecies

pma-theme-build-tools.zip

All deps are updated to the latest version.
WARNING

• phpMyAdmin 5.2.1 use Bootstrap v5.2.3 - DO NOT UPDATE to v5.3.2 (latest)
• to avoid sass depreciation warnings - DO NOT UPDATE sass package

Building

To build the theme you must have Node, Yarn and Git installed.
Then follow step by step:

1. Open your command-line and navigate to your theme folder
2. Copy the jquery, img and scss folders from the Bootstrap theme (or pmahomme)
3. Update package.json, theme.json and screen.png with your info
4. Install project dependecies: yarn install
5. Do any modifications you want
6. Compile scss files to css

# production, minified files
yarn run build
# development
yarn run build:dev

7. Theme files are in themes/YourTheme.

Publish theme

Follow instructions: https://github.com/phpmyadmin/themes#updatingcreating-themes

[williamdes]

Hello @adorade
Would you mind opening a PR to update our README?
Setting your above recommendations as a baseline for new themes?

[adorade]

Hi @williamdes
I will try in this weekend. Keep in touch!

[adorade]

I have some questions to ask before I create a new pull request. This will help me understand some details better.

PMA v5.2.1 relies on npm scripts to build the assets, while I employ webpack in my theme, similar to PMA v6.0.0-dev version. Do I need to create a .webpack folder with configurations for production and development mode?

I will check the compatibility of the latest versions of dependencies, especially sass. Do you want me to add a package-example.json file?

I plan to include a new section called How to build a theme in the README file, right before the Releasing section. Which option do you think is better: creating a separate file named HOW-TO-BUILD-A-THEME.md and linking it, or writing all the instructions in the new section?

I would appreciate any advice or recommendation.

[ibennetch]

@adorade Thanks! That would be very helpful.

We have a bit of duplicated documentation (in https://github.com/phpmyadmin/themes#updatingcreating-themes and https://github.com/phpmyadmin/phpmyadmin/blob/master/docs/themes.rst#creating-custom-theme) and I am a big fan of reducing duplication so we only have one true source. I'd personally prefer to have that in the themes repository, and then I can write a small paragraph in the "phpmyadmin" repository linking to that.

So to answer your question, my personal preference is to make a new file in the themes repository, and it doesn't need to be all capital letters so I think "Creating-a-theme.md" would be a great filename.

[adorade]

Having duplicate documentation can occasionally cause confusion, particularly if one of the sources is not up-to-date. I believe that all details pertaining to the creation of a PMA theme ought to be consolidated within the README.md file located at "phpmyadmin/themes", which is the true source.

A preferable approach would be to add new sections containing all the essential information about:

1. Build tools

This section covers build tools (webpack configuration), dependencies, and the organization of the folder structure.

2. Theme configuration

Instructions on how to configure a theme using package.json, theme.json, screen.png, and README.md (the latter provides optional information about the theme).

3. How to create a theme

Guidance on creating theme.scss and utilizing build tools for both development and production environments.

4. Testing Procedures

Currently, the sole method to test a theme is by navigating through the PMA interface. One must click on every link and button to ensure no elements have been overlooked.
It may be beneficial to develop a cheatsheet for this purpose: phpmyadmin/phpmyadmin#17487

5. How to upload

How to upload it to the "phpmyadmin/themes" repository.

6. Releasing

Releasing the new theme.

The step-by-step process described above should be simple for the theme developer, whether a novice or an expert, as well as for the one who reviews and tests the theme.
A folder named _pma-theme-build-tools should be created within this repository, containing only the essential settings required as a foundation. This folder, like any theme, will be available for download.

pma-theme-build-tools.zip