doc/themes.rst

   1 .. _themes:
   2
   3 Custom Themes
   4 =============
   5
   6 phpMyAdmin comes with support for third party themes. You can download
   7 additonal 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:`./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:`./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:`layout.inc.php` in "your\_theme\_name"
  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
  45 In theme directory there is file :file:`theme.json` which contains theme
  46 metadata. Currently it consists of:
  47
  48 .. describe:: name
  49
  50     Display name of the theme.
  51
  52     **This field is required.**
  53
  54 .. describe:: version
  55
  56     Theme version, can be quite arbirary and does not have to match phpMyAdmin version.
  57
  58     **This field is required.**
  59
  60 .. describe:: desciption
  61
  62     Theme description. this will be shown on the website.
  63
  64     **This field is required.**
  65
  66 .. describe:: author
  67
  68     Theme author name.
  69
  70     **This field is required.**
  71
  72 .. describe:: url
  73
  74     Link to theme author website. It's good idea to have way for getting
  75     support there.
  76
  77 .. describe:: supports
  78
  79     Array of supported phpMyAdmin major versions.
  80
  81     **This field is required.**
  82
  83 For example, the definition for Original theme shipped with phpMyAdnin 4.8:
  84
  85 .. code-block:: json
  86
  87     {
  88         "name": "Original",
  89         "version": "4.8",
  90         "description": "Original phpMyAdmin theme",
  91         "author": "phpMyAdmin developers",
  92         "url": "https://www.phpmyadmin.net/",
  93         "supports": ["4.8"]
  94     }
  95
  96 Sharing images
  97 ++++++++++++++
  98
  99 If you do not want to use your own symbols and buttons, remove the
 100 directory "img" in "your\_theme\_name". phpMyAdmin will use the
 101 default icons and buttons (from the system-theme ``pmahomme``).