admin

README

Admin

Web based admin interface for Go, inspired by Django admin.

Features

• Single user login (TODO: Implement support for custom login / user handlers).
• Register and group structs as "models" that map to your database manually or via an ORM.
• Set custom attributes via each struct field's tag to choose which columns are shown in lists, searchable etc (see below).
• Search, list and sort rows.
• Custom formatting of values like time.Time etc.
• Override / add custom fields with custom validation, formatting etc (may not work at the moment, but will soon).
• Auto generate forms from structs for easy content management. Foreign keys and ManyToMany relationships are supported, as long as target struct is also registered (choose by ID or via popup window).

Example

See the example app in /example for a working test app.

// Set up admin
a, err := admin.New("/admin", "sqlite3", "db.sqlite")
if err != nil {
	panic(err)
}

// Override settings as needed
a.Title = "Example admin"
a.NameTransform = snakeString // Optional (for ORM support)
a.User("admin", "example")    // Username / password to log in.

group, err := a.Group("Blog")
if err != nil {
	panic(err)
}
group.RegisterModel(new(Category))
group.RegisterModel(new(BlogPost))

// Get a http.Handler to attach to your router/mux.
adminHandler, err := a.Handler()
if err != nil {
	panic(err)
}

// Serve admin.
router := http.NewServeMux()
router.Handle("/admin/", adminHandler)

A model is just a struct

type Page struct {
	Id      int
	Name    string    `admin:"list search width=6"` // Listed, searchable and half width (12 columns is full width)
	Slug    string    `admin:"list search width=6"` // Listed, searchable and half width (displayed to the right of Name in edit form)
	Content string    `admin:"list textarea label='Page content'"`
	Added   time.Time `admin:"list label='Publish date' format='02.01.2006'"`
}

NameTransform is a function that takes a string and returns a string. It's used to transform struct field names to database table names. For example, Beego ORM uses snake case versions of struct fields for table / column names, so it'll convert "CompanyEmployee" to "company_employee". This is optional, so if no NameTransform is specified, lookups in the database will use the CamelCase versions like in Go.

Struct tags

Additional options can be provided in the admin struct tag, as in the example above. If more than one is used, separate them by a single space . Multiple word values must be single quoted. Currently, these are supported:

• - Skip / hide column (id / first column can't be hidden)
• list Show column in list view
  • list='FieldName' is available for pointers / ForeignKeyFields and will display RelatedField.FieldName instead of its Id value.
• search Make column searchable
• blank Allow this field to be empty.
• null Only works if blank is used. Instead of inserting empty values, NULL will be used for empty fields.
• field=file Lets you specify a non-default field type. url and file are currently supported
  • file also takes an optional upload_to='some/path'
• label='Custom name' Custom label for column
• default='My default value' Default value in "new"/"create" form
• width=4 Custom field width / column width (Optional, if not specified, 12 / full width is default)
• format='01.02.2006' For time.Time fields
• textarea Used by string / text field to display field as a textarea instead of an input

This project is still early in development. More documentation and features will be added over time.

Screenshots (outdated)

Documentation

Index

• type Admin
  • func New(path, dbDriver, dbSource string) (*Admin, error)
  • func NewFromConnection(path string, db *sql.DB) (*Admin, error)
  • func (a *Admin) Group(name string) (*modelGroup, error)
  • func (a *Admin) Handler() (http.Handler, error)
  • func (a *Admin) SourceDir(dir string) error
  • func (a *Admin) User(username, password string) error
• type NameTransformFunc
• type NamedModel
• type SortedModel

Types

type Admin

type Admin struct {
	// Title allows you to set a custom title for the admin panel. Default is "Admin".
	Title string

	// NameTransform is optional, and allows you to set a function that model names and field names are sent through
	// to maintain compatibility with an ORM. For example, Beego ORM saves tables/columns in snake_case, while CamelCase
	// is used in Go.
	NameTransform NameTransformFunc
	// contains filtered or unexported fields
}

func New

func New(path, dbDriver, dbSource string) (*Admin, error)

New sets up the admin with a "path" prefix (typically /admin) and the name of a database driver and source.

func NewFromConnection

func NewFromConnection(path string, db *sql.DB) (*Admin, error)

NewFromConnection sets up the admin with a "path" prefix (typically /admin) and connection of a database

func (*Admin) Group

func (a *Admin) Group(name string) (*modelGroup, error)

Group adds a model group to the admin front page. Use this to organize your models.

func (*Admin) Handler

func (a *Admin) Handler() (http.Handler, error)

Handler returns a http.Handler that you can attach to any mux to serve the admin.

func (*Admin) SourceDir

func (a *Admin) SourceDir(dir string) error

SourceDir allows you to override the location in which templates and static content is looked for / served from. If not set, it defaults to $GOPATH/src/github.com/oal/admin. You may also copy "templates" and "static" from there, into your own project, and change SourceDir accordingly.

func (*Admin) User

func (a *Admin) User(username, password string) error

User sets username and password for the admin panel. This will change in the future, when support for custom login backends is implemented. No promises on when that will happen, though.

type NameTransformFunc

type NameTransformFunc func(string) string

NameTransformFunc is a function that takes the name of a Go struct field and outputs another version of itself. This is used to be compatible with various ORMs. See NameTransform on the Admin struct.

type NamedModel

type NamedModel interface {
	AdminName() string
}

NamedModel requires an AdminName method to be present, to override the model's displayed name in the admin panel.

type SortedModel

type SortedModel interface {
	SortBy() string
}