Kaffy

Introduction

Kaffy was created out of a need to have a powerfully simple, flexible, and customizable admin interface without the need to touch the current codebase. It was inspired by django's lovely built-in admin app and rails' powerful activeadmin gem.

Sections

• Introduction
• Sections
• Sponsors
• Demo
• Minimum Requirements
• Installation
  • Add kaffy as a dependency
  • These are the minimum configurations required
• Customizations
  • Configurations
    • Breaking change in v0.9
  • Dashboard page
  • Side Menu
    • Custom Links
  • Custom Pages
  • Index pages
  • Form Pages
    • Association Forms
  • Custom Form Fields
  • Customize the Queries
  • Extensions
  • Embedded Schemas and JSON Fields
  • Search
  • Authorization
  • Changesets
  • Singular vs Plural
  • Custom Actions
    • Single Resource Actions
    • List Actions
  • Callbacks
  • Overwrite actions
  • Scheduled Tasks
• The Driving Points

Sponsors

Sponsor the development of Kaffy through GitHub Sponsors.

Demo

Check out the simple demo here

Minimum Requirements

Starting with v0.10.0, Kaffy will officially support the latest two phoenix versions.

| Kaffy | Supported phoenix versions | |---------|----------------------------| | v0.11.x | 1.7.21, 1.8.x | | v0.10.x | 1.6, 1.7.0 | | | |

Support Policy

The latest released major.minor version will be supported. For example, if the latest version is 0.9.0, then 0.9.1 will be released with bug fixes. If a new version 0.10.0 is released, then 0.9.1 will no longer receive bug fixes or security patches.

Installation

Add :kaffy as a dependency

def deps do
  [
    {:kaffy, "~> 0.10.0"}
  ]
end

If you are using kaffy v0.9.x with phoenix 1.7, you need to add phoenix_view to your dependencies:

def deps do
  [
    {:phoenix_view, "~> 2.0.2"},
    {:kaffy, "~> 0.9.4"}
  ]
end

These are the minimum configurations required

# in your router.ex
use Kaffy.Routes, scope: "/admin", pipe_through: [:some_plug, :authenticate]
# :scope defaults to "/admin"
# :pipe_through defaults to kaffy's [:kaffy_browser]
# when providing pipelines, they will be added after :kaffy_browser
# so the actual pipe_through for the previous line is:
# [:kaffy_browser, :some_plug, :authenticate]

# in your endpoint.ex
# configure the path to your application static assets in :at
# the path must end with `/kaffy`
plug Plug.Static,
  at: "/kaffy", # or "/path/to/your/static/kaffy"
  from: :kaffy,
  gzip: false,
  only: ~w(assets)

# in your config/config.exs
config :kaffy,
  # required keys
  otp_app: :my_app, # required
  ecto_repo: MyApp.Repo, # required
  router: MyAppWeb.Router, # required
  # optional keys
  admin_title: "My Awesome App",
  admin_logo: [
    url: "https://example.com/img/logo.png",
    style: "width:200px;height:66px;"
  ],
  admin_logo_mini: "/images/logo-mini.png",
  hide_dashboard: true,
  home_page: [schema: [:accounts, :user]],
  enable_context_dashboards: true, # since v0.10.0
  admin_footer: "Kaffy © 2023" # since v0.10.0

Note that providing pipelines with the :pipe_through option will add those pipelines to kaffy's :kaffy_browser pipeline which is defined as follows:

pipeline :kaffy_browser do
  plug :accepts, ["html", "json"]
  plug :fetch_session
  plug :fetch_flash
  plug :protect_from_forgery
  plug :put_secure_browser_headers
end

Phoenix version 1.7

Note that if you use Phoenix version 1.7 you also need to manually add the use of phoenix views in your project. Follow the instructions at https://hexdocs.pm/phoenix_view/Phoenix.View.html

You will also need to change helpers: false to true in the myapp_web.ex file as shown in example below.

  # lib/myapp_web.ex
  def router do
    quote do
      use Phoenix.Router, helpers: true # <- set to true

Customizations

Configurations

Breaking change in v0.9

If you're upgrading from an earlier version to v0.9, you need to replace your :schemas with :resources.

If you don't specify a resources option in your configs, Kaffy will try to auto-detect your schemas and your admin modules. Admin modules should be in the same namespace as their respective schemas in order for kaffy to detect them. For example, if you have a schema MyApp.Products.Product, its admin module should be MyApp.Products.ProductAdmin.

Otherwise, if you'd like to explicitly specify your schemas and their admin modules, you can do like the following:

# config.exs
config :kaffy,
  admin_title: "My Awesome App",
  admin_logo: "/images/logo.png",
  admin_logo_mini: "/images/logo-mini.png",
  admin_footer: "Kaffy © 2023",
  hide_dashboard: false,
  enable_context_dashboards: true,
  home_page: [kaffy: :dashboard],
  ecto_repo: MyApp.Repo,
  router: MyAppWeb.Router,
  resources: &MyApp.Kaffy.Config.create_resources/1

# in your custom resources function
defmodule MyApp.Kaffy.Config do
  def create_resources(_conn) do
    [
      blog: [
        name: "My Blog", # a custom name for this context/section.
        resources: [ # this line used to be "schemas" in pre v0.9
          post: [schema: MyApp.Blog.Post, admin: MyApp.SomeModule.Anywhere.PostAdmin],
          comment: [schema: MyApp.Blog.Comment],
          tag: [schema: MyApp.Blog.Tag, in_menu: false]
        ]
      ],
      inventory: [
        name: "Inventory",
        resources: [
          category: [schema: MyApp.Products.Category, admin: MyApp.Products.CategoryAdmin],
          product: [schema: MyApp.Products.Product, admin: MyApp.Products.ProductAdmin]
        ]
      ]
    ]
  end
end

Starting with Kaffy v0.9, the :resources option can take a literal list or a function. If a function is provided, it should take a conn and return a list of contexts and schemas like in the example above. Passing a conn to the function provides more flexibility and customization to your resources list.

You can set the :hide_dashboard option to true to hide the dashboard link from the side menu. To change the home page, change the :home_page option to one of the following:

• [kaffy: :dashboard] for the default dashboard page.
• [schema: ["blog", "post"]] to make the home page the index page for the Post schema under the 'Blog' context.
• [page: "my-custom-page"] to make the custom page with the :slug "my-custom-page" the home page. See the Custom Pages section below.

Note that, for auto-detection to work properly, schemas in different contexts should have different direct "prefix" namespaces. That is:

# auto-detection works properly with this:
MyApp.Posts.Post
MyApp.Posts.Category
MyApp.Products.Product
MyApp.Products.Category # this Category will not be confused with Posts.Category

# auto-detection will be confused with this:
# both Category schemas have the same "Schemas" prefix.
MyApp.Posts.Schemas.Post
MyApp.Posts.Schemas.Category
MyApp.Products.Schemas.Product
MyApp.Products.Schemas.Category

# To fix this, define resources manually:
resources: [
  posts: [
    resources: [
      post: [schema: MyApp.Posts.Schemas.Post],
      category: [schema: MyApp.Posts.Schemas.Category]
    ]
  ],
  products: [
    resources: [
      product: [schema: MyApp.Products.Schemas.Product],
      category: [schema: MyApp.Products.Schemas.Category]
    ]
  ]
]

Dashboard page

Kaffy supports dashboard customizations through widgets.

Currently, kaffy provides support for 4 types of widgets:

• text widgets. Suitable for display relatively long textual information. Candidates: a short review, a specific message for the admin, etc.
• tidbit widgets. Suitable for tiny bits of information (one word, or one number). Cadidates: total sales, a specific date, system status ("Healthy", "Down"), etc.
• progress widgets. Suitable for measuring progress in terms of percentages. Candidates: task progress, survey results, memory usage, etc.
• chart widgets. Suitable for displaying chart data with X and Y values. Candidates: any measurable number over a period of time (e.g. sales, visits, etc).

Widgets have shared options:

• :type (required) is the type of the widget. Valid options are text, tidbit, progress, and chart.
• :title (required) is the title for the widget. What this widget is about.
• :content (required) is the main content of the widget. This can be a string or a map depending on the type of widget.
• :order (optional) is the displaying order of the widget. Widgets are display in order based