From 9e0b4640e6035d01b8b9dfca20016e5a3e246d4a Mon Sep 17 00:00:00 2001 From: Ivo Valchev Date: Tue, 3 Aug 2021 12:15:49 +0200 Subject: [PATCH 1/3] Document creating backend pages --- docs/extensions/pages.md | 138 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 137 insertions(+), 1 deletion(-) diff --git a/docs/extensions/pages.md b/docs/extensions/pages.md index 15d022c5..9e02f3d6 100644 --- a/docs/extensions/pages.md +++ b/docs/extensions/pages.md @@ -1,4 +1,140 @@ Adding Pages in the backend =========================== -[todo] Write some stuff here adding pages in the backend, that kinda look like they fit in with the overall backend. +## Create a page in the Bolt's backend + +You can add pages to Bolt's backend by creating a custom +Controller in the `src` folder of your project. + +To configure it as a backend controller, two steps are necessary: +* The controller class needs to implement the `BackendZoneInterface` + that Bolt provides +* The `routes.yaml` file needs to add Bolt backend prefix for +the controller's routes. + +### Creating a backend page controller + +```php +render('content_user.html.twig', [ + 'title' => 'User content' + ]); + } +} +``` + + +### Defining the controller route with the backend url prefix + +Localte the `config/routes.yaml` file and add the following **after** +`project`: + +```yaml +app_panel: + resource: '../src/UserContentController.php' + prefix: '%bolt.backend_url%' + type: annotation +``` + +

Make sure to replace UserContentController.php +with the name of your controller class.

+ +### Using a Twig template to render the page + +You can use any Twig template of your choosing to render the page. +In this example, the controller defined `content_user.html.twig` as +the template that will be used to generate the response. Make sure +to create a file with that name in the `templates` folder in the root of +your project. + +For example, the `content_user.html.twig` file may contain the following: + +```twig +{% extends '@bolt/_base/layout.html.twig' %} + +{% block main %} +

This is the content for a user. It is currently empty.

+{% endblock %} +``` + +#### Provided templates + +Bolt provides two templates that you can extend when creating +custom backend pages: + +| Template | Function | Link | +| --- | --- | --- | +| `@bolt/_base/layout.html.twig` | This is the standard template that any Bolt page uses. It contains the top bar, the sidebar and aside components. | [Layout link][layout-link] +| `@bolt/_base/layout_blank.html.twig` | This is the barebones version of the layout. Use it only if you do not want to show the default Bolt backend look and feel. | [Blank layout link][blank-layout-link] + +All available templates that Bolt uses under the hood are available in Bolt's [repository][https://github.com/bolt/core/tree/master/templates]. + +## Add a page to Bolt's sidebar menu + +Bolt allows the sidebar menu to be extended to add extra items and links. +To do so, create a class inside the `src` folder of your project that +implements the `ExtensionBackendMenuInterface`. + +The example below defines a new menu section for the User Content page shown above. + +```php +urlGenerator = $urlGenerator; + } + + public function addItems(MenuItem $menu): void + { + // This adds a new heading + $menu->addChild('User Content Extension', [ + 'extras' => [ + 'name' => 'User Content Extension', + 'type' => 'separator', + ] + ]); + + // This adds the link + $menu->addChild('Content list', [ + 'uri' => $this->urlGenerator->generate('app_content_user'), + 'extras' => [ + 'icon' => 'fa-user-circle' + ] + ]); + } +} +``` + +[layout-link]: https://github.com/bolt/core/blob/master/templates/_base/layout.html.twig +[blank-layout-link]: https://github.com/bolt/core/blob/master/templates/_base/layout_blank.html.twig +[all-templates]: https://github.com/bolt/core/tree/master/templates From 42d3a44c44fbf11419025d82f4bb36e7f9f26f08 Mon Sep 17 00:00:00 2001 From: Ivo Valchev Date: Tue, 3 Aug 2021 13:24:44 +0200 Subject: [PATCH 2/3] Capitalize controller --- docs/extensions/pages.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/extensions/pages.md b/docs/extensions/pages.md index 9e02f3d6..3e040ef1 100644 --- a/docs/extensions/pages.md +++ b/docs/extensions/pages.md @@ -6,13 +6,13 @@ Adding Pages in the backend You can add pages to Bolt's backend by creating a custom Controller in the `src` folder of your project. -To configure it as a backend controller, two steps are necessary: -* The controller class needs to implement the `BackendZoneInterface` +To configure it as a backend Controller, two steps are necessary: +* The Controller class needs to implement the `BackendZoneInterface` that Bolt provides * The `routes.yaml` file needs to add Bolt backend prefix for the controller's routes. -### Creating a backend page controller +### Creating a backend page Controller ```php Make sure to replace UserContentController.php -with the name of your controller class.

+with the name of your Controller class.

### Using a Twig template to render the page You can use any Twig template of your choosing to render the page. -In this example, the controller defined `content_user.html.twig` as +In this example, the Controller defined `content_user.html.twig` as the template that will be used to generate the response. Make sure to create a file with that name in the `templates` folder in the root of your project. From a5064076661421c146db99d9f88932e53f98d7ce Mon Sep 17 00:00:00 2001 From: Ivo Valchev Date: Tue, 3 Aug 2021 13:29:34 +0200 Subject: [PATCH 3/3] Fix typo --- docs/extensions/pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extensions/pages.md b/docs/extensions/pages.md index 3e040ef1..71e80336 100644 --- a/docs/extensions/pages.md +++ b/docs/extensions/pages.md @@ -43,7 +43,7 @@ class UserContentController extends TwigAwareController implements BackendZoneIn ### Defining the controller route with the backend url prefix -Localte the `config/routes.yaml` file and add the following **after** +Locale the `config/routes.yaml` file and add the following **after** `project`: ```yaml