doc/themes.rst

   1 .. _themes:
   2
   3 Custom Themes
   4 =============
   5
   6 phpMyAdmin comes with support for third party themes. You can download
   7 additional themes from our website at <https://www.phpmyadmin.net/themes/>.
   8
   9 Configuration
  10 -------------
  11
  12 Themes are configured with :config:option:`$cfg['ThemeManager']` and
  13 :config:option:`$cfg['ThemeDefault']`.  Under :file:`./public/themes/`, you should not
  14 delete the directory ``pmahomme`` or its underlying structure, because this is
  15 the system theme used by phpMyAdmin. ``pmahomme`` contains all images and
  16 styles, for backwards compatibility and for all themes that would not include
  17 images or css-files.  If :config:option:`$cfg['ThemeManager']` is enabled, you
  18 can select your favorite theme on the main page. Your selected theme will be
  19 stored in a cookie.
  20
  21 Creating custom theme
  22 ---------------------
  23
  24 To create a theme:
  25
  26 * make a new subdirectory (for example "your\_theme\_name") under :file:`./public/themes/`.
  27 * copy the files and directories from ``pmahomme`` to "your\_theme\_name"
  28 * edit the css-files in "your\_theme\_name/css"
  29 * put your new images in "your\_theme\_name/img"
  30 * edit :file:`_variables.scss` in "your\_theme\_name/scss"
  31 * edit :file:`theme.json` in "your\_theme\_name" to contain theme metadata (see below)
  32 * make a new screenshot of your theme and save it under
  33   "your\_theme\_name/screen.png"
  34
  35 Theme metadata
  36 ++++++++++++++
  37
  38 .. versionchanged:: 4.8.0
  39
  40     Before 4.8.0 the theme metadata was passed in the :file:`info.inc.php` file.
  41     It has been replaced by :file:`theme.json` to allow easier parsing (without
  42     need to handle PHP code) and to support additional features.
  43
  44 In theme directory there is file :file:`theme.json` which contains theme
  45 metadata. Currently it consists of:
  46
  47 .. describe:: name
  48
  49     Display name of the theme.
  50
  51     **This field is required.**
  52
  53 .. describe:: version
  54
  55     Theme version, can be quite arbitrary and does not have to match phpMyAdmin version.
  56
  57     **This field is required.**
  58
  59 .. describe:: description
  60
  61     Theme description. this will be shown on the website.
  62
  63     **This field is required.**
  64
  65 .. describe:: author
  66
  67     Theme author name.
  68
  69     **This field is required.**
  70
  71 .. describe:: url
  72
  73     Link to theme author website. It's good idea to have way for getting
  74     support there.
  75
  76 .. describe:: supports
  77
  78     Array of supported phpMyAdmin major versions.
  79
  80     **This field is required.**
  81
  82 For example, the definition for Original theme shipped with phpMyAdmin 4.8:
  83
  84 .. code-block:: json
  85
  86     {
  87         "name": "Original",
  88         "version": "4.8",
  89         "description": "Original phpMyAdmin theme",
  90         "author": "phpMyAdmin developers",
  91         "url": "https://www.phpmyadmin.net/",
  92         "supports": ["4.8"]
  93     }
  94
  95 Sharing images
  96 ++++++++++++++
  97
  98 If you do not want to use your own symbols and buttons, remove the
  99 directory "img" in "your\_theme\_name". phpMyAdmin will use the
 100 default icons and buttons (from the system-theme ``pmahomme``).