top
(README.md)
# Transition

Transition is a Golang state machine implementation.

Transition can be used standalone, but it works very nicely with [GORM](https://github.com/jinzhu/gorm) models. When integrated with GORM, it will also store state change logs in the database automatically.

[![GoDoc](https://godoc.org/github.com/qor/transition?status.svg)](https://godoc.org/github.com/qor/transition)

# Usage

### Enable Transition for your struct

Embed `Transition` into your struct, it will enable the state machine feature for the struct:

```go
import "github.com/qor/transition"

type Order struct {
  ID uint
  transition.Transition
}
```

### Define States and Events

```go
var OrderStateMachine = transition.New(&Order{})

// Define initial state
OrderStateMachine.Initial("draft")

// Define a State
OrderStateMachine.State("checkout")

// Define another State and what to do when entering and exiting that state.
OrderStateMachine.State("paid").Enter(func(order interface{}, tx *gorm.DB) error {
  // To get order object use 'order.(*Order)'
  // business logic here
  return
}).Exit(func(order interface{}, tx *gorm.DB) error {
  // business logic here
  return
})

// Define more States
OrderStateMachine.State("cancelled")
OrderStateMachine.State("paid_cancelled")


// Define an Event
OrderStateMachine.Event("checkout").To("checkout").From("draft")

// Define another event and what to do before and after performing the transition.
OrderStateMachine.Event("paid").To("paid").From("checkout").Before(func(order interface{}, tx *gorm.DB) error {
  // business logic here
  return
}).After(func(order interface{}, tx *gorm.DB) error {
  // business logic here
  return
})

// Different state transitions for one event
cancellEvent := OrderStateMachine.Event("cancel")
cancellEvent.To("cancelled").From("draft", "checkout")
cancellEvent.To("paid_cancelled").From("paid").After(func(order interface{}, tx *gorm.DB) error {
  // Refund
}})
```

### Trigger an Event

```go
// func (*StateMachine) Trigger(name string, value Stater, tx *gorm.DB, notes ...string) error
OrderStatemachine.Trigger("paid", &order, db, "charged offline by jinzhu")
// notes will be used to generate state change logs when works with GORM

// When using without GORM, just pass nil to the db, like
OrderStatemachine.Trigger("cancel", &order, nil)

OrderStatemachine.Trigger("cancel", &order, db)
// order's state will be changed to cancelled if current state is "draft"
// order's state will be changed to paid_cancelled if current state is "paid"
```

### Get/Set State

```go
var order Order

// Get Current State
order.GetState()

// Set State
order.SetState("finished") // this will only update order's state, won't save it into database
```

## State change logs

When working with GORM, it will store all state change logs in the database, use `GetStateChangeLogs` to get those logs:

```go
// create the table used to store logs first
db.AutoMigrate(&transition.StateChangeLog{})

// get order's state change logs
var stateChangeLogs = transition.GetStateChangeLogs(&order, db)

// type StateChangeLog struct {
// 	 From       string  // from state
// 	 To         string  // to state
// 	 Note       string  // notes
// }
```

## License

Released under the [MIT License](http://opensource.org/licenses/MIT).

Imported by 39 package(s)

  1. github.com/GazeboXu/qor-example/app/orders
  2. github.com/GazeboXu/qor-example/models/orders
  3. github.com/andboson/qor-admin-test/db/migrations
  4. github.com/averrin/shodan
  5. github.com/chazzuka/qor-example/app/models
  6. github.com/chazzuka/qor-example/config/admin
  7. github.com/chazzuka/qor-example/db/migrations
  8. github.com/mmanjoura/cms-api/app/orders
  9. github.com/mmanjoura/cms-api/config/db/migrations
  10. github.com/mmanjoura/cms-api/models/orders
  11. github.com/mmanjoura/qor-app/qor-example/config/db/migrations
  12. github.com/mmanjoura/qor-example/app/models
  13. github.com/mmanjoura/qor-example/config/admin
  14. github.com/mmanjoura/qor-example/db/migrations
  15. github.com/mstat/qor-example/app/models
  16. github.com/mstat/qor-example/config/admin
  17. github.com/mstat/qor-example/db/migrations
  18. github.com/oywc410/qor-example/app/models
  19. github.com/oywc410/qor-example/config/admin
  20. github.com/oywc410/qor-example/db/migrations
  21. github.com/qor/qor-example/app/models
  22. github.com/qor/qor-example/app/orders
  23. github.com/qor/qor-example/config/admin
  24. github.com/qor/qor-example/config/db/migrations
  25. github.com/qor/qor-example/db/migrations
  26. github.com/qor/qor-example/models/orders
  27. github.com/reechou/erp/app/models
  28. github.com/reechou/erp/db/migrations
  29. github.com/reechou/real-erp/admin
  30. github.com/reechou/real-erp/models
  31. github.com/steveoc64/qor-example/app/models
  32. github.com/steveoc64/qor-example/config/admin
  33. github.com/steveoc64/qor-example/db/migrations
  34. github.com/whimsycwd/qor-example/app/models
  35. github.com/whimsycwd/qor-example/config/admin
  36. github.com/whimsycwd/qor-example/db/migrations
  37. github.com/youryharchenko/qor-example/app/models
  38. github.com/youryharchenko/qor-example/config/admin
  39. github.com/youryharchenko/qor-example/db/migrations

Imported only in test by 3 package(s)

  1. github.com/mmanjoura/qor-app/transition
  2. github.com/rbastic/transition
  3. github.com/uzmo/transition

Imports 5 package(s)

  1. github.com/qor/roles
  2. github.com/jinzhu/gorm
  3. github.com/qor/admin
  4. github.com/qor/audited
  5. github.com/qor/qor/resource

Test imports 2 package(s)

  1. github.com/mattn/go-sqlite3
  2. github.com/qor/qor/test/utils