|
1 | 1 | --- |
2 | | -title: Admin controller |
3 | | -description: Add a custom PHP controller to an extension's admin page |
4 | | -author: |
| 2 | +title: Custom admin page controller |
| 3 | +description: Render your admin view using a custom controller |
| 4 | +author: Emma |
5 | 5 | category: dev |
6 | 6 | thumbnail: controller.jpeg |
7 | | -order: |
8 | | -unlisted: true |
9 | 7 | --- |
10 | 8 |
|
11 | | -... |
| 9 | +## Introduction |
| 10 | + |
| 11 | +Using the `admin.controller` [conf.yml bind](/docs/configs/confyml#admincontroller) you can add additional logic to how your `admin.view` is rendered, as well as how additional HTTP methods are handled. |
| 12 | + |
| 13 | +Admin views are always rendered through controllers. Unless you are shipping your own custom controller (which you will when following this guide), your extension will use the default one shipped by us. |
| 14 | + |
| 15 | +## Create the controller |
| 16 | + |
| 17 | +Create a file called `controller.php`, and bind it to `admin.controller` in your [conf.yml](/docs/configs/confyml#admincontroller) configuration. |
| 18 | + |
| 19 | +```yaml [conf.yml] |
| 20 | +admin: |
| 21 | + controller: 'controller.php' |
| 22 | +``` |
| 23 | +
|
| 24 | +Then, add the code below to your `controller.php` file. |
| 25 | + |
| 26 | +```php [controller.php] |
| 27 | +<?php |
| 28 | +
|
| 29 | +// Define namespace. This is the namespace needed for admin controllers. |
| 30 | +// {identifier} automatically gets replaced with your extension's |
| 31 | +// identifier upon extension installation. |
| 32 | +namespace Pterodactyl\Http\Controllers\Admin\Extensions\{identifier}; |
| 33 | +
|
| 34 | +// Import the controller class. |
| 35 | +use Pterodactyl\Http\Controllers\Controller; |
| 36 | +
|
| 37 | +// Register the extension-specific controller class. |
| 38 | +class {identifier}ExtensionController extends Controller { |
| 39 | + // The index() function gets called upon a GET request. |
| 40 | + public function index() { |
| 41 | + // Respond with plain text. |
| 42 | + return "hello from {identifier}'s custom controller" |
| 43 | + } |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +Open up your extension's admin page and it should respond with plain text. |
| 48 | + |
| 49 | + |
| 50 | + |
| 51 | +Alright, so with that out of the way, let's actually render our view. |
| 52 | + |
| 53 | +## Rendering the admin view |
| 54 | + |
| 55 | +After the `namespace` definition, import the following classes into `controller.php`. These will be used by our functions later on in the guide. |
| 56 | + |
| 57 | +```php [controller.php] |
| 58 | +// Import classes needed for view rendering. |
| 59 | +use Illuminate\View\View; |
| 60 | +use Illuminate\View\Factory as ViewFactory; |
| 61 | +
|
| 62 | +// Import BlueprintExtensionLibrary. This is required for admin views to function. |
| 63 | +use Pterodactyl\BlueprintFramework\Libraries\ExtensionLibrary\Admin\BlueprintAdminLibrary as BlueprintExtensionLibrary; |
| 64 | +``` |
| 65 | + |
| 66 | +Inside of the controller's `class`, add a `__construct()` method. The `__construct()` method is automatically called on class instantiation. |
| 67 | + |
| 68 | +```php [controller.php] |
| 69 | +class {identifier}ExtensionController extends Controller { |
| 70 | + public function __construct( |
| 71 | + private ViewFactory $view, |
| 72 | + private BlueprintExtensionLibrary $blueprint, |
| 73 | + ) {} |
| 74 | +
|
| 75 | + // ..your other functions |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +### Update the `index()` function |
| 80 | + |
| 81 | +Because we're going to be rendering a view, we should expect our response to be one too. `View` is imported from `use Illuminate\View\View;` in [this step](#rendering-the-admin-view). |
| 82 | + |
| 83 | +```diff [controller.php] |
| 84 | +- public function index() { |
| 85 | ++ public function index(): View { |
| 86 | +``` |
| 87 | + |
| 88 | +Finally, we can return a view, instead of a plaintext response. |
| 89 | + |
| 90 | +This code makes a view with `$this->view->make` (through ViewFactory) and makes the variables `$root` and `$blueprint` available to it. |
| 91 | + |
| 92 | +```diff [controller.php] |
| 93 | +public function index(): View { |
| 94 | +- return "hello from {identifier}'s custom controller" |
| 95 | ++ return $this->view->make( |
| 96 | ++ 'admin.extensions.{identifier}.index', [ |
| 97 | ++ 'root' => "/admin/extensions/{identifier}", |
| 98 | ++ 'blueprint' => $this->blueprint, |
| 99 | ++ ] |
| 100 | ++ ); |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +Save your changes and visit your extension's admin page again. You should see your admin view instead of the plaintext response from earlier. |
| 105 | + |
| 106 | +## Adding variables to the view |
| 107 | + |
| 108 | +Through ViewFactory's `make()` function, we can define variables that we can then use in our admin view. |
| 109 | + |
| 110 | +The following piece of code adds a `$foo` variable to the view, with the contents of `bar`. |
| 111 | + |
| 112 | +```diff [controller.php] |
| 113 | +public function index(): View { |
| 114 | ++ $foo = 'bar' |
| 115 | + return $this->view->make( |
| 116 | + 'admin.extensions.{identifier}.index', [ |
| 117 | + 'root' => "/admin/extensions/{identifier}", |
| 118 | + 'blueprint' => $this->blueprint, |
| 119 | ++ 'foo' => $foo, |
| 120 | + ] |
| 121 | + ); |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +Then in your admin view (`admin.view` in your [conf.yml](/docs/configs/confyml#adminview-required) configuration), read out the `$foo` variable. |
| 126 | + |
| 127 | +We're assuming your `admin.view` file is called `view.blade.php`, but it can be different depending on your extension configuration. |
| 128 | + |
| 129 | +<!-- prettier-ignore --> |
| 130 | +```html [view.blade.php] |
| 131 | +<p> |
| 132 | + {{ $foo }} |
| 133 | +</p> |
| 134 | +``` |
| 135 | + |
| 136 | +Save your changes, install your extension and check out your admin view. There should be a paragraph element with 'bar' (the value of `$foo`) as it's content. |
| 137 | + |
| 138 | +## Final results |
| 139 | + |
| 140 | +Below is the final version of the `controller.php` file composed in the previous steps. |
| 141 | + |
| 142 | +While there's nothing stopping you from copy pasting them into your extension, we still highly recommend going through the steps above. This file is solely here for comparison. |
| 143 | + |
| 144 | +```php [controller.php] |
| 145 | +<?php |
| 146 | +
|
| 147 | +// Define namespace. This is the namespace needed for admin controllers. |
| 148 | +// {identifier} automatically gets replaced with your extension's |
| 149 | +// identifier upon extension installation. |
| 150 | +namespace Pterodactyl\Http\Controllers\Admin\Extensions\{identifier}; |
| 151 | +
|
| 152 | +// Import classes needed for view rendering. |
| 153 | +use Illuminate\View\View; |
| 154 | +use Illuminate\View\Factory as ViewFactory; |
| 155 | +// Import the controller class. |
| 156 | +use Pterodactyl\Http\Controllers\Controller; |
| 157 | +// Import BlueprintExtensionLibrary. This is required for admin views |
| 158 | +// to function. |
| 159 | +use Pterodactyl\BlueprintFramework\Libraries\ExtensionLibrary\Admin\BlueprintAdminLibrary as BlueprintExtensionLibrary; |
| 160 | +
|
| 161 | +// Register the extension-specific controller class. |
| 162 | +class {identifier}ExtensionController extends Controller { |
| 163 | + public function __construct(private ViewFactory $view, private BlueprintExtensionLibrary $blueprint) {} |
| 164 | +
|
| 165 | + // Render page. The index() function gets called when the |
| 166 | + // /admin/extensions/{identifier} path receives a GET request. |
| 167 | + public function index(): View { |
| 168 | + // Define the $foo variable to 'bar'. |
| 169 | + $foo = 'bar'; |
| 170 | + // Render the admin view, assign $root to the URL path, |
| 171 | + // $blueprint to BlueprintExtensionLibrary and $foo to the $foo |
| 172 | + // variable. These variables can be directly used within the view. |
| 173 | + return $this->view->make( |
| 174 | + 'admin.extensions.{identifier}.index', [ |
| 175 | + 'root' => "/admin/extensions/{identifier}", |
| 176 | + 'blueprint' => $this->blueprint, |
| 177 | + 'foo' => $foo, |
| 178 | + ] |
| 179 | + ); |
| 180 | + } |
| 181 | +} |
| 182 | +``` |
0 commit comments