ml-archive/admin-panel-provider

Build easy customizable admin features for your app ✍️

Admin Panel ✍️

Admin Panel makes it easy to setup and maintain admin features for your Vapor project. Here's a list of some of the top feautures that comes out of the box with this package:

• UI Components: Admin Panel is built using AdminLTE, a highly battle-tested and maintained Control Panel Template. This means that you'll have access to features from AdminLTE through Leaf tags.
• User System: This package come with a (admin panel) user system with roles built-in. The package also handles welcome emails and reset-password flows.
• SSO Support: Built-in support for adding your own custom SSO provider.
• Activities: Need to broadcast certain updates to the admin panel users? No problem, Admin Panel gives you some convenient functionality to manage an activity log.

📦 Installation

Install package using SPM

Update your Package.swift file:

.package(url: "https://github.com/nodes-vapor/admin-panel-provider.git", .upToNextMinor(from: "0.7.0")),

targets: [
    .target(
        name: "App",
        dependencies: [
            ...
            "AdminPanelProvider"
        ]
    ),
    ...
]

Next time you run e.g. vapor update Admin Panel will be installed.

Install resources

Copy the Resources and Public folders from this repo into your project. You can download the repo as a zip and then move the folders to the root of your project. Remember to check that you're not overwriting any files in your project.

If you are using Meta don't forget to add the following paths to the exceptPaths array within meta.json:

• "/bower_components/*"
• "/dist/*"
• "/plugins/*"

🚀 Getting started

Add provider

In your Config+Setup.swift (or wherever you setup your providers), make sure to add the Admin Panel provider:

import AdminPanelProvider

// ...

private func setupProviders() throws {
    // ...
    try addProvider(AdminPanelProvider.Provider.self)
}

Also make sure that you add the Fluent provider if it hasn't been already:

try addProvider(FluentProvider.Provider.self)

Setup view renderer

This package relies heavily on the Leaf view renderer. For Admin Panel to work, please make sure that you have added the LeafProvider:

import LeafProvider

// ...

private func setupProviders() throws {
    // ...
    try addProvider(LeafProvider.Provider.self)
}

Make sure your project is using Leaf as the view renderer. You can set leaf as your renderer by setting the key view to the value leaf in your droplet.json. In case it's not given yet, just add it:

"//": "Choose which view renderer to use",
"//": "leaf: Vapor's Leaf renderer",
"view": "leaf",

Seed a user

If you haven't added a SSO provider, the next thing you need to do is to seed a user in order to be able to login into your new admin panel. To do this, add the seeder command to your commands array in your droplet.json:

"//": "Choose which commands this application can run",
"//": "prepare: Supplied by the Fluent provider. Prepares the database (configure in fluent.json)",
"commands": [
    "prepare",
    "admin-panel:seeder"
],

Now you have two ways of running the seeder. You either run the seeder in your terminal by:

vapor build; vapor run admin-panel:seeder

Or you temporarily edit the Run scheme in Xcode and add admin-panel:seeder under "Arguments Passed On Launch". This will run the seeder when you run the project. Run the project and remove the argument after the user has been seeded.

The user that will be created using the seeder will have the following credentials:

• Email: [email protected]
• Password: admin

Vapor & Fuzzy Array

Vapor has a Node.fuzzy array that's used for dynamically casting at runtime. If you're experiencing inconsistencies with rendering templates it's most likely because your fuzzy array is missing ViewData.self Ensure that you have added it to the array or that all of your models conform to JSON/Node. Example Node.fuzzy:

extension Config {
    public func setup() throws {
        // allow fuzzy conversions for these types
        // (add your own types here)
        Node.fuzzy = [JSON.self, Node.self, ViewData.self]

Custom Leaf tags

Admin Panel comes with a bunch of custom Leaf tags that help ease the burden of frontend development. Check out the full list here.

CORS:

It's highly recommended that you add the CORS middleware to your project.

🔧 Configurations

Admin Panel can be configured by (adding or) modifying the adminpanel.json config file. Below is a breakdown of the available keys.

Key	Example value	Required	Description
name	My Tech Blog	No	This will be the title inside of the admin panel.
baseUrl	http://mytechblog.com	No	This will be used to generate urls for the admin panel (e.g. when resetting a password).
skin	green-light	No	The skin to use for the admin panel. The options will correspond to the available skins supported by AdminLTE. Please omit the skin- prefix when specifying the skin.
email	{"fromName": "Admin Panel", "fromAddress": "[email protected]"} `	No	This will be used to configure the AdminPanel's mailer.

🔐 SSO

Single sign-on can be a convenient way to offer users of your project to login into your admin panel.

🏆 Credits

This package is developed and maintained by the Vapor team at Nodes. The package owner for this project is Steffen.

📄 License

This package is open-sourced software licensed under the MIT license

admin-panel-provider's Issues

Make it possible to redefine routes

Currently we are using a workaround by just define the same route again in Droplet+Setup.swift but with another destination.

It would be nice if you could do something like in JWTKeychain: pass in a delegate that subclasses the AdminPanel delegate so you can override functions.

In addition it would be nice to not change the direction (controller + function) but the route itself.
Say a route /admin/backend/users is defined by AdminPanle. But you want the route to say /admin/backend/admins instead while at the same time keeping the destination/controller/function.

Improve README

We need have some documentation on the structure of the package as well as some examples on the different leaf tags.

Nodes SSO button

Figure out how we should handle the Nodes SSO button in the top right corner. Should that be a modified index page that comes with the SSO package instead? Not relevant for people outside of Nodes.

updating a profile leads always to password regeneration

Vapor 3

Hi All

Is there any plan to upgrade this project to use Vapor 3 ?

Thanks
Dave

updating your email should send verification token to email

Gracefully handle a large number of pages

See ml-archive/paginator#49 for details

verify shouldResetPassword works when updating user

ViewData and Node.Fuzzy

Figure out how to handle/avoid the ViewData type being added to Node.fuzzy. @BrettRToomey knows the details.

restrict admin to be able to create and delete super admin

API documentation

Make API documentation throughout the code base.

Allow supplying your own user type

This can be achieved by using protocols and providing a default type that conforms to them.

How do I use this package?

Sorry, these might be really basic questions, but it seems like the documentation on this package is very thin. On the other hand, I could imagine many other people trying to get started with this package would have similar questions, so it might be useful to answer these in a convenient-to-access place — possibly in a proper "Getting Started" tutorial. (The current "Getting started" section does not cover any of these questions; it essentially stops after installing the package but does not cover using it.)

Please note that I already have some experience building a Fluent+Vapor-based API, but little experience serving HTML pages using Leaf.

Here are the questions:

1. Is this supposed to be just another dependency on my Vapor-based web app that adds e.g. an "/admin/" path, or will this run a separate standalone HTTP server on a different port? (The *Routes.swift files indicate the former, but I am not entirely sure.)
2. If the first case is true, how am I supposed to add extra routes (e.g. to show a table of all entities of a specific type) to my admin panel? Is there an example of adding such a route/displaying such a table somewhere? How could I add the route to show up as an item in the panel's navigation menu?
3. Similarly, how can I ensure that the panel's UI chrome (e.g. the navigation bar) is displayed on these custom tables, so that it fits in with the rest of the panel? In general, how would I supposed to render such a table?
4. The documentation says "It's highly recommended that you add the CORS middleware to your project.". Why? What does CORS enable in this case?

I would really appreciate some guidance on these questions. Thanks!

What mailer should be used?

Should we just use the mailer from the Droplet?

CSRF/CORS

Look into this and figure what needs to be done.

Backend user with "User" role cannot reset password

The update route is not accessible for "user" roles which means they end up in a loop when they need to (force) reset password:
https://github.com/nodes-vapor/admin-panel-provider/blob/82f16e0531cddcb77b52ef6a0d42426a7a6a0642/Sources/AdminPanelProvider/Controllers/AdminPanelUserController.swift#L143

Remove password encryption from AdminPanelUser.init

Add GateKeys like "Super Admin" etc.

I one would like to query all let's say admins from the database, it would be nice to have keys for these string instead of either having to define the Keys for each project or at worst, typing the strings yourself: "Super Admin", "Admin", "User"

Incorrect errors on tags when providing illegal input

As an example, SelectGroup throws an Abort error with an incorrect "reason" string.

Flash error messages based on environment

Consider if it makes sense to abstract flash error messages depending on environment

auditEvents vs actions

It seems like Action is a leftover from before we integrated/made the Audit package. Go through codebase and see if we can remove Action (e.g. check how recent activities works in the UI).

Title missing

It seems like the title (<title>) is missing on some pages.

Being able to define a redirect route after login

It would be nice it we were able to somehow define where the user gets redirected to after login instead of having it statically se to dashboard

Consider more flexible role system

We currently distinguish between super-admin, admin, and user. Each role comes with its own, fixed privileges.
A more flexible system could be on with roles and privileges. A role would would be a group of privileges (1 to n relation). Examples of privileges could be:

• create/update/delete user
• grant privilege to user
• view section 'x'

A few standard privileges can come bundled with the package but they could be extended for clients' use cases.

@steffendsommer @BrettRToomey what do you think?

Deploy demo project

Let's get a project deployed using the package where we can show all the different leaf tags that are currently implemented

consider adding exception path when using meta

when adding Public folder and the project uses the Meta-Middleware please add a gotcha to add the paths to the exceptPaths array in meta.json

Why is mysql-provider a dependency?

The package manifest (https://github.com/nodes-vapor/admin-panel-provider/blob/master/Package.swift) contains this line:

        .Package(url: "https://github.com/vapor/mysql-provider.git", majorVersion: 2),

yet the code doesn't reference MySQL explicitly anywhere. So why is this a dependency? Could this package be used with a PostgreSQL database (and the corresponding Fluent provider) as well?

Remember me feature

• Checked = store cookie (e.g. 60 days) which would auto-login the user until one logs out manually.
• Not checked = automatically logged out after closing the browser

Keep password requirements consistent

When resetting password you can have a password like admin
When setting your password via the edit view in the cms it requires a more complex one like Password1!

Look at UX/UI

Go through the package and consider if it's good enough from a UX/UI standpoint.

Suggestion: #button:delete

Currently the LeafTag #button:delete forces a sr-only of Delete User.

Suggestion to change it to:

Delete \(title)

Or add an option third option for the sr-only