231 lines
9.9 KiB
Markdown
231 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.
|
|||
|
|