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  ![base-event-diagram](images/base-event-scheme.png)
    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  ![empty text message](images/example-event-text-empty.png)
   121  
   122  #### With the filled text message in Execute method
   123  ![with text message](images/demo-who-are-you.gif)
   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