github.com/sharovik/devbot@v1.0.1-0.20240308094637-4a0387c40516/documentation/events.md (about) 1 # Events 2 This feature will help you to improve the skills of your bot. With it you are able to create your own event for your custom message. 3 4 ## Table of contents 5 - [Good to know](#good-to-know-for-event-setup) 6 - [Prerequisites](#prerequisites) 7 - [The event diagram](#the-event-diagram) 8 - [Event setup](#event-setup) 9 - [Example](#example) 10 11 ## Prerequisites 12 * run `cp defined-events.go.dist defined-events.go` to create the file where you will define your events 13 14 ## The event diagram 15  16 17 ## Event setup 18 * create your event directory in `events` directory. Ex: `events/mybrandnewevent` 19 * create in your new directory file with name `event.go`. There is no black magic inside the naming, we just introduce the structured way of how to define the event files. 20 * create the logic for your new event struct object and make sure this logic is compatible with the interface `container.DefinedEvent` 21 * add your object to the "map" of the events `events.DefinedEvents` in the `defined-events.go` file 22 ```go 23 var DefinedEvents = map[string]container.DefinedEvent{ 24 //... 25 mybrandnewevent.EventName: mybrandnewevent.Event, 26 } 27 ``` 28 29 ## Example 30 Now let's take a deep dive into custom event creation and create a custom event. 31 32 ### Prepare event folder 33 You need to specify the folder name without spaces. There should not be dashes or underscores in the package name, so please make sure you use a proper naming. 34 Let's call it `example` and create this example folder in the `events` folder. 35 36 ### The code 37 There is a [Base DefinedEvent interface](../internal/dto/event/defined_event.go) which defines the structure of each event. 38 The main methods are: 39 - `Install` - method, which install the scenarios for your event 40 - `Update` - once you introduce a migration for your event, this method will be triggered and migration will be applied 41 - `Execute` - main method for event logic execution. This method receives as argument the [message object](event-message.md) type of `dto.BaseChatMessage`. 42 43 Below, you can find an example of the event, which you can use as the base for your event 44 ```go 45 package example 46 47 import ( 48 "fmt" 49 50 "github.com/sharovik/devbot/internal/database" 51 52 "github.com/sharovik/devbot/internal/log" 53 54 "github.com/sharovik/devbot/internal/container" 55 "github.com/sharovik/devbot/internal/dto" 56 ) 57 58 const ( 59 //EventName the name of the event 60 EventName = "example" 61 62 //EventVersion the version of the event 63 EventVersion = "1.0.1" 64 65 helpMessage = "Ask me `who are you?` and you will see the answer." 66 ) 67 68 // EventStruct the struct for the event object. It will be used for initialisation of the event in defined-events.go file. 69 type EventStruct struct { 70 } 71 72 // Event - object which is ready to use 73 var Event = EventStruct{} 74 75 func (e EventStruct) Help() string { 76 return helpMessage 77 } 78 79 func (e EventStruct) Alias() string { 80 return EventName 81 } 82 83 // Execute method which is called by message processor 84 func (e EventStruct) Execute(message dto.BaseChatMessage) (dto.BaseChatMessage, error) { 85 //This answer will be show once the event get triggered. 86 //Leave message.Text empty, once you need to not show the message, once this event get triggered. 87 message.Text = "This is an example of the answer." 88 return message, nil 89 } 90 91 // Install method for installation of event 92 func (e EventStruct) Install() error { 93 log.Logger().Debug(). 94 Str("event_name", EventName). 95 Str("event_version", EventVersion). 96 Msg("Triggered event installation") 97 98 return container.C.Dictionary.InstallNewEventScenario(database.EventScenario{ 99 EventName: EventName, 100 EventVersion: EventVersion, 101 Questions: []database.Question{ 102 { 103 Question: "who are you?", 104 Answer: fmt.Sprintf("Hello, my name is %s", container.C.Config.MessagesAPIConfig.BotName), 105 QuestionRegex: "(?i)who are you?", 106 QuestionGroup: "", 107 }, 108 }, 109 }) 110 } 111 112 // Update for event update actions 113 func (e EventStruct) Update() error { 114 return nil 115 } 116 ``` 117 118 ### Result 119 #### With empty text message in Execute method 120  121 122 #### With the filled text message in Execute method 123  124 125 ### Source code 126 You can find the source code of the event in [events/example](https://github.com/sharovik/devbot/tree/master/events/example) folder