Skip to content

Latest commit

 

History

History
561 lines (430 loc) · 15.2 KB

admin.md

File metadata and controls

561 lines (430 loc) · 15.2 KB

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.

  • This is the Form.

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

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.