]> BookStack Code Mirror - bookstack/blobdiff - dev/docs/logical-theme-system.md
Add optional OIDC avatar fetching from the “picture” claim
[bookstack] / dev / docs / logical-theme-system.md
index b950d7df95cb656cc51506f4d2bdd64fab2e75e3..84bd26a5387135921c16a40b9e3c8c1f44e13621 100644 (file)
@@ -2,10 +2,14 @@
 
 BookStack allows logical customization via the theme system which enables you to add, or extend, functionality within the PHP side of the system without needing to alter the core application files.
 
-WARNING: This system is currently in alpha so may incur changes. Once we've gathered some feedback on usage we'll look to removing this warning. This system will be considered semi-stable in the future. The `Theme::` system will be kept maintained but specific customizations or deeper app/framework usage using this system will not be supported nor considered in any way stable. Customizations using this system should be checked after updates.
+This is part of the theme system alongside the [visual theme system](./visual-theme-system.md).
+
+**Note:** This system is considered semi-stable. The `Theme::` system is kept maintained but specific customizations or deeper app/framework usage using this system will not be supported nor considered in any way stable. Customizations using this system should be checked after updates.
 
 ## Getting Started
 
+*[Video Guide](https://www.youtube.com/watch?v=YVbpm_35crQ)*
+
 This makes use of the theme system. Create a folder for your theme within your BookStack `themes` directory. As an example we'll use `my_theme`, so we'd create a `themes/my_theme` folder.
 You'll need to tell BookStack to use your theme via the `APP_THEME` option in your `.env` file. For example: `APP_THEME=my_theme`.
 
@@ -50,6 +54,23 @@ This method allows you to register a custom social authentication driver within
 
 *See "Custom Socialite Service Example" below.*
 
+### `Theme::registerCommand`
+
+This method allows you to register a custom command which can then be used via the artisan console.
+
+**Arguments**
+- string $driverName
+- array $config
+- string $socialiteHandler
+
+**Example**
+
+*See "Custom Command Registration Example" below for a more detailed example.*
+
+```php
+Theme::registerCommand(new SayHelloCommand());
+```
+
 ## Available Events
 
 All available events dispatched by BookStack are exposed as static properties on the `\BookStack\Theming\ThemeEvents` class, which can be found within the file `app/Theming/ThemeEvents.php` relative to your root BookStack folder. Alternatively, the events for the latest release can be [seen on GitHub here](https://github.com/BookStackApp/BookStack/blob/release/app/Theming/ThemeEvents.php).
@@ -77,6 +98,33 @@ Theme::listen(ThemeEvents::APP_BOOT, function($app) {
 });
 ```
 
+## Custom Command Registration Example
+
+The logical theme system supports adding custom [artisan commands](https://laravel.com/docs/8.x/artisan) to BookStack.
+These can be registered in your `functions.php` file by calling `Theme::registerCommand($command)`, where `$command` is an instance of `\Symfony\Component\Console\Command\Command`. 
+
+Below is an example of registering a command that could then be ran using `php artisan bookstack:meow` on the command line.
+
+```php
+<?php
+
+use BookStack\Facades\Theme;
+use Illuminate\Console\Command;
+
+class MeowCommand extends Command
+{
+    protected $signature = 'bookstack:meow';
+    protected $description = 'Say meow on the command line';
+
+    public function handle()
+    {
+        $this->line('Meow there!');
+    }
+}
+
+Theme::registerCommand(new MeowCommand);
+```
+
 ## Custom Socialite Service Example
 
 The below shows an example of adding a custom reddit socialite service to BookStack.