BookStack Code Mirror - bookstack/blob - dev/docs/logical-theme-system.md

   1 # Logical Theme System
   2
   3 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.
   4
   5 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.
   6
   7 ## Getting Started
   8
   9 *[Video Guide](https://www.youtube.com/watch?v=YVbpm_35crQ)*
  10
  11 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.
  12 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`.
  13
  14 Within your theme folder create a `functions.php` file. BookStack will look for this and run it during app boot-up. Within this file you can use the `Theme` facade API, described below, to hook into certain app events.
  15
  16 ## `Theme` Facade API
  17
  18 Below details the public methods of the `Theme` facade that are considered stable:
  19
  20 ### `Theme::listen`
  21
  22 This method listens to a system event and runs the given action when that event occurs. The arguments passed to the action depend on the event. Event names are exposed as static properties on the `\BookStack\Theming\ThemeEvents` class.
  23
  24 It is possible to listen to a single event using multiple actions. When dispatched, BookStack will loop over and run each action for that event.
  25 If an action returns a non-null value then BookStack will stop cycling through actions at that point and make use of the non-null return value if possible (Depending on the event).
  26
  27 **Arguments**
  28 - string $event
  29 - callable $action
  30
  31 **Example**
  32
  33 ```php
  34 Theme::listen(
  35     \BookStack\Theming\ThemeEvents::AUTH_LOGIN,
  36     function($service, $user) {
  37         \Log::info("Login by {$user->name} via {$service}");
  38     }
  39 );
  40 ```
  41
  42 ### `Theme::addSocialDriver`
  43
  44 This method allows you to register a custom social authentication driver within the system. This is primarily intended to use with [Socialite Providers](https://socialiteproviders.com/).
  45
  46 **Arguments**
  47 - string $driverName
  48 - array $config
  49 - string $socialiteHandler
  50
  51 **Example**
  52
  53 *See "Custom Socialite Service Example" below.*
  54
  55 ### `Theme::registerCommand`
  56
  57 This method allows you to register a custom command which can then be used via the artisan console.
  58
  59 **Arguments**
  60 - string $driverName
  61 - array $config
  62 - string $socialiteHandler
  63
  64 **Example**
  65
  66 *See "Custom Command Registration Example" below for a more detailed example.*
  67
  68 ```php
  69 Theme::registerCommand(new SayHelloCommand());
  70 ```
  71
  72 ## Available Events
  73
  74 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).
  75
  76 The comments above each constant with the `ThemeEvents.php` file describe the dispatch conditions of the event, in addition to the arguments the action will receive. The comments may also describe any ways the return value of the action may be used.
  77
  78 ## Example `functions.php` file
  79
  80 ```php
  81 <?php
  82
  83 use BookStack\Facades\Theme;
  84 use BookStack\Theming\ThemeEvents;
  85
  86 // Logs custom message on user login
  87 Theme::listen(ThemeEvents::AUTH_LOGIN, function($method, $user) {
  88     Log::info("Login via {$method} for {$user->name}");
  89 });
  90
  91 // Adds a `/info` public URL endpoint that emits php debug details
  92 Theme::listen(ThemeEvents::APP_BOOT, function($app) {
  93     \Route::get('info', function() {
  94         phpinfo(); // Don't do this on a production instance!
  95     });
  96 });
  97 ```
  98
  99 ## Custom Command Registration Example
 100
 101 The logical theme system supports adding custom [artisan commands](https://laravel.com/docs/8.x/artisan) to BookStack.
 102 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`.
 103
 104 Below is an example of registering a command that could then be ran using `php artisan bookstack:meow` on the command line.
 105
 106 ```php
 107 <?php
 108
 109 use BookStack\Facades\Theme;
 110 use Illuminate\Console\Command;
 111
 112 class MeowCommand extends Command
 113 {
 114     protected $signature = 'bookstack:meow';
 115     protected $description = 'Say meow on the command line';
 116
 117     public function handle()
 118     {
 119         $this->line('Meow there!');
 120     }
 121 }
 122
 123 Theme::registerCommand(new MeowCommand);
 124 ```
 125
 126 ## Custom Socialite Service Example
 127
 128 The below shows an example of adding a custom reddit socialite service to BookStack.
 129 BookStack exposes a helper function for this via `Theme::addSocialDriver` which sets the required config and event listeners in the platform.
 130
 131 The require statements reference composer installed dependencies within the theme folder. They are required manually since they are not auto-loaded like other app files due to being outside the main BookStack dependency list.
 132
 133 ```php
 134 require "vendor/socialiteproviders/reddit/Provider.php";
 135 require "vendor/socialiteproviders/reddit/RedditExtendSocialite.php";
 136
 137 Theme::listen(ThemeEvents::APP_BOOT, function($app) {
 138     Theme::addSocialDriver('reddit', [
 139         'client_id' => 'abc123',
 140         'client_secret' => 'def456789',
 141         'name' => 'Reddit',
 142     ], '\SocialiteProviders\Reddit\RedditExtendSocialite@handle');
 143 });
 144 ```
 145
 146 In some cases you may need to customize the driver before it performs a redirect.
 147 This can be done by providing a callback as a fourth parameter like so:
 148
 149 ```php
 150 Theme::addSocialDriver('reddit', [
 151     'client_id' => 'abc123',
 152     'client_secret' => 'def456789',
 153     'name' => 'Reddit',
 154 ], '\SocialiteProviders\Reddit\RedditExtendSocialite@handle', function($driver) {
 155     $driver->with(['prompt' => 'select_account']);
 156     $driver->scopes(['open_id']);
 157 });
 158 ```