Ktor Panel

Maven Central Live Demo GitHub Kotlin Ktor License

A lightweight, customisable admin interface library for Ktor applications. Ktor Panel provides a simple way to manage your database entities through an intuitive and secure web interface with minimal configuration.

Guides

Installation

Gradle (Kotlin DSL)

dependencies {
    implementation("xyz.daimones:ktor-panel:0.4.2")
}

Gradle (Groovy)

dependencies {
    implementation 'xyz.daimones:ktor-panel:0.4.2'
}

Maven

<dependency>
    <groupId>xyz.daimones</groupId>
    <artifactId>ktor-panel</artifactId>
    <version>0.4.2</version>
</dependency>

Quick Start

Basic Setup

// Import necessary components
import xyz.daimones.ktor.panel.Admin
import xyz.daimones.ktor.panel.Configuration
import xyz.daimones.ktor.panel.EntityView
import org.jetbrains.exposed.sql.Database

fun Application.configureAdminPanel(database: Database) {
    // Create admin configuration
    val config = Configuration(
        url = "admin",           // Access at /admin
        adminName = "My App Admin"
    )

    // Initialise admin panel
    val admin = Admin(this, config, database)

    // Add your entities to the admin panel
    admin.addViews(arrayOf(EntityView(Users::class), EntityView(Products::class)))
}

Add to your Ktor application

fun Application.module() {
    // Configure other Ktor features
    install(ContentNegotiation) {
        json()
    }

    // Setup your database connection
    val database = Database.connect(
        "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1",
        driver = "org.h2.Driver"
    )

    // OPTIONAL: Install Mustache for templates (by default ktor-panel configures Mustache for rendering views)
    install(Mustache) {
        val roots = listOf("templates", "panel_templates")
        mustacheFactory = object : DefaultMustacheFactory() {
            override fun getReader(resourceName: String): Reader {
                for (root in roots) {
                    val stream = this.javaClass.classLoader.getResourceAsStream("$root/$resourceName")
                    if (stream != null) {
                        return stream.reader()
                    }
                }
                throw java.io.FileNotFoundException("Template $resourceName not found in $roots")
            }
        }
    }

    // Add admin panel
    configureAdminPanel(database)
}

Customisation

Custom Configuration

val config = Configuration(
   url = "dashboard",          // Change URL to /dashboard
   endpoint = "/",             // Set index endpoint
   setAuthentication = true,   // Enable authentication (default is true)
   adminName = "Custom Admin", // Change admin panel name
   adminUsername = "my_admin", // Set the default username
   adminPassword = "a_very_strong_password" // Set the default password
)

Custom Templates

Create your own Mustache templates in your resources directory to override the defaults:

  • kt-panel-login.hbs - Login form template

  • kt-panel-logout.hbs - Logout template

  • kt-panel-index.hbs - Main dashboard template

  • kt-panel-list.hbs - List view for database records

  • kt-panel-create.hbs - Form for creating new records

  • kt-panel-details.hbs - Detailed view of a record

  • kt-panel-delete.hbs - Confirmation for deleting records

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Acknowledgments