datatables

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2025 License: MIT Imports: 12 Imported by: 0

README

jQuery DataTables API for Go with Gorm

The golang-gorm-datatables package is a Go library which provides support for jQuery DataTables server-side processing using Gorm. It contains functions for generating SQL queries for filtering, sorting and pagination, as well as functions for counting the total and filtered records.

Requirements

  • Go 1.24 or higher
  • Gorm 1.26 or higher

Installation

To install the Request package, run the following command:

go get github.com/ZihxS/golang-gorm-datatables

Simple Usage

package main

import (
  // ...

  "github.com/ZihxS/golang-gorm-datatables" // [👉🏼 FOCUS HERE]

  // ...
)

func main() {
  // ...

  type User struct {
    ID   int
    Name string
    Age  int
  }

  // ...

  // example using mux router
  r.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
    req, err := datatables.ParseRequest(r) // parse the request [👉🏼 FOCUS HERE]
    if err != nil {
      http.Error(w, fmt.Sprintf("Error processing request: %v", err), http.StatusInternalServerError)
      return
    }

    tx := db.Model(&User{}) // gorm query [👉🏼 FOCUS HERE]
    response, err := datatables.New(tx).Req(*req).Make() // make datatables [👉🏼 FOCUS HERE]
    if err != nil {
      http.Error(w, fmt.Sprintf("Error processing request: %v", err), http.StatusInternalServerError)
      return
    }

    w.Header().Set("Content-Type", "application/json")
    _ = json.NewEncoder(w).Encode(response)
  })
}

// ...

More Example & Documentation

You can visit this link to see more example and documentation:

  • Documentation: ?
  • Example on Server Side: ?
  • Example on Client Side: ?

Contributing

Contributions are welcome! If you'd like to contribute to the Request package, please follow these steps:

  1. Fork the repository to your own GitHub account.
  2. Clone the repository to your local machine.
  3. Run make deps to install dependencies.
  4. Make changes to the code, following the guidelines below.
  5. Run make test to ensure your changes pass the test suite.
  6. Run make fmt to ensure your code is formatted correctly.
  7. Run make lint to ensure your code lint is clean.
  8. Commit your changes with a meaningful commit message.
  9. Push your changes to your forked repository.
  10. Submit a pull request to the original repository.
Makefile Commands

The Makefile provides several commands to help with development and testing:

  • make deps: Installs dependencies for the package.
  • make test: Runs the test suite for the package.
  • make test-coverage: Runs the test suite with code coverage analysis.
  • make view-coverage: Opens the test coverage report in your web browser.
  • make fmt: Formats the code according to the Go standard.
  • make lint: Runs the linter to check for coding style issues.
  • make build: Builds the package and its dependencies.
  • make clean: Removes any build artifacts and temporary files.
Guidelines

When contributing to the Request package, please follow these guidelines:

  • Use the Go standard coding style.
  • Write comprehensive tests for any new functionality.
  • Keep commits small and focused on a single change.
  • Use meaningful commit messages that describe the change.

License

The Request package is licensed under the MIT License.

Authors

Contributors

Credits

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Column 

type Column struct {
	Searchable bool
	Orderable  bool
	Name       string
	Data       string
	RenderFunc func(map[string]any) any
}

Column represents a single column in a DataTable.

A Column has the following properties:

Fields:

  • Searchable: A boolean indicating whether the column is searchable.
  • Orderable: A boolean indicating whether the column is orderable.
  • Name: The display name of the column.
  • Data: The data property name of the column.
  • RenderFunc: An optional function that can be used to render the column value.

type ColumnRequest 

type ColumnRequest struct {
	Searchable bool   `form:"searchable"`
	Orderable  bool   `form:"orderable"`
	Data       string `form:"data"`
	Name       string `form:"name"`
	Search     Search `form:"search"`
}

ColumnRequest represents a request for a DataTable column configuration.

Fields:

  • Searchable: Indicates if the column is searchable.
  • Orderable: Indicates if the column can be ordered.
  • Data: The data property name of the column.
  • Name: The display name of the column.
  • Search: The search criteria applied to the column.

type Config 

type Config struct {
	Searchable      bool
	Orderable       bool
	Paginate        bool
	Union           bool
	Distinct        bool
	CaseInsensitive bool
	ResponseFormat  string
	GroupBy         []string
	Having          []string
	DefaultSort     map[string]string
}

Config holds the configuration options for a DataTable.

The Config struct allows customization of various features such as searchability, ordering, pagination, and more.

Fields:

  • Searchable: Enables or disables global searching.
  • Orderable: Enables or disables column ordering.
  • Paginate: Enables or disables pagination.
  • Union: Allows the use of UNION in queries.
  • Distinct: Enables DISTINCT selection in queries.
  • CaseInsensitive: Enables case-insensitive searches.
  • ResponseFormat: Specifies the format of the response.
  • GroupBy: Specifies columns for GROUP BY clause.
  • Having: Specifies conditions for HAVING clause.
  • DefaultSort: Specifies default sorting for columns.

type DataTable 

type DataTable struct {
	// contains filtered or unexported fields
}

The data is represented by the totalRecords, filteredRecords, and columns fields, which are used to store the data.

func New 

func New(tx *gorm.DB) *DataTable

New returns a new DataTable with the given Gorm DB and default configuration.

func (*DataTable) AddColumn 

func (dt *DataTable) AddColumn(col Column) *DataTable

AddColumn adds a column to the DataTable. If a column with the same Data field exists, it is overwritten. The column is added to the columnsMap with the Data field as the key.

func (*DataTable) AddColumns 

func (dt *DataTable) AddColumns(columns ...Column) *DataTable

AddColumns adds multiple columns to the DataTable. If a column with the same Data field exists, it is overwritten. The columns are added to the columnsMap with the Data field as the key.

func (*DataTable) BlacklistColumn 

func (dt *DataTable) BlacklistColumn(columns ...string) *DataTable

BlacklistColumn marks one or more columns as blacklisted. Columns that are blacklisted will be excluded from the final response. If no columns are passed, this function does nothing.

func (*DataTable) CaseInsensitive 

func (dt *DataTable) CaseInsensitive() *DataTable

CaseInsensitive enables case-insensitive search for the DataTable.

This method sets the CaseInsensitive field in the DataTable's configuration to true, allowing the DataTable to perform case-insensitive search operations. After calling this method, any search queries executed by the DataTable will ignore the case of the search terms.

Returns the updated DataTable instance.

func (*DataTable) DisableOrder 

func (dt *DataTable) DisableOrder() *DataTable

DisableOrder disables the ordering functionality for the DataTable.

This method sets the Orderable field in the DataTable's configuration to false, effectively disabling any ordering operations on the DataTable. After calling this method, the DataTable will not perform ordering on the data.

Returns the updated DataTable instance.

func (*DataTable) DisablePagination 

func (dt *DataTable) DisablePagination() *DataTable

DisablePagination disables the pagination functionality for the DataTable.

This method sets the Paginate field in the DataTable's configuration to false, effectively disabling any pagination operations on the DataTable. After calling this method, the DataTable will not perform pagination on the data.

Returns the updated DataTable instance.

func (*DataTable) DisableSearch 

func (dt *DataTable) DisableSearch() *DataTable

DisableSearch disables the search functionality for the DataTable.

This method sets the Searchable field in the DataTable's configuration to false, effectively disabling any search operations on the DataTable. After calling this method, the DataTable will not perform search filtering on the data.

Returns the updated DataTable instance.

func (*DataTable) EditColumn 

func (dt *DataTable) EditColumn(name string, editFunc func(any) any) *DataTable

EditColumn edits the render function of a column with the given name.

If a column with the given name exists, the render function is replaced with a new one that calls the given editFunc with the value of the column from the given row. If the column does not exist, the function does nothing.

The RenderFunc field of the column is replaced with a new one, and the new column is stored in the columnsMap with the Data field as the key.

func (*DataTable) Filter 

func (dt *DataTable) Filter(filterFunc func(*gorm.DB) *gorm.DB) *DataTable

Filter adds the specified filter function to the DataTable's filters slice.

This function allows the user to specify custom filtering logic that should be applied to the DataTable's query. The function takes a single argument, a function that takes a gorm.DB instance and returns a gorm.DB instance. The function should apply its desired filtering logic to the provided gorm.DB instance and return the updated instance.

Returns the updated DataTable instance.

func (*DataTable) FinalizeResponseColumns 

func (dt *DataTable) FinalizeResponseColumns(data []map[string]any) []map[string]any

FinalizeResponseColumns removes any columns from the data that are not whitelisted or that are blacklisted.

func (*DataTable) Make 

func (dt *DataTable) Make() (map[string]any, error)

Make processes the query and returns a DataTables compatible response.

It will execute the following steps:

  1. Validate the DataTable configuration.
  2. Execute the query and get the total records count, filtered records count and the actual data.
  3. Run the custom column rendering functions in parallel.
  4. Apply the row attributes in parallel.
  5. Apply the custom columns in parallel.
  6. If selected columns are defined, it will filter the columns for the response.
  7. Merge the additional data into the response.
  8. Return the response.

The function returns a DataTables compatible response or an error if it occurs.

func (*DataTable) Model 

func (dt *DataTable) Model(model any) *DataTable

Model sets the model to be used for the datatables request.

This can either be a struct or a string representing the table name.

If a struct is provided, it should have the same fields as the table being queried. If a string is provided, it should be the table name. The query will be executed on this table.

The model can also be set when creating a new DataTable with the New function.

func (*DataTable) Only 

func (dt *DataTable) Only(columns ...string) *DataTable

Only sets the selectedColumns field of the DataTable to the specified columns.

This function allows the user to specify which columns should be included in the DataTable's operations. It takes one or more string arguments, representing the Data fields of the columns to be included. The selected columns will be used in subsequent operations, such as filtering and rendering the table. The function returns the updated DataTable instance.

func (*DataTable) Raw 

func (dt *DataTable) Raw() (any, error)

Raw returns the raw data retrieved from the database by executing the DataTable's query.

This function does not apply any custom column rendering functions or row attributes. It returns the raw data as retrieved from the database, along with any error that may have occurred.

func (*DataTable) RemoveColumn 

func (dt *DataTable) RemoveColumn(data ...string) *DataTable

RemoveColumn removes one or more columns from the DataTable. The columns are removed from the selectedColumns and columns fields of the DataTable. If the selectedColumns field is empty, the columns are removed from the columns field. If the selectedColumns field is not empty, the columns are removed from the selectedColumns field and the columns field is updated accordingly.

The function takes one or more string arguments, which are the Data fields of the columns to be removed. If a column with one of the given Data fields exists, it is removed from the DataTable. If a column does not exist, the function does nothing.

func (*DataTable) Req 

func (dt *DataTable) Req(req Request) *DataTable

Req sets the request parameters for the DataTable and adds the specified columns.

The request contains various configurations such as draw counter, pagination info, search terms, and column specifications. Each column specified in the request is added to the DataTable. The columns are set with their respective properties, including name, data, searchable, and orderable attributes.

Returns the updated DataTable instance.

func (*DataTable) SetConfig 

func (dt *DataTable) SetConfig(config Config) *DataTable

SetConfig sets the DataTable's configuration to the specified Config instance.

This method is a convenience method that can be used to set the DataTable's configuration after it has been created. The Config instance should contain the desired settings for the DataTable, such as whether or not to allow searching, ordering, and pagination. The Config instance should also contain the desired settings for the DataTable's request, such as the draw counter, start, and length.

Returns the updated DataTable instance.

func (*DataTable) SetFilteredRecords 

func (dt *DataTable) SetFilteredRecords(count int64) *DataTable

SetFilteredRecords sets the total number of records in the table that are visible after filtering.

This is a convenience method, and is used internally by the DataTable to store the total number of records returned by the filtered query.

Returns the updated DataTable instance.

func (*DataTable) SetRowAttributes 

func (dt *DataTable) SetRowAttributes(idFunc func(map[string]any) string, class string, dataFunc func(map[string]any) map[string]any) *DataTable

SetRowAttributes sets the row attributes of the DataTable.

This method is a convenience method that can be used to set the row attributes of the DataTable. The row attributes are used by the DataTable to generate the HTML for the table.

The idFunc parameter is a function that takes a row and returns the ID of the row. The class parameter is the class to be applied to the table row. The dataFunc parameter is a function that takes a row and returns a map of data to be added to the table row as data-* attributes.

Returns the updated DataTable instance.

func (*DataTable) SetTotalRecords 

func (dt *DataTable) SetTotalRecords(count int64) *DataTable

SetTotalRecords sets the total number of records in the table.

This is a convenience method, and is used internally by the DataTable to store the total number of records returned by the count query.

Returns the updated DataTable instance.

func (*DataTable) SkipPaging 

func (dt *DataTable) SkipPaging() *DataTable

SkipPaging disables the pagination functionality for the DataTable.

This is a convenience method, and is equivalent to calling DisablePagination. After calling this method, the DataTable will not perform pagination on the data.

Returns the updated DataTable instance.

func (*DataTable) Validate 

func (dt *DataTable) Validate() error

Validate checks the integrity of the DataTable configuration and request.

It ensures that either a model or a transaction (tx) with a valid gorm statement is provided. If a model is not explicitly set, it attempts to derive it from the gorm statement. The function also validates the request by checking the draw and columns parameters. If a regex search pattern is provided, it verifies that the pattern is valid. Returns an error if any of these validations fail, otherwise returns nil.

func (*DataTable) WhitelistColumn 

func (dt *DataTable) WhitelistColumn(columns ...string) *DataTable

WhitelistColumn marks one or more columns as whitelisted. Only columns that are whitelisted will be included in the final response. If no columns are passed, this function does nothing.

func (*DataTable) With 

func (dt *DataTable) With(relations ...string) *DataTable

With appends the specified relations to the DataTable's relations slice.

This function allows the user to specify related models that should be included in the query. The relations are typically defined as strings representing the names of the related models. These relations will be processed during query execution to preload associated data.

Returns the updated DataTable instance.

func (*DataTable) WithData 

func (dt *DataTable) WithData(key string, value any) *DataTable

WithData adds a key-value pair to the DataTable's additional data map.

This function allows the user to specify arbitrary key-value pairs that should be included in the DataTable's response. The key should be a string representing the key of the value, and the value should be the value itself. The function returns the updated DataTable instance.

func (*DataTable) WithNumber 

func (dt *DataTable) WithNumber() *DataTable

WithNumber adds a column named "No" to the DataTable, which is non-searchable and non-orderable. The column is then blacklisted, meaning it will not be included in the final response. This function returns the updated DataTable instance.

type Order 

type Order struct {
	Column int    `form:"column"`
	Dir    string `form:"dir"`
}

Order specifies the ordering criteria for a DataTable column.

Fields:

  • Column: The index of the column to be ordered.
  • Dir: The direction of ordering, either "asc" for ascending or "desc" for descending.

type Request 

type Request struct {
	Draw    int             `form:"draw"`
	Start   int             `form:"start"`
	Length  int             `form:"length"`
	Search  Search          `form:"search"`
	Order   []Order         `form:"order"`
	Columns []ColumnRequest `form:"columns"`
}

Request represents a DataTables request.

Fields:

  • Draw: The draw counter for this request.
  • Start: The start position for this request.
  • Length: The length of the request.
  • Search: The search criteria for this request.
  • Order: The ordering criteria for this request.
  • Columns: The columns to be processed for this request.

func ParseRequest 

func ParseRequest(r *http.Request) (*Request, error)

ParseRequest parses a DataTables request from the given http request.

It will automatically parse the draw, start, length, search, order, and columns parameters from the request. The request is validated and an error is returned if any part of the request is invalid.

The function returns the parsed request and nil if the request is valid, otherwise it returns nil and an error. 

type Search struct {
	Value string `form:"value"`
	Regex bool   `form:"regex"`
}

Search represents the search criteria for a DataTable.

Fields:

  • Value: The search term or value to be used.
  • Regex: A boolean indicating whether the search should be treated as a regular expression.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.