DEV Community: abidibo

wezterm-cmdpicker: A Command Palette for Your WezTerm Terminal

abidibo — Thu, 12 Mar 2026 14:20:15 +0000

If you've ever used whichkey in Neovim, you know the feeling: you press a key, a popup appears, and suddenly all your bindings are right there — discoverable, searchable, no memorization required.

I wanted that same experience in WezTerm. So I built wezterm-cmdpicker.

In short:

Fuzzy-searchable command palette for all your WezTerm keybindings
Auto-discovers bindings from your config — no re-definition needed
Register action-only commands (SSH servers, Docker workflows, anything) without keybindings
Color-coded layers: your registered bindings, config bindings, and WezTerm defaults
Smart deduplication — overridden defaults are hidden automatically

The Problem

WezTerm is an incredibly powerful terminal emulator with a Lua-based configuration that lets you bind pretty much anything to a key combination. The downside? Once you have 20, 30, or 50+ keybindings, good luck remembering them all.

You end up in a loop:

"What was the shortcut for splitting panes again?"
Open your config file
Scroll through a wall of keybindings
Find it, go back to the terminal
Forget it again next week

Sound familiar?

The Solution

wezterm-cmdpicker adds a command palette to WezTerm. Press one key combo (default: Leader + Space) and a fuzzy-searchable picker pops up showing all your keybindings — with descriptions, organized by source, and color-coded for clarity.

It works through a 3-layer discovery system:

Registered bindings (yellow) — keybindings you explicitly register with descriptions through the plugin
Config bindings (cyan) — keybindings from your config.keys table, auto-discovered without any extra work
Default bindings (grey) — WezTerm's built-in defaults, optionally included

The key idea: you don't have to re-define your existing keybindings. If they're already in config.keys, the plugin picks them up automatically. You only register explicitly when you want to add a human-readable description.

If you override a WezTerm default (say, rebinding Ctrl+Shift+T), only your version shows up in the picker. No duplicates, no confusion.

Getting Started

Here's a complete working example:

local wezterm = require('wezterm')
local act = wezterm.action
local config = wezterm.config_builder()

-- Load the plugin
local cmdpicker = wezterm.plugin.require(
  'https://github.com/abidibo/wezterm-cmdpicker'
)

-- Register keybindings with descriptions
cmdpicker.add_keys(config, {
  {
    key = 'n',
    mods = 'LEADER',
    action = act.SpawnTab('CurrentPaneDomain'),
    desc = 'New tab',
  },
  {
    key = 'x',
    mods = 'LEADER',
    action = act.CloseCurrentPane({ confirm = true }),
    desc = 'Close pane',
  },
  {
    key = 'z',
    mods = 'LEADER',
    action = act.TogglePaneZoomState,
    desc = 'Toggle zoom',
  },
})

-- Any binding added directly to config.keys is also discovered
table.insert(config.keys, {
  key = 'f',
  mods = 'LEADER',
  action = act.ToggleFullScreen,
})

-- Apply the picker (must be called LAST)
cmdpicker.apply_to_config(config, {
  title = 'Command Palette',
})

return config

That's it. Press Leader + Space, start typing, and find any command instantly.

Real-World Use Cases

1. Separate Keybindings File

Many people keep keybindings in a separate file for organization. cmdpicker handles this cleanly:

-- keybindings.lua
local wezterm = require('wezterm')
local act = wezterm.action

return {
  {
    key = 'h',
    mods = 'LEADER',
    action = act.SplitHorizontal({ domain = 'CurrentPaneDomain' }),
    desc = 'Split horizontal',
  },
  {
    key = 'v',
    mods = 'LEADER',
    action = act.SplitVertical({ domain = 'CurrentPaneDomain' }),
    desc = 'Split vertical',
  },
}

-- wezterm.lua
config.keys = require('keybindings')

-- Single-arg form: registers for the picker
-- without modifying config.keys
cmdpicker.add_keys(config.keys)

cmdpicker.apply_to_config(config)

2. SSH Server Quick Access

This one is my favorite. You can register action-only commands — entries that appear in the picker without needing a keybinding:

local servers = {
  { name = 'Production', host = 'user@prod.example.com' },
  { name = 'Staging', host = 'user@staging.example.com' },
  { name = 'Dev', host = 'user@dev.example.com' },
}

for _, s in ipairs(servers) do
  cmdpicker.register({
    action = act.SpawnCommandInNewTab({
      args = { 'ssh', s.host },
    }),
    desc = 'SSH: ' .. s.name .. ' (' .. s.host .. ')',
  })
end

Now open the picker, type "ssh", and all your servers are right there. No keybinding needed, no separate SSH manager, just your terminal.

3. Project-Specific Workflows

Build quick-access commands for your daily workflows:

cmdpicker.register({
  {
    action = act.SpawnCommandInNewTab({
      args = { 'docker', 'compose', 'up', '-d' },
    }),
    desc = 'Docker: Start services',
  },
  {
    action = act.SpawnCommandInNewTab({
      args = { 'docker', 'compose', 'logs', '-f' },
    }),
    desc = 'Docker: Follow logs',
  },
  {
    action = act.SpawnCommandInNewTab({
      args = { 'lazygit' },
    }),
    desc = 'Open lazygit',
  },
})

Configuration Options

The apply_to_config function accepts several options to customize the picker:

cmdpicker.apply_to_config(config, {
  key = ' ',                          -- Trigger key (default: Space)
  mods = 'LEADER',                    -- Trigger modifiers (default: LEADER)
  title = 'Command Palette',          -- Picker window title
  include_defaults = true,            -- Include WezTerm defaults
  include_key_tables = false,         -- Include copy_mode, search_mode, etc.
  fuzzy = true,                       -- Enable fuzzy search
  fuzzy_description = 'Search: ',     -- Search prompt text
})

Try It Out

If you're not on WezTerm yet — it's a GPU-accelerated, cross-platform terminal emulator configured entirely in Lua, with a built-in plugin system. With cmdpicker, it gets the kind of command palette you know from VS Code — right in your terminal.

The plugin is open source and takes one line to install:

GitHub: github.com/abidibo/wezterm-cmdpicker

If it saves you a trip to your config file, drop a star on the repo. And if you have ideas or find bugs, issues and PRs are welcome!

WebSocket Mock Server with a Beautiful Terminal UI

abidibo — Thu, 08 Jan 2026 13:47:10 +0000

The problem: WebSockets are cool, but testing them sucks

Let's be honest. We all love json-server for quickly mocking REST APIs during development. You create a db.json file, run one command, and boom - you have a fake API. Beautiful. Simple. Fast.

But what about WebSockets?

If you're building real-time features (chat apps, live notifications, collaborative editors, stock tickers...), you know the pain:

Your backend team is still working on the WebSocket endpoints
You need to test different data scenarios but restarting the backend is slow
You want to see what's happening with connections and messages in real-time
Setting up a proper WebSocket mock server is... annoying

Many years ago, I wrote ws-server-ftw. Now archived, it’s been reborn with a new face and a new package name: @abidibo/ws-server-ftw — basically json-server’s cool, simpler cousin that speaks WebSocket and comes with a gorgeous Terminal UI.

Why Should You Care?

Here's what you get:

✨ Works like json-server: Point it to a JSON file (or a js file which exports an object), and it serves data via WebSocket
🎨 Beautiful TUI: See connections, messages, and your database in real-time with syntax highlighting
🔄 Live updates: Send data to connected clients with merge, deep-merge, or append operations
📍 Path-based routing: Different WebSocket paths serve different parts of your database
⚡ Fast development: No backend needed, change data on the fly

Installation

npm install @abidibo/ws-server-ftw --save-dev

Quick Start (It's Really Simple)

1. Create a database file (db.json):

{
  "api": {
    "v1": {
      "chat": {
        "messages": [
          {
            "id": 1,
            "user": "Alice",
            "text": "Hey there!",
            "timestamp": "2025-01-08T10:00:00Z"
          }
        ]
      },
      "notifications": {
        "unread": 5,
        "items": []
      }
    }
  }
}

2. Start the server:

npx ws-server -i db.json

3. Connect from your app:

const ws = new WebSocket('ws://localhost:9704/api/v1/chat');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
  // You get: { messages: [...] }
};

That's it. Your WebSocket client automatically receives the data from db.api.v1.chat.

The TUI is Where Magic Happens

When you run ws-server, you get this beautiful terminal interface with four panels and an informative header:

1. Connections Panel (Top Left)

See all connected clients in real-time. Each connection shows:

Connection ID
WebSocket path
Sent/Received messages

Use arrow keys to select a connection, press x to kill it (perfect for testing reconnection logic).

2. Command Input Panel (Bottom Left)

Send data to the selected connection with powerful commands:

Resend original data (press Enter with empty input):

[Enter]

Merge data (shallow - replaces top-level keys):

merge {"unread": 10}

Deep merge (recursive - keeps nested properties):

deepmerge {"messages": [{"id": 2, "user": "Bob", "text": "Hello!"}]}

Append to arrays:

append [{"id": 3, "user": "Charlie", "text": "Hi everyone"}]

Send raw JSON:

{"status": "updated", "timestamp": 1234567890}

Update the database permanently:

db set api.v1.chat.unread 0

3. Database Viewer (Middle Panel)

Your entire database with beautiful syntax highlighting:

Keys in cyan
Strings in green
Numbers in yellow
Booleans in magenta

Press r to refresh from file if you edit it manually.

4. Message Log (Right Panel)

Every connection/disconnection event and every WebSocket message, sent and received.

Real-World Example: Building a Chat App

Let's say you're building a chat application. Here's your workflow:

1. Set up your mock data:

{
  "chat": {
    "rooms": {
      "general": {
        "messages": [
          {"id": 1, "user": "Alice", "text": "Hello world"}
        ],
        "users": ["Alice", "Bob"]
      }
    }
  }
}

2. Start the server:

ws-server -i chat-db.json -p 8080

3. Connect your frontend to ws://localhost:8080/chat/rooms/general

4. Test different scenarios from the TUI:

Want to simulate a new message?

deepmerge {"messages": [{"id": 2, "user": "Bob", "text": "Hi Alice!"}]}

Want to test a user leaving?

db set chat.rooms.general.users ["Alice"]

Then press Enter to resend.

Want to see how your UI handles connection drops? Select the connection and press x.

All without touching your backend code.

Path-Based Routing

The server uses paths to serve different data:

// Connect to ws://localhost:9704/api/v1/chat
// Receives: db['api']['v1']['chat']

// Connect to ws://localhost:9704/notifications
// Receives: db['notifications']

This means one database file can serve multiple WebSocket endpoints. Just like real-world APIs.

Use Cases (When This Tool Shines)

🎮 Frontend development: Build your real-time UI without waiting for backend
🧪 Testing: Create predictable WebSocket responses for integration tests
🎨 Prototyping: Demo WebSocket features to clients/stakeholders quickly
🐛 Debugging: Test edge cases and error scenarios easily
📚 Learning: Experiment with WebSocket APIs without complex setup

Tech Stack (For the Curious)

Built with:

TypeScript
Ink - React for terminals (yes, the TUI is React components!)
ws - the battle-tested WebSocket library
Node.js ESM - modern module system

Tips and Tricks

Use JavaScript files instead of JSON if you need dynamic data:

// db.js
export default {
  api: {
    users: Array.from({ length: 100 }, (_, i) => ({
      id: i + 1,
      name: `User ${i + 1}`
    }))
  }
};

Then: ws-server -i db.js

Navigate the TUI like a pro:

Tab - Switch between panels
Arrow keys - Navigate/scroll in focused panel
r - Refresh database (in DB panel)
x or c - Close connection (in Connections panel)
q or Ctrl+C - Quit

Limitations (Being Honest)

This tool is for development and testing. It's not meant for production. It:

Doesn't handle authentication
Doesn't scale to thousands of connections
Doesn't persist data between restarts (unless you use db set)

But for local development? It's perfect.

Try It Out!

npx @abidibo/ws-server-ftw -i your-db.json

No installation needed with npx. Give it a try on your next WebSocket project.

Star the Repo! ⭐

If this tool saves you time (or if you just think the TUI looks cool), drop a star on GitHub:

👉 github.com/abidibo/ws-server-ftw

Found a bug? Want a feature? Open an issue

Wrapping Up

WebSocket development doesn't have to be painful. With @abidibo/ws-server-ftw, you get:

Fast setup (one command)
Visual feedback (beautiful TUI)
Full control (send any data anytime)
Zero backend dependency

It's the json-server experience, but for WebSockets, with a gorgeous terminal UI on top.

Give it a try and let me know what you think!

Happy coding! 🚀

Links:

Django Baton v5.0 Released

abidibo — Tue, 03 Jun 2025 14:35:42 +0000

Django Baton 5.0: Modernizing Admin Interfaces with a Fresh Look and Enhanced Intelligence

The Django admin has long been a cornerstone of rapid development. For developers seeking a more modern and customizable experience, Django Baton offers (since 2017) a dedicated solution to transform the admin into a sleek, responsive, and feature-rich control panel. With the release of version 5.0.0, Baton takes a notable step forward, introducing a comprehensive visual overhaul that aims to enhance the Django admin experience.

If you're looking to elevate your Django projects with an admin interface that balances power with user-friendliness, we believe Baton 5.0 offers significant improvements.

The v5.0.0 Refresh: A Visual and Technical Update

Version 5.0.0 is a significant update for Django Baton, focusing on a complete restyling of the application. This update is more than a minor theme change; it's an important step designed to improve usability, modernize the aesthetic, and align with contemporary design principles.

Key Visual Highlights of Baton 5.0

Full UI Restyling with Bootstrap 5:
Baton continues to build upon Bootstrap 5, and v5.0.0 further refines this integration. Users can expect cleaner lines, improved spacing, more intuitive component interactions, and an overall more polished and professional appearance across the admin interface.
Introducing Google Material Symbols:
A major change in this release is the transition from FontAwesome to Google Material Symbols. This move offers several benefits:
- Modern & Consistent Aesthetics: Material Symbols provide a vast library of clean, contemporary icons that fit well with modern web design trends.
- Potential Performance & Customization Improvements: As variable icon fonts, Material Symbols can offer good performance and more granular control over aspects like optical size, weight, fill, and grade.
- Seamless Integration: This helps create a more unified visual language throughout the Baton interface.
Refined Typography with Inter Tight & Archivo Narrow:
Baton 5.0 enhances readability and modernizes its typographic appeal by replacing the Dosis font. It now utilizes Inter Tight for general UI text and body content, known for its excellent legibility on screens, and Archivo Narrow for headings, providing a sharp, contemporary, and space-efficient display style. This combination contributes to a cleaner and more professional visual hierarchy.

Why Baton Still Shines: Core Features in a New Light

Beyond the visual refresh, Baton 5.0 retains the powerful feature set that has made it a popular choice for many Django developers:

🧠 AI-Powered Admin (Introduced in v4.x):
- Automatic Translations: Integrates smoothly with django-modeltranslation.
- Text Intelligence: Provides summarization and correction capabilities.
- Image Understanding & Generation: Includes image vision for alt text generation and DALL·E 3 integration for creating images directly within the admin. (A Baton subscription key is required for full AI functionality)
🔧 Extensive Customization:
- Flexible Sidebar Menu: Configure your navigation with a JSON-based structure, supporting titles, app lists, model links, and custom free links with icons and permissions.
- Themes: Easily apply pre-built themes or create your own by overriding CSS variables. The v5.0 restyling enhances the impact of these themes.
- Layout Control: Offers options for modal filters, fixed submit rows, collapsable user areas, and more.
🚀 Improved Developer & User Experience:
- Minimal Template Overrides: Baton's approach is to enhance the admin primarily through CSS and JS, helping staying away from serious bugs when Django version changes.
- Advanced Filters & Includes: Provides text input filters, dropdown filters, multiple-choice filters, and the ability to inject custom templates into changelist and change form pages.
- Dynamic Row Attributes & Form Tabs: Allows adding custom attributes to changelist rows/cells and organizing complex forms with an intuitive tabbed interface.

Migrating to Baton 5.0: Smooth and Forward-Looking

Upgrading from Baton v4.x to v5.0.0 is designed to be straightforward. However, due to the significant visual changes and the switch in icon libraries, there are a few key points to consider:

Django Compatibility: Baton 5.0.0 is intended for Django >= 5.x. If you are on older Django versions (2.1 to <5.x), it's recommended to stick with Baton 4.x.
Icon Changes: If you've customized templates or CSS that directly referenced FontAwesome icon classes, these will need to be updated to use Material Symbols. The icon property in the MENU configuration, for example, now expects Material Symbol names.
Theme Updates: If you're using custom themes, they might need tweaking to fully leverage the v5.0 restyling and new icon set.

For detailed instructions and potential breaking changes, please refer to the official Migrate from v4 to v5 Wiki Page.

Explore the Latest in Django Admin Interfaces

Django Baton 5.0.0 is more than just an update; it's a refinement of our vision to provide a modern, capable, and developer-friendly admin interface for Django. The new styling and adoption of Material Symbols aim to significantly enhance the user experience, making your admin panel more functional and visually appealing.

🚀 Try the Live Demo: See Baton 5.0 in action at django-baton.sqrt64.it (Login: demo/demo).
🛠️ Install or Upgrade:
```
pip install "django-baton>=5.0.0"
```
Follow the installation instructions in the documentation.
📖 Dive into the Documentation: Explore all features and configuration options at django-baton.readthedocs.io.

Conclusion

With its v5.0.0 release, Django Baton continues to be a strong option for developers looking for an alternative to the traditional Django admin aesthetic. The focus on a modern user experience, combined with useful AI integrations and deep customization options, makes Baton a valuable tool for many Django projects.

We invite you to try Django Baton 5.0 and see how it can enhance your admin panel.

We welcome your feedback and contributions!

A wezterm sessions plugin

abidibo — Tue, 11 Feb 2025 08:15:55 +0000

In this article I'll introduce you WezTerm Sessions, a new WezTerm sessions plugin.

So I was searching for a session manager (similar to tmux) for WezTerm. WezTerm is a powerful terminal emulator with many features and is highly configurable using Lua scripting, much like NeoVim.

I found several existing solutions, but none of them worked well for me. The most comprehensive one, resurrect.wezterm had issues — it randomly messed up my terminal layout and occasionally caused my tab bar to disappear.

For this reason I decided to fork WezTerm Session Manager by Daniel Copper adding some functionalities that were left unimplemented. Eventually, I refactored the entire codebase and added even more features, so I decided to rename the project. And here we are.

Before listing the features of this plugin, let me clarify one thing: I am a Linux-only user. I haven't tested, nor do I plan to test, new features on Windows or macOS. If anyone is willing to contribute in that regard, it would be much appreciated.

Features

Save a workspace state – The state (windows, tabs, panes, and foreground processes) is stored in a JSON file so it can be recovered later. Foreground process detection works well for my use cases, but it may not be perfect.
Restore a session state – When activating a workspace, you can attempt to restore its saved state.
Load a session state – You can switch to a workspace and restore it in one step, selecting the workspace via fuzzy search.
Delete a session state – Fuzzy search for a saved session and delete it.
Edit a session state – Fuzzy search for a workspace state and open it in your preferred editor ($EDITOR) for modifications. This can be useful for tweaking the tty key, which represents the command to be executed. If the foreground process wasn’t detected correctly during saving, you can fix it manually.

Installation

Add the following to your WezTerm configuration:

 local sessions = wezterm.plugin.require("https://github.com/abidibo/wezterm-sessions")
 sessions.apply_to_config(config) -- optional, this adds default keybindings

The second line is optional and unnecessary if you prefer to set your own keybindings.

Configuration

You can define your own keybindings (the following are the defaults):

config.keys = {
    {
        key = 's',
        mods = 'ALT',
        action = act({ EmitEvent = "save_session" }),
    },
    {
        key = 'l',
        mods = 'ALT',
        action = act({ EmitEvent = "load_session" }),
    },
    {
        key = 'r',
        mods = 'ALT',
        action = act({ EmitEvent = "restore_session" }),
    },
    {
        key = 'd',
        mods = 'CTRL|SHIFT',
        action = act({ EmitEvent = "delete_session" }),
    },
    {
        key = 'e',
        mods = 'CTRL|SHIFT',
        action = act({ EmitEvent = "edit_session" }),
    },
}

in order to use the restore functionality may be useful to easily rename the current workspace or create a new namespace with a custom name, so for example you can add two keybindings like the following:

-- Rename current workspace
{
    key = '$',
    mods = 'CTRL|SHIFT',
    action = act.PromptInputLine {
        description = 'Enter new workspace name',
        action = wezterm.action_callback(
            function(window, pane, line)
                if line then
                    wezterm.mux.rename_workspace(wezterm.mux.get_active_workspace(), line)
                end
            end
        ),
    },
},
-- Prompt for a name to use for a new workspace and switch to it.
{
    key = 'w',
    mods = 'CTRL|SHIFT',
    action = act.PromptInputLine {
        description = wezterm.format {
            { Attribute = { Intensity = 'Bold' } },
            { Foreground = { AnsiColor = 'Fuchsia' } },
            { Text = 'Enter name for new workspace' },
        },
        action = wezterm.action_callback(function(window, pane, line)
            -- line will be `nil` if they hit escape without entering anything
            -- An empty string if they just hit enter
            -- Or the actual line of text they wrote
            if line then
                window:perform_action(
                    act.SwitchToWorkspace {
                        name = line,
                    },
                    pane
                )
            end
        end),
    },
},

Events

WezTerm Sessions triggers several events that you can use to react and perform actions when something happens. Each available action emits a start and end event:

wezterm-sessions.save.start(file_path)
wezterm-sessions.save.end(file_path, res)
wezterm-sessions.load.start(workspace_name)
wezterm-sessions.load.end(workspace_name)
wezterm-sessions.restore.start(workspace_name)
wezterm-sessions.restore.end(workspace_name)
wezterm-sessions.delete.start(file_path)
wezterm-sessions.delete.end(file_path, res)
wezterm-sessions.edit.start(file_path, editor)

Limitations

This plugin works well in my scenario, but there are a few caveats:

As mentioned, it has not been tested on Windows or macOS. Additionally, on Windows, the foreground process of a pane is not detected.
Remote sessions can be tricky. Before restoring or load a session you have to connect to your host:
```
wezterm connect SSHMUX:hostname
```
Also foreground processes are not detected, but you can use the edit action to fix it. Maybe there are other issues with remote session I'm not aware of, because I barely use it.
The plugin should be able to restore even complex pane layouts, but who knows.
The current active tab/pane is not restored at the moment, not difficult to implement, but it's a feature I'm really not missing at the moment.

Conclusions

WezTerm Sessions is a WezTerm plugin that adds session (workspace) management to your favorite terminal multiplexer. It is designed to work well on Linux (and hopefully macOS) but does not support Windows. Contributions to improve Windows compatibility are welcome.

In my use cases, it works pretty well, restoring complex layouts with foreground processes while allowing you to save, restore, load, delete, and edit states easily.

Baton: a cool, modern and responsive Django admin application based on Bootstrap 5

abidibo — Mon, 22 Mar 2021 15:07:26 +0000

I must admit, one of the features that made me immediately fall in love with Django was the built-in admin application. Coming from a PHP framework, constructing all the CRUD stuff by hand, application after application, and suddenly having all this stuff autogenerated was a big deal.

The problem is, the Django default admin application doesn't look really cool, does it? It surely does its job and includes the most important features, but I'm not sure it could be delivered to a client without tweaking it. I mean, almost every web application framework or CMS has a pretty admin area, and people are somewhat used to something similar.

Here at Otto srl we (also) develop web applications, and we do that from scratch using the Django framework. We tend to use the Django admin application to provide access to data whenever possible.
We used to adopt django-suit as admin application because it really looked nice. The problem is that django-suit was based on bootstrap 2 and even if darklow started developing a v2 based on bootstrap 4, such version never really come to life.

That's why we decided to develop our own Django admin application, and that's the beginning of Django Baton. The project started in February 2017, so it turned 4 years old this year :).
We use it extensively in every web application, we really have many projects deployed in production using it and that's why we continue its development and fix bugs quite quickly.

Django Baton

Baton is a cool, modern and responsive Django admin application based on Bootstrap 5.

It was built with one concept in mind: override as few Django stuff as possible.

If you're wondering why the answer is: in order to stay as much compatible with the default Django admin.
We are quite satisfied with the default admin app features, we just want it to be more appealing. Not overriding things is also a good way to prevent bugs. Baton can work with every Django/python version without too much effort, and only recently, in v2, we dropped support for Django < 2.1, and it was by design, because boys, it's time to abandon python 2 and move on.

First things first

You can try it. There's a live demo available here.
It's MIT licensed and the repo project is available here.
The documentation covers every aspect of the application, and it's available here.

Features

Based on Bootstrap 5 and FontAwesome Free 5
Fully responsive (really)
Custom and flexible sidebar menu
Configurable search field
Text input filters and dropdown list filters facilities
Form tabs out of the box
Easy way to include templates in the change form and change list pages
Easy way to add attributes to change list table rows/cells
Collapsable stacked inline entries
Lazy loading of uploaded images
Optional display of changelist filters in a modal
Optional use of changelist filters as a form (combine some filters at once and perform the search action)
Optional index page filled with google analytics widgets
Customization available recompiling the js app provided
Supports custom translations

Getting started

You can install Baton directly from pip:

$ pip install django-baton

Add baton and baton.autodiscover to your INSTALLED_APPS:

INSTALLED_APPS = (
    # ...
    'baton', # place it before django.contrib.admin
    'django.contrib.admin',
    # ...
    'baton.autodiscover', # place it at the very end
)

Replace django.contrib.admin in your project urls, and add Baton urls:

# from django.contrib import admin
from baton.autodiscover import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('baton/', include('baton.urls')),
]

You need to add both baton and baton.autodiscover to your INSTALLED_APPS in order to avoid registering all applications directly to Baton. Baton autodiscover module will run last and will detect all the applications registered to the default admin and make use of them. This way you can easily switch from one admin application to another one, and you can easily integrate Baton into any existing project.

Configuration

Let's see a full configuration example:

# in your settings.py
BATON = {
    'SITE_HEADER': 'Baton',
    'SITE_TITLE': 'Baton',
    'INDEX_TITLE': 'Site administration',
    'SUPPORT_HREF': 'https://github.com/otto-torino/django-baton/issues',
    'COPYRIGHT': 'copyright © 2020 <a href="https://www.otto.to.it">Otto srl</a>', # noqa
    'POWERED_BY': '<a href="https://www.otto.to.it">Otto srl</a>',
    'CONFIRM_UNSAVED_CHANGES': True,
    'SHOW_MULTIPART_UPLOADING': True,
    'ENABLE_IMAGES_PREVIEW': True,
    'CHANGELIST_FILTERS_IN_MODAL': True,
    'CHANGELIST_FILTERS_ALWAYS_OPEN': False,
    'CHANGELIST_FILTERS_FORM': True,
    'MENU_ALWAYS_COLLAPSED': False,
    'MENU_TITLE': 'Menu',
    'MESSAGES_TOASTS': False,
    'GRAVATAR_DEFAULT_IMG': 'retro',
    'LOGIN_SPLASH': '/static/core/img/login-splash.png',
    'SEARCH_FIELD': {
        'label': 'Search contents...',
        'url': '/search/',
    },
    'MENU': (
        { 'type': 'title', 'label': 'main', 'apps': ('auth', ) },
        {
            'type': 'app',
            'name': 'auth',
            'label': 'Authentication',
            'icon': 'fa fa-lock',
            'models': (
                {
                    'name': 'user',
                    'label': 'Users'
                },
                {
                    'name': 'group',
                    'label': 'Groups'
                },
            )
        },
        { 'type': 'title', 'label': 'Contents', 'apps': ('flatpages', ) },
        { 'type': 'model', 'label': 'Pages', 'name': 'flatpage', 'app': 'flatpages' },
        { 'type': 'free', 'label': 'Custom Link', 'url': 'http://www.google.it', 'perms': ('flatpages.add_flatpage', 'auth.change_user') },
        { 'type': 'free', 'label': 'My parent voice', 'default_open': True, 'children': [
            { 'type': 'model', 'label': 'A Model', 'name': 'mymodelname', 'app': 'myapp' },
            { 'type': 'free', 'label': 'Another custom link', 'url': 'http://www.google.it' },
        ] },
    ),
    'ANALYTICS': {
        'CREDENTIALS': os.path.join(BASE_DIR, 'credentials.json'),
        'VIEW_ID': '12345678',
    }
}

I won't describe here each available setting, they're all well explained in the documentation or in the repo page.

But I'd like to explore here in more detail some of the coolest features which Baton provides.

Login splash

As shown in the cover image of this post, you can easily customize the login page providing an image background, just use the LOGIN_SPLASH option.

Sidebar

The sidebar is very handy. True, the last Django version comes with a default sidebar menu in its admin app but is not very configurable and I don't like it very much.
I think Baton does a good job here, providing a nice and extremely configurable sidebar menu to your application. Baton also provides a search field widget, that can be very powerful, more on it later.

Baton sidebar is visible by default on desktop devices, but you can decide to collapse it (see MENU_ALWAYS_COLLAPSED option) and make it accessible through a dedicated icon in the top bar if you need more space for your data (same behaviour as for mobile devices).
Also, the user area can be collapsed to save some space in the sidebar, see the COLLAPSABLE_USER_AREA option.

Baton menu system offers four kinds of menu items: title, app, model and free. I won't cover here all the possible configuration since this is explained in detail in the documentation, but let's say that:

title items can be used to group other items
app items lets you create a menu iten for an application, whose children items are all the models of the app (but you can customize the children prop)
model items lets you create a menu item for a model
free items can be used to create any other kind of menu items (you can provide an URL, an icon and a regular expression to indicate when an item should be considered active, the match is calculated against the URL path).

What follows is an example of the menu configuration.

help_modal = '''
modalContent = `
    <div>
        <p><strong style="font-weight: 900">Welcome to django-baton!</strong></p>
    </div>
`;
modal = new Baton.Modal({
    title: 'Help',
    content: modalContent,
});
modal.open();
'''

BATON = {
    'MENU': (
        { 'type': 'title', 'label': 'System', 'apps': ('auth', ) },
        {
            'type': 'model',
            'app': 'auth',
            'name': 'user',
            'label': 'Users',
            'icon': 'fa fa-user',
        },
        {
            'type': 'model',
            'app': 'auth',
            'name': 'group',
            'label': 'Groups',
            'icon': 'fa fa-users',
        },
        { 'type': 'title', 'label': 'Contents', 'apps': ('kitchensink', ) },
        {
            'type': 'model',
            'app': 'kitchensink',
            'name': 'news',
            'label': 'News',
            'icon': 'fa fa-newspaper',
        },
        { 'type': 'title', 'label': 'Utilitites', 'apps': () },
        {
            'type': 'free',
            'url': 'javascript:%s' % help_modal,
            'label': 'Help',
            'icon': 'fa fa-life-ring',
        },
        {
            'type': 'free',
            'url': 'https://www.otto.to.it',
            'label': 'Otto',
            'icon': 'fa fa-grin-stars',
        },
    ),
}

As you can see, you can use title items to group menu items and you can use the app keyword to set the group visibility so that users which cannot act on children will not see the group entirely.

You can use free voices to add custom URLs or even to trigger some javascript function.

The search field

The last Baton release added support for a full-text search component in the sidebar. Baton provides the component and the autocomplete feature (suggest as you type), while you should provide your backend implementation. This way you can decide which contents to filter and which results to provide given a search text.

You need to configure it this way:

BATON = {
  'SEARCH_FIELD': {
    'label': 'Label shown as placeholder',
    'url': '/api/path/',
  },
}

The label will be shown as a placeholder for the input field, so you can set it to something like "search blog and news...", while the url parameter is the endpoint for your backend implementation.

The backend implementation should return the search result in a format that Baton can understand:

{
    "length": 2,
    "data": [
        { "label": "My result #1", icon: "fa fa-edit", "url": "/admin/myapp/mymodel/1/change" },
        // ...
    ]
}

That's simply a JSON. You should provide a length attribute that represents the number of results and an array of results collected in the data attribute. Each result should be an object containing a label and an url properties. Optionally you can also define an icon property.

While the user types some chars in the fieldset, Baton will call your endpoint passing the inserted text and asking for results. Results are then presented to the user. A click on a result will cause the browser to follow the associated URL. The user can move between results also using the keyboard arrows and select a result hitting the return key.

Let's see a backend implementation example:

@staff_member_required
def admin_search(request):
    text = request.GET.get('text', None)
    res = []
    news = News.objects.all()
    if text:
        news = news.filter(title__icontains=text)
    for n in news:
        res.append({
            'label': str(n) + ' edit',
            'url': '/admin/news/news/%d/change' % n.id,
            'icon': 'fa fa-edit',
        })
    if text.lower() in 'Lucio Dalla Wikipedia'.lower():
        res.append({
            'label': 'Lucio Dalla Wikipedia',
            'url': 'https://www.google.com',
            'icon': 'fab fa-wikipedia-w'
        })
    return JsonResponse({
        'length': len(res),
        'data': res
    })

In this case, we're searching on our News model, adding also the possibility to search for a wiki page. As you can see you're not restricted to display results tied to your models, you can literally send the user everywhere!

Jacascript signals

Baton tries to avoid overriding templates and views. All it's styled through CSS and when more control is needed, javascript is used in order to adjust the DOM. That means that Baton performs DOM manipulation at startup, and there may be situations in which you need to know when it finishes its job.

For this reason, Baton provides an easy way to attach listeners that will be notified when some event occurs:

onNavbarReady: dispatched when the navbar is fully rendered
onMenuReady: dispatched when the menu is fully rendered (probably the last event fired since the menu contents are retrieved async)
onTabsReady: dispatched when the change form tabs are fully rendered
onMenuError: dispatched if the request sent to retrieve menu contents fails
onReady: dispatched when Baton JS has finished its sync job

You can then attach your listener this way:

Baton.Dispatcher.register('onMenuReady', function () { console.log('BATON MENU IS READY') })

Where to put this code?

You need to override the admin/base_site.html template. This is something I always do.

How?

Just define an app before baton in the INSTALLED_APPS, let's call it core for example. Create a template core/templates/admin/base_site.html and just copy the code of the baton/templates/admin/base_site.html. Then you can add your own stuff.

Other javascript utilities

Baton uses javascript a lot to provide its features. So it also provides some useful classes in its namespace:

Dispatcher: a mediator pattern dispatcher you can use to emit and subscribe to events.
Modal: a modal class that lets you use bootstrap modals without dealing with all the markup.

You can read more about them and see some examples in the documentation.

Translations

Baton does not override Django stuff, you already know that. So it almost doesn't define new strings. Almost, because some strings are needed and used here and there and cannot be retrieved from the page content. Baton comes with en and it translations out of the box, but you can add your locale translations, and even change the default strings simply by overriding Baton translation property:

Baton.translations = {
  unsavedChangesAlert: 'You have some unsaved changes.',
  uploading: 'Uploading...',
  filter: 'Filter',
  close: 'Close',
  save: 'Save',
  search: 'Search',
  cannotCopyToClipboardMessage: 'Cannot copy to clipboard, please do it manually: Ctrl+C, Enter',
  retrieveDataError: 'There was an error retrieving the data'
}

Since you'll put this code inside a template you'll be able to use every i18n template tag.

Include, include and yes, include

This feature was added to please earlier Baton users. Its a feature coming from django-suit, something that I've never used so much, but many developers did.

Baton uses the template HTML tag to inject contents inside the document. All this functionalities are well documented so I'll simply link the documentation page for each of them:

And then, there is one more cool "include" functionality, that lets you inject attributes in the change list table rows. This is nice, because you can inject CSS classes (.table-info, .table-success) and attributes (title will show its content on a tooltip on mouseover). And most important, you can inject this stuff inside a table row (tr), a single table cell (td) or even some other custom element making use of the selector and getParent properties. All this is well documented.

Form tabs

If you used django-suit you loved its tab system. Forms become just too much cleaner using them that I just cannot think any more of a change form without this feature. For this reason, Baton had support for form tabs since its first days. And it brings tab support even further, allowing to group fieldsets and inlines, and to change tabs ordering.

Everything is done just by adding some well-defined CSS classes to your fieldsets.

Take a look at the documentation for a complete explanation of all the rules. Keep in mind that you can also open a tab by default just by appending the right hash to an URL.

Change list filters

A few words about the change list filters. They're cool but not always perfect in the default admin. I mean, sometimes the FK filtering is a mess because you have too many entries. Sometimes you need to perform a text search. Sometimes there are so many filters you may desire to have them in a different place.

Baton adds some juice to your admin filters:

Input text filters: add simple text filters (something like a search_fields but restricted to one field).
Dropdown filters: when the related entries grow too much, just avoid having an infinite unordered list and use dropdowns.
Filters in modal: I like this one: open your list filters in a modal above the document. It's clean.
Filters in modal: I like this one: open your list filters on a modal above the document. It's clean.
Filters form: by default, you can apply one filter at a time. That can be cumbersome, and there are times when you prefer to tweak some filters at once and then perform the search action. Using this option Baton will transform your list filters in a form with a submit button: adjust all your filters and submit them all together.

And more...

There are many more features that Baton provides:

Google analytics dashboard out of the box
Images preview
Multipart uploading undetermined progress
Unsaved changes confirmation
...

Take your time to surf through the documentation, you'll find everything explained.

Customization

This has been a long journey, I'd like just to spend a few more words about Baton customization.

Baton comes with an arguably neutral palette, but there are situations in which even the administrative area should be heavily customized in order to reflect the brand, and changing the logo is not enough.

We've seen that Baton does all its job through styling and javascript. That's true, and in fact, Baton core it's a modern js application injected in the base_site.html admin template.

Baton uses webpack to build the javascript application which also includes all the CSS. For this reason, it's very simple to customize how it looks. The Baton core app is nothing more that a static served content that obeys to the same rules of all other static resources: the first installed app which serves that content wins.

That means that you can serve a customized version of the baton core app from an application defined before baton in your installed apps.

But how can you create a customized version of Baton core app?

Easy.

First: clone the Baton repository:

$ git clone https://github.com/otto-torino/django-baton.git

Cd into the core app folder and install all dependencies:

$ cd django-baton/baton/static/baton/app/
$ npm install

Now you can make your modifications, in particular, you may want to change the font, the colours, or any bootstrap configurable variable. That's easy, just edit the src/styles/_variables.scss file. You can override any bootstrap variable in place!

Of course, you can see your changes live: Baton comes with a webpack dev server ready to be started. It's necessary to change the path of the included Baton app in the base_site.html template. The default Baton template already have the right path commented out, you just need to switch the two script tags:

<!-- <script src="{% static 'baton/app/dist/baton.min.js' %}"></script> comment the compiled src and uncomment the webpack served src -->
<script src="http://localhost:8080/dist/baton.min.js"></script>

Now you can see the changes live, and after editing and saving a source file the page refreshes.

When you're satisfied with your job you can compile your app:

npm run compile

And finally you can copy the generated build in your custom app defined before baton (remember also to switch again the script tags in your base_site.html template):

cp dist/baton.min.js ROOTAPP/static/baton/app/dist/

That's it!

Conclusion

Baton is a Django application that aims to provide a better admin experience without changing too much stuff.

I would say that using Baton you're still using Django admin application, it feels Django, but at the same time it has a cooler face and some helpful additions which can help you design a great UI/UX.

The project is completely open-source, each contribution is welcome and if you like it, please ★ star it on GitHub!