How to make a custom module for Humhub (some interpretation on the official page) (1)

Aug 29, 2020 PHP yii2 HumHub

#Introduction I took a quick look around, and although I found a humhub operation article in Japanese, I found that there was little information on module development. In addition, there was an opinion as to whether to record and disseminate technical information within the colleagues operating humhub. Therefore, I decided to make a memorandum of my work and the meaning of succession of technology to make a record and to disseminate the information.

This document contains the minimum required information. For more information, please rely on the “latest” information document on the official page. Please be aware that the official website will be rewritten suddenly without showing any notice or update history. In addition, although there may be some thorns against the formula in this text, the reader’s sympathy may be obtained because it is an official document that makes you want to grow thorns. It’s It may be a remoteness that cannot keep up with the ideas of adolescents born in Heisei. I want you to forgive me.

https://docs.humhub.org/docs/develop/modules

Below, please read with a broad mind. This is because there are a lot of junk commentary created from experience about parts that are not known from the official information. It may be a misinterpretation, or it may contain extra information. It’s hard to say it’s not fake news, but at the very least, I’m seriously writing that system event callbacks can be used. I’m sorry because it’s written only in Japanese, but at least one person in the world believes that this information will be useful, and I write it. Again, I would like you to understand that I made it with the feeling that I want you to forgive it and decided to send information.

#How custom modules work

Custom module location

 Default: (humhub root) /protected/modules

There is no problem even if you use the default settings (should). You can change this folder (as a humhub system), but that’s not relevant to this document. It is enough to remember for reference only that it depends on the setting value of moduleAutoloadPaths. https://docs.humhub.org/docs/develop/environment#module-loader-path

Required minimum operation file

The custom module requires the following three files:

・Config.php ・Module.json ・Module.php

The humhub system searches for these files by crawling the folder in the custom module location. If there are not enough files or there is a mistake in drawing the file, not only a “module cannot be read” error will occur, but the system will stop booting there. The description operation requires caution.

Briefly describe the contents of each file.

・Config.php A file in which the basic information of the module is written.

It must be made to return the associative array of the following information. There are other options, but only the required items (requirement) are written here. It seems safe to write the item names in lowercase letters because it seems that the character strings are compared in the system. Also, it is a rule to put only static declaration here, and dynamic code should not be written in this php file (it does not work well if written).

These three are the “mandatory items” in the official document. However, when actually operating a module, it is not possible to operate only with such “information about self-introduction of the module”. By describing the following items, it will be possible to describe and operate a callback triggered by an event of the humhub system.

I have introduced events according to the official information, but what about? I think there are many geniuses in the world who can write programs with just this, and the Uncle of Showa couldn’t hide his astonishment. Does anyone wonder if the contents of the array will be touched only by the array of event configuration information (the original text: Array containing the modules event configuration)? If you are curious, please rest assured that there is a description on the official page of another page (Event Handler). https://docs.humhub.org/docs/develop/modules-event-handler

By the way, the contents of this array of events are as follows.

An array in the array to describe as the value of the events item

The config.php created based on the above is the following example.

// @example/config.php
use humhub\widgets\TopMenu;

return [
    'id' =>'example',
    'class' =>'johndoe\example\Module',
    'namespace' =>'johndoe\example',
    'events' => [
        [
           'class' => TopMenu::class,'event' => TopMenu::EVENT_INIT,
           'callback' => ['johndoe\example\Events','onTopMenuInit']
        ]
    ]
];

(This example is taken from the official description.) Please note that the function file and the name of the function you want to execute are described in the callback item of the first element of the events array. It is also possible to add an element to the events array to create a module that responds to multiple triggers.

• Module.json File that describes the metadata of the module.

This file is used by humhub system’s module manager and marketplace. You can think of it as a file to write external module introduction information. Again, only the essential items are explained.

The above are the required items required by the system. The official comment has been added, but I personally recommend that you also list the version of Humhub that the development module supports. For the time being, listing the version of the Humhub system of your own development environment in minVersion should give other users peace of mind knowing the available system version.

Module.json created based on the above is the following example.

{
    "id": "example",
    "version": "1.0",
    "name": "My Example Module",
    "description": "My testing module.",
    "humhub": {
        "minVersion": "1.2",
        "maxVersion": "2.0"
    },
    "keywords": ["my", "cool", "module"],
    "screenshots": ["assets/screen_1.jpg"],
    "homepage": "https://www.example.com",
    "authors": [
        {
            "name": "Tom Coder",
            "email": "[email protected]",
            "role": "Developer"
        },
        {
            "name": "Sarah Mustermann",
            "email": "[email protected]",
            "homepage": "http://example.com",
            "role": "Translator"
        }
    ]
}

(This example is taken from the official description.)

-Module.php A file that describes the basic operation of the module by inheriting the base module class.

Not only the callback function of events, but also the operation option at the time of installation/uninstallation, and the description for multilingual can be described. For details, see the official next page. https://docs.humhub.org/docs/develop/modules-base-class

There are two classes to inherit: humhub\components\Module or humhub\modules\content\components\ContentContainerModule. The criteria for selecting these two base modules are whether the former is for modules that act on the global level, the latter is for the space or user level (space and/or user level), But… Specifically, the former is a type that is widely used by the system, such as a post-like function or user information, and the latter is a type that the user selects and uses as a space module such as a calendar or Wiki. I think you should get it. (I’m sorry for the explanation that only humhub specification experts can understand)

Module life cycleThe explanation is officially handed over. https://docs.humhub.org/docs/develop/modules#module-lifecycle

Other files that can be included in the module

Documents

Docs folder is created and stored for documents. Please note that some files are required when listing on the Marketplace.

Module file structure

Officially, the following common module diretories are suggested for file allocation. Some of them are designated by the system, so it may be safer to follow the basics.

This is the end of the explanation on the official page on how to create a custom module.

As you can see, it is not practical because it explains how to make formwork. The point when making a custom module as a practice is how to write the events item described in config.php. Especially, understanding how to pick up events is important.

Regarding how to pick up events, we are considering the explanation on the next page. https://docs.humhub.org/docs/develop/modules-event-handler

This is the end of this article.