Documentation fixes and additions

This commit is contained in:
buddh4 2018-07-24 17:17:56 +02:00
parent e79f09eaba
commit 2c32e33e2f
7 changed files with 127 additions and 72 deletions

View File

@ -1,16 +1,15 @@
Content
=======
Content record classes as for example `Post`, `Poll` and `Wiki` are subclasses of
[[\humhub\modules\content\components\ContentContainerActiveRecord]].
Instances ofand are related to a
[[humhub\modules\content\models\Content]] record.
A ContentContainerActiveRecord subclass provides all features of a basic
Yii [ActiveRecords](http://www.yiiframework.com/doc-2.0/yii-db-activerecord.html) as validation and data access methods,
please refer to the [Yii Guide](http://www.yiiframework.com/doc-2.0/guide-db-active-record.html) for more information
about [ActiveRecords](http://www.yiiframework.com/doc-2.0/yii-db-activerecord.html).
[[humhub\modules\content\models\Content|Content]] entries are the base of HumHub content-types as Posts, Polls and Wiki Pages. Content entries reside in the
`content` table and are related to a specific [[\humhub\modules\content\components\ContentContainerActiveRecord|ContentActiveRecord]] instance by a polymorphic relation defined by the `object_model`
and `object_class` columns.
While the ContentContainerActiveRecord class contains the actual content data as texts and content settings, the related Content instance is beside others used to check **Permissions**, the **ContentContainer** relation, content **visibility** and is furthermore connected to ContentAddons as Like and Comments.
You can implement your own [[\humhub\modules\content\components\ContentContainerActiveRecord|ContentActiveRecord]] classes in order to embed your content to [Streams](stream.md)
and make it enable comments and likes.
While the [[\humhub\modules\content\components\ContentContainerActiveRecord|ContentActiveRecord] class contains the actual content data as texts and content-type related settings, the underlying Content instance can be used to
check and define **Permissions**, access the related **ContentContainer**, define the content **visibility** and is furthermore connected to ContentAddons as Likes and Comments.
Beside the basic ActiveRecord methods your ContentContainerActiveRecord class should at least implement the following functions
@ -18,8 +17,14 @@ Beside the basic ActiveRecord methods your ContentContainerActiveRecord class sh
- `getContentDescription()` - returns a short description of the content instance used to preview the content for example in activities etc.
```php
class Example extends \humhub\modules\content\components\ContentContainerActiveRecord
namespace mymodule\models;
class MyModel extends \humhub\modules\content\components\ContentContainerActiveRecord
{
protected $moduleId = 'mymodule';
protected $canMove = true;
public static function tableName()
{
return 'example_content';
@ -40,29 +45,50 @@ class Example extends \humhub\modules\content\components\ContentContainerActiveR
//return validation rules
}
.....
}
```
Your content model should be **instantiated** as follows:
### Instantiating a ContentContainerActiveRecord:
```php
// Instantiate my model assign a content container and visibility.
// Only provide an array of attributes
$model = new MyModel(['some_field' => $field]);
// Instantiate my model by providing only content-container, the default visibility of the space will be used
$model = new MyModel($someSpace);
// Provide content-container and attribute options
$model = new MyModel($someSpace, ['some_field' => $field]);
// Instantiate my model by providing content-container and visibility
$model = new MyModel($someSpace, Content::VISIBILITY_PRIVATE);
// Provide content-container, visibility and options array
$model = new MyModel($someSpace, Content::VISIBILITY_PRIVATE, ['some_field' => $field]);
// Setting of container and visibility and fields manually
$model = new MyModel();
$model->content->container = $someSpace;
$model->content->container = Content::VISIBILITY_PRIVATE;
...
$model->content->visibility = Content::VISIBILITY_PRIVATE;
$model->some_field = $field;
// Save model and content
$model->save();
```
Get the model instance from a given content instance:
> Note: You won't have to worry about instantiating or saving the underlying content record, since this is handled within
the ContentContainerActiveRecord automatically.
When given a Content instance, you can load the related model as follow:
```php
$model = $content->getPolymorphicRelation();
$model = $content->getModel();
```
### Use of ActiveQueryContent:
Calling [[\humhub\modules\content\components\ContentActiveRecord::find()]] will return a [[\humhub\modules\content\components\ActiveQueryContent]] with additional methods to select specific content:
```php
@ -90,7 +116,34 @@ 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
### Content features
> Note: A ContentContainerActiveRecord subclass provides all features of a basic Yii [ActiveRecords](http://www.yiiframework.com/doc-2.0/yii-db-activerecord.html)
as validation and data access methods, please refer to the [Yii Guide](http://www.yiiframework.com/doc-2.0/guide-db-active-record.html) for more information
about [ActiveRecords](http://www.yiiframework.com/doc-2.0/yii-db-activerecord.html).
### 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.
This is required for example when your content is related to any sub content or other content-container related settings.
```php
public function afterMove($container = null)
{
foreach($this->subcontent as $subcontent)
{
$subcontent->move($container);
}
}
```
### Silent Content Creation
By default, the creation of a content triggers the an activity and notifications for content-container 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 interest.
### Other Content Features
**Content visibility**
@ -138,13 +191,13 @@ $model->content->canArchive();
**Content Url**
By default the `Content::getUrl()` returns the permalink of the wallentry. In case the content is used outside of the default stream, this behaviour can be changed by implementing a `getUrl()` method in your ContentActiveRecord class.
By default the `Content::getUrl()` returns the permalink of the stream-entry. In case the content is used outside of the default stream, this behaviour can be changed by implementing a `getUrl()` method in your ContentActiveRecord class.
```php
$permaLink = $model->content->getUrl();
```
### Check content permissions
### Content permissions
By default a user can edit a content if one of the following conditions defined in `Content::canEdit()` are met:
@ -172,7 +225,8 @@ Since HumHub v1.2.1 you can overwrite the default ManageContent permission as fo
class Example extends ContentContainerActiveRecord
{
$managePermission = MyCustomManagePermission::class;
.....
// ...
}
```
@ -248,7 +302,6 @@ Beside others, this abstract class provides the following functionality:
- [Permission Management](dev-permissions.md) `getPermissionManager()`
- Profile-/Banner-image access `getProfileImage()`, `getProfileBannerImage()`
- Rendering the container stream `getWallOut()` (see [Permission Management](dev-stream.md))
Profile image example:
@ -268,9 +321,6 @@ See the [Getting Started](modules-index.md) section
See the [Stream](stream.md) section
## Global content
(TBD)
## Content addons
TBD

View File

@ -1,34 +1,35 @@
Development Environment
=======================
This guide shows some recommended settings of your development environment.
Quick Notes
-----------
- Make sure you are using a [Git/Composer HumHub installation](git-installation.md)
- Enable the debug mode, see [Disable Errors Section](../admin/security.md#disable-errors-debugging)
- Disable caching under `Administration -> Settings -> Advanced -> Caching -> None`
- Use file based mailing `Administration -> Settings -> Advanced -> E-Mail`
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 seperation can
setting the `moduleAutoloadPaths` parameter in your `/protected/config/common.php` configuration. This separation can
be useful while working with custom modules.
```php
return [
//...
'params' => [
'moduleAutoloadPaths' => ['/some/folder/modules'],
],
//...
]
```
Yii Debug Module
----------------
Add following block to your local web configuration `/protected/config/web.php` in order
Add the following block to your local web configuration `/protected/config/web.php` in order
to allow [Yii's debug Module](http://www.yiiframework.com/doc-2.0/ext-debug-index.html).
```php

View File

@ -1,35 +1,31 @@
Installation (Developers)
=========================
> Warning: This installation method allows you to fetch the latest branch from the repository which may not stable enough for production use.
Preparation
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).
Database Setup
-----------
Create a MySQL Database, e.g.:
```sql
CREATE DATABASE `humhub` CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL ON `humhub`.* TO `humhub_dbuser`@localhost IDENTIFIED BY 'password_changeme';
FLUSH PRIVILEGES;
```
> Note: Do not forget to change the `humhub_dbuser` and `password_changeme` placeholders!
Please follow the [Database Setup Section](../admin/installation.md#database-setup) of the administration installation guide.
Get HumHub
----------
- Install [git](https://git-scm.com/)
- Clone git Repository:
- Clone the git Repository:
```
git clone https://github.com/humhub/humhub.git
```
- Install composer ([https://getcomposer.org/doc/00-intro.md](https://getcomposer.org/doc/00-intro.md))
- Navigate to your HumHub webroot and fetch dependencies:
```
php composer.phar global require "fxp/composer-asset-plugin:~1.3"
php composer.phar update
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)

View File

@ -38,8 +38,8 @@ There is a compatibility layer for the 1.3 release.
- `humhub\components\Theme.php` -> `humhub\modules\ui\view\components\Theme`
- `humhub\components\View` -> `humhub\modules\ui\view\components\View`
- `humhub\libs\ThemeHelper` -> `humhub\modules\ui\view\components\ThemeHelper`
- `humhub\modules\content\widgets\richtext\HumHubRichText` -> Compatibility class for legacy richtext was replaced with prosemirror richtext.
- `humhub\modules\content\widgets\richtext\HumHubRichTextEditor` -> Compatibility class for legacy richtext was replaced with prosemirror richtext editor.
- `humhub\modules\content\widgets\richtext\HumHubRichText` -> Compatibility class for the legacy rich-text, which was replaced with prosemirror richtext.
- `humhub\modules\content\widgets\richtext\HumHubRichTextEditor` -> Compatibility class for the legacy rich-text, which was replaced with prosemirror richtext editor.
- `humhub\widgets\RichText` -> `humhub\modules\content\widgets\richtext\RichText`
- `humhub\widgets\RichTextField` -> `humhub\modules\content\widgets\richtext\RichTextField`
- `humhub\modules\user\models\Mentioning::parse()` -> `humhub\modules\content\widgets\richtext\RichText::processText()`

View File

@ -75,7 +75,7 @@ return [
'class' => 'johndoe\example\Module',
'namespace' => 'johndoe\example',
'events' => [
['class' => TopMenu::className(), 'event' => TopMenu::EVENT_INIT, 'callback' => ['johndoe\example\Module', 'onTopMenuInit']],
['class' => TopMenu::class, 'event' => TopMenu::EVENT_INIT, 'callback' => ['johndoe\example\Module', 'onTopMenuInit']],
]
];
?>
@ -112,19 +112,23 @@ class Module extends \humhub\components\Module
}
}
```
>Note: The default implementation of `disable()` will clear some module data automatically as the module global and ContentContainer settings, profile/space module relations.
> Note: The default implementation of `disable()` will clear some module data automatically as the modules global and ContentContainer settings, profile/space module relations.
#### Handling the enabling and disabling of this module for a given space or profile
See the [Container Module]() section for more information.
- Handling the enabling and disabling of this module for a given space or profile
#### Export Module Permissions
Module specific permissions are exported by means of the [[humhub\components\Module::getPermissions()]] function. See the [Permissions]() section for more information.
See the [Container Module](#container-module) section for more information.
- Export Module Permissions
Module specific permissions are exported by means of the [[humhub\components\Module::getPermissions()]] function. See the [Permissions](permissions.md) section for more information.
- Export Module Notification
#### Export Module Notification
Modules can export Notificaions in order to make them configurable in the notificaiton settings.
See the [Notifications]() section for more information.
See the [Notifications](notifications.md) section for more information.
- Module Assets and `$resourcesPath`
#### Module Assets and `$resourcesPath`
The [[humhub\components\Module::resourcesPath]] defines the modules resource directory, containing images, javascript files or other assets.
See the [Module Assets]() section for more information.
@ -159,7 +163,7 @@ Example `module.php` file:
## Extended Module Structure
The following structure contains some additional directories and files, which should be added for specific usecases or features.
The following structure contains some additional directories and files, which should be added for specific use-cases or features.
```
@ -185,7 +189,7 @@ The following structure contains some additional directories and files, which sh
module.json - see above
```
>Note: the extended module structure and it's directory names is just a recommendation.
> Note: the extended module structure and it's directory names is just a recommendation.
## Container Module
@ -198,6 +202,7 @@ In case your module can be enabled on space or profile level your `Module` class
- The `getContentContentContainerDescription()` method provides a general description of this module for the given ContentContainer.
The following example module can be enabled on space and profile level:
```php
class Module extends \humhub\modules\content\components\ContentContainerModule
{
@ -215,8 +220,7 @@ class Module extends \humhub\modules\content\components\ContentContainerModule
// Is called when the whole module is disabled
public function disable()
{
// Clear all Module data and call parent disable
[...]
// Clear all Module data and call parent disable!
parent::disable();
}
@ -239,8 +243,8 @@ class Module extends \humhub\modules\content\components\ContentContainerModule
}
```
> Note: If you're working with content or other persistent data, make sure to delete container related data when the module is disabled on a contentcontainer. This can be archieved by overwriting the [[humhub\modules\content\components\ContentContainerModule::disableContentContainer]] function.
> Note: If you're working with content or other persistent data, make sure to delete container related data when the module is disabled on a contentcontainer. This can be archieved by overwriting the [[humhub\modules\content\components\ContentContainerModule::disableContentContainer()]] function.
## Creating a Module Template with Gii
## Devtools Module
(TBD)
You may want to use the [devtools Module](https://github.com/humhub/humhub-modules-devtools) to create a module skeleton.

View File

@ -10,7 +10,7 @@ HumHub is based on the Model-View-Controller (MVC) pattern and uses frontend tec
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 this framework:
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:
- [The Definitive Guide to Yii 2.0](http://www.yiiframework.com/doc-2.0/guide-index.html)
@ -49,15 +49,18 @@ and consists of the following core modules:
- **live:** Used for frontend live updates
- **notification:** User Notifications
- **post:** Simple user-post related functionality
- **queue:** Queue drivers and interfaces
- **search:** Luceene Search Module
- **space:** Space related functionality
- **stream:** Content streams and walls
- **topic:** Topics are used to categorize and filter content
- **tour:** HumHub user-guide
- **ui:** Base ui components as widgets and theme logic
- **user:** Basic user module
### Application structure
### Application structure
```
```
assets/ - contains published asset files
protected/ - protected files as sources, modules, configuration etc.
protected/config - dynamic and user configuration
@ -68,4 +71,4 @@ and consists of the following core modules:
static/ - static asset files as production assets core javascript/less files etc.
themes/ - contains standalone themes (not bundled within a module)
uploads/ - uploaded files profile images etc.
```
```

View File

@ -11,7 +11,7 @@ filters.
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_
streams and the `activity` stream channel is exclusively used in activity streams.
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.
@ -44,6 +44,7 @@ class WallEntry extends \humhub\modules\content\widgets\WallEntry
```
wallEntry.php:
```php
<div>
<?= $model->title ?>
@ -53,7 +54,7 @@ wallEntry.php:
```
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.
[[humhub\modules\content\components\ContentActiveRecord|ContentActiveRecord]] model to be rendered.
Your [[humhub\modules\content\widgets\WallEntry|WallEntry]] class can also set the following attributes:
@ -218,13 +219,13 @@ class WallCreateForm extends \humhub\modules\content\widgets\WallCreateContentFo
Create a view file for widget which contains module specific fields. All standard fields (e.g. visibility) are added automatically.
```php
<?php echo 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", "", array('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">
<?php echo 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", "", 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)"))); ?>
<div class="checkbox">
<label>
<?php echo 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", "", array('id' => "contentForm_allowMultiple", 'class' => 'checkbox contentForm', "tabindex" => "4")); ?> <?php echo Yii::t('PollsModule.widgets_views_pollForm', 'Allow multiple answers per user?'); ?>
</label>
</div>
@ -235,7 +236,7 @@ Create a view file for widget which contains module specific fields. All standar
Create an action in your modules controller to receive form inputs.
All default tasks (e.g. access validation, ContentContainer assignment) are handled by [[humhub\modules\content\widgets\WallCreateContentForm::create]]
All default tasks (e.g. access validation, ContentContainer assignment) are handled by [[humhub\modules\content\widgets\WallCreateContentForm::create()]]
Example: