Gin-bat

Gin-bat adds the missing batteries to Gin Web Framework. Gin Web Framework is the fastest go web framework available, however it doesn't provide the most required features out-of-box. It's maily inspired by Django.

Features:

• MVC structure
• Database connection
• Basic routes
• Authentication system
• Project command line management
• Admin user interface

Contents

• Gin-bat
  • Contents
  • Command line
  • Project structure
  • Getting started
  • Customization
    • Logo
    • Title
    • Imports
    • Create a new page
    • Raise a html alert
    • Redirect
  • Write compatible queries/sql commands

Command line

Provides the following sub-commands:

• create-project : create a new project, copies all the required files for building a new server, to the given path
• create-user : create a new user profile
• update-user : modify an existing profile
• delete-user : delete a user
• change-password : change password access for a user
• create-token : create a token for an existing user, to enable api usage
• display-token : display the token for a given user
• runserver : run the server

Project structure

Once the project has been created, the following files are available for working on your web-application:

• urls.go : defines the route
• controller.go : defines the back-end source code (handlers)
• models.go : defines database tables golang objects (User struct with its methods are provided by default)
• common.go : includes function which are shared in the project. You add more there.

The remaining go files are supposed to be untouched, unless there are behaviours you wish to change to the core:

• main.go
• cmd.go
• built-in.go
• authentication.go

Getting started

1. Create a project with

   ginbat create-project <project-path>

   <project-path> will contain all the necessary files for running the server

2. Review the settings.json file for database connection and host/port settings. Note, the settings.json supports comments starting with // (they are discarded while reading the lines)

3. Run the server

   go run . runserver 

   Alternatively provide -H and/or -P for specifying respectively Host and Port

   go run . runserver -H 0.0.0.0 -P 8080

Customization

Logo

Modify templates/structure/topbar.html

Title

Modify templates/structure/middle.html

Imports

For convenience, all imports are located in templates/structure/imports.html - edit it for adding more.

Create a new page

1. Create html file in templates folder
2. For giving the same style, include the "structure" html files using the template keyword (remember to include the dot . character for passing the variables from the first html template to the nested ones).

   {{ template "Header"  . }}
   {{ template "Imports" . }}
   {{ template "Middle"  . }}
   {{ template "Topbar"  . }}
   <!-- Content -->
   <h1>Home</h1>
   {{ template "Footer"  . }}
   </body>
   </html>

3. Customize the content below the comment <!-- Content --> leaving the inclusions untouched.

Raise a html alert

ginbat ships a javascript function raiseAlert() (defined in templates/structure/alert.html) which renders bootstrap5 alerts

From the controller, return

func myHandler(c *gin.Context) {
  message := "My message"
  status := "0"  // successful status

  c.HTML(http.StatusOK, "page.html", gin.H{"Feedback": map[string]string{message: status}})
}

Accepted status are:

• "0" : 🟢 success ➡️ Green
• "1" : 🔴 danger ➡️ Red
• "2" : 🟠 warning ➡️ Orange

Hint: multiple (unique) messages can be provided in the map.

Redirect

Gin redirect works fine, however the page rendering doesn't allow to pass parameters. As workaround, you can render the page you wish and pass "Url" parameter for adjusting the url in the browser.

This is defined in templates/structure/footer.html

From the controller, return

func myHandler(c *gin.Context) {
  c.HTML(http.StatusOK, "page.html", gin.H{"Url": "/"})
}

Write compatible queries/sql commands

1. Use ` as string limitator instead of "

   myQuery := `SELECT id, username FROM "Users"`
   

2. Table must be in double quotes SELECT id, username FROM "Users"
3. Avoid keyword as fields or table names (e.g: key and Users are used by Postgres)
4. Parameter must be specified in the query string with $1, $2 etc., not with ?
5. Bool values needs to be expressed with 0 (False) and 1 (True)