GORM

Installing GORM and the GORM Integrator

First, ensure you have GORM installed:

go get -u gorm.io/gorm
go get -u gorm.io/driver/sqlite # or the driver of your choice

Then, install the GORM integrator package:

go get -u github.com/go-advanced-admin/orm-gorm

Setting Up the Database Connection

Set up your GORM database connection as you normally would. For example, using SQLite:

import (
    "gorm.io/driver/sqlite"
    "gorm.io/gorm"
)

func main() {
    db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})
    if err != nil {
        panic("failed to connect database")
    }
    // Rest of your code
}

Initializing the GORM Integrator

Create a new instance of the GORM integrator and pass your GORM database connection to it:

import (
    "github.com/go-advanced-admin/admin"
    "github.com/go-advanced-admin/orm-gorm"
)

// ...

ormIntegrator := admingorm.NewIntegrator(db)

Integrating with the Admin Panel

When creating your admin panel, pass the GORM integrator to it:

panel, err := admin.NewPanel(
    ormIntegrator, webIntegrator, permissionFunc, nil,
)
if err != nil {
    log.Fatal(err)
}

Defining Your Models

Define your GORM models as you normally would:

type Post struct {
    ID      uint   `gorm:"primarykey"`
    Title   string
    Content string
}

type User struct {
    ID       uint   `gorm:"primarykey"`
    Username string
    Email    string
}

Migrating Your Models

Ensure your models are migrated to the database:

err = db.AutoMigrate(&Post{}, &User{})
if err != nil {
    log.Fatal(err)
}

Registering Models with the Admin Panel

Register your models with the admin panel using the RegisterModel method:

app, err := panel.RegisterApp("Blog", "Blog Management", nil)
if err != nil {
    log.Fatal(err)
}

_, err = app.RegisterModel(&Post{}, nil)
if err != nil {
    log.Fatal(err)
}

_, err = app.RegisterModel(&User{}, nil)
if err != nil {
    log.Fatal(err)
}

Searching and Filtering

The integrator supports searching and filtering through its FetchInstancesOnlyFieldWithSearch method. This method constructs SQL queries using GORM's API to search across specified fields.

Pagination

Pagination is handled by the admin panel, which uses the integrator to fetch a subset of data based on the current page and items per page.

Overview

The integrator uses GORM's API to interact with the database. It provides implementations for all required methods, allowing the admin panel to perform CRUD operations without worrying about the underlying database logic.

Key Methods

func (i *Integrator) GetPrimaryKeyValue(model interface{}) (interface{}, error)

func (i *Integrator) GetPrimaryKeyType(model interface{}) (reflect.Type, error)

func (i *Integrator) FetchInstances(model interface{}) (interface{}, error)

func (i *Integrator) FetchInstancesOnlyFields(
    model interface{}, fields []string,
) (interface{}, error)

func (i *Integrator) FetchInstancesOnlyFieldWithSearch(
    model interface{}, fields []string, query string, searchFields []string,
) (interface{}, error)

func (i *Integrator) DeleteInstance(
    model interface{}, instanceID interface{},
) error

func (i *Integrator) FetchInstanceOnlyFields(
    model interface{}, id interface{}, fields []string,
) (interface{}, error)

func (i *Integrator) FetchInstance(
    model interface{}, instanceID interface{},
) (interface{}, error)

func (i *Integrator) CreateInstance(instance interface{}) error

func (i *Integrator) UpdateInstance(
    instance interface{}, primaryKey interface{},
) error

func (i *Integrator) CreateInstanceOnlyFields(
    instance interface{}, fields []string,
) error

func (i *Integrator) UpdateInstanceOnlyFields(
    instance interface{}, fields []string, primaryKey interface{},
) error

Reflection and GORM Statements

The integrator heavily relies on Go's reflect package and GORM's Statement struct to parse models and extract metadata such as field names and primary keys.

• Reflection:

  • Used to dynamically interact with model types and values.

• GORM Statements:

  • Provide schema information about models.

  • Help in identifying database column names and primary keys.

Error Handling

All methods return detailed errors to help diagnose issues during database operations. Proper error handling ensures that any problems are surfaced to the admin panel for appropriate user feedback.

Extending the Integrator

You can extend the Integrator struct to add custom methods or override existing ones.

type CustomGormIntegrator struct {
    *admingorm.Integrator
}

func NewCustomGormIntegrator(db *gorm.DB) *CustomGormIntegrator {
    return &CustomGormIntegrator{
        Integrator: admingorm.NewIntegrator(db),
    }
}

// Override methods or add new ones as needed

Implementing Custom Logic

Override methods to implement custom logic, such as additional query filters, soft deletes, or custom error handling.

Example: Adding Soft Delete Support

func (i *CustomGormIntegrator) DeleteInstance(
    model interface{}, instanceID interface{},
) error {
    // Custom logic for soft delete
    // Update the 'deleted_at' timestamp instead of hard deleting
    modelValue := reflect.ValueOf(model).Elem()
    deletedAtField := modelValue.FieldByName("DeletedAt")
    if !deletedAtField.IsValid() {
        return errors.New("model does not have a DeletedAt field")
    }
    deletedAtField.Set(reflect.ValueOf(time.Now()))
    return i.DB.Save(model).Error
}

Registering the Custom Integrator

When initializing the admin panel or registering an app, pass your custom integrator:

customOrmIntegrator := NewCustomGormIntegrator(db)

panel, err := admin.NewPanel(
    customOrmIntegrator, webIntegrator, permissionFunc, nil,
)
// ...

How to Contribute

For detailed guidelines, please refer to our Contributing Guide.

Reporting Issues

If you encounter any issues or have suggestions, please open an issue on GitHub in the admin-gorm repository.