diff --git a/wire/core/AdminThemeFramework.php b/wire/core/AdminThemeFramework.php index 8e46bbc8..939b7e8a 100644 --- a/wire/core/AdminThemeFramework.php +++ b/wire/core/AdminThemeFramework.php @@ -9,7 +9,7 @@ * This file is licensed under the MIT license. * https://processwire.com/about/license/mit/ * - * ProcessWire 3.x, Copyright 2021 by Ryan Cramer + * ProcessWire 3.x, Copyright 2022 by Ryan Cramer * https://processwire.com * * @property bool $isSuperuser @@ -19,6 +19,7 @@ * @property bool|int $useAsLogin * @method array getUserNavArray() * @method array getPrimaryNavArray() + * @method string renderFile($basename, array $vars = array()) * */ abstract class AdminThemeFramework extends AdminTheme { @@ -61,6 +62,30 @@ abstract class AdminThemeFramework extends AdminTheme { */ protected $sanitizer; + /** + * Custom template path when it exists, i.e. /site/templates/AdminThemeUikit/ + * + * @var string|null Null when not yet known, blank '' when it does not exist, populated when it exists + * + */ + protected $customTemplatePath = null; + + /** + * Default template path + * + * @var string|null + * + */ + protected $defaultTemplatePath = null; + + /** + * Is the renderFile() method hooked? Null when not known, bool when known + * + * @var bool|null + * + */ + protected $renderFileHooked = null; + /** * Construct * @@ -766,6 +791,88 @@ abstract class AdminThemeFramework extends AdminTheme { if(empty($extras)) $extras = $this->getExtraMarkup(); return isset($extras[$for]) ? $extras[$for] : ''; } + + /** + * Render a admin theme template file + * + * This method is only used if it is hooked + * + * #pw-hooker + * + * @param string $file Full path and filename + * @param array $vars Associative array of variables to populate in rendered file + * @return string Returns blank string when $echo is true + * @since 3.0.196 + * + */ + protected function ___renderFile($file, array $vars = array()) { + extract($vars); + ob_start(); + include($file); + $out = ob_get_contents(); + ob_end_clean(); + return $out; + } + + /** + * Include an admin theme file + * + * @param string $basename + * @param array $vars + * @since 3.0.196 + * + */ + public function includeFile($basename, array $vars = array()) { + + $file = ''; + + if($this->renderFileHooked === null) { + $this->renderFileHooked = $this->hasHook('renderFile()'); + } + + if($this->defaultTemplatePath === null) { + $this->defaultTemplatePath = $this->wire()->config->paths($this); + } + + if($this->customTemplatePath === null) { + $path = $this->wire()->config->paths->templates . $this->className() . '/'; + $this->customTemplatePath = is_dir($path) ? $path : ''; + } + + if($this->customTemplatePath) { + $file = $this->customTemplatePath . $basename; + if(file_exists($file)) $this->warning($file); + if(!file_exists($file)) $file = ''; + } + + if($file === '') $file = $this->defaultTemplatePath . $basename; + + $fuel = $this->wire()->fuel; + $vars['fuel'] = $fuel; + $vars = array_merge($fuel->getArray(), $vars); + unset($vars['file'], $vars['vars']); // just in case either was set + + if($this->renderFileHooked) { + echo $this->renderFile($file, $vars); + } else { + extract($vars); + include($file); + } + } + + /** + * Set custom path for admin theme templates + * + * This is for modules to optionally set a custom template path. If not set then the default + * in /site/templates/AdminTheme[Class]/ is used. + * + * @param string $path + * @since 3.0.196 + * + */ + public function setCustomTemplatePath($path) { + $this->customTemplatePath = $path; + } /** * Module Configuration diff --git a/wire/modules/AdminTheme/AdminThemeUikit/README.md b/wire/modules/AdminTheme/AdminThemeUikit/README.md index 4bea9304..b3b1cc0b 100755 --- a/wire/modules/AdminTheme/AdminThemeUikit/README.md +++ b/wire/modules/AdminTheme/AdminThemeUikit/README.md @@ -1,11 +1,96 @@ # AdminThemeUikit -This document currently covers customization of Uikit styles and instructions on -how to upgrade the core Uikit version. +This document currently covers customization of the Uikit styles, overriding admin theme +template files and markup, and instructions on how to upgrade the core Uikit version. -## Customization +## Customizing Markup -### Short version +### Overriding markup files + +You can overwrite any of the markup files located in `wire/modules/AdminTheme/AdminThemeUikit/` +by placing a file with the same name in `/site/templates/AdminThemeUikit/`. You could for example +overwrite the footer by adding the file `/site/templates/AdminThemeUikit/_footer.php` to your +installation: + +```html +
My custom footer
+``` + +The files you can replace include: + + - `_head.php*` - Document ``. + - `_masthead.php` - Masthead and primary navigation. + - `_search-form.php` - Search form that appears in the masthead. + - `_content.php` - Main content area. + - `_content-head.php` - Main content header, including breadcrumbs, headline, etc. + - `_content-body.php` - Main content body where most output goes. + - `_footer.php` - Footer area. + - `_offcanvas.php` - Offcanvas navigation bar. + - `_body-scripts.php` - Scripts that appear before ``. + - `_main.php` - The main markup file that includes all the others above. + +For example, let's say you wanted to replace the main content `#pw-content-body` +with "Hello World", add file `/site/templates/AdminThemeUikit/_content-body.php` +and place the following in it: + +```html +

Hello World

+``` + +This replaces all the content of every admin page with your Hello World message. That's not +very useful so let's instead copy the contents of the default `_content-body.php` and use +that as our starting point, and append our Hello World message within it: + +```php + +
+ get('body') . $content; ?> +

Hello World

+
+``` + +### Customizing markup with hooks + +You can hook into rendering of the admin theme partials: + +```php +$wire->addHookAfter('AdminThemeUikit::renderFile', function($event) { + $file = $event->arguments(0); // full path/file being rendered + $vars = $event->arguments(1); // assoc array of vars sent to file + if(basename($file) === '_footer.php') { + $event->return = str_replace( + "ProcessWire", + "ProcessWire is the best CMS", + $event->return + ); + } +}); +``` + +### Additional recognized extra markup regions + +You can use `$adminTheme->addExtraMarkup($name, $value)` to add additional markup to +several recognized regions. + +```php +$adminTheme->addExtraMarkup("head", ""); +``` + +The `$value` can be any additional markup that you want to insert and the `$name` can be +any of the following (in order of appearance): + +- `head` - Inserted before ``. +- `masthead` - Inserted at the end of `div#pw-mastheads`. +- `notices` - Inserted after notifications `ul#notices`. +- `content` - Inserted at end of `div#pw-content-body`. +- `footer` - Inserted at end of `footer#pw-footer`. +- `body` - Inserted before ``. +--- + +## Customizing CSS + +### Summary You can easily customize AdminThemeUikit in 3 simple steps: @@ -15,9 +100,7 @@ You can easily customize AdminThemeUikit in 3 simple steps: Either step 2 or 3 can be optional too, more details below. ---- - -### Long version +### Full instructions Now that you know what to do, let’s run through 3 steps above again, but with more details: diff --git a/wire/modules/AdminTheme/AdminThemeUikit/_body-scripts.php b/wire/modules/AdminTheme/AdminThemeUikit/_body-scripts.php new file mode 100644 index 00000000..8848995a --- /dev/null +++ b/wire/modules/AdminTheme/AdminThemeUikit/_body-scripts.php @@ -0,0 +1,31 @@ + + * + */ + +if(!defined("PROCESSWIRE")) die(); + +/** @var string $layout */ +/** @var Process $process */ +/** @var WireInput $input */ + +?> + diff --git a/wire/modules/AdminTheme/AdminThemeUikit/_content-body.php b/wire/modules/AdminTheme/AdminThemeUikit/_content-body.php new file mode 100644 index 00000000..9af9b379 --- /dev/null +++ b/wire/modules/AdminTheme/AdminThemeUikit/_content-body.php @@ -0,0 +1,19 @@ + #content > #pw-content-head) + * + */ + +if(!defined("PROCESSWIRE")) die(); + +/** @var AdminThemeUikit $adminTheme */ +/** @var string $content */ +/** @var Page $page */ + +?> + +
+ get('body') . $content; ?> +
+ diff --git a/wire/modules/AdminTheme/AdminThemeUikit/_content-head.php b/wire/modules/AdminTheme/AdminThemeUikit/_content-head.php new file mode 100644 index 00000000..0d7733bc --- /dev/null +++ b/wire/modules/AdminTheme/AdminThemeUikit/_content-head.php @@ -0,0 +1,32 @@ + #content > #pw-content-head) + * + */ + +if(!defined("PROCESSWIRE")) die(); + +/** @var string $layout */ +/** @var AdminThemeUikit $adminTheme */ +/** @var string $headline */ +/** @var Page $page */ + +?> + +
+ + renderBreadcrumbs(); ?> + +
+ renderAddNewButton(); ?> +
+ + isModal) { + echo "

$headline

"; + } + ?> + +
+ diff --git a/wire/modules/AdminTheme/AdminThemeUikit/_content.php b/wire/modules/AdminTheme/AdminThemeUikit/_content.php new file mode 100644 index 00000000..0d4592ce --- /dev/null +++ b/wire/modules/AdminTheme/AdminThemeUikit/_content.php @@ -0,0 +1,26 @@ + #content) + * + */ + +if(!defined("PROCESSWIRE")) die(); + +/** @var string $layout */ +/** @var AdminThemeUikit $adminTheme */ +/** @var string $content */ +/** @var string $headline */ +/** @var Page $page */ + +?> + +
+
+ includeFile('_content-head.php', array('layout' => $layout, 'headline' => $headline)); + $adminTheme->includeFile('_content-body.php', array('content' => &$content)); + ?> +
+
+ diff --git a/wire/modules/AdminTheme/AdminThemeUikit/_footer.php b/wire/modules/AdminTheme/AdminThemeUikit/_footer.php index 908ce483..f667a73f 100644 --- a/wire/modules/AdminTheme/AdminThemeUikit/_footer.php +++ b/wire/modules/AdminTheme/AdminThemeUikit/_footer.php @@ -9,7 +9,7 @@ if(!defined("PROCESSWIRE")) die(); /** @var array $extras */ ?> - +