mirror of
https://github.com/humhub/humhub.git
synced 2025-01-17 06:08:21 +01:00
Developer doc enhancements.
This commit is contained in:
buddh4
parent
4d7c09423a
commit
7b981d6caa
@ -17,13 +17,11 @@ Call the following commands in your humhub root directory:
|
||||
|
||||
## Build Assets
|
||||
|
||||
HumHub uses Yiis build in mechanism for compressing and combining assets as javascript or stylesheet files in combination with grunt.
|
||||
HumHub uses Yii`s build-in mechanism for compressing and combining assets as javascript or stylesheet files in combination with grunt.
|
||||
Those compressed assets are only used when running in [production mode](admin-installation.md#disable-errors-debugging) and in [acceptance tests](testing.md).
|
||||
|
||||
Your compressed files will be saved under `/humhub/js/all-*.js` respectively `static/css/all-*.css`.
|
||||
|
||||
> Note: HumHub will only use the compressed assets if operated in [production mode](admin-installation.md#disable-errors-debugging), otherwise
|
||||
all assets will be served seperatly.
|
||||
|
||||
### Grunt Asset Built
|
||||
|
||||
The simples way to build your production assets is using the following grunt task:
|
||||
|
||||
@ -57,7 +57,7 @@ public function actionEdit($id = null) {
|
||||
}
|
||||
```
|
||||
|
||||
## Implement Custom ContentActiveRecords
|
||||
## Content and ContentActiveRecords
|
||||
|
||||
Just like other [ActiveRecords](https://www.yiiframework.com/doc/guide/2.0/en/db-active-record) `ContentActiveRecord` classes should be put under the `yourModule/models` namespace of your module.
|
||||
Beside the basic `ActiveRecord` features as `validation` and `attributeLabels` your `ContentContainerActiveRecord` class should at least implement the following fields and methods:
|
||||
@ -99,7 +99,7 @@ class MyModel extends ContentActiveRecord
|
||||
}
|
||||
```
|
||||
|
||||
## Instantiating a ContentContainerActiveRecord:
|
||||
### Instantiating a ContentContainerActiveRecord:
|
||||
|
||||
You can instantiate your `ContentContainerActiveRecord` as follows:
|
||||
|
||||
@ -139,7 +139,7 @@ $model = $content->getModel();
|
||||
> Note: You won't have to worry about instantiating or saving the underlying content record, since this is handled within
|
||||
the ContentContainerActiveRecord class automatically.
|
||||
|
||||
## Use of ActiveQueryContent:
|
||||
### Use of ActiveQueryContent:
|
||||
|
||||
The `Content` class furthermore provides some extended [ActiveQuery](https://www.yiiframework.com/doc/guide/2.0/en/db-active-record#querying-data) capabilities.
|
||||
Calling [[\humhub\modules\content\components\ContentActiveRecord::find()|ContentActiveRecord::find()]] will return a [[\humhub\modules\content\components\ActiveQueryContent]] instance with additional methods to filter specific content entries:
|
||||
@ -169,7 +169,7 @@ There are the following user related scopes available:
|
||||
- `USER_RELATED_SCOPE_FOLLOWED_USERS` = Content related to the users followed user profiles
|
||||
- `USER_RELATED_SCOPE_OWN_PROFILE` = Content related to the users own profile
|
||||
|
||||
## Move Content (since v1.3)
|
||||
### Move Content (since v1.3)
|
||||
|
||||
In case your content should be movable to other spaces you'll have to enable the [[\humhub\modules\content\components\ContentActiveRecord::canMove|ContentActiveRecord::canMove]] flag.
|
||||
For complex content-types you may want to overwrite the [[\humhub\modules\content\components\ContentActiveRecord::afterMove()|ContentActiveRecord::afterMove()]] function.
|
||||
@ -185,13 +185,13 @@ public function afterMove($container = null)
|
||||
}
|
||||
```
|
||||
|
||||
## Silent Content Creation
|
||||
### Silent Content Creation
|
||||
|
||||
By default, the creation of a content entry triggers an activity and notifications for space subscribers.
|
||||
This behaviour can be deactivated by setting the [[\humhub\modules\content\components\ContentActiveRecord::silentContentCreation|ContentActiveRecord::silentContentCreation]]
|
||||
to `true`. This setting can for example be used for sub content-types which are not of high interest.
|
||||
|
||||
## Content Visibility
|
||||
### Content Visibility
|
||||
|
||||
The content visibility specifies who is be allowed to view the content. When instantiating a new `ContentActiveRecord` without [a predefined visibility](#instantiating-a-contentcontaineractiverecord)
|
||||
the underlying content will adapt the default content visibility of its `ContentContainerActiveRecord`.
|
||||
@ -230,7 +230,7 @@ if(!$model->content->canView()) {
|
||||
|
||||
> Info: Private spaces can not create public content.
|
||||
|
||||
## Content Write Permission
|
||||
### Content Write Permission
|
||||
|
||||
By default users can edit a content if one of the following conditions defined in `Content::canEdit()` are met:
|
||||
|
||||
@ -271,7 +271,9 @@ class Example extends ContentContainerActiveRecord
|
||||
|
||||
>Info: For more information about permissions, please see the [Permission Section](module-permissions.md).
|
||||
|
||||
## Content Url
|
||||
### Other content features
|
||||
|
||||
#### Content Url
|
||||
|
||||
By default the url returned by `Content::getUrl()` links to the space or profile stream with active `contentId` filter.
|
||||
If you want to change this behaviour and for example rather link to a content-type specific detail view of your content, you can
|
||||
@ -290,9 +292,7 @@ Retrieve the content url:
|
||||
$url = $model->content->getUrl();
|
||||
```
|
||||
|
||||
## Other content features
|
||||
|
||||
### Pin content
|
||||
#### Pin content
|
||||
|
||||
The default space stream supports the pinning of content, which will load the pinned entries at the top of the
|
||||
stream. Normally you won't need to call the pin/unpin methods by yourself, since this is part of the default stream
|
||||
@ -308,7 +308,7 @@ $model->content->isPinned();
|
||||
$model->content->canPin();
|
||||
```
|
||||
|
||||
### Archive content
|
||||
#### Archive content
|
||||
|
||||
Archived content is by default excluded from the streams. As with the pin logic, you won't have to handle this by yourself.
|
||||
|
||||
@ -396,10 +396,6 @@ This will add the required cguid parameter to your request.
|
||||
|
||||
See the [Use of ContentContainerModule](modules.md#use-of-container-module) section.
|
||||
|
||||
## Content Streams
|
||||
|
||||
See the [Stream](stream.md) section
|
||||
|
||||
## Content addons
|
||||
|
||||
TBD
|
||||
@ -407,3 +403,7 @@ TBD
|
||||
- Always linked to particual Content, inherits access rules from it
|
||||
- Examples: Like, File, Comment
|
||||
- Can be nested (e.g. Container -> Content -> Addon (Comment) -> Addon (Like)
|
||||
|
||||
## Content Streams
|
||||
|
||||
See the [Stream](stream.md) section
|
||||
|
||||
@ -15,7 +15,7 @@ External Modules Directory
|
||||
-----------------
|
||||
|
||||
Custom modules can also be located outside of the default HumHub `modules` directory by
|
||||
setting the `moduleAutoloadPaths` parameter in your `protected/config/common.php` configuration. This separation can
|
||||
adding a path to the `moduleAutoloadPaths` array parameter in your `protected/config/common.php` configuration. This separation can
|
||||
be useful while developing custom modules.
|
||||
|
||||
```php
|
||||
@ -29,8 +29,10 @@ return [
|
||||
Yii Debug Module
|
||||
----------------
|
||||
|
||||
Add the following block to your local web configuration `protected/config/web.php` in order
|
||||
to enable the [Yii's debug Module](http://www.yiiframework.com/doc-2.0/ext-debug-index.html).
|
||||
You may want to enable the [Yii's debug Module](http://www.yiiframework.com/doc-2.0/ext-debug-index.html) for detailed
|
||||
request and query debugging.
|
||||
|
||||
Just add the following block to your local web configuration `protected/config/web.php`:
|
||||
|
||||
```php
|
||||
return [
|
||||
@ -50,4 +52,4 @@ return [
|
||||
Developer Tools Module
|
||||
-------------------
|
||||
|
||||
The [devtools Module](https://github.com/humhub/humhub-modules-devtools) provides useful showcases of widgets and a Module generator based on [Gii](https://www.yiiframework.com/doc/guide/2.0/en/start-gii).
|
||||
The [devtools Module](https://github.com/humhub/humhub-modules-devtools) provides some useful showcases of widgets and a Module generator based on [Gii](https://www.yiiframework.com/doc/guide/2.0/en/start-gii).
|
||||
|
||||
@ -2,7 +2,8 @@ Git/Composer Installation
|
||||
=========================
|
||||
|
||||
The following guide describes a git based installation of the HumHub platform. Please note that this is only recommended for
|
||||
developers and testers and should not be used as production installation. For production systems, please follow the [Installation Guide for Administrators](../admin/installation.md).
|
||||
developers and testers and should not be used in production environments.
|
||||
For production environments, please follow the [Installation Guide for Administrators](../admin/installation.md).
|
||||
|
||||
Database Setup
|
||||
-----------
|
||||
@ -25,6 +26,7 @@ composer install
|
||||
```
|
||||
|
||||
> Note: The composer update may have to be executed again after an update of your local repository by a git pull. Read more about updating ([Update Guide](../admin/updating.md))
|
||||
|
||||
> Note: Since HumHub 1.3 you have to build the production assets manually, please see the [Build Assets Section](build.md#build-assets) for more information.
|
||||
|
||||
- Follow further instructions of the [Installation Guide](../admin/installation.md)
|
||||
|
||||
@ -1,12 +1,10 @@
|
||||
Javascript API Getting Started
|
||||
Javascript Module Guide
|
||||
=======
|
||||
|
||||
Since version 1.2, HumHub provides a module based Javascript API within the `humhub` namespace.
|
||||
Instead of embeding inline script blocks into your views, it's highly recommended to store your Javascript code in external script files and use the HumHub module system.
|
||||
|
||||
## Modules System
|
||||
|
||||
### Publish a Module Asset
|
||||
## 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.
|
||||
|
||||
@ -48,7 +46,7 @@ If your bundle is registered to a view retrieved by an ajax call, make sure to r
|
||||
|
||||
> Note: Yii loads Javascript Files only once per page load, therefore all your script files will only be loaded and executed once. This can lead to unexpected behaviour especially with [Pjax](javascript-client.md) single page loading enabled.
|
||||
|
||||
### Register Modules
|
||||
## Register Modules
|
||||
|
||||
Modules are registered by calling the `humhub.module` function as follows
|
||||
|
||||
@ -75,7 +73,7 @@ Your module function is provided with the following arguments:
|
||||
2. `require` - Used for injecting other modules.
|
||||
3. `$` - jQuery instance.
|
||||
|
||||
##### Export Module Logic
|
||||
### 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 `module.export`.
|
||||
|
||||
@ -109,7 +107,7 @@ module.export = MyClass;
|
||||
```
|
||||
> 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.
|
||||
|
||||
##### Module Initialization
|
||||
### Module Initialization
|
||||
|
||||
Your module can define its initialization logic by implementing and exporting an `init` function.
|
||||
|
||||
@ -136,7 +134,7 @@ module.export({
|
||||
|
||||
> Warning: Once registered, your modules `init` function may be called even if you are not currently in your desired modules view. This occures especially if [Pjax](javascript-pjax.md) is enabled and `initOnPjaxLoad` is 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: `if(!$('#mySpecialElement').length) {return;}`.
|
||||
|
||||
##### Module Unload
|
||||
### Module Unload
|
||||
|
||||
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.
|
||||
|
||||
@ -152,7 +150,7 @@ module.export({
|
||||
|
||||
> Note: Some third party libraries append helper elements to the document body. Make sure to remove such elements in the `unload` function.
|
||||
|
||||
##### Module Dependencies
|
||||
### Module Dependencies
|
||||
|
||||
Other modules can be injected into your module by using the `require` function as follows
|
||||
|
||||
@ -207,7 +205,7 @@ humhub.module('example', function(module, require, $) {
|
||||
|
||||
> 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.
|
||||
|
||||
### Module Lifecycle
|
||||
## Module Lifecycle
|
||||
|
||||
A module runs through the following lifecycle (by the example of our `example` module):
|
||||
|
||||
@ -226,7 +224,7 @@ A module runs through the following lifecycle (by the example of our `example` m
|
||||
13. `humhub:modules:client:pjax:success`
|
||||
14. Reinitialize all modules with `initOnPjaxLoad=true` by calling `init` with `isPjax = true`
|
||||
|
||||
### Module Configuration
|
||||
## Module Configuration
|
||||
|
||||
If you need to transfer values as texts, flags or urls from your php backend to your Javascript module, you can use the `module.config` array as follows
|
||||
|
||||
@ -283,7 +281,7 @@ humhub.config.set('myModule', 'myKey', 'value');
|
||||
|
||||
> Warning: Since the configuration can easily be manipulated, you should not set values which can compromise the security of your application.
|
||||
|
||||
### Module Texts
|
||||
## Module Texts
|
||||
|
||||
Beside the `config` array, the module instance furthermore provides a `text` utility function for accessing texts configurations.
|
||||
|
||||
@ -305,7 +303,7 @@ module.text('error.notallowed');
|
||||
module.config['text']['error.notallowed'];
|
||||
```
|
||||
|
||||
### Module Log
|
||||
## Module Log
|
||||
|
||||
Your module can be used to create module specific log entries by using the `module.log` utility.
|
||||
The log object supports the following log level functions:
|
||||
@ -345,4 +343,26 @@ The trace level of your module can be configured by setting the `traceLevel` con
|
||||
|
||||
> Info: The `module.log.success()` function will trigger a status bar update by default.
|
||||
|
||||
> Note: If you change the `traceLevel` of a module at runtime, you'll have to call `module.log.update()`.
|
||||
> Note: If you change the `traceLevel` of a module at runtime, you'll have to call `module.log.update()`.
|
||||
|
||||
## Overwrite Module Behaviour
|
||||
|
||||
You can overwrite the default module exports within your custom module by listening to the `beforeInit` function the target module.
|
||||
|
||||
Within your example module:
|
||||
|
||||
```javascript
|
||||
// you can also use humhub.modules.event instead in case you are outside a humhub module
|
||||
var event = require('event');
|
||||
|
||||
event.on('humhub:modules:someModule:afterInit', function(evt, someModule) {
|
||||
|
||||
someModule.someExport = function() {
|
||||
// overwritten
|
||||
};
|
||||
|
||||
someModule.config['someConfigKey'] = 'overwritten';
|
||||
|
||||
});
|
||||
|
||||
```
|
||||
|
||||
@ -4,9 +4,172 @@ Change the behavior of core features
|
||||
This guide describes possible ways for modules to change the behavior of core features.
|
||||
|
||||
## Events
|
||||
|
||||
One commonly used way of intercepting core processes or adding new features within modules are `event handlers`.
|
||||
Please refer to the [Yii Events Guide](https://www.yiiframework.com/doc/guide/2.0/en/concept-events) for general information
|
||||
about the usage of events. And also check the [Module Events](modules.md#module-events) section.
|
||||
|
||||
The following list shows an overview of most of the events available in the HumHub core:
|
||||
|
||||
- Models:
|
||||
- `Model::EVENT_BEFORE_VALIDATE`
|
||||
- `Model::EVENT_AFTER_VALIDATE`
|
||||
- ActiveRecord:
|
||||
- `ActiveRecord::EVENT_INIT`
|
||||
- `ActiveRecord::EVENT_AFTER_FIND`
|
||||
- `ActiveRecord::EVENT_BEFORE_INSERT`
|
||||
- `ActiveRecord::EVENT_AFTER_INSERT`
|
||||
- `ActiveRecord::EVENT_BEFORE_UPDATE`
|
||||
- `ActiveRecord::EVENT_AFTER_UPDATE`
|
||||
- `ActiveRecord::EVENT_BEFORE_DELETE`
|
||||
- `ActiveRecord::EVENT_AFTER_DELETE`
|
||||
- `ActiveRecord::EVENT_AFTER_REFRESH`
|
||||
- Controller:
|
||||
- `Controller::EVENT_INIT`
|
||||
- `Controller::EVENT_BEFORE_ACTION`
|
||||
- `Controller::EVENT_AFTER_ACTION`
|
||||
- Application
|
||||
- `Application::EVENT_ON_INIT`
|
||||
- CronController:
|
||||
- `CronController::EVENT_ON_HOURLY_RUN`
|
||||
- `CronController::EVENT_ON_DALY_RUN`
|
||||
- Integrity:
|
||||
- `IntegrityController::EVENT_ON_RUN`
|
||||
- Response:
|
||||
- `Response::EVENT_BEFORE_SEND`
|
||||
- `Response::EVENT_AFTER_SEND`
|
||||
- `Response::EVENT_AFTER_PREPARE`
|
||||
- ModuleManager:
|
||||
- `ModuleManager::EVENT_BEFORE_MODULE_ENABLED`
|
||||
- `ModuleManager::EVENT_AFTER_MODULE_ENABLED`
|
||||
- `ModuleManager::EVENT_BEFORE_MODULE_DISABLED`
|
||||
- `ModuleManager::EVENT_AFTER_MODULE_DISABLED`
|
||||
- Widget:
|
||||
- `Widget::EVENT_CREATE`
|
||||
- `Widget::EVENT_INIT`
|
||||
- `Widget::EVENT_BEFORE_RUN`
|
||||
- `Widget::EVENT_AFTER_RUN`
|
||||
- AbstractRichText:
|
||||
- `AbstractRichText::EVENT_POST_PROCESS`
|
||||
- `AbstractRichText::EVENT_BEFORE_OUTPUT`
|
||||
- BaseStack:
|
||||
- `BaseStack::EVENT_INIT`
|
||||
- `BaseStack::EVENT_RUN`
|
||||
- BaseMenu:
|
||||
- `BaseMenu::EVENT_INIT`
|
||||
- `BaseMenu::EVENT_RUN`
|
||||
- User:
|
||||
- `User::EVENT_CHECK_VISIBILITY`
|
||||
- `User::EVENT_BEFORE_SOFT_DELETE`
|
||||
- Registration:
|
||||
- `Registration::EVENT_AFTER_REGISTRATION`
|
||||
- ActiveQueryUser:
|
||||
- `ActiveQueryUser::EVENT_CHECK_VISIBILITY`
|
||||
- `ActiveQueryUser::EVENT_CHECK_ACTIVE`
|
||||
- Follow:
|
||||
- `Follow::EVENT_FOLLOWING_CREATED`
|
||||
- `Follow::EVENT_FOLLOWING_REMOVED`
|
||||
- Friendship:
|
||||
- `Friendship::EVENT_FRIENDSHIP_CREATED`
|
||||
- `Friendship::EVENT_FRIENDSHIP_REMOVED`
|
||||
- Search:
|
||||
- `Search::EVENT_SEARCH_ATTRIBUTES`
|
||||
- `Search::EVENT_ON_REBUILD`
|
||||
- FileHandlerCollection:
|
||||
- `FileHandlerCollection::EVENT_INIT`
|
||||
- humhub\modules\installer\Module:
|
||||
-`humhub\modules\installer\Module::EVENT_INIT_CONFIG_STEPS`
|
||||
- humhub\modules\installer\controllers\ConfigController:
|
||||
- `humhub\modules\installer\controllers\ConfigController::EVENT_INSTALL_SAMPLE_DATA`
|
||||
- Search:
|
||||
- `Search::EVENT_SEARCH_ATTRIBUTES`
|
||||
- `Search::EVENT_ON_REBUILD`
|
||||
- Search:
|
||||
- `Search::EVENT_SEARCH_ATTRIBUTES`
|
||||
- `Search::EVENT_ON_REBUILD`
|
||||
- Searchable:
|
||||
- `Searchable::EVENT_SEARCH_ADD`
|
||||
- Membership:
|
||||
- `Membership::EVENT_MEMBER_REMOVED`
|
||||
- `Membership::EVENT_MEMBER_ADDED`
|
||||
- Stream:
|
||||
- `Stream::EVENT_BEFORE_RUN`
|
||||
- `Stream::EVENT_AFTER_RUN`
|
||||
- StreamFilter:
|
||||
- `StreamFilter::EVENT_BEFORE_FILTER`
|
||||
- BaseClient:
|
||||
- `BaseClient::EVENT_UPDATE_USER`
|
||||
- `BaseClient::EVENT_CREATE_USER`
|
||||
- humhub\modules\user\authclient\Collection
|
||||
- `Collection::EVENT_AFTER_CLIENTS_SET`
|
||||
|
||||
## Widgets
|
||||
## Views
|
||||
## Controller
|
||||
## ActiveRecord
|
||||
|
||||
Widget events are often used to extend view components as menus and forms. Here are some usecases for widget events:
|
||||
|
||||
### Extend menus
|
||||
|
||||
Widgets based on [[humhub\widgets\BaseMenu]] and [[humhub\widgets\BaseStack]] can be intercepted and extended by means of the [[humhub\widgets\BaseMenu|BaseMenu::EVENT_INIT]] event.
|
||||
Please see the [Sidebars and Snippets](snippet.md#event-handlers) section for useful examples of such event handlers.
|
||||
|
||||
### Overwrite widget classes
|
||||
|
||||
In order to completely replace a widget implementation you can use the [[humhub\components\Widget::EVENT_CREATE]] as follows:
|
||||
|
||||
**config.php:**
|
||||
|
||||
```php
|
||||
'events' => [
|
||||
['class' => SomeWidgetIWantToOverwrite::class, 'event' => Widget::EVENT_CREATE, 'callback' => [Events::class, 'onCreateSomeWidget']],
|
||||
]
|
||||
```
|
||||
|
||||
**Events.php:**
|
||||
|
||||
```php
|
||||
public static function onCreateSomeWidget($event)
|
||||
{
|
||||
// Switch to Enterprise Space Chooser
|
||||
$event->config['class'] = MyOverwriteWidget::class;
|
||||
}
|
||||
```
|
||||
|
||||
> Note: Your replacement widget have to support the same fields as the original widget.
|
||||
|
||||
### Append widget content
|
||||
|
||||
In some cases you may want to append or otherwise manipulate the output of a widget. For this use-case you can listen to the
|
||||
[[yii\base\Widget::EVENT_AFTER_RUN]] event. The following example appends the output of `MyWidgetToAppend` to the result of
|
||||
`SomeWidgetIWantToExtend`:
|
||||
|
||||
**config.php:**
|
||||
|
||||
```php
|
||||
'events' => [
|
||||
['class' => SomeWidgetIWantToExtend::class, 'event' => Widget::EVENT_AFTER_RUN, 'callback' => [Events::class, 'onSomeWidgetRun']],
|
||||
]
|
||||
```
|
||||
|
||||
**Events.php:**
|
||||
|
||||
```php
|
||||
public static function onCreateSomeWidget($event)
|
||||
{
|
||||
$event->result .= MyWidgetToAppend::widget();
|
||||
}
|
||||
```
|
||||
|
||||
## Module Interfaces
|
||||
|
||||
Some Modules as for example the [Calendar Module](https://github.com/humhub/humhub-modules-calendar/blob/master/docs/interface.md) provide interfaces in order to
|
||||
facilitate its features.
|
||||
|
||||
## Javascript
|
||||
## Configuration
|
||||
|
||||
See [Overwrite Module Behavior](javascript-index.md#overwrite-module-behaviour) in the javascript guide.
|
||||
|
||||
## Embeded Theme
|
||||
|
||||
Your custom module can be bundled with custom themes, please see the [Theme - Module Integration](../theme/module.md) section for more information.
|
||||
|
||||
|
||||
|
||||
@ -6,9 +6,9 @@ The modular nature of the HumHub platform allows you to add new features or chan
|
||||
custom modules.
|
||||
|
||||
Other languages used throughout the platform, besides PHP, are JavaScript, HTML, SQL and CSS/Less.
|
||||
HumHub is based on the Model-View-Controller (MVC) pattern and uses frontend technologies such as [jQuery](https://jquery.com/), [Bootstrap](http://getbootstrap.com/) and [Less](http://lesscss.org/).
|
||||
HumHub is based on the [Model-View-Controller (MVC)](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) pattern and uses frontend technologies such as [jQuery](https://jquery.com/), [Bootstrap](http://getbootstrap.com/) and [Less](http://lesscss.org/).
|
||||
|
||||
In this guide, you will find all the necessary information to customize your HumHub installation and implement your own modules.
|
||||
In this guide you will find all the necessary information to customize your HumHub installation and implement your own modules.
|
||||
|
||||
As HumHub is based on the [Yii 2.0 PHP Framework](http://www.yiiframework.com/) make sure you're also familiar with the basic concepts of this framework:
|
||||
|
||||
|
||||
@ -42,7 +42,7 @@ You can manually execute new migrations by the following commands:
|
||||
php yii migrate/up --inclueModuleMigrations=1
|
||||
```
|
||||
|
||||
or grunt
|
||||
or by grunt
|
||||
|
||||
```
|
||||
grunt migrate-up
|
||||
|
||||
@ -1,14 +1,12 @@
|
||||
Sidebars and Snippets
|
||||
======================
|
||||
|
||||
Snippets are self contained panels which can be added to the sidebar, for example the space, directory, or dashboard layout.
|
||||
Snippets are self contained panels which can be added to the sidebar, for example the _space_, _directory_, or _dashboard_ layout.
|
||||
|
||||
|
||||
## Adding content to the sidebar
|
||||
|
||||
You can use the [Yii2 View Blocks](https://www.yiiframework.com/doc/guide/2.0/en/structure-views#using-blocks) feature to move content from your view file into the sidebar.
|
||||
|
||||
Example:
|
||||
You can use the [Yii2 View Blocks](https://www.yiiframework.com/doc/guide/2.0/en/structure-views#using-blocks) feature to move content from your view file into the sidebar as follows:
|
||||
|
||||
```php
|
||||
<?php $this->beginBlock('sidebar'); ?>
|
||||
@ -21,56 +19,103 @@ See also: [[humhub\modules\ui\view\components\View|getSidebar]]
|
||||
|
||||
## Event Handlers
|
||||
|
||||
You can use the [[humhub\widgets\BaseMenu::EVENT_INIT]] event in order to append `snippets` to a sidebar.
|
||||
Your event handler will look something like this:
|
||||
|
||||
```php
|
||||
public static function onSpaceSidebarInit($event)
|
||||
{
|
||||
$space = $event->sender->space;
|
||||
$settings = SnippetModuleSettings::instantiate();
|
||||
|
||||
if ($space->isModuleEnabled('mymodule')) {
|
||||
if ($settings->showUpcomingEventsSnippet()) {
|
||||
$event->sender->addWidget(MySnippet::class, ['contentContainer' => $space], ['sortOrder' => $settings->upcomingEventsSnippetSortOrder]);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following snippet view rendered by your `MySnippet::class` appends an extra meu item to the `PanelMenu`.
|
||||
|
||||
```php
|
||||
<?php
|
||||
use humhub\widgets\PanelMenu;
|
||||
|
||||
$extraMenus = '<li><a href="'.$url.'"><i class="fa fa-arrow-circle-right"></i> '. Yii::t('MyModule.base', 'Some extra snippet men item') .'</a></li>';
|
||||
?>
|
||||
<div class="panel calendar-upcoming-snippet" id="my-module-snippet">
|
||||
|
||||
<div class="panel-bath">
|
||||
<i class="fa fa-home"></i> <?= Yii::t('MyModule.base', '<strong>My</strong> snippet'); ?>
|
||||
<?= PanelMenu::widget(['id' => 'my-module-snippet', 'extraMenus' => $extraMenus]); ?>
|
||||
</div>
|
||||
|
||||
<div class="panel-body" style="padding:0px;">
|
||||
<?php /* Put content */?>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
> Note: The snippet concept will be enhanced in a future version after HumHub 1.3 in order to provide a global and container settings view which can be used
|
||||
to configurate all available snippets.
|
||||
|
||||
The following sections describe how to register your event listener for the different sidebars available.
|
||||
|
||||
### Dashboard Layout
|
||||
|
||||
Adding the following in your module's `config.php` file will enable the view of your snippet on your dashboard.
|
||||
|
||||
```php
|
||||
namespace humhub\modules\yourmodule;
|
||||
|
||||
use humhub\widgets\BaseMenu;
|
||||
use humhub\modules\dashboard\widgets\Sidebar;
|
||||
|
||||
return [
|
||||
'id' => 'yourmodule',
|
||||
'class' => 'humhub\modules\yourmodule\Module',
|
||||
'namespace' => 'humhub\modules\yourmodule',
|
||||
'events' => [
|
||||
['class' => humhub\modules\dashboard\widgets\Sidebar::className(), 'event' => BaseMenu::EVENT_INIT, 'callback' => ['humhub\modules\yourmodule\Module', 'onDashboardSidebarInit']],
|
||||
['class' => Sidebar::class, 'event' => Sidebar::EVENT_INIT, 'callback' => ['humhub\modules\yourmodule\Module', 'onDashboardSidebarInit']],
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
### Space Layout
|
||||
|
||||
Adding the following in your module's `config.php` file will enable the view of your snippet in your Spaces.
|
||||
|
||||
```php
|
||||
namespace humhub\modules\yourmodule;
|
||||
|
||||
use humhub\widgets\BaseMenu;
|
||||
use humhub\modules\space\widgets\Sidebar;
|
||||
|
||||
return [
|
||||
'id' => 'yourmodule',
|
||||
'class' => 'humhub\modules\yourmodule\Module',
|
||||
'namespace' => 'humhub\modules\yourmodule',
|
||||
'events' => [
|
||||
['class' => humhub\modules\space\widgets\Sidebar::className(), 'event' => BaseMenu::EVENT_INIT, 'callback' => ['humhub\modules\yourmodule\Events', 'onSpaceSidebarInit']],
|
||||
['class' => Sidebar::class, 'event' => Sidebar::EVENT_INIT, 'callback' => ['humhub\modules\yourmodule\Events', 'onSpaceSidebarInit']],
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
### Directory Layout
|
||||
|
||||
Adding the following in your module's `config.php` file will enable the view of your snippet in your Directory.
|
||||
|
||||
```php
|
||||
namespace humhub\modules\yourmodule;
|
||||
|
||||
use humhub\widgets\BaseMenu;
|
||||
use humhub\modules\directory\widgets\Sidebar;
|
||||
|
||||
return [
|
||||
'id' => 'yourmodule',
|
||||
'class' => 'humhub\modules\yourmodule\Module',
|
||||
'namespace' => 'humhub\modules\yourmodule',
|
||||
'events' => [
|
||||
['class' => humhub\modules\directory\widgets\Sidebar::className(), 'event' => BaseMenu::EVENT_INIT, 'callback' => ['humhub\modules\yourmodule\Events', 'onDirectorySidebarInit']],
|
||||
['class' => Sidebar::class, 'event' => Sidebar::EVENT_INIT, 'callback' => ['humhub\modules\yourmodule\Events', 'onDirectorySidebarInit']],
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
@ -4,33 +4,33 @@ Streams are used to asynchronously load batches of content entries which can be
|
||||
The stream concept is used for example in _space and profile walls_, the _dashboard_ and
|
||||
_activity stream_.
|
||||
|
||||
Custom modules can use own streams for example to filter content by a specific type, or other custom
|
||||
filters.
|
||||
|
||||
### Stream Channel
|
||||
## Stream Channel
|
||||
|
||||
The `stream_channel` attribute of a [[humhub\modules\content\models\Content]] entry defines the relation of this content to
|
||||
a specific type of stream. The `default` stream channel for example is used by _space/profile_ and _dashboard_
|
||||
a specific type of stream. The `default` stream channel for example is used by _space_, _user_ and _dashboard_
|
||||
streams whereas the `activity` stream-channel is exclusively used in activity streams.
|
||||
|
||||
The stream channel of your content type can be overwritten by setting the [[humhub\modules\content\components\ContentActiveRecord::streamChannel|ContentActiveRecord::streamChannel]] attribute.
|
||||
The `stream_channel` of your content type can be overwritten by setting the [[humhub\modules\content\components\ContentActiveRecord::streamChannel|ContentActiveRecord::streamChannel]] attribute.
|
||||
|
||||
You can consider the following stream channel options for your own [[humhub\modules\content\components\ContentActiveRecord|ContentActiveRecord]]:
|
||||
For own `ContentActiveRecord` you can consider the following `stream_channel` options:
|
||||
|
||||
- `default` stream channel will include your content to default _space/profile walls_ and the _dashboard_. You are still able to create a custom stream view which filters content by type.
|
||||
- `default` this stream_channel will include your content to default _space/profile walls_ and the _dashboard_. You are still able to create a custom stream view which filters content by type.
|
||||
- `null` will exclude the content from the default streams
|
||||
- Use a custom stream channel if you exclusively want your content to be included in your own custom stream (similar to activity concept).
|
||||
- Use a custom stream channel if you exclusively want your content to be included in your own custom stream (similar to the activity concept).
|
||||
|
||||
> Note: A custom stream channel should be unique, so choose a meaningful name preferably with module prefix.
|
||||
|
||||
### WallEntry Widget
|
||||
## WallEntry Widget
|
||||
|
||||
A [[humhub\modules\content\widgets\WallEntry|WallEntry widget]] is responsible for rendering the individual stream entries
|
||||
of a stream and is defined by [[humhub\modules\content\components\ContentActiveRecord::wallEntryClass|ContentActiveRecord::wallEntryClass]].
|
||||
A [[humhub\modules\content\widgets\WallEntry|WallEntry widget]] is responsible for rendering the individual `stream entries`
|
||||
of a `stream` and is defined by [[humhub\modules\content\components\ContentActiveRecord::wallEntryClass|ContentActiveRecord::wallEntryClass]].
|
||||
|
||||
The following example shows a very basic WallEntry widget implementation.
|
||||
|
||||
> Note: By default your WallEntry view only have to render the actual content, the default WallEntry layout is available in `@humhub/modules/content/widgets/views/wallEntry.php`
|
||||
|
||||
**mymodule\widgets\WallEntry.php**:
|
||||
|
||||
```php
|
||||
class WallEntry extends \humhub\modules\content\widgets\WallEntry
|
||||
{
|
||||
@ -43,7 +43,7 @@ class WallEntry extends \humhub\modules\content\widgets\WallEntry
|
||||
}
|
||||
```
|
||||
|
||||
wallEntry.php:
|
||||
**mymodule\widgets\views\wallEntry.php**:
|
||||
|
||||
```php
|
||||
<div>
|
||||
@ -53,17 +53,17 @@ wallEntry.php:
|
||||
</div>
|
||||
```
|
||||
|
||||
The WallEntry widget will be provided with a [[humhub\modules\content\widgets\WallEntry::contentObject|contentObject]] which holds the
|
||||
[[humhub\modules\content\components\ContentActiveRecord|ContentActiveRecord]] model to be rendered.
|
||||
The `WallEntry` widget will be provided with a [[humhub\modules\content\widgets\WallEntry::contentObject|contentObject]] which holds the
|
||||
`ContentActiveRecord` model to be rendered.
|
||||
|
||||
Your [[humhub\modules\content\widgets\WallEntry|WallEntry]] class can also set the following attributes:
|
||||
Your `WallEntry` widget class can also set the following attributes:
|
||||
|
||||
- [[humhub\modules\content\widgets\WallEntry::editRoute|editRoute]] defines an edit route to your edit action which will be used to render an edit link (see WallEntryControls section)
|
||||
- [[humhub\modules\content\widgets\WallEntry::editMode|editMode]] defines the way the edit action is triggered (see WallEntryControls section)
|
||||
- [[humhub\modules\content\widgets\WallEntry::wallEntryLayout|wallEntryLayout]] defines the layout used to embed the result of `render()`, by default you only have to care about rendering the content section of your WallEntry
|
||||
|
||||
|
||||
#### WallEntryControls
|
||||
### WallEntryControls
|
||||
|
||||
The default WallEntry layout contains a context menu with content actions like `edit`, `delete`, `archive` etc.
|
||||
This menu can be manipulated by overwriting the [[humhub\modules\content\widgets\WallEntry::getContextMenu()|getContextMenu()]] function and
|
||||
@ -107,7 +107,7 @@ class WallEntry extends \humhub\modules\content\widgets\WallEntry
|
||||
}
|
||||
```
|
||||
|
||||
CloseLink example:
|
||||
**CloseLink example**:
|
||||
|
||||
```php
|
||||
class CloseLink extends humhub\modules\content\widgets\WallEntryControlLink
|
||||
@ -133,102 +133,107 @@ class CloseLink extends humhub\modules\content\widgets\WallEntryControlLink
|
||||
}
|
||||
```
|
||||
|
||||
## Create own Module Content Stream
|
||||
## Create Module Content Streams
|
||||
|
||||
### Implement StreamAction
|
||||
|
||||
Derived from [[humhub\modules\content\components\actions\ContentContainerStream]]
|
||||
|
||||
Example:
|
||||
A `StreamAction` is responsible for handling a stream request and filtering stream entries.
|
||||
The following example extends the default [[humhub\modules\content\components\actions\ContentContainerStream|ContentContainerStream]] and
|
||||
adds an content-type filter:
|
||||
|
||||
```php
|
||||
class StreamAction extends humhub\modules\content\components\actions\ContentContainerStream
|
||||
namespace mymodule\actions;
|
||||
|
||||
use humhub\modules\content\components\actions\ContentContainerStream;
|
||||
|
||||
class StreamAction extends ContentContainerStream
|
||||
{
|
||||
public function setupFilters()
|
||||
{
|
||||
// Limit output to specific content type
|
||||
$this->activeQuery->andWhere(['content.object_model' => Poll::className()]);
|
||||
$this->activeQuery->andWhere(['content.object_model' => MyModel::class]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Specify Action in Controller
|
||||
|
||||
Example:
|
||||
Add the `StreamAction` to your Controller:
|
||||
|
||||
```php
|
||||
class PollController extends ContentContainerController
|
||||
class StreamController extends ContentContainerController
|
||||
{
|
||||
|
||||
public function actions()
|
||||
{
|
||||
return array(
|
||||
'stream' => array(
|
||||
'class' => \humhub\modules\polls\components\StreamAction::className(),
|
||||
'mode' => \humhub\modules\polls\components\StreamAction::MODE_NORMAL,
|
||||
return [
|
||||
'stream' => [
|
||||
'class' => StreamAction::class,
|
||||
'contentContainer' => $this->contentContainer
|
||||
),
|
||||
);
|
||||
],
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### Display Stream
|
||||
|
||||
You can use the Stream Widget to display the Stream in your View.
|
||||
You can use the [[humhub\modules\stream\widgets\StreamViewer|StreamViewer]] widget to display your stream within your view as follows:
|
||||
|
||||
```php
|
||||
|
||||
echo \humhub\modules\content\widgets\Stream::widget(array(
|
||||
<?= \humhub\modules\stream\widgets\StreamViewer::widget([
|
||||
'contentContainer' => $contentContainer,
|
||||
'streamAction' => '//polls/poll/stream',
|
||||
'streamAction' => '/mymodule/stream/stream',
|
||||
'messageStreamEmpty' => ($contentContainer->canWrite()) ?
|
||||
Yii::t('PollsModule.widgets_views_stream', '<b>There are no polls yet!</b><br>Be the first and create one...') :
|
||||
Yii::t('PollsModule.widgets_views_stream', '<b>There are no polls yet!</b>'),
|
||||
'messageStreamEmptyCss' => ($contentContainer->canWrite()) ?
|
||||
'placeholder-empty-stream' :
|
||||
'',
|
||||
));
|
||||
'messageStreamEmptyCss' => ($contentContainer->canWrite()) ? 'placeholder-empty-stream' : '',
|
||||
]); ?>
|
||||
|
||||
```
|
||||
|
||||
## Create Content Form
|
||||
|
||||
You can add a [[humhub\modules\content\widgets\WallCreateContentForm|WallCreateContentForm]] on top of your custom `stream` in
|
||||
order to create new stream-entries within your stream view.
|
||||
|
||||
### Create Form Widget
|
||||
|
||||
Create a Form Widget derived from [[humhub\modules\content\widgets\WallCreateContentForm]]
|
||||
|
||||
```php
|
||||
|
||||
namespace humhub\modules\polls\widgets;
|
||||
namespace mymodule\widgets;
|
||||
|
||||
class WallCreateForm extends \humhub\modules\content\widgets\WallCreateContentForm
|
||||
use humhub\modules\content\widgets\WallCreateContentForm;
|
||||
|
||||
class WallCreateForm extends WallCreateContentForm
|
||||
{
|
||||
|
||||
public $submitUrl = '/polls/poll/create';
|
||||
public $submitUrl = '/mymodule/mymodel/create';
|
||||
|
||||
public function renderForm()
|
||||
{
|
||||
// Render your custom form here
|
||||
return $this->render('form', array());
|
||||
return $this->render('form', []);
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Create a view file for widget which contains module specific fields. All standard fields (e.g. visibility) are added automatically.
|
||||
Create a widget `view` which contains module specific fields. All standard fields (e.g. visibility) are added automatically.
|
||||
|
||||
```php
|
||||
<?= Html::textArea("question", "", array('id' => 'contentForm_question', 'class' => 'form-control autosize contentForm', 'rows' => '1', "tabindex" => "1", "placeholder" => Yii::t('PollsModule.widgets_views_pollForm', "Ask something..."))); ?>
|
||||
<?= Html::textArea("question", "", ['id' => 'contentForm_question', 'class' => 'form-control autosize contentForm', 'rows' => '1', "tabindex" => "1", "placeholder" => Yii::t('PollsModule.widgets_views_pollForm', "Ask something..."])); ?>
|
||||
|
||||
<div class="contentForm_options">
|
||||
<?= Html::textArea("answersText", "", array('id' => "contentForm_answersText", 'rows' => '5', 'style' => 'height: auto !important;', "class" => "form-control contentForm", "tabindex" => "2", "placeholder" => Yii::t('PollsModule.widgets_views_pollForm', "Possible answers (one per line)"))); ?>
|
||||
<?= Html::textArea("answersText", "", ['id' => "contentForm_answersText", 'rows' => '5', 'style' => 'height: auto !important;', "class" => "form-control contentForm", "tabindex" => "2", "placeholder" => Yii::t('PollsModule.widgets_views_pollForm', "Possible answers (one per line)")]); ?>
|
||||
<div class="checkbox">
|
||||
<label>
|
||||
<?= Html::checkbox("allowMultiple", "", array('id' => "contentForm_allowMultiple", 'class' => 'checkbox contentForm', "tabindex" => "4")); ?> <?php echo Yii::t('PollsModule.widgets_views_pollForm', 'Allow multiple answers per user?'); ?>
|
||||
<?= Html::checkbox("allowMultiple", "", ['id' => "contentForm_allowMultiple", 'class' => 'checkbox contentForm', "tabindex" => "4"]); ?> <?= Yii::t('PollsModule.widgets_views_pollForm', 'Allow multiple answers per user?'); ?>
|
||||
</label>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
@ -245,15 +250,14 @@ Example:
|
||||
|
||||
public function actionCreate()
|
||||
{
|
||||
$poll = new Poll();
|
||||
$poll->question = Yii::$app->request->post('question');
|
||||
$poll->answersText = Yii::$app->request->post('answersText');
|
||||
$poll->allow_multiple = Yii::$app->request->post('allowMultiple', 0);
|
||||
$model = new MyModel();
|
||||
$model->question = Yii::$app->request->post('question');
|
||||
$model->answersText = Yii::$app->request->post('answersText');
|
||||
$model->allow_multiple = Yii::$app->request->post('allowMultiple', 0);
|
||||
|
||||
return \humhub\modules\polls\widgets\WallCreateForm::create($poll);
|
||||
return \mymodule\widgets\WallCreateForm::create($model);
|
||||
}
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Display Form
|
||||
@ -264,7 +268,7 @@ e.g.
|
||||
|
||||
```php
|
||||
|
||||
<?php echo \humhub\modules\polls\widgets\WallCreateForm::widget(array('contentContainer' => $contentContainer)); ?>
|
||||
<?= \humhub\modules\polls\widgets\WallCreateForm::widget(array('contentContainer' => $contentContainer)); ?>
|
||||
|
||||
```
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user