Mibew/docs.mibew.org
1
0
Fork 0
mirror of https://github.com/Mibew/docs.mibew.org.git synced 2025-05-01 22:56:41 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Refactor the docs

Browse Source
This commit is contained in:
Fedor A. Fetisov 2017-11-01 04:08:13 +03:00
parent 64cf06d1fe
commit 363c6009f5
10 changed files with 655 additions and 569 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
src/development.md
View File

@ -6,10 +6,14 @@ nav_sort: 20
# Development overview # Development overview
Mibew is a web application which uses Apache, PHP, MySQL and JavaScript. If you **Mibew Messenger** is a web application which uses PHP, MySQL, and JavaScript.
want to patch the Core you also needs node.js and npm to build the sources. If you want to patch the **Core** of **Mibew Messenger** and/or change the
appearance by creating your custom theme you will also need node.js and npm to
build the sources.
All mibew sources are placed on GitHub: https://github.com/Mibew/mibew. All All source code of **Mibew Messenger** is available on GitHub:
official plugins are stored on GitHub too. Take a look at https://github.com/Mibew/mibew. All official plugins, themes, and translations
[Mibew organization](https://github.com/Mibew) on GitHub to get a list of all for **Mibew Messenger** are available on GitHub too.
official repositories.
Take a look at [Mibew organization](https://github.com/Mibew) on GitHub to get
the list of all official repositories.

54
src/development/build-system.md
View File

@ -6,35 +6,43 @@ nav_sort: 40
# Build System # Build System
The build process is needed to download third-party libraries, compile The build process is needed to download third party libraries, compile
templates, minify and concatenate JavaScript files, etc. It means that you have templates, minify and concatenate JavaScript files, etc. It means that you have
to use build system if you want to modify Mibew's Core or use the latest to use build system whenever you want to modify the **Core** of
unreleased version from the respository. **Mibew Messenger** and/or use the development version of **Mibew Messenger**
from the repository.
Mibew uses [Gulp.js](http://gulpjs.com/) as a build system. You also needs **Mibew Messenger** utilizes [Gulp.js](http://gulpjs.com/) as a build system.
[node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) to make Gulp To make Gulp run [node.js](https://nodejs.org/) and
works. For the most common tasks [PHP](http://php.net/) is also needed. [npm](https://www.npmjs.com/) are required. For most common build tasks
[PHP](http://php.net/) is required too.
There are several actions one should do before use the version from the repository: There are several steps one should take before using the development version
of **Mibew Messenger** from the repository:
1. Obtain a copy of the repository using `git clone`, download button, or another way. 1. Obtain a local copy of the repository using `git clone`, download button,
or in another way.
2. Make sure that [PHP](http://php.net/) is installed and can be used in CLI
mode.
2. Install [node.js](http://nodejs.org/) and [npm](https://www.npmjs.org/). 2. Install [node.js](http://nodejs.org/) and [npm](https://www.npmjs.org/).
3. Install [Gulp](http://gulpjs.com/). 3. Install [Gulp](http://gulpjs.com/).
4. Navigate to `src/` directory of the local copy of the repository. 5. Navigate to `src/` directory of the local copy of the repository.
5. Install npm dependencies using `npm install`. 6. Install npm dependencies using `npm install`.
6. Run Gulp to build Mibew using `gulp default`. 7. Run Gulp to build **Mibew Messenger** using `gulp default`.
Finally `.tar.gz` and `.zip` archives of the ready-to-use Mibew will be Finally, `.tar.gz` and `.zip` archives of the ready-to-use development version
available in `src/release/` directory. of **Mibew Messenger** will be available in `src/release` directory.
The `default` task that was used above is just one of many available build The `default` task that was given above is just one of many available build
tasks. The full list can be got by running `gulp -T` in `src/` directory of tasks. The full list of build tasks can be obtained by running `gulp -T` in
Mibew repository. Here is descripion of the most frequently used tasks: `src/` directory of the repository. Here are descriptions of several most
frequently used tasks:
* `gulp rebuild`: installs all necessary dependencies and compile (minifies, concats, * `gulp rebuild`: installs all necessary dependencies and compile (minifies,
...) all files that should be compiled. The result of the task is a concats, ...) all files that should be compiled. The result of the task is a
redy-to-use development version of Mibew. redy-to-use development version of **Mibew Messenger**.
* `gulp default`: the same as `gulp rebuild` but also packs the sources into * `gulp default`: the same as `gulp rebuild` but also packs **Mibew Messenger**
archives under `src/release/` directory. into the installation archives in `src/release/` directory.
* `gulp phpcs`: runs [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) * `gulp phpcs`: runs
to check if the sources follows coding style. [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) to check
whether the source code complies with the coding style.

181
src/development/core-architecture.md
View File

@ -6,138 +6,147 @@ nav_sort: 0
# Core Architecture # Core Architecture
The Core of Mibew can be separated in three parts: server-side application and The **Core** of **Mibew Messenger** can be divided into three basic parts: the
client side application and widget. This page does not describe low-level **Server** side application, client side applications and the **Widget**. This
organization of the parts but provides their overview, describes their purpose page does not describe low-level organization of the parts, but provides their
and illustrates how they interact with each other. overview, describes their purpose and illustrates how they interacts with each
other.
## Server side application ## Server side application
Server side part of Mibew works with Apache, PHP and MySQL. It's written in the The **Server** side part of **Mibew Messenger** is written in PHP and works
top of [Symfony 2](http://symfony.com/) framework. At the current state Mibew with MySQL database. It's built on top of [Symfony 2](http://symfony.com/) web
does not use full Symfony's stack but uses several Symfony's components. framework. In its actual state **Mibew Messenger** does not use full Symfony's
stack but utilizes several Symfony's components.
Mibew does not depends only on Symfony. There are some other third-party **Mibew Messenger** does not depend solely on Symfony. There are other third
server-side libraries that are used in Mibew. Here is the list: party server side libraries used in **Mibew Messenger** too. Here is the list:
* [Composer](https://getcomposer.org/) is used to manage dependencies. * [Composer](https://getcomposer.org/) is used to manage dependencies.
* [Handlebars.php](https://github.com/XaminProject/handlebars.php) is the * [Handlebars.php](https://github.com/XaminProject/handlebars.php) is the
template engine of Mibew. server side template engine of **Mibew Messenger**.
* [Handlebars.php helpers](https://github.com/JustBlackBird/handlebars.php-helpers) * [Handlebars.php helpers](https://github.com/JustBlackBird/handlebars.php-helpers)
gives extra power to templates. gives some extra power to templates.
* [Stash](http://www.stashphp.com/) is used to work with cache. * [Stash](http://www.stashphp.com/) is used to work with cache.
* [Canteen HTML5](https://github.com/Canteen/CanteenHTML5) library simplifies * [Canteen HTML5](https://github.com/Canteen/CanteenHTML5) library simplifies
dynamic markup generation. dynamic markup generation.
* [PHP semver](https://github.com/vierbergenlars/php-semver) is used within * [PHP semver](https://github.com/vierbergenlars/php-semver) is used within the
plugins manager to resolve plugins' dependencies. plugins manager to handle plugins' dependencies.
* [Swiftmailer](http://swiftmailer.org/) is used as an abstraction over mail * [Swiftmailer](http://swiftmailer.org/) is used as an abstraction layer for
sending functionality. sending emails.
* [UAParser](https://github.com/ua-parser/uap-php) helps to determine browser * [UAParser](https://github.com/ua-parser/uap-php) helps to detect browser
used by a client. used by a client.
* [Punycode](https://github.com/true/php-punycode) library is used to build IDN * [Punycode](https://github.com/true/php-punycode) library is used to provide
support. IDN support.
Server side part of Mibew can be split into subsystem. This subsystems are not The **Server** side part of **Mibew Messenger** can be divided into a number of
completely isolated but can be described separately. At the moment the most subsystems. These subsystems are not completely isolated but can be described
important subsystems are: separately. At the moment the most important subsystems are:
* Cache subsystem * Cache subsystem.
* Client application's requests processor * Client application's requests processor.
* Events dispatcher * Events dispatcher.
* Plugins manager * Plugins manager.
* Routing subsystem * Routing subsystem.
* Styles and templates * Styles and templates.
## Client side application ## Client side applications
Client side application is written in JavaScript. It's built on the top of Client side applications are written in JavaScript. They're built on top of
[Marionette.js](http://marionettejs.com/) framework and uses some other [Marionette.js](http://marionettejs.com/) framework and utilize several other
third-party libraries: third party libraries:
* [jQuery](https://jquery.com/) is used for DOM manipulations * [jQuery](https://jquery.com/) is used for DOM manipulations.
* [Underscore.js](http://underscorejs.org/) is used to simplify routine * [Underscore.js](http://underscorejs.org/) is used to simplify routine
JavaScript operations. JavaScript operations.
* [Backbone.js](http://backbonejs.org/) is the base of Marionette.js. * [Backbone.js](http://backbonejs.org/) is the base of Marionette.js framework.
* [Handlebars.js](http://handlebarsjs.com/) is the template engine. * [Handlebars.js](http://handlebarsjs.com/) is the client side template engine.
* [Vex](http://github.hubspot.com/vex/docs/welcome/) provides beautiful and * [Vex](http://github.hubspot.com/vex/docs/welcome/) provides beautiful and
customizable dialog popups. customizable dialog popups.
* [Validator.js](https://github.com/chriso/validator.js) simplifies data * [Validator.js](https://github.com/chriso/validator.js) simplifies data
validation at client side. validation at the client side.
Client side application is a Marionette.js application which does restricted As it was pointed above a client side application is a Marionette.js
number of tasks. Not all JavaScript files in Mibew are related with client side application that performs a limited number of tasks. One should note that not
all JavaScript files in **Mibew Messenger** are related to client side
applications. At the moment there are three client side applications: applications. At the moment there are three client side applications:
* Chat application * **Chat application**.
* Users application * **Users application**.
* Thread log application * **Thread log application**.
_Chat application_ implements all client-side logic behind both user and **Chat application** implements all client side logic for both user and
operator chat windows. The application exchanges data with the server-side operator chat windows. The application communicates with the **Server** side
application using special RPC-like protocol. application using the special RPC-like protocol.
_Users application_ represents all client-side logic behind the page with **Users application** implements all client side logic for the page with the
awaiting users. The application exchanges data with the server-side list of awaiting users. The application communicates with the **Server** side
application using special RPC-like protocol. application using the special RPC-like protocol.
_Thread log application_ is a stub application that only renders thread log. **Thread log application** is a stub application that only renders thread log.
This application does not exchange data with the server. This application does not exchange data with the **Server** side application.
## Client — Server interaction ## Client — Server interaction
This is just an overview of the interaction. It does not contains full This is just an overview of the interaction. It does not contain a full
description of low level stuff powers the interaction. description of low level stuff that powers the interaction.
Interaction between client-side application and server-side application is a Interaction between a client side application and the **Server** side
kind of RPC interaction. Let's name interaction parts as Alice and Bob. Each application is an RPC-like interaction. Let's call interacting parties
data package which is transferred from Alice to Bob can contain requests for Alice and Bob. Each data package that is transferred from Alice to Bob
functions invocation and results of previous Bob's requests. may contain requests for functions invocation and results of previous Bob's
requests.
Alice can synchronously run several functions at Bob's side. Each function can Alice can synchronously call several functions at Bob's side. Each function can
use use results of previously ran functions as its arguments. Such behavior use results of previously called functions as its arguments. Such behaviour
provides unlimited flexibility and reduces transferred packages count. provides unlimited flexibility and reduces the number of transferred packages.
Let's back to programming. A part of client side app (namely `Mibew.Server` A part of a client side application (namely `Mibew.Server` object which is
object which is placed in `js/source/default/server.js`) sends AJAX request to defined in `js/source/default/server.js`) sends AJAX request to the web server
the Mibew server at regular intervals. Also there is an option to send such of **Mibew Messenger** at regular intervals. Also there is an option to send
requests immediately. such request immediately.
Encoded package is sent as body of HTTP(S) POST request. The server-side Encoded package is sent as the body of HTTP(S) POST request. The **Server**
application invoke all requested functions and generates response package in side application invokes all requested functions and generates the response
JSON format. If the server-side application needs to call something at client package in JSON format. If the **Server** side application needs to call
side requests for calls are included in the response package. something at the client side, requests for these calls should be included in
the response package.
At the server side `\Mibew\RequestProcessor\ClientSideProcessor` class is At the **Server** side `\Mibew\RequestProcessor\ClientSideProcessor` class is
responsible for the interaction. Actually it's an abstract class, so different responsible for the interaction. Actually it's an abstract class, so requests
client side application are served by different requests processors: from different client side applications are served by different requests
processors:
* `\Mibew\RequestProcessor\ThreadProcessor` is used to interact with * `\Mibew\RequestProcessor\ThreadProcessor` is used to interact with the
_chat application_. **Chat application**.
* `\Mibew\RequestProcessor\UsersProcessor` is used to interact with * `\Mibew\RequestProcessor\UsersProcessor` is used to interact with the
_users application_. **Users application**.
## Widget ## The Widget
Widget is a bunch of HTML markup and JavaScript code which is inserted in the The **Widget** is a mix of HTML markup and JavaScript code that should be
target page. In other words the widget is a chat button. inserted into the markup of the target site. In other words the **Widget** is a
chat button.
Code of The widget is written with pure JavaScript without any The code of the **Widget** is written in pure JavaScript without use of any
libraries/frameworks. It's done intentionally to avoid problems with the target libraries or frameworks. It is done intentionally to avoid possible problems
site's libraries. with the JavaScript code of the target site.
## Widget — Server interaction ## Widget — Server interaction
Interaction between server and widget is optional. It's used only when Interaction between the **Server** and the **Widget** is optional. It is used
**Enable "Tracking and inviting"** option is turned on in Mibew settings. only if _Enable "Tracking and inviting"_ option is turned on in the settings of
**Mibew Messenger**.
The widget sends requests to the server at regular intervals. To avoid problems The **Widget** sends requests to the **Server** at regular intervals. To avoid
with cross-domain requests JSONP technique is used. problems with cross-domain requests JSONP technique is used.
At the moment there is no way to pass custom data from widget to server. At the moment there is no way to pass custom data from the **Widget** to the
Nevertheless the server can use powerful RPC-like protocol to do something at **Server**. Nevertheless the **Server** can use powerful RPC-like protocol to
widget side (within target page context). It also allows to load external do something at the **Widget** side (within the context of the target web page).
JavaScript libraries before a function will be invoked. It also makes possible to load external JavaScript libraries before invocation
of a function.

673
src/development/server-side-events.md
View File

File diff suppressed because it is too large Load Diff

15
src/index.md
View File

@ -2,12 +2,13 @@
title: Documentation title: Documentation
--- ---
# Mibew documentation # Mibew Messenger documentation
Mibew Messenger is an open-source live support application written in PHP and **Mibew Messenger** is an open-source live support application written in PHP
MySQL. It enables one-on-one chat assistance in real-time directly from your and MySQL. It enables one-on-one chat assistance in real-time directly from
website. your web site.
Mibew documentation is now available for the community. If you want to improve **Mibew Messenger** documentation is now available for the community. If you
the documentation fork its [repository](https://github.com/mibew/docs.mibew.org) want to improve the documentation, feel free to fork its
and create an issue (or even a pull request) there. [repository](https://github.com/mibew/docs.mibew.org) and create an issue (or
even a pull request) there.

158
src/installation-and-update.md
View File

@ -9,113 +9,133 @@ nav_sort: 0
## Requirements ## Requirements
* Apache web server 1.3.34 or above with the ability to use local .htaccess * Apache web server 1.3.34 or above with the ability to use local .htaccess
files (mod_rewrite module is optional, but recommended) files (mod_rewrite module is optional, but highly recommended).
* MySQL database 5.0 or above * MySQL database 5.0 or above.
* PHP 5.4 or above with PDO, pdo_mysql and gd extensions * PHP 5.4 or above with PDO, pdo_mysql and gd extensions.
## Getting the sources ## Getting the sources
At the moment there are several options to get the source of Mibew. At the moment there are several options to get the source of **Mibew
Messenger**.
### Prebuilt version ### Prebuilt version
This version should be used in the most cases. The installation package is just This version should be used in most cases. The installation package is just
a `.zip` (`.tar.gz`) archive with all Mibew's files. It contains all third-party a `.zip` archive (`.tar.gz` archive is also available) with all files of
dependencies. The current stable version is available at SourceForge **Mibew Messenger**. It contains all third party dependencies too. The link to
[here](http://sourceforge.net/projects/mibew/). the current stable version is available at the
[dedicated page](https://mibew.org/download) on the official site of the
project.
### Building from sources ### Building from sources
Prebuilt version cannot suit all needs of the community. In some cases a user Prebuilt version cannot suit all needs of the community. In some cases a user
may be interested in the latest development version of Mibew or in using custom may be interested in the latest development version of **Mibew Messenger**, or
(patched) version of the Core. in using custom (patched) version of the **Core**.
The following instructions are addressed to users who have basic knowledge about The following instructions are addressed to users who have basic knowledge
[node.js](http://nodejs.org/), [npm](https://www.npmjs.org/), [Gulp](http://gulpjs.com/) about [node.js](http://nodejs.org/), [npm](https://www.npmjs.org/),
and [Composer](https://getcomposer.org/). [Gulp](http://gulpjs.com/), and [Composer](https://getcomposer.org/).
There are several actions one should do before use the latest version of Mibew There are several steps one should take before using the development version
from the repository: of **Mibew Messenger** from the repository:
1. Obtain a copy of the repository using `git clone`, download button, or another way. 1. Obtain a local copy of the repository using `git clone`, download button,
2. Make sure [PHP](http://php.net/) is installed and can be used in CLI mode. or in another way.
2. Make sure that [PHP](http://php.net/) is installed and can be used in CLI
mode.
2. Install [node.js](http://nodejs.org/) and [npm](https://www.npmjs.org/). 2. Install [node.js](http://nodejs.org/) and [npm](https://www.npmjs.org/).
3. Install [Gulp](http://gulpjs.com/). 3. Install [Gulp](http://gulpjs.com/).
5. Navigate to `src/` directory of the local copy of the repository. 5. Navigate to `src/` directory of the local copy of the repository.
6. Install npm dependencies using `npm install`. 6. Install npm dependencies using `npm install`.
7. Run Gulp to build Mibew using `gulp default`. 7. Run Gulp to build **Mibew Messenger** using `gulp default`.
Finally `.tar.gz` and `.zip` archives of the ready-to-use Mibew will be Finally, `.tar.gz` and `.zip` archives of the ready-to-use development version
available in `src/release` directory. of **Mibew Messenger** will be available in `src/release` directory.
## Installation ## Installation
When the archive with Mibew is downloaded the installation process can be When the archive with **Mibew Messenger** is downloaded the installation
started. Here are the instructions: process can be started. Here are the instructions:
1. Create folder with name 'mibew' in the root of your website. 1. Create the directory with name 'mibew' in the document root of your
2. Upload all the files contained in installation archive (retaining the directory website.
structure) into created folder. 2. Upload all files from the installation archive (retaining the directory
Be sure to chmod the mibew folder to `0755`. structure) into the created directory.
3. On unix/linux platforms change the owner of `/mibew/files/avatar` and Make sure that both you and your web server can access the contents of the
`/mibew/cache` folders to the user, under which the web server is running directory. On \*nix platform you may have to manually set the permissions
(for instance, www). The owner should have all rights on the folders bitmask to `0755` (`chmod 0755 mibew`).
`/mibew/files/avatar` and `/mibew/cache` 3. In case of \*nix platform change the owner of `mibew/files/avatar` and
(`chmod 0700 /mibew/files/avatar && chmod 0700 /mibew/cache`). `mibew/cache` directories to the user of the web server (depending on
4. Add a MySQL database with the name `mibew` system the name of the user could vary, for example it can be `www` or
5. Copy `/mibew/configs/default_config.yml` to `/mibew/configs/config.yml` `www-data`).
6. Edit `/mibew/configs/config.yml` to the information needed to connect to the The owner should have all rights on the directories `mibew/files/avatar`
database and `mibew/cache`
(`chmod 0700 mibew/files/avatar && chmod 0700 mibew/cache`).
4. Create a MySQL database with the name `mibew`.
5. Copy the file `mibew/configs/default_config.yml` to
`mibew/configs/config.yml`.
6. Edit `mibew/configs/config.yml` to specify the information needed to
connect to the database.
7. Using your web browser visit `http://<yourdomain>/mibew/install` and 7. Using your web browser visit `http://<yourdomain>/mibew/install` and
perform step-by-step installation. perform step-by-step installation via the web interface.
8. Remove `/mibew/install.php` file from your server 8. Delete the `mibew/install.php` file.
9. Logon as 9. Login as
user: admin user: `admin`
password: <your password> password: `<your password>`
10. Configure periodically running tasks by setting up an automated 10. Configure periodically running tasks by setting up an automated
process to visit the page `http://<yourdomain>/cron?cron_key=<key>` process to access the web page
`http://<yourdomain>/cron?cron_key=<cron key>`
The full URL including the secret "cron key" used to protect against The full URL including the secret "cron key" used to protect against
unauthorized access can be seen on the 'General' tab at the 'Settings' page. unauthorized access can be seen on the 'General' tab at the 'Settings'
page in the administrative interface of your **Mibew Messenger**.
## Update ## Update
Mibew starting from 2.0.0-beta.1 version can be updated to later versions using Starting from the 2.0.0-beta.1 version **Mibew Messenger** can be updated to
built-in update tool. later versions using built-in update tool.
Notice that there are neither migration tools nor updtate guides from 1.6.x Please note that the update tool doesn't fully automate the whole update
versions. process, but only the database migrations.
1. Backup your `mibew/configs/config.yml` Also please note that there are neither migration tools nor update guides for
2. Backup your `mibew/files/avatar` folder. the obsolete 1.6.x versions of **Mibew Messenger**.
Here are the instructions for the update process:
1. Backup your `mibew/configs/config.yml` file.
2. Backup your `mibew/files/avatar` directory.
3. Backup your database. Although it's not required, it's strongly recommended 3. Backup your database. Although it's not required, it's strongly recommended
to to so. to do so.
3. Disable all plugins 3. Disable all plugins.
4. Delete all items in mibew folder on the server. 4. Delete all items in `mibew` directory on the server.
5. Upload all files contained in the downloaded archive (retaining the 5. Upload all files from the installation archive (retaining the directory
directory structure) into mibew folder. structure) into `mibew` directory.
6. On unix/linux platforms change the owner of `/mibew/files/avatar` and 6. In case of \*nix platform change the owner of `mibew/files/avatar` and
`/mibew/cache` folders to the user, under which the web server is running `mibew/cache` directories to the user of the web server (depending on system
(for instance, www). The owner should have all rights on the folders the name of the user could vary, for example it can be `www` or `www-data`).
`/mibew/files/avatar` and `/mibew/cache` The owner should have all rights on the directories `mibew/files/avatar` and
(`chmod 0700 /mibew/files/avatar && chmod 0700 /mibew/cache`). `mibew/cache`
7. Restore all settings in `mibew/configs/config.yml` (`chmod 0700 mibew/files/avatar && chmod 0700 mibew/cache`).
8. Restore contents of `mibew/files/avatar` folder. 7. Restore all **Mibew Messenger** settings in `mibew/configs/config.yml`.
9. Visit `http://<yourdomain>/mibew/update/` and follow the instructions 8. Restore contents of `mibew/files/avatar` directory.
to update the database tables (if needed). 9. Using your web browser Visit `http://<yourdomain>/mibew/update/` and follow
10. Remove `mibew/install.php` file from your server. the instructions to update the database tables (if needed).
10. Delete the `mibew/install.php` file.
11. Enable disabled plugins. 11. Enable disabled plugins.
## Start work ## Get started
Congratulations! You finished the installation/update process. Now you should Congratulations! You finished the installation/update process. Now you should
perform several steps to start work: take several steps to get started:
1. Get button code at `http://<yourdomain>/mibew/operator/button-code`. 1. Configure and generate the button code at
2. Add HTML code of the button setup to the target's site markup. `http://<yourdomain>/mibew/operator/button-code`.
3. Wait for your visitors on "Pending users" 2. Add HTML code of the button to a target's site markup.
(`http://<yourdomain>/mibew/operator/users`) page. 3. Wait for visitors on 'Pending users' page in the administrative interface
of your **Mibew Messenger** (i.e. `http://<yourdomain>/mibew/operator/users`).

12
src/plugins.md
View File

@ -6,7 +6,13 @@ nav_sort: 10
# Plugins overview # Plugins overview
Mibew can be easily extended via plugins. A plugin is a bunch of features that **Mibew Messenger** can be extended via plugins. A plugin is a bunch of
could be used without core patching. features that can be used without patching of the **Core**.
The list of officially approved plugins can be found at https://mibew.org/plugins. The list of all stable and officially approved plugins can be found at the
[dedicated page](https://mibew.org/plugins) on the official web site of the
project.
The source code of the official plugins for **Mibew Messenger** is available in
the separate repositories of [Mibew organization](https://github.com/Mibew)
on GitHub.

72
src/plugins/installation.md
View File

@ -7,53 +7,61 @@ nav_sort: 0
# Plugin installation # Plugin installation
Installation procedure can vary from plugin to plugin but the common steps are Installation procedure can vary from plugin to plugin but the common steps are
the same and listed below. Also it's recommended to check README file shipped the same and listed below. Also it's recommended to check the README file
with a plugin before install it. shipped with a plugin before installation.
## The process ## The process
### Get the plugin ### Get the plugin
First of all you need to download the plugin sources. In the most cases plugin's First of all you need to download the plugin. In most cases plugin's author
author provides prepared `.zip` or `.tar.gz` archive with the plugin sources. provides prepared `.zip` (or `.tar.gz`) archive with the code.
All officially approved plugins are listed at https://mibew.org/plugins page. The list of all stable and officially approved plugins can be found at the
[dedicated page](https://mibew.org/plugins) on the official web site of the
project.
### Upload the plugin ### Upload the plugin
When you've got the plugin's archive you should extract files from it and upload When you've got the plugin's archive you should extract files from it and
them to the Mibew's server. The files of the plugin should be in upload them to the **Mibew Messenger**'s web server. The files of the plugin
`<mibew base path>/plugins/<Vendor name>/Mibew/Plugin/<Plugin name>/` directory. should be placed in
`<mibew base path>/plugins/<Vendor name>/Mibew/Plugin/<Plugin name>/`
directory.
For example, the main file of "**FooCorp:Connector**" plugin should have For example the full name of the main file of "**FooCorp:Connector**" plugin
`<mibew base path>/plugins/FooCorp/Mibew/Plugin/Connector/Plugin.php` path. should be
`<mibew base path>/plugins/FooCorp/Mibew/Plugin/Connector/Plugin.php`.
**Warning**: Letters case in the path is important! **Warning**: Paths are case sensitive! One should preserve the letters case in
it!
### Configure the plugin ### Configure the plugin
A plugin may require additional configuration. Check plugin's description or A plugin may require additional configuration. Check plugin's description or
README file that shipped with plugin's archive to know if the plugin needs to be README file shipped with a plugin to find out whether the plugin needs to be
configured. configured.
All configuration value are set in `configs/config.yml` file. If you are not All configuration values for plugins are set in the basic configuration file
familiar with YAML syntax take a look at https://en.wikipedia.org/wiki/YAML or of **Mibew Messenger**, i.e. in `configs/config.yml`. If you are not familiar
any other description that can be find on the Internet. with YAML syntax, please take a look at https://en.wikipedia.org/wiki/YAML or
any other description that can be found on the Internet.
Plugins configurations are stored in `plugins` associative array, which keys are Plugins' configurations are stored in the `plugins` associative array, whose
fully qualified plugins' names and the values are plugins' options. If there is keys are fully qualified plugins' names and the values are plugins' options.
no configurable plugins installed the `plugins` array is looks like: If there are no configurable plugins installed, the `plugins` array should
looks like:
```yaml ```yaml
plugins: [] plugins: []
``` ```
Lets assume you are trying to install "**FooCorp:Connector**" plugin that requires Let's assume, you are trying to install "**FooCorp:Connector**" plugin that
`timeout` and `reconnects` options. The `plugins` array from `configs/config.yml` requires `timeout` and `reconnects` options. In that case the `plugins` array
file becomes: in `configs/config.yml` file should looks like:
```yaml ```yaml
plugins: plugins:
@ -62,19 +70,19 @@ plugins:
reconnects: 3 reconnects: 3
``` ```
Also there are special configuration option `weight` that can be applied to Also there is a special service configuration option `weight` that can be
any plugin and controls order in which plugins are loaded. A plugin with lower applied to any plugin and controls the order in which plugins are loaded.
weight will be loaded and executed earlier than the one with higher weight. This The lower the weight, the earlier a plugin is loaded. This option can be
option can be omitted and equals to `0` by default. omitted and equals to `0` by default.
### Install the plugin ### Install the plugin
After the plugin's files are in place and the plugin is configured it should be After the plugin's files are in place and the plugin is properly configured it
installed using Mibew web interface. To do so you should navigate to should be installed using the administrative interface of **Mibew Messenger**.
`<mibew base URL>/operator/plugin` page and click on "_enable_" link in plugin's To do so you should navigate to `<mibew base URL>/operator/plugin` page and
row. click on '_enable_' link in the plugin's row.
If the plugin was installed and enabled correctly the value in "_state_" column If the plugin was installed and enabled successfully the value in '_state_'
will be changed to "_working_". If it does not check apache's error log for column will change to '_working_'. If it did not, one should check the error
details about the problem. log of the web server for details of the problem.

39
src/plugins/update.md
View File

@ -7,42 +7,39 @@ nav_sort: 10
# Plugin update # Plugin update
Update procedure can vary from plugin to plugin but the common steps are the Update procedure can vary from plugin to plugin but the common steps are the
same and listed below. Also it's recommended to check README file shipped same and listed below. Also it's recommended to check the README file shipped
with a plugin before update it. with a plugin before update.
## The process ## The process
### Get the plugin ### Get the plugin
First of all you need to download new version of plugin's sources. In the most First of all you need to download the plugin. In most cases plugin's author
cases plugin's author provides prepared `.zip` or `.tar.gz` archive with the provides prepared `.zip` (or `.tar.gz`) archive with the code.
plugin sources.
All officially approved plugins are listed at https://mibew.org/plugins page. The list of all stable and officially approved plugins can be found at the
[dedicated page](https://mibew.org/plugins) on the official web site of the
project.
### Update sources ### Update sources
When you've got the plugin's archive you should extract files from it and When you've got the archive with an actual version of a plugin you should
replace old plugin's files with new ones. extract files from it and upload them to the **Mibew Messenger**'s web server
replacing the old version of a plugin.
For example, files of "**FooCorp:Connector**" plugin should be situated in It is highly recommended to backup old files before replacement.
`<mibew base path>/plugins/FooCorp/Mibew/Plugin/Connector/` directory.
**Warning**: Letters case in the path is important!
It's highly recommended to backup files before replace them.
### Update database ### Update database
After plugin's files are updated the database should be updated too. To do so After update of the plugin's files, the database should be updated too. To do
navigate to `<mibew base URL>/operator/plugin` page and click on "_update_" link so you should navigate to `<mibew base URL>/operator/plugin` page and click on
in plugin's row. '_update_' link in the plugin's row.
It's highly recommended to backup database before the update. It is highly recommended to backup the database before update.
If the plugin was updated correctly the value in "_state_" column will be If the plugin was updated successfully the value in '_state_' column will
changed to "_working_". If it does not check apache's error log for details change to '_working_'. If it did not, one should check the error log of the
about the problem. web server for details of the problem.

4
templates/default.handlebars
View File

@ -9,7 +9,7 @@
<meta name="author" content=""> <meta name="author" content="">
<link rel="icon" href="{{baseUrl}}/assets/favicon.ico"> <link rel="icon" href="{{baseUrl}}/assets/favicon.ico">
<title>{{title}} &mdash; Mibew docs</title> <title>{{title}} &mdash; Mibew Messenger docs</title>
<!-- Bootstrap core CSS --> <!-- Bootstrap core CSS -->
<link href="{{baseUrl}}/assets/third-party/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> <link href="{{baseUrl}}/assets/third-party/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
@ -33,7 +33,7 @@
<nav class="navbar navbar-default"> <nav class="navbar navbar-default">
<div class="container"> <div class="container">
<div class="navbar-header"> <div class="navbar-header">
<a class="navbar-brand" href="{{baseUrl}}">Mibew</a> <a class="navbar-brand" href="{{baseUrl}}">Mibew Messenger</a>
</div> </div>
<div id="navbar"> <div id="navbar">
<ul class="nav navbar-nav navbar-right"> <ul class="nav navbar-nav navbar-right">