Links

How To Use Admin Plugin

The Admin plugin can help you to quickly generate a platform for database data table query, adding, deleting, and editing.

Quick Start

Following the steps:
  • Generate a configuration file corresponding to the data table
  • Set access routing
  • Initialize and load in the engine
  • Set access menu

Step 1. Generate configuration file

Suppose you have a data table users in your database, such as:
CREATE TABLE `users` (
`id` int(11) unsigned NOT NULL AUTO_INCREMENT,
`name` varchar(50) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
`gender` tinyint(4) DEFAULT NULL,
`city` varchar(50) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
`ip` varchar(20) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
`phone` varchar(10) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
`created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` timestamp NULL DEFAULT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=0 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
Use the command line tools - adm to help you quickly generate configuration files:
  • install adm
go install github.com/GoAdminGroup/adm
  • generate
Execute the command in your project folder
adm generate
Notice: use space to choose table, not enter
Fill in the information according to the prompts. After the run, a file users.go will be generated. This is the configuration file corresponding to the data table. How to configure it is described in detail later.

Step 2. Set access url

After the configuration file is generated, a routing configuration file tables.go will also be generated :
package main
import "github.com/GoAdminGroup/go-admin/plugins/admin/models"
// The key of Generators is the prefix of table info url.
// The corresponding value is the Form and Table data.
//
// http://{{config.DOMAIN}}:{{PORT}}/{{config.PREFIX}}/info/{{key}}
//
// example:
//
// "user" => http://localhost:9033/admin/info/user
//
var Generators = map[string]models.TableGenerator{
"user": GetUserTable,
}
"user" is the corresponding access route prefix, GetUserTable is the table data generation method. The corresponding access routing address is: http://localhost:9033/admin/info/user

Step 3. Initialize and load in the engine

To initialize, you need to call the eng.AddGenerators method, and then pass the Generators above.
package main
import (
_ "github.com/GoAdminGroup/go-admin/adapter/gin" // Import the adapter, it must be imported. If it is not imported, you need to define it yourself.
_ "github.com/GoAdminGroup/themes/adminlte" // Import the theme
_ "github.com/GoAdminGroup/go-admin/modules/db/drivers/mysql" // Import the sql driver
"github.com/gin-gonic/gin"
"github.com/GoAdminGroup/go-admin/engine"
"github.com/GoAdminGroup/go-admin/plugins/admin"
"github.com/GoAdminGroup/go-admin/modules/config"
"github.com/GoAdminGroup/go-admin/modules/language"
)
func main() {
r := gin.Default()
eng := engine.Default()
cfg := config.Config{
Databases: config.DatabaseList{
"default": {
Host: "127.0.0.1",
Port: "3306",
User: "root",
Pwd: "root",
Name: "godmin",
MaxIdleCon: 50,
MaxOpenCon: 150,
Driver: config.DriverMysql,
},
},
UrlPrefix: "admin",
Store: config.Store{
Path: "./uploads",
Prefix: "uploads",
},
Language: language.CN,
}
// AddGenerator can also be used to load the Generator, like:
// eng.AddGenerator("user", GetUserTable)
eng.AddConfig(cfg).
AddGenerators(Generators). // 加载插件
Use(r)
r.Run(":9033")
}

Step 4. Set access menu

After running, access the login URL, enter the menu management page, and then set the management menu of the data table to enter in the sidebar.
In the above example, the login URL is http://localhost:9033/admin/login
The menu management page is http://localhost:9033/admin/menu

Introduction of the business data table generation method

package datamodel
import (
"fmt"
"github.com/GoAdminGroup/go-admin/modules/db"
form2 "github.com/GoAdminGroup/go-admin/plugins/admin/modules/form"
"github.com/GoAdminGroup/go-admin/plugins/admin/modules/table"
"github.com/GoAdminGroup/go-admin/template/types"
"github.com/GoAdminGroup/go-admin/template/types/form"
)
func GetUserTable(ctx *context.Context) (userTable table.Table) {
// config the table model.
userTable = table.NewDefaultTable(table.Config{
Driver: db.DriverMysql,
CanAdd: true,
Editable: true,
Deletable: true,
Exportable: true,
Connection: table.DefaultConnectionName,
PrimaryKey: table.PrimaryKey{
Type: db.Int,
Name: table.DefaultPrimaryKeyName,
},
})
info := userTable.GetInfo()
// set id sortable.
info.AddField("ID", "id", db.Int).FieldSortable(true)
info.AddField("Name", "name", db.Varchar)
// use FieldDisplay.
info.AddField("Gender", "gender", db.Tinyint).FieldDisplay(func(model types.FieldModel) interface{} {
if model.Value == "0" {
return "men"
}
if model.Value == "1" {
return "women"
}
return "unknown"
})
info.AddField("Phone", "phone", db.Varchar)
info.AddField("City", "city", db.Varchar)
info.AddField("CreatedAt", "created_at", db.Timestamp)
info.AddField("UpdatedAt", "updated_at", db.Timestamp)
// set the title and description of table page.
info.SetTable("users").SetTitle("Users").SetDescription("Users").
SetAction(template.HTML(`<a href="http://google.com"><i class="fa fa-google"></i></a>`)) // custom operation button
formList := userTable.GetForm()
// set id editable is false.
formList.AddField("ID", "id", db.Int, form.Default).FieldNotAllowEdit()
formList.AddField("Ip", "ip", db.Varchar, form.Text)
formList.AddField("Name", "name", db.Varchar, form.Text)
// use FieldOptions.
formList.AddField("Gender", "gender", db.Tinyint, form.Radio).
FieldOptions(types.FieldOptions{
{
Text: "male",
Value: "0",
}, {
Text: "female",
Value: "1",
},
}).FieldDefault("0")
formList.AddField("Phone", "phone", db.Varchar, form.Text)
formList.AddField("City", "city", db.Varchar, form.Text)
// add a custom field and use FieldPostFilterFn to do more things.
formList.AddField("Custom Field", "role", db.Varchar, form.Text).
FieldPostFilterFn(func(value types.PostFieldModel) interface{} {
fmt.Println("user custom field", value)
return ""
})
formList.AddField("UpdatedAt", "updated_at", db.Timestamp, form.Default).FieldNotAllowAdd(true)
formList.AddField("CreatedAt", "created_at", db.Timestamp, form.Default).FieldNotAllowAdd(true)
// use SetTabGroups to group a form into tabs.
formList.SetTabGroups(types.
NewTabGroups("id", "ip", "name", "gender", "city").
AddGroup("phone", "role", "created_at", "updated_at")).
SetTabHeaders("profile1", "profile2")
// set the title and description of form page.
formList.SetTable("users").SetTitle("Users").SetDescription("Users")
// use SetPostHook to add operation when form posted.
formList.SetPostHook(func(values form2.Values) {
fmt.Println("userTable.GetForm().PostHook", values)
})
return
}
Initialized by calling models.NewDefaultTable(models.DefaultTableConfig) method to pass data table model configuration. The data table model is configured as:
type Config struct {
Driver string // database driver
Connection string // database connection name, defined in the global configuration
CanAdd bool // Can I add data
Editable bool // Can I edit
Deletable bool // Can I delete it
Exportable bool // Whether it can be exported
PrimaryKey PrimaryKey // primary key of the data table
}
type PrimaryKey struct {
Type db.DatabaseType // primary key type
Name string // primary key name
}
The business data table generation method is a function that returns a type object of models.Table. The following is the definition of models.Table:
type Table interface {
GetInfo() *types.InfoPanel
GetDetail() *types.InfoPanel
GetDetailFromInfo() *types.InfoPanel
GetForm() *types.FormPanel
GetCanAdd() bool
GetEditable() bool
GetDeletable() bool
GetExportable() bool
GetPrimaryKey() PrimaryKey
GetData(params parameter.Parameters) (PanelInfo, error)
GetDataWithIds(params parameter.Parameters) (PanelInfo, error)
GetDataWithId(params parameter.Parameters) (FormInfo, error)
UpdateData(dataList form.Values) error
InsertData(dataList form.Values) error
DeleteData(pk string) error
GetNewForm() FormInfo
Copy() Table
}
It mainly includes GetInfo() and GetForm(). The UI corresponding to the type returned by these two functions is the table for displaying data and the form for editing or creating data. The screenshots are as follows:
  • This is the Info.
Could not load image
  • This is the Form.
Could not load image

Info

type InfoPanel struct {
FieldList FieldList
Table string
Title string
Description string
TabGroups TabGroups
TabHeaders TabHeaders
Sort Sort
SortField string
PageSizeList []int
DefaultPageSize int
ExportType int
IsHideNewButton bool
IsHideExportButton bool
IsHideEditButton bool
IsHideDeleteButton bool
IsHideDetailButton bool
IsHideFilterButton bool
IsHideRowSelector bool
IsHidePagination bool
IsHideFilterArea bool
FilterFormLayout form.Layout
FilterFormHeadWidth int
FilterFormInputWidth int
Wheres Wheres
WhereRaws WhereRaw
TableLayout string
DeleteHook DeleteFn
PreDeleteFn DeleteFn
DeleteFn DeleteFn
DeleteHookWithRes DeleteFnWithRes
GetDataFn GetDataFn
Action template.HTML
HeaderHtml template.HTML
FooterHtml template.HTML
}
type Field struct {
Head string // title
Field string // field name
TypeName db.DatabaseType // database type name
Join Join // join table setting
Width int // width
Sortable bool // sortable
Fixed bool // fixed
Filterable bool // filterable
Hide bool // hide or not
EditType table.Type // edit type
EditOptions FieldOptions // edit options
Display FieldFilterFn // display filter callback function
DisplayProcessChains DisplayProcessFnChains // display process function chains
}
// join table setting
// example: left join Table on Table.JoinField = Field
type Join struct {
Table string
Field string
JoinField string
}

Form

type FormPanel struct {
FieldList FormFields // form field list
curFieldListIndex int
// Warn: may be deprecated future.
TabGroups TabGroups // tabs, [example](https://github.com/GoAdminGroup/go-admin/blob/master/examples/datamodel/user.go#L76)
TabHeaders TabHeaders // tabs headers, [example](https://github.com/GoAdminGroup/go-admin/blob/master/examples/datamodel/user.go#L78)
Table string
Title string
Description string
Validator FormValidator // form post validator function
PostHook FormPostHookFn // form post hook function
PreProcessFn FormPreProcessFn // form post pre process function
IsHideContinueEditCheckBox bool
IsHideContinueNewCheckBox bool
IsHideResetButton bool
IsHideBackButton bool
HeaderHtml template.HTML // header custom html content
FooterHtml template.HTML // footer custom html content
UpdateFn FormPostFn // Form update function, set up this function, it took over the form of updates, PostHook is no longer in effect
InsertFn FormPostFn // Form inserts function, set up this function, it took over the form of the insert, PostHook effect no longer
}
type FormPostFn func(values form.Values) error
// form hook function type
type PostHookFn func(values form.Values)
type FormField struct {
Field string
TypeName string
Head string
FormType form.Type
Default string
Value string
Options []map[string]string
DefaultOptionDelimiter string
Editable bool
NotAllowAdd bool
Must bool
Hide bool
HelpMsg template.HTML
OptionExt template.JS
Display FieldFilterFn
DisplayProcessChains DisplayProcessFnChains
PostFilterFn PostFieldFilterFn
Placeholder string
CustomContent template.HTML
CustomJs template.JS
CustomCss template.CSS
Width int
Divider bool
DividerTitle string
OptionExt template.JS
OptionInitFn OptionInitFn
OptionTable OptionTable
}
The currently supported form types are:
  • default
  • normal text
  • Single selection
  • Password
  • rich text
  • File
  • Code
  • double selection box
  • Multiple choices
  • icon drop-down selection box
  • time selection box
  • radio selection box
  • email input box
  • url input box
  • ip input box
  • color selection box
  • Currency input box
  • Digital input box
</br>
Can be used like this:
import "github.com/GoAdminGroup/go-admin/template/types/form"
...
FormType: form.File,
...
See more in:admin form components
Where field is the name of the field and value is the value corresponding to the selection.

Filter function FilterFn and processing function PostFn description

The data which framework retrieve from database will be displayed in the table or form. If you want to transform them before displaying, for example turn capital or add some html style etc, you can do that using the field filter callback function. Of course, the framework have some built-in data process functions which will be introduced in the chapter of admin table.
// FieldModel contains ID and value of the single query result.
type FieldModel struct {
ID string
Value string
}
// FieldFilterFn determines the value that is retrieved from the database
// and passes to the format displayed by the front end.
//
// The type currently accepted for return is: template.HTML, string, []string
//
// For tables, you can return the template.HTML type, including html and css
// styles, so that the fields in the table can be personalized, such as:
//
// FilterFn: func(model types.FieldModel) interface{} {
// return template.Get("adminlte").Label().SetContent(template2.HTML(model.Value)).GetContent()
// },
//
// For forms, note that if it is a select box type: Select/SelectSingle/SelectBox,
// you need to return an array: []string, such as:
//
// FilterFn: func(model types.FieldModel) interface{} {
// return strings.Split(model.Value, ",")
// },
//
// For other form types, return the string type
//
type FieldFilterFn func(value FieldModel) interface{}
// PostFieldModel contains ID and value of the single query result.
type PostFieldModel struct {
ID string
Value FieldModelValue
Row map[string]interface{}
}
type FieldModelValue []string
func (r FieldModelValue) Value() string {
return r.First()
}
func (r FieldModelValue) First() string {
return r[0]
}
English is not my main language. If any typo or wrong translation you found, you can help to translate in github here. I will very appreciate it.