Build tools for PMA v5
Opened this issue ยท 6 comments
@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! ๐ช
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
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:
- Open your command-line and navigate to your theme folder
- Copy the
jquery
,img
andscss
folders from the Bootstrap theme (or pmahomme) - Update
package.json
,theme.json
andscreen.png
with your info - Install project dependecies:
yarn install
- Do any modifications you want
- Compile
scss
files tocss
# production, minified files
yarn run build
# development
yarn run build:dev
- Theme files are in
themes/YourTheme
.
Publish theme
Follow instructions: https://github.com/phpmyadmin/themes#updatingcreating-themes
Hello @adorade
Would you mind opening a PR to update our README?
Setting your above recommendations as a baseline for new themes?
Hi @williamdes
I will try in this weekend. Keep in touch!
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.
@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.
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.