Plugin Tutorial

1. Structure Of A Plugin

Including 2 part:

  • Delivery: Where receive parameters are passed from a module. Then, it will validate some fields in the parameter that is required before going to UseCase.
  • UseCase: It will receive the parameters which are validated in the Delivery. Then, the UseCase will process each logic business step.

2. Connect important Ugene Libraries.

  • Delivery:

    • _signinUsecase “ugene/modules/auth/plugin/sign-in/usecase”: import package Usecase to create a object usecase of plugin.
    • _repository “ugene/modules/auth/repo”: import the package Repository that will process some tasks with database such as Get, Insert, Update, Delete etc.
    • “ugene/modules/auth/lib”: import the package lib that will contain functions and interface. It supports processing data for Delivery and UseCase such as convert and validate data, generate, assign type data… etc.
    • “ugene/modules/auth/model”: import the package which contains some structure of table will be used in UseCase. Besides, it also contains an interface of UserCase and Repository for each plugin.
    • “github.com/gookit/validate”: import the Validate package which is used to validate data of some field. Some cases need to be validated including check empty value, check data type, check numeric of string… etc.
    • “github.com/microcosm-cc/bluemonday”: The package is used to remove all html tags and script tags out a string.
    • “github.com/spf13/viper”: Import the package which is used to take value in any field in configuration.
    • “gorm.io/gorm”: The package is used to communicate with the database and create some queries which will impact the table of the database.

  • UseCase: Logic business of each plugin is different. So UseCase will use some packages which are not the same.

    • “github.com/spf13/viper”: Import the package which is used to take value in any field in configuration.
    • “ugene/modules/auth/model”: import the package which contains some structure of table will be used in UseCase. Besides, it also contains an interface of UserCase and Repository for each plugin.
    • “ugene/modules/auth/lib”: import the package lib that will contain functions and interface. It supports processing data for Delivery and UseCase such as convert and validate data, generate, assign type data… etc.
    • “time”: the package is used to process tasks about time such as get time now.

3. Ugene Table Structure

  • import: “ugene/modules/auth/model” to use struct of tables. Because each module will use some difference table and package model will be outside the plugin. All plugins in the module will use the general package model.
  • Some table structures are usually used for plugins such as: User, UserConfig, Roles, UserHash, UserToken… etc.

4. Input Data Flow

  • To infuse parameters into any plugin, you have to import package Delivery of plugin and call function Init(). res = _signinDelivery.Init(db, args, redis, memcached)
  • Four variable are passed into function Init() including:
    • db: type is *gorm.DB. a connection was created by Ugene and passed into the module.
    • args: type is map[string]interface. this variable contains all parameters and is passed into the plugin. because parameters have many type data differences, the value of each field in args will be interface type.
    • redis: type is interface. It is a variable which simulates functions of the redis package. These functions allow you to get, insert, update or delete any key in redis server.
    • memcached: type is interface. It is a variable which simulates functions of memcached packages. These functions allow you to get, insert, update or delete any key in memcached server.
  • Data flow of Delivery:
    • Function Init(): It is the function which is called first by module. The function Init() will initialize some objects from the package repository. Then, it will pass parameters including args into the function SignIn() which will process the validation step.
    • Function SignIn(): The function will receive a parameter which is args. After the validation requirement field, it will call the function processing of UseCase.
  • Data flow of UseCase:
    • InitSignInUseCase(): This function will be called by the function Init() of Delivery when the plugin wants to initialize object UseCase and assign it to Delivery. Each repository is passed into InitSignInUseCase() will be a table which is used by the plugin.
    • SignIn(): it will receive a parameter which is named args. The variable args contain values that the plugin needs to process.

5. Output Data Flow

  • All plugins always return a response which has a type map[string]interface.

  • The fields of response will be formatted by the UseCase of plugin. if response have fail status, response have format: map[string]interface{}{ “error”: true, “code”: “001101”, “result”: nil, “msg”: err.Error(), }

  • If responses have successful status, responses have format same below.

    • Field “action”: It is a string array with each value represented for a processing will be run after the module return result. These actions could be sending email, backup data or export data which will process when the plugin finishes.

    • Field “error”: this is the status of response which has value true or false.

    • Field “code”: The notice code of response. Maybe it is a result or error, so Ugene will compare it with fields in configuration.

      map[string]interface{}{ “error”: false, “code”: “100104”, “action”: []string{“send-email”}, “data”: map[string]interface{}{ “fullname”: userObj.Username, “email”: userObj.Email, “hash”: userHash.Hash, “type”: “send-otp”, }, “msg”: “”, }