Publish a Module Asset
Your script files should reside within the
resources/js folder of your humhub module and should ideally be appended at the bottom of the document.
assets directory of your module. By setting
public $jsOptions = ['position' => \yii\web\View::POS_END];, your assets will be appended to the end of the document body. This will assure all core modules are already registered.
Be careful though, when you want to edit your files in
resources/js. All asset files are bundled and then copied to the
@webroot-folder of your application, when registered in the view for the first time (see below). In order to force your module assets to be re-published with each requests, you can add the publish option
forceCopy as in the following example. This can be useful while developing your module, but don't forget to disable this option in official releases!
The Asset Bundle can be registered to a view by calling
$this is the view instance. More infos about Asset Bundles are available in the Yii Guide.
If your bundle is registered to a view retrieved by an ajax call, make sure to render your view by using your controllers
$this->renderAjaxContent() function. In contrast to
renderPartial(), this function will add all your asset dependencies to your partial content.
Note: Make sure to add your assets after the core scripts, which are added within the documents head section.
Modules are registered by calling the
humhub.module function as follows
Submodules can be registered as follows
The first argument of the
humhub.module function defines the module id which will be appended to the
humhub namespace. The previous
example module will be added to the following namespace
humhub.modules.example. The second argument is the actual module function.
Note: Your module id has to be unique amongst all available modules and should ideally be consistent with your backend module id.
Your module function is provided with the following arguments:
module- Your module instance, used for exporting module logic and accessing module specific utilities as
require- Used for injecting other modules.
$- jQuery instance.
Export Module Logic
Module functions and attributes can only be accessed outside of the module if they are exported, either by directly appending them to the
module instance or by calling
In case you only want to export a single object/function/class you can use the following syntax:
Note: When exporting a single object or class, the exported object won't have the usual module attributes and utilities. The plain object or function will simply be added to the namespace.
Your module can define its initialization logic by implementing and exporting an
By default this function is only called once after a full page load or directly after the registration in case the module was loaded per ajax. If your module requires an initialization also after Pjax page loads, your module has to set the
initOnPjaxLoad flag. In this case the
init function will provide an
isPjax parameter for beeing able to distinguish between full page loads and Pjax page loads.
Warning: Once registered, your modules
initfunction may be called even if you are not currently in your desired modules view. This occures especially if Pjax is enabled and
initOnPjaxLoadis set to
true. Therfore, if your modules initialization logic only makes sense in a specific context, make sure you reside in the desired view before running your actual initialization code e.g:
For the purpose of cleaning up module related dom nodes etc. there is also an
unload function which is called before each Pjax page load. This function is mainly used to remove obsolete dom nodes, prevent memory leaks, remove obsolete dom listeners or clear some module data.
Note: Some third party libraries append helper elements to the document body. Make sure to remove such elements in the
Other modules can be injected into your module by using the
require function as follows
It is a good practice to require all dependent modules at the beginning of your module. You should only require modules at the beginning of your module, if you are sure the required module is already registered. Since all core modules are registered in the head section of your document, they are available within the document body.
If your module requires another module, which is not part of the core API, you can ensure the order by means of the
$depends attribute of your Asset Bundle class.
In case you can't assure the module registration order of a required module, but need to import the module, you can either require the module on demand within your module function or use the
lazy flag of the require function.
The call to
require('anotherModule', true) will return an empty namespace object in case the dependent module has not been registered yet. The actual module logic will be available after the dependent module is registered.
Warning: When using the
lazyflag, you can't assure the required module is already initialized within your own modules
Info: All core modules are appended to the head section of your document, so they should not be any dependency problem if you append your assets either at the begin or the end of the document body.
A module runs through the following lifecycle (by the example of our
- Full Page load
humhub.module- the module is registered but not initialized
- Document Ready
- Calling the modules
- Pjax call
- Calling the modules
- Reinitialize all modules with
isPjax = true
module.config array as follows
The configuration can be set in your php view as follows
Warning: Since the configuration can easily be manipulated, you should not set values which can compromise the security of your application.
config array, the module instance furthermore provides a
text utility function for accessing texts configurations.
Access your text within your js module as this
Your module can be used to create module specific log entries by using the
The log object supports the following log level functions:
- trace - For detailed trace output
- debug - For debug output
- info - Info messages
- success - Used for success info logs
- warn - Warnings
- error - For error messages
- fatal - Fatal errors
All log functions accept up to three arguments:
- The actual message (or text key)
- Details about the message this could be an js object an error or a client response object
- A setStatus flag, which will trigger a global
humhub:modules:log:setStatusevent. This can be used to trigger the status bar for providing user feedback.
The following calls are valid:
The trace level of your module can be configured by setting the
traceLevel configuration. If your module does not define an own trace level the log modules's traceLevel configuration will be used instread. In production mode the default log level is set to
INFO, in dev mode its set to
Info: Your module logger will try to resolve a given text key to a module or global text.
module.log.success()function will trigger a status bar update by default.
Note: If you change the
traceLevelof a module at runtime, you'll have to call
Overwrite Module Behaviour
You can overwrite the default module exports within your custom module by listening to the
beforeInit function of the target module.
Within your example module: