From 7e1e5974f75dbe9c2325cb1e4e4eb6564de630a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 09:19:26 +0200 Subject: [PATCH 01/11] Improve wording --- README.md | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e8480a4a..f402edd3 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,10 @@ [![Build Status](https://travis-ci.org/kontenta/kontour.svg?branch=master)](https://travis-ci.org/kontenta/kontour) -Kontour is a package of admin page utilities for Laravel. -It provides a shared "frame" for the admin routes you create -in your Laravel apps, or in packages you write. +Kontour is a package of admin page utilities for +[Laravel](https://laravel.com/docs). +It provides a shared "frame" for the admin tool routes you create +in your Laravel apps, or in packages you install or create. The idea is that your admin tools can pull in and use functionality from Kontour to provide a consistent experience for the whole admin area of a website. @@ -18,7 +19,7 @@ You need at least **Laravel 5.8** and **PHP 7.2** to use this package. ## Features - Admin login and password reset routes with configurable Guard - to separate admin users from frontend users. + to separate admin users from frontend users. Bring your own `AdminUser` model! - Extendable Blade Layouts with named sections for admin tool views and configurable stylesheet and javascript dependencies. - Widgets that are placeable in named Blade sections: @@ -34,15 +35,22 @@ You need at least **Laravel 5.8** and **PHP 7.2** to use this package. ## Architecture -- Kontour is installed as a dependency, not a boilerplate. +- Kontour is installed as a dependency in a Laravel project, not a boilerplate. - Kontour uses core Laravel functionality wherever possible, - for example authentication and authorization. + like authentication and authorization, and has no dependencies outside of the + Laravel ecosystem. +- Everything Kontour provides is optional and can be configured to leave a + minimal footprint in the Laravel app in which it has been installed. ## Install Maybe you're here because some package you installed requires Kontour for its -admin pages? In that case it's already installed by composer, but you may still -want to read further below about how to configure Kontour to your liking. +admin pages? In that case Kontour is already installed by composer, but you will +still want to read further below about how to configure Kontour to your liking. + +You are the owner of your Laravel app, even if Kontour was required by some +other package, and you'll at least need to setup the admin user model before +you can log in to the Kontour admin area. Installing Kontour explicitly in your Laravel project: @@ -90,7 +98,7 @@ By default the Kontour dashboard route `kontour.index` is reached by going to To enable login you need to make sure the user model you want to give access to the admin area implements the [`Kontenta\Kontour\Contracts\AdminUser` contract](src/Contracts/AdminUser.php) -which has method `getDisplayName()` that should return... a display name! +which has a method `getDisplayName()` that should return... a display name! The default Kontour configuration uses Laravel's `web` Guard from `config/auth.php` which in turn uses the Eloquent user provider with model @@ -101,8 +109,8 @@ the interface, by having it extend `Kontenta\Kontour\Auth\AdminUser`. This requirement is deliberate to avoid any situation where someone accidentally gives front end users access to their admin routes. -You need to make an active choice about which user model to let into the admin -area. +**You need to make an active choice about which user model to let into the admin +area.** ### Creating a separate user provider for admins @@ -182,13 +190,13 @@ $user->password = ''; $user->save(); ``` -If you're feeling adventuorus, you can then create an admin tool within Kontour +If you're feeling adventurous, you can then create an admin tool within Kontour to let a logged in admin create and invite new admin users! ## Publish the default CSS and js in your Laravel project You probably want to add some style to your admin area, -perhaps pure HTML is too brutalist for your taste... +pure HTML with default browser styles is too brutalist for most people... A good place to start is the default Kontour stylesheet. The included javascript includes a feature to confirm any delete-action before From b7e2844041a2430b5b37a809b22cce4c0e4419e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 09:20:48 +0200 Subject: [PATCH 02/11] Move tool creation docs to separate file Closes #164 --- README.md | 112 +++++------------------------------------- docs/tool-creation.md | 107 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 100 deletions(-) create mode 100644 docs/tool-creation.md diff --git a/README.md b/README.md index f402edd3..88f0b4e2 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,18 @@ area. You need at least **Laravel 5.8** and **PHP 7.2** to use this package. +## Using Kontour in a Laravel app + +This document aims to provide instructions how to configure Kontour in a Laravel +app. Once configured you can log in to the Kontour admin area and use any admin +tools from installed packages. + +## Creating admin tools using Kontour + +For documentation how to create and register your own tools leveraging the +features Kontour provides, you'll find the documentation and helpful guides in +[Using Kontour to build admin tools](docs/tool-creation.md). + ## Features - Admin login and password reset routes with configurable Guard @@ -256,106 +268,6 @@ In `config/kontour.php` Casting Mix's output to a string in the config file makes it possible to cache the config in a production environment. -## Registering admin routes - -In a service provider you can register your admin routes -using methods from the -[`RegistersAdminRoutes` trait](src/Concerns/RegistersAdminWidgets.php). - -## Running code only before admin routes are accessed - -For anything that needs to be "booted" before an admin page/route is loaded, -inject `Kontenta\Kontour\Contracts\AdminBootManager` and add callables to it -using `beforeRoute()`. -Those callables will be called (with any dependencies injected) by a middleware. -This avoids running admin-related code on every page load on the public site. - -## Extending Kontour's Blade layouts - -In the Blade views you create for your admin pages you can inject -a "view manager" instance: - -```php -@inject('view_manager', 'Kontenta\Kontour\Contracts\AdminViewManager') -``` - -...that can be used to pull out one of the common Blade layouts to extend for -any admin pages that wants to be part of the family: - -```php -@extends($view_manager->toolLayout()) -``` - -The `toolLayout` has sections `kontourToolHeader`, `kontourToolMain`, -`kontourToolWidgets`, and `kontourToolFooter` for you to populate. - -```php -@section('kontourToolHeader') -

A splendid tool

- @parent -@endsection - -@section('kontourToolMain') -
- - -
-@endsection -``` - -It's a good idea to include `@parent` in your sections for other content, -for example registered widgets. - -## Adding menu items - -Usually adding menu items is done in a service provider's boot method: - -```php -use Kontenta\Kontour\Contracts\AdminBootManager; -use Kontenta\Kontour\Contracts\MenuWidget; -use Kontenta\Kontour\AdminLink; - -$this->app->make(AdminBootManager::class)->beforeRoute(function (MenuWidget $menuWidget) { - $menuWidget->addLink( - AdminLink::create('A menu item', route('named.route')) - ->registerAbilityForAuthorization('gate or other ability'), - 'A menu heading' - ); -}); -``` - -## Authorizing controller actions - -The -[`AuthorizesAdminRequests` trait](src/Concerns/AuthorizesAdminRequests.php) -has convenince methods for controllers that both authorizes the current user -against an ability, and dispatches an event that records the visit for the -recent visits widgets. - -With the trait used on your controller you can call -`$this->authorizeShowAdminVisit()` for view-only routes or -`$this->authorizeEditAdminVisit()` for routes that present a form. - -Both methods take 4 parameters: - -- The name of the ability to authorize against -- The name of the link to present in recent visits widgets -- The description string for link `title` attribute (optional) -- Arguments for the ability (optional) - -## Registering widgets - -All widgets implement the -[`AdminWidget` interface](src/Contracts/AdminWidget.php) -and can be registered into a section from a service provider -or controller using methods from the -[`RegistersAdminWidgets`](src/Concerns/RegistersAdminWidgets.php) -trait. - -In the `kontour.php` config file you may specify the widgets for all -admin pages using the `global_widgets` array, mapping classname/contract to the -desired section name. - ## Fallback implementations This package contains implementations of the Kontour contracts that are used as diff --git a/docs/tool-creation.md b/docs/tool-creation.md new file mode 100644 index 00000000..1443a20f --- /dev/null +++ b/docs/tool-creation.md @@ -0,0 +1,107 @@ +# Using Kontour to build admin tools + +Admin tools that leverage Kontour are built as any other Laravel +controller with routes. +Usually a +[resource controller](https://laravel.com/docs/controllers#resource-controllers) +is suitable to create admin tools that edit instances of a specific model. + +## Registering admin routes + +In a service provider you can register your admin routes +using methods from the +[`RegistersAdminRoutes` trait](src/Concerns/RegistersAdminWidgets.php). + +## Running code only before admin routes are accessed + +For anything that needs to be "booted" before an admin page/route is loaded, +inject `Kontenta\Kontour\Contracts\AdminBootManager` and add callables to it +using `beforeRoute()`. +Those callables will be called (with any dependencies injected) by a middleware. +This avoids running admin-related code on every page load on the public site. + +## Extending Kontour's Blade layouts + +In the Blade views you create for your admin pages you can inject +a "view manager" instance: + +```php +@inject('view_manager', 'Kontenta\Kontour\Contracts\AdminViewManager') +``` + +...that can be used to pull out one of the common Blade layouts to extend for +any admin pages that wants to be part of the family: + +```php +@extends($view_manager->toolLayout()) +``` + +The `toolLayout` has sections `kontourToolHeader`, `kontourToolMain`, +`kontourToolWidgets`, and `kontourToolFooter` for you to populate. + +```php +@section('kontourToolHeader') +

A splendid tool

+ @parent +@endsection + +@section('kontourToolMain') +
+ + +
+@endsection +``` + +It's a good idea to include `@parent` in your sections for other content, +for example registered widgets. + +## Adding menu items + +Usually adding menu items is done in a service provider's boot method: + +```php +use Kontenta\Kontour\Contracts\AdminBootManager; +use Kontenta\Kontour\Contracts\MenuWidget; +use Kontenta\Kontour\AdminLink; + +$this->app->make(AdminBootManager::class)->beforeRoute(function (MenuWidget $menuWidget) { + $menuWidget->addLink( + AdminLink::create('A menu item', route('named.route')) + ->registerAbilityForAuthorization('gate or other ability'), + 'A menu heading' + ); +}); +``` + +## Authorizing controller actions + +The +[`AuthorizesAdminRequests` trait](src/Concerns/AuthorizesAdminRequests.php) +has convenince methods for controllers that both authorizes the current user +against an ability, and dispatches an event that records the visit for the +recent visits widgets. + +With the trait used on your controller you can call +`$this->authorizeShowAdminVisit()` for view-only routes or +`$this->authorizeEditAdminVisit()` for routes that present a form. + +Both methods take 4 parameters: + +- The name of the ability to authorize against +- The name of the link to present in recent visits widgets +- The description string for link `title` attribute (optional) +- Arguments for the ability (optional) + +## Registering widgets + +All widgets implement the +[`AdminWidget` interface](src/Contracts/AdminWidget.php) +and can be registered into a section from a service provider +or controller using methods from the +[`RegistersAdminWidgets`](src/Concerns/RegistersAdminWidgets.php) +trait. + +In the `kontour.php` config file you may specify the widgets for all +admin pages using the `global_widgets` array, mapping classname/contract to the +desired section name. From 9fe970b1d5dd7cf0344104d2b386d88d9cda750e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 09:24:03 +0200 Subject: [PATCH 03/11] Fix links to src files --- docs/tool-creation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index 1443a20f..af13cd47 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -10,7 +10,7 @@ is suitable to create admin tools that edit instances of a specific model. In a service provider you can register your admin routes using methods from the -[`RegistersAdminRoutes` trait](src/Concerns/RegistersAdminWidgets.php). +[`RegistersAdminRoutes` trait](../src/Concerns/RegistersAdminWidgets.php). ## Running code only before admin routes are accessed @@ -77,7 +77,7 @@ $this->app->make(AdminBootManager::class)->beforeRoute(function (MenuWidget $men ## Authorizing controller actions The -[`AuthorizesAdminRequests` trait](src/Concerns/AuthorizesAdminRequests.php) +[`AuthorizesAdminRequests` trait](../src/Concerns/AuthorizesAdminRequests.php) has convenince methods for controllers that both authorizes the current user against an ability, and dispatches an event that records the visit for the recent visits widgets. @@ -96,10 +96,10 @@ Both methods take 4 parameters: ## Registering widgets All widgets implement the -[`AdminWidget` interface](src/Contracts/AdminWidget.php) +[`AdminWidget` interface](../src/Contracts/AdminWidget.php) and can be registered into a section from a service provider or controller using methods from the -[`RegistersAdminWidgets`](src/Concerns/RegistersAdminWidgets.php) +[`RegistersAdminWidgets`](../src/Concerns/RegistersAdminWidgets.php) trait. In the `kontour.php` config file you may specify the widgets for all From 1afeaad4e1b04cb1b8a74bb11a14c2bee1a20868 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 09:31:31 +0200 Subject: [PATCH 04/11] Fix incorrect link --- docs/tool-creation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index af13cd47..b5388345 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -10,7 +10,7 @@ is suitable to create admin tools that edit instances of a specific model. In a service provider you can register your admin routes using methods from the -[`RegistersAdminRoutes` trait](../src/Concerns/RegistersAdminWidgets.php). +[`RegistersAdminRoutes` trait](../src/Concerns/RegistersAdminRoutes.php). ## Running code only before admin routes are accessed From d2d58d458f82838a84caaf0edbfd1f5e208944b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 10:03:52 +0200 Subject: [PATCH 05/11] Improve wording --- docs/tool-creation.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index b5388345..86bf3a55 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -1,8 +1,7 @@ # Using Kontour to build admin tools -Admin tools that leverage Kontour are built as any other Laravel -controller with routes. -Usually a +Admin tools that leverage Kontour are built as any other Laravel controller with +corresponding routes. Usually a [resource controller](https://laravel.com/docs/controllers#resource-controllers) is suitable to create admin tools that edit instances of a specific model. @@ -20,7 +19,7 @@ using `beforeRoute()`. Those callables will be called (with any dependencies injected) by a middleware. This avoids running admin-related code on every page load on the public site. -## Extending Kontour's Blade layouts +## Extending Kontour Blade layouts In the Blade views you create for your admin pages you can inject a "view manager" instance: From 5076b9b9c6ea0dd5d6c6da303b255f7f20661e62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 10:04:05 +0200 Subject: [PATCH 06/11] Improve route registration docs --- docs/tool-creation.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index 86bf3a55..a3ef57b3 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -9,7 +9,27 @@ is suitable to create admin tools that edit instances of a specific model. In a service provider you can register your admin routes using methods from the -[`RegistersAdminRoutes` trait](../src/Concerns/RegistersAdminRoutes.php). +[`RegistersAdminRoutes` trait](../src/Concerns/RegistersAdminRoutes.php) +that will group the routes with all route attributes configured with Kontour, +like middleware etc. + +In a Laravel app you can for example create a routes file `routes/kontour.php` +to keep routes for all Kontour tools you create. A service provider using the +trait may then register them in the boot method. + +```php +use Kontenta\Kontour\Concerns\RegistersAdminRoutes; + +public function boot() +{ + $this->registerAdminRoutes(base_path('routes/kontour.php')); +} +``` + +If you're writing a package, the routes file would probably be named something +more package specific, and the service provider would need to use a relative +path, like +`__DIR__ . '/../routes/kontour.php'` to register the routes. ## Running code only before admin routes are accessed From bec1d5e172861c9ce76f473e9cc4f5bfcbce3293 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 10:10:13 +0200 Subject: [PATCH 07/11] Fix typo --- docs/tool-creation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index a3ef57b3..b393bb84 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -97,7 +97,7 @@ $this->app->make(AdminBootManager::class)->beforeRoute(function (MenuWidget $men The [`AuthorizesAdminRequests` trait](../src/Concerns/AuthorizesAdminRequests.php) -has convenince methods for controllers that both authorizes the current user +has convenience methods for controllers that both authorizes the current user against an ability, and dispatches an event that records the visit for the recent visits widgets. From 13adf20978919c5e5898f64f0cac1b61bf5be2a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 10:10:42 +0200 Subject: [PATCH 08/11] Link to use case for beforeRoute usage --- docs/tool-creation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index b393bb84..be58fe48 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -39,6 +39,9 @@ using `beforeRoute()`. Those callables will be called (with any dependencies injected) by a middleware. This avoids running admin-related code on every page load on the public site. +A good use case when [adding menu items](#adding-menu-items) +is documented below. + ## Extending Kontour Blade layouts In the Blade views you create for your admin pages you can inject From 0a978063294baaf3b53fa267fc01360077429fd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 11:29:18 +0200 Subject: [PATCH 09/11] Document Kontour usage in packages See discussion in #87 --- docs/tool-creation.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index be58fe48..a6c4ebbf 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -1,5 +1,47 @@ # Using Kontour to build admin tools +You can create a set of admin tools specific to your Laravel app within the app +itself after [installing Kontour with composer](../README.md#install). + +## Using Kontour in packages + +If you author a composer package that would benefit from some Laravel admin +tools, a good strategy is to release a separate package for the admin tools +related to the main package. +This way consumers of your main package can actively choose to install the +Kontour admin tools if they want to. + +You may even release alternative admin packages for other admin systems like +[Laravel Nova](https://nova.laravel.com), and let the consumer pick the best +match for their Laravel app. +If you create a companion Kontour admin package of your own, consider suffixing +the name like `-kontour-admin`, so you may release `-nova-admin` and possibly +others too! + +### Example packages using Kontour + +The Laravel package +[`bjuppa/laravel-blog`](https://github.com/bjuppa/laravel-blog), +created by on of the main contributors to Kontour, provides add-on blog +functionality for any Laravel app. +Public routes, controllers, views, styling, and models & migrations +are all included there – but it doesn't provide any admin tools for editors to +manage the blog posts. + +Consumers of the package are free to create their own admin area, but there +is also the option to install the companion package +[`bjuppa/laravel-blog-admin`](https://github.com/bjuppa/laravel-blog-admin), +that in turn depends on Kontour. + +If you're a source diver you'll find many examples of Kontour usage there. +A good place to start is in the +[`BlogAdminServiceProvider`](https://github.com/bjuppa/laravel-blog-admin/blob/master/src) +and then look at the +[controllers](https://github.com/bjuppa/laravel-blog-admin/tree/master/src/Http/Controllers) +and [routes](https://github.com/bjuppa/laravel-blog-admin/tree/master/routes). + +## Kontour tools are just Laravel controllers + Admin tools that leverage Kontour are built as any other Laravel controller with corresponding routes. Usually a [resource controller](https://laravel.com/docs/controllers#resource-controllers) From b87ba1de7435b332a26532ac8e8a4e1113f5b022 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 14:28:11 +0200 Subject: [PATCH 10/11] Fix typo --- docs/tool-creation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tool-creation.md b/docs/tool-creation.md index a6c4ebbf..64fa6a86 100644 --- a/docs/tool-creation.md +++ b/docs/tool-creation.md @@ -22,7 +22,7 @@ others too! The Laravel package [`bjuppa/laravel-blog`](https://github.com/bjuppa/laravel-blog), -created by on of the main contributors to Kontour, provides add-on blog +created by one of the main contributors to Kontour, provides add-on blog functionality for any Laravel app. Public routes, controllers, views, styling, and models & migrations are all included there – but it doesn't provide any admin tools for editors to From 5de6c884fddf2571f073904fd1f1f7cbe94066a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Nilsved?= Date: Fri, 8 May 2020 14:29:13 +0200 Subject: [PATCH 11/11] Fix wording --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 88f0b4e2..6f95e6e5 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,9 @@ You need at least **Laravel 5.8** and **PHP 7.2** to use this package. ## Using Kontour in a Laravel app -This document aims to provide instructions how to configure Kontour in a Laravel -app. Once configured you can log in to the Kontour admin area and use any admin -tools from installed packages. +This document aims to provide instructions on how to configure Kontour in a +Laravel app. Once configured you can log in to the Kontour admin area and use +any admin tools from installed packages. ## Creating admin tools using Kontour