Instead of embeding inline script blocks into your view files, it's highly recommended to use the new module system for your modules frontend logic.
CSP Nonce Support
In order to be compatible with CSP nonce support, introduced with HumHub 1.4, you'll have to add a nonce attribute to all of your script blocks.
The nonce attribute is automatically added to script blocks registered by Asset Bundles
As mentioned above you should avoid using inline scripts and instead store code in separated source files. If you need to use inline script blocks you can use one of the following:
humhub\modules\ui\view\components\View::registerJs()will automatically add the nonce attribute
humhub\libs\Html::script()will automatically add the nonce attribute
humhub\libs\Html::beginTag()will automatically add the nonce attribute
- Or by using
Note: In case your module for any reason does have CSP nonce support or any other security restriction, you should highlight this in your module description.
Module script files should reside within the
resources/js folder of your humhub module and should ideally be appended at the bottom of your document. This can be achieved by using Asset Bundles.
Note: Make sure to add your assets after the core scripts, which are added within the html head.
Note: Your Asset Bundle should reside in the
assetssubdirectory of your module.
In your view you can register your Asset Bundle by calling
$this is the view instance. More infos about the use of Asset Bundles are available in the Yii Guide.
Modules are added to the
humhub.modules namespace by calling the
Example of a submodule:
The first argument of the
humhub.module function defines the module id, which should be unique within your network. The second argument is the actual module function itself.
Note: You should use an unique namespace for your custom modules as
myproject.mymoduleotherwise it may interfere with other modules.
Your module function will be called with the following arguments:
module- Your module instance, used for exporting module logic and accessing module specific utilities
require- Used for injecting other modules.
$- jQuery instance.
Module functions and attributes can only be accessed outside of the module if they are exported, either by directly appending them to the
module object or by calling
Your module's initialization logic can be implemented by exporting an
init function. This function will automatically be called after the page is loaded.
By default this function is only called once after a full page load (or directly after the registration if it was loaded per ajax). If your module requires a reinitialization also after Pjax page loads, your module has to set the
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 in order to prevent memory leaks, remove obsolete dom listeners, or clear some module data.
Other modules can be injected into your module by using the
Note: You should only require modules at the beginning of your own module, if you are sure the required module is already registered.
If your module requires other modules, which are not part of the core you can ensure the order by means of the
$depends attribute of your Asset Bundle:
If you can't assure the module registration order for another module, but need to require the module, you can either require it within your module function or use the
lazy flag of the require function.
The call of
require('anotherModule', true) will return an empty namespace object, in case the module was not registered yet. The module logic will be available after the registration of the dependent module.
Note: When using the
lazyflag, you can't assure the required module will be initialized within your own module's
Info: Since core modules are appended to the head section of your document, there shouldn't be any dependency problem.
If you need to transfer values as texts, settings or urls from your php backend to your frontend module, you can use the
module.config array which is automatically available within your module as in the following example:
In your view you can set the module configuration as follows
Note: Since the configuration can easily be manipulated, you should not set values which can compromise the security of your application.
TIP: Module setter are normally called within views or widgets to inject urls or translated text for user feedback or modals.
Beside the configuration addition, the module instance does furthermore provide a
module.text function for easily accessing texts of your configuration.
Example of an error text.
Access your text within your module function as this
Your module is able to create module specific log entries by using the
module.log object of your module instance.
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
- Details about the message (or errors in case of warn/error/fatal)
- A setStatus flag, which will trigger a global
humhub:modules:log:setStatusevent. This can be used to give user-feedback (status bar).
Instead of an actual message, you can also just provide a text key as the first argument. The following calls are valid:
Info: Your module logger will try resolving your message string to a module or global text.
Note: The success log will by default trigger a status log event.
The trace level of your module can be configured by setting the
traceLevel of your module configuration.
If your module does not define an own trace level the log modules's traceLevel configuration will be used.
Info: In production mode the default log level is set to
INFO, in dev mode its set to
Note: If you change the
traceLevelof a module at runtime, you'll have to call
module.config utility you can also use the global configuration as follows
humhub.config.is, you are able to check if a value is true