Configuration Options
The Watchtower config file (\config\watchtower.php) is meant to give you control over which views to load and provide access to the varying parts of the package. The file itself contains some other miscellaneous options as well.
By editing the dashboard section of the config file you can change what links are presented to your admins. You can add more, change the order, colour and icons, or even remove them altogether. For more customization of the layout, you can also edit the view used for the dashboard. (:scroll: config option : watchtower.views.layout.adminlinks)
By default the three sections that are available in Watchtower are shown with a link to each's index page and using some bootstrap theme-ing.
######Default Appearance
By modifying the order they appear in the array (moving the permissions array from the end to the start of the 'dashboard' array), and changing their colour options (permissions to warning, users to danger and roles to default) we can get an entire different customized display for the dashboard.
'dashboard' => [
'permissions' => [
'name' => "Permissions",
'route' => 'watchtower.permission.index',
'icon' => 'fa fa-5x fa-key',
'colour'=> 'warning'
],
'users' => [
'name' => "Users",
'route' => 'watchtower.user.index',
'icon' => 'fa fa-user fa-5x',
'colour'=> 'danger'
],
'roles' => [
'name' => "Roles",
'route' => 'watchtower.role.index',
'icon' => 'fa fa-users fa-5x',
'colour'=> 'success'
]
]
💡 Tip You can add as many of these dashboard shortcuts as you like just by adding them into the config file. The only caveat is that the 'route' option must be a named route within your application. From a command prompt: php artisan route:list will show you a list of all your routes with their names to make sure your desired one is available.
✋ Note : If you are using your own custom layout, and don't need these route definition files, feel free to ignore this section.
Laravel 5.2 changed the routes that they always used for authentication (login, logout, register, forgot password and reset password). Whereas in the past, when you went with the automagical Laravel auth methods, all the authentication routes were prefixed with "auth/" in the current version, Laravel has dropped the prefix of "auth/" from its authentication routes.
In an effort to keep with a one install package for laravel, the config file allows you to specify the routes you want to use for authentication. By default Watchtower will try to detect the app's version of Laravel that is running and load the common default authentication routes. You can override these routes if you have your own customized routing scheme.
|
| Laravel 5.1 default:
| /auth/login, /auth/logout and /auth/register
|
| Laravel 5.2 default:
| /login, /logout and /register
|
*/
'auth_routes' => [
'login' => (str_contains( app()->version(), '5.2') ? '' : '/auth').'/login',
'logout' => (str_contains( app()->version(), '5.2') ? '' : '/auth').'/logout',
'register' => (str_contains( app()->version(), '5.2') ? '' : '/auth').'/register',
],
💡 Tip If you do have your own custom layout, and still want to use these route definitions, they are always accessible with Laravel's built-in config getter. For example, config( 'watchtower.auth_routes.login' ); will get return the /auth/login with laravel 5.1 and just login with laravel 5.2
Site Title
This is the text that shows up where you see "Watchtower". If you don't like "Watchtower", you can rename it to whatever suits your needs.
Default Theme
Watchtower loads the css for whatever named bootstrap theme from https://www.bootstrapcdn.com/bootswatch/ so you can pick any of the many choices there. Or you can alter the master.layout and load them locally or not at all. Default is for spacelab. (Flatly is also pretty cool for a material look.)
✋ Note There is a View Composer registered within the Watchtower Service Provider that sets both the site title and default theme.
❗ Optional The View Composer also does a check to see if there is a "theme" property under the Auth::user() collection and uses the value from "theme" if one is defined. So if you wish to allow your users the ability to pick their own theme, you can do so. (You would need to add a field to your users table called "theme" and then probably add a theme option to a profile page where they can choose from a list of available themes.)
Pagination
By default, Watchtower uses a pagination of "15". You can modify that for users, roles, or permissions by changing the values in this configuration section.
✋ Note Does not apply to matrices.
Route Prefix
If you prefer to have your routes hidden behind a "prefix", this is the place to enter it. Route Prefix Info For example 'route_prefix' => 'admin' will change your urls to look like 'http://YOUR_SITE/admin/watchtower/user' instead of looking like 'http://YOUR_SITE/watchtower/user'. By default, the route prefix is blank.
Watchtower comes ready to go with pre-defined permissions to access all the different areas. Feel free to change them to match your needs, if you wish. The value for each permission can be a permission slug from Shinobi's permission table or a boolean true/false to globally enable/disable permission. However, the permissions in watchtower will return "false" for security if nothing else is supplied in a config file.
✋ Note If you already have defined permissions for accessing the roles & permissions, you are free to change the options under ACL in the watchtower config file to match your environment.
Watchtower permissions are stored under 'acl' and these are what Watchtower checks using Shinobi's can method before any of the admin functions are performed. The following is an example of the Role Index view where the user's permission to view the index page is checked before the list is shown.
@if ( \Shinobi::can( config('watchtower.acl.role.index', false) ) )
The permission "watchtower.acl.role.index" uses the 'show.role.index' slug that is available in the permission table within Shinobi. Note that a default false is applied if the requested permission is not found. This will prevent Watchtower from inadvertently giving access to any functions or views in your admin area. So with this permission in place, the only people that can view your 'role index page' would need to have this permission.
'acl' => [
...
'role' => [
'index' => 'show.role.index',
...
However, if you were to change the "watchtower.acl.role.index" from 'show.role.index' to (bool) true everyone will have the ability to view that page. (not recommended; for illustrative purposes only)
'acl' => [
...
'role' => [
'index' => (bool) true, //or just true (no apostrophes or quotes)
...
Much like the Dashboard Links and Access Control, the views that Watchtower uses can be controlled from the config file. So if you already have your own master layout or view partials that you want to use, simply tell Watchtower where to find them.
For example, if you have a view you already use for your layout that you call in your other views as "app.layout" and wish to use it as your master layout for Watchtower, you would simply change 'watchtower::layouts.master' to 'app.layout'.
'views' => [
'layouts' => [
'master' => 'app.layout', // 'watchtower::layouts.master',
If you don't have anything created yet or are happy with the ones provided you don't need to make any changes to this section.
By default, Watchtower, comes with a layout that contains a navigational menu along the top that contains drop down links to the various areas of the package. This navigation menu is generated from another config file called "watchtower-menu" and you are free to edit it to add your own groups, links or to consolidate multiple groups into one group if you wish.
If you notice from the image, there is an extra "$" icon that contains two links to another admin area of the app. This was created by simply adding the following array to the watchtower-menu config file.
[
'group' => 'Lex',
'class' => 'fa fa-usd fa-lg',
'links' => [
[
'title' => 'Add Currency',
'class' => 'fa fa-fw fa-plus',
'route' => 'lex.create'
],
[
'title' => 'List Currencies',
'class' => 'fa fa-fw fa-th-list',
'route' => 'lex.index'
]
]
],
- 'group' is the name of the container to hold the links, and also serves as the title for screen-readers.
- 'class' are the classes that will be applied to specify which icon appears (I use font-awesome, you can use the typical bootstrap 'glyphicons' if you prefer)
-
'links' is the array to all the different points you want to link to in your app. Each array contained in links will appear as a separate link in the navigation menu.
- 'title' is the text that will appear for the link
- 'class' are the classes that will be applied to specify which icon appears
- 'route' is the named route to where you want this link to point
If you wish to add a "separator" between some links, add that as an entry wherever you want the separator to appear.
[
'title' => 'List Users',
'class' => 'fa fa-fw fa-th-list',
'route' => 'watchtower.user.index'
],
'separator',
[
'title' => 'User Matrix',
'class' => 'fa fa-fw fa-table',
'route' => 'watchtower.user.matrix'
]
It is also possible to group multiple links under one group and to add separating headers inside the dropdown groups. In the image below two previously separate dropdown groups are merged into one "modules" group with a header for each specifying its section.
To achieve a header add another link with the special route of "header" like in the following example. This will add the group headers like in the image above. This is the code use to create the drop down group in the image above (note the links containing the route "header").
[
'group' => 'Modules',
'class' => 'fa fa-gears fa-lg',
'links' => [
[
'title' => 'Lex Currency',
'class' => 'fa fa-fw fa-usd',
'route' => 'header'
],
[
'title' => 'Add Currency',
'class' => 'fa fa-fw fa-plus',
'route' => 'lex.create'
],
[
'title' => 'List Currencies',
'class' => 'fa fa-fw fa-th-list',
'route' => 'lex.index'
],
'separator',
[
'title' => 'Amazo Damage Types',
'class' => 'fa fa-fw fa-hand-rock-o',
'route' => 'header'
],
[
'title' => 'Add Damage Type',
'class' => 'fa fa-fw fa-plus',
'route' => 'amazo.create'
],
[
'title' => 'List Damage Types',
'class' => 'fa fa-fw fa-th-list',
'route' => 'amazo.index'
]
]
]
✋ NOTE : Headers are optional. Your menu will function just fine without any headers.
Watchtower has a number of defined routes to make it function out of the box. By default these routes are wrapped in a Route::Group using the following three config options as defaults.
You are welcome to change these three options to suit your needs.
- 'middleware' is an array of middlewares you want Watchtower to use. (By default, Laravel 5.2 uses "web" and Laravel 5.1 uses "auth" but you are free to add others to the array.)
- 'prefix' is a string to prepend on your URI routes
- 'as' is a string to use to prepend on the named routes to avoid clashing or to match your existing blade layouts.
An example of the default route options config :
'route' => [
'prefix' => '',
'as' => 'watchtower.',
'middleware'=> ( str_contains( app()->version(), '5.2') ? ['web'] : ['auth'] )
]
An example of a modified route options config to put all routes behind "admin" in the uri (http://YOURSITE/admin/watchtower) and change all the routes to use "office" instead of "watchtower" :
'route' => [
'prefix' => 'admin',
'as' => 'office.',
'middleware'=> ( str_contains( app()->version(), '5.2') ? ['web'] : ['auth'] )
]