230 lines
9.9 KiB
Markdown
230 lines
9.9 KiB
Markdown
# AdminThemeUikit
|
||
|
||
This document currently covers customization of Uikit styles and instructions on
|
||
how to upgrade the core Uikit version.
|
||
|
||
## Customization
|
||
|
||
### Short version
|
||
|
||
You can easily customize AdminThemeUikit in 3 simple steps:
|
||
|
||
1. Install the ProcessWire [Less](https://processwire.com/modules/less/) module.
|
||
2. Specify the “reno” or “rock” base style in `/site/config.php`.
|
||
3. Create and edit `/site/templates/admin.less` and see your changes in the admin.
|
||
|
||
Either step 2 or 3 can be optional too, more details below.
|
||
|
||
---
|
||
|
||
### Long version
|
||
|
||
Now that you know what to do, let’s run through 3 steps above again, but with more details:
|
||
|
||
#### 1. Install the “Less” module
|
||
|
||
Download and install the “Less” module from <https://processwire.com/modules/less/>.
|
||
This module is required to compile customizations to AdminThemeUikit. If this module is
|
||
not installed then all of the capabilities described here will not be available.
|
||
|
||
#### 2. Choose a base style
|
||
|
||
To proceed, edit the `/site/config.php` file and specify what base style you want to start
|
||
from. Currently you can specify either “reno” or “rock”, like in the example below:
|
||
```php
|
||
$config->AdminThemeUikit('style', 'rock');
|
||
```
|
||
Below are descriptions of both base styles:
|
||
|
||
- **Reno:** The “reno” base style is the default that you see when using AdminThemeUikit.
|
||
It is named after Tom Reno (aka Renobird) creator of the AdminThemeReno module. The reno
|
||
style of AdminThemeUikit attempts to retain much of the color scheme of Tom’s original theme.
|
||
If you choose to use this style, you can optionally skip step #2 since reno is the default.
|
||
|
||
- **Rock:** The “rock” base style is designed to use the default UIkit UI as much as possible
|
||
and have only one single primary color that can easily be changed without destroying the
|
||
overall look and feel. This makes it easy to customize for your client’s color scheme. It is
|
||
named after Bernhard Baumrock who is the creator of this style and the system that
|
||
enables you to customize AdminThemeUikit in ProcessWire. Because this style is largely
|
||
stock Uikit, it is intended as a base to build from for your own custom admin style. While
|
||
it looks quite nice in its stock form, you should also think of it as your blank canvas.
|
||
|
||
*If you selected the “rock” style and want to see what it looks like before moving to the
|
||
next step, simply reload/refresh the ProcessWire admin in your web browser and it should
|
||
compile and use it.*
|
||
|
||
#### 3. Create and edit an admin.less file
|
||
|
||
Create a new LESS file named `/site/templates/admin.less` for your customizations and add
|
||
a style or two just to test things out. For example:
|
||
```less
|
||
div { border: 1px solid red; }
|
||
```
|
||
Save the LESS file and the admin theme will automatically recompile and include your
|
||
change(s). Click reload/refresh in your web browser to start the recompile and see the
|
||
changes.
|
||
|
||
- Whether using “reno” or “rock”, you can modify any LESS variable from UIkit or the base
|
||
style, including all UIkit variables like `@global-font-family` or `@global-margin`, and
|
||
so on… there are hundreds of variables available to you. See the LESS variables reference
|
||
later in this document.
|
||
|
||
- If you are using the “rock” base style, you can set the primary color like this:
|
||
`@rock-primary: blue;`
|
||
|
||
- If there is a compile error, you will see it in an admin error notification. In that case,
|
||
correct the error in your admin.less file, save and refresh again.
|
||
|
||
- Note that the default compiled CSS file is: `/site/assets/admin.css`. Do not make changes
|
||
to this css file directly as ProcessWire may periodically recompile it during version
|
||
upgrades and such.
|
||
|
||
#### Additional notes
|
||
|
||
- ProcessWire monitors the timestamps of your custom .less file and the resulting .css file.
|
||
If your .less file is newer than the .css file, it will automatically recompile.
|
||
|
||
- ProcessWire also monitors for changes to your `$config->AdminThemeUikit` settings. If any
|
||
of those settings change, it will automatically recompile.
|
||
|
||
- If you are using `@import` statements in your .less file, ProcessWire does not monitor the
|
||
times of files that are imported. In this case, to trigger a recompile, you should either
|
||
make some minor change to your admin.less file so the timestamp is updated, or you should
|
||
use the `recompile` config setting described in the next section.
|
||
|
||
#### LESS variables reference
|
||
|
||
- [Rock style](https://github.com/processwire/processwire/blob/dev/wire/modules/AdminTheme/AdminThemeUikit/uikit-pw/styles/rock.less)
|
||
- [Reno style](https://github.com/processwire/processwire/blob/dev/wire/modules/AdminTheme/AdminThemeUikit/uikit-pw/styles/reno.less)
|
||
- [Uikit base](https://github.com/uikit/uikit/blob/develop/src/less/components/base.less)
|
||
- [Uikit components](https://github.com/uikit/uikit/tree/develop/src/less/components)
|
||
|
||
#### Further reading
|
||
|
||
See the README in AdminStyleRock which has additional topics of interest related to
|
||
customizing AdminThemeUikit: <https://github.com/baumrock/AdminStyleRock>
|
||
|
||
---
|
||
|
||
### AdminThemeUikit $config settings
|
||
|
||
The `$config->AdminThemeUikit` array has various settings you can customize in your
|
||
`/site/config.php` file. Below is an example of all settings with their default values:
|
||
|
||
```php
|
||
$config->AdminThemeUikit = [
|
||
'style' => '',
|
||
'recompile' => false,
|
||
'compress' => true,
|
||
'customCssFile' => '/site/assets/admin.css',
|
||
'customLessFiles' => [ '/site/templates/admin.less' ],
|
||
];
|
||
```
|
||
When modifying a setting from your `/site/config.php` file, you can specify one or
|
||
more of them in a PHP array like above, or you can specify any individually
|
||
using a method call like in the example below. Use whatever definition style you prefer.
|
||
```php
|
||
$config->AdminThemeUikit('style', 'rock');
|
||
$config->AdminThemeUikit('compress', false);
|
||
```
|
||
### Description of all settings
|
||
|
||
#### `style` (string)
|
||
|
||
Admin theme base style: `reno`, `rock`, or blank for system default.
|
||
The default value is blank. When blank, ProcessWire uses the current system default,
|
||
which is presently “reno”.
|
||
|
||
**Advanced option:** you may also specify a .less filename relative to the ProcessWire
|
||
installation root. However, if you are looking to start a theme from scratch, the
|
||
the “rock” style combined with your own `/site/templates/admin.less` may be what you
|
||
really want.
|
||
|
||
#### `recompile` (boolean)
|
||
|
||
This is a runtime-only setting that when set to `true` forces the recompile of the
|
||
admin theme. When necessary, set this to true for one request, then set it back
|
||
to false, otherwise it will recompile the admin theme on every admin page load
|
||
(maybe that’s what you want in some cases too). But in most cases you should not
|
||
need this setting as ProcessWire already monitors your admin.less file for changes.
|
||
|
||
#### `compress` (boolean)
|
||
|
||
When true, compiled CSS will be compressed or minified so that it consumes less
|
||
bandwidth. The default value is `true`. You might choose to set this to false when
|
||
doing custom admin style development and debugging. Otherwise you should leave this
|
||
at the default value, which is true.
|
||
|
||
#### `customCssFile` (string)
|
||
|
||
The target custom .css file to compile custom .less file(s) into. The default value is
|
||
`/site/assets/admin.css`. If you modify this value, it must be in a location that
|
||
ProcessWire can write to. Within `/site/assets/` is the only directory that is known
|
||
writable to all ProcessWire installations, though individual installations may vary.
|
||
|
||
#### `customLessFiles` (array)
|
||
|
||
These are the custom .less files that you want to be compiled. The default value is
|
||
one file: `/site/templates/admin.less`. The given file(s) must be relative to the
|
||
ProcessWire installation root directory.
|
||
|
||
#### Note for `customCssFile` and `customLessFiles`
|
||
|
||
Chances are you won’t ever need to change these settings, but just in case you do,
|
||
please make note of the following. Your values for these settings should literally
|
||
begin with one of the following paths below. Meaning, the literal words, regardless
|
||
of your actual `/site/` directory name (if you happen to be using something different).
|
||
|
||
- `/site/assets/`
|
||
- `/site/templates/`
|
||
- `/site/modules/`
|
||
|
||
This is because the paths above are automatically converted to their actual values at
|
||
runtime. This ensures the same value works everywhere (development, production, staging,
|
||
etc.) and regardless of whether the site is running from a subdirectory or not.
|
||
|
||
Should you choose to use a different location, that’s also okay, but just note that
|
||
ProcessWire will not perform any runtime conversion on it.
|
||
|
||
|
||
---
|
||
|
||
## Upgrading the core Uikit version
|
||
|
||
*This section is likely only of interest to core or admin theme developers.*
|
||
|
||
1. Download a fresh copy of Uikit from GitHub:
|
||
<https://github.com/uikit/uikit/archive/refs/heads/develop.zip>
|
||
|
||
2. For this step choose either option A or B below, depending on what is simpler for you,
|
||
likely option A:
|
||
|
||
**Option A:** Replace the `/src/` and `/dist/` directories from the old Uikit
|
||
installation in `AdminThemeUikit/uikit/` with those directories from the new installation.
|
||
Then you may remove these unnecessary directories from it:
|
||
|
||
- `src/scss/`
|
||
- `src/js/`
|
||
|
||
**Option B:** Replace the `uikit/` directory with the new one, and then remove unnecessary
|
||
files and directories in the new `uikit/` directory, including:
|
||
|
||
- `build/`
|
||
- `tests/`
|
||
- `src/scss/`
|
||
- `src/js/`
|
||
- `*.json`
|
||
- `*.lock`
|
||
- `.*` (all hidden files)
|
||
|
||
3. Edit the `AdminThemeUikit::upgrade` constant and set it to `true` temporarily.
|
||
|
||
4. Increment the `AdminThemeUikit::requireCssVersion` constant by 1. This will ensure that
|
||
custom /site/assets/admin.css files will also be recompiled on individual installations.
|
||
If you don’t want that to happen then skip this step.
|
||
|
||
5. In your browser, reload any page in the admin and it will generate a new
|
||
`pw.min.css` file in the correct location, overwriting the old one.
|
||
|
||
6. Set the `AdminThemeUikit::upgrade` constant back to false. Changes can now be committed.
|
||
|