diff --git a/src/development.md b/src/development.md index 221d68f..afaa00c 100644 --- a/src/development.md +++ b/src/development.md @@ -6,10 +6,14 @@ nav_sort: 20 # Development overview -Mibew is a web application which uses Apache, PHP, MySQL and JavaScript. If you -want to patch the Core you also needs node.js and npm to build the sources. +**Mibew Messenger** is a web application which uses PHP, MySQL, and JavaScript. +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 -official plugins are stored on GitHub too. Take a look at -[Mibew organization](https://github.com/Mibew) on GitHub to get a list of all -official repositories. +All source code of **Mibew Messenger** is available on GitHub: +https://github.com/Mibew/mibew. All official plugins, themes, and translations +for **Mibew Messenger** are available on GitHub too. + +Take a look at [Mibew organization](https://github.com/Mibew) on GitHub to get +the list of all official repositories. diff --git a/src/development/build-system.md b/src/development/build-system.md index ad86dac..9dcbb71 100644 --- a/src/development/build-system.md +++ b/src/development/build-system.md @@ -6,35 +6,43 @@ nav_sort: 40 # 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 -to use build system if you want to modify Mibew's Core or use the latest -unreleased version from the respository. +to use build system whenever you want to modify the **Core** of +**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 -[node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) to make Gulp -works. For the most common tasks [PHP](http://php.net/) is also needed. +**Mibew Messenger** utilizes [Gulp.js](http://gulpjs.com/) as a build system. +To make Gulp run [node.js](https://nodejs.org/) and +[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/). 3. Install [Gulp](http://gulpjs.com/). -4. Navigate to `src/` directory of the local copy of the repository. -5. Install npm dependencies using `npm install`. -6. Run Gulp to build Mibew using `gulp default`. +5. Navigate to `src/` directory of the local copy of the repository. +6. Install npm dependencies using `npm install`. +7. Run Gulp to build **Mibew Messenger** using `gulp default`. -Finally `.tar.gz` and `.zip` archives of the ready-to-use Mibew will be -available in `src/release/` directory. +Finally, `.tar.gz` and `.zip` archives of the ready-to-use development version +of **Mibew Messenger** will be available in `src/release` directory. -The `default` task that was used above is just one of many available build -tasks. The full list can be got by running `gulp -T` in `src/` directory of -Mibew repository. Here is descripion of the most frequently used tasks: +The `default` task that was given above is just one of many available build +tasks. The full list of build tasks can be obtained by running `gulp -T` in +`src/` directory of the repository. Here are descriptions of several most +frequently used tasks: -* `gulp rebuild`: installs all necessary dependencies and compile (minifies, concats, - ...) all files that should be compiled. The result of the task is a - redy-to-use development version of Mibew. -* `gulp default`: the same as `gulp rebuild` but also packs the sources into - archives under `src/release/` directory. -* `gulp phpcs`: runs [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) - to check if the sources follows coding style. +* `gulp rebuild`: installs all necessary dependencies and compile (minifies, + concats, ...) all files that should be compiled. The result of the task is a + redy-to-use development version of **Mibew Messenger**. +* `gulp default`: the same as `gulp rebuild` but also packs **Mibew Messenger** + into the installation archives in `src/release/` directory. +* `gulp phpcs`: runs + [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) to check + whether the source code complies with the coding style. diff --git a/src/development/core-architecture.md b/src/development/core-architecture.md index 85c0f82..f9e8986 100644 --- a/src/development/core-architecture.md +++ b/src/development/core-architecture.md @@ -6,138 +6,147 @@ nav_sort: 0 # Core Architecture -The Core of Mibew can be separated in three parts: server-side application and -client side application and widget. This page does not describe low-level -organization of the parts but provides their overview, describes their purpose -and illustrates how they interact with each other. +The **Core** of **Mibew Messenger** can be divided into three basic parts: the +**Server** side application, client side applications and the **Widget**. This +page does not describe low-level organization of the parts, but provides their +overview, describes their purpose and illustrates how they interacts with each +other. ## Server side application -Server side part of Mibew works with Apache, PHP and MySQL. It's written in the -top of [Symfony 2](http://symfony.com/) framework. At the current state Mibew -does not use full Symfony's stack but uses several Symfony's components. +The **Server** side part of **Mibew Messenger** is written in PHP and works +with MySQL database. It's built on top of [Symfony 2](http://symfony.com/) web +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 -server-side libraries that are used in Mibew. Here is the list: +**Mibew Messenger** does not depend solely on Symfony. There are other third +party server side libraries used in **Mibew Messenger** too. Here is the list: * [Composer](https://getcomposer.org/) is used to manage dependencies. * [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) - gives extra power to templates. + gives some extra power to templates. * [Stash](http://www.stashphp.com/) is used to work with cache. * [Canteen HTML5](https://github.com/Canteen/CanteenHTML5) library simplifies dynamic markup generation. -* [PHP semver](https://github.com/vierbergenlars/php-semver) is used within - plugins manager to resolve plugins' dependencies. -* [Swiftmailer](http://swiftmailer.org/) is used as an abstraction over mail - sending functionality. -* [UAParser](https://github.com/ua-parser/uap-php) helps to determine browser +* [PHP semver](https://github.com/vierbergenlars/php-semver) is used within the + plugins manager to handle plugins' dependencies. +* [Swiftmailer](http://swiftmailer.org/) is used as an abstraction layer for + sending emails. +* [UAParser](https://github.com/ua-parser/uap-php) helps to detect browser used by a client. -* [Punycode](https://github.com/true/php-punycode) library is used to build IDN - support. +* [Punycode](https://github.com/true/php-punycode) library is used to provide + IDN support. -Server side part of Mibew can be split into subsystem. This subsystems are not -completely isolated but can be described separately. At the moment the most -important subsystems are: +The **Server** side part of **Mibew Messenger** can be divided into a number of +subsystems. These subsystems are not completely isolated but can be described +separately. At the moment the most important subsystems are: -* Cache subsystem -* Client application's requests processor -* Events dispatcher -* Plugins manager -* Routing subsystem -* Styles and templates +* Cache subsystem. +* Client application's requests processor. +* Events dispatcher. +* Plugins manager. +* Routing subsystem. +* Styles and templates. -## Client side application +## Client side applications -Client side application is written in JavaScript. It's built on the top of -[Marionette.js](http://marionettejs.com/) framework and uses some other -third-party libraries: +Client side applications are written in JavaScript. They're built on top of +[Marionette.js](http://marionettejs.com/) framework and utilize several other +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 JavaScript operations. -* [Backbone.js](http://backbonejs.org/) is the base of Marionette.js. -* [Handlebars.js](http://handlebarsjs.com/) is the template engine. +* [Backbone.js](http://backbonejs.org/) is the base of Marionette.js framework. +* [Handlebars.js](http://handlebarsjs.com/) is the client side template engine. * [Vex](http://github.hubspot.com/vex/docs/welcome/) provides beautiful and customizable dialog popups. * [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 -number of tasks. Not all JavaScript files in Mibew are related with client side +As it was pointed above a client side application is a Marionette.js +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: -* Chat application -* Users application -* Thread log application +* **Chat application**. +* **Users application**. +* **Thread log application**. -_Chat application_ implements all client-side logic behind both user and -operator chat windows. The application exchanges data with the server-side -application using special RPC-like protocol. +**Chat application** implements all client side logic for both user and +operator chat windows. The application communicates with the **Server** side +application using the special RPC-like protocol. -_Users application_ represents all client-side logic behind the page with -awaiting users. The application exchanges data with the server-side -application using special RPC-like protocol. +**Users application** implements all client side logic for the page with the +list of awaiting users. The application communicates with the **Server** side +application using the special RPC-like protocol. -_Thread log application_ is a stub application that only renders thread log. -This application does not exchange data with the server. +**Thread log application** is a stub application that only renders thread log. +This application does not exchange data with the **Server** side application. ## Client — Server interaction -This is just an overview of the interaction. It does not contains full -description of low level stuff powers the interaction. +This is just an overview of the interaction. It does not contain a full +description of low level stuff that powers the interaction. -Interaction between client-side application and server-side application is a -kind of RPC interaction. Let's name interaction parts as Alice and Bob. Each -data package which is transferred from Alice to Bob can contain requests for -functions invocation and results of previous Bob's requests. +Interaction between a client side application and the **Server** side +application is an RPC-like interaction. Let's call interacting parties +Alice and Bob. Each data package that is transferred from Alice to Bob +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 -use use results of previously ran functions as its arguments. Such behavior -provides unlimited flexibility and reduces transferred packages count. +Alice can synchronously call several functions at Bob's side. Each function can +use results of previously called functions as its arguments. Such behaviour +provides unlimited flexibility and reduces the number of transferred packages. -Let's back to programming. A part of client side app (namely `Mibew.Server` -object which is placed in `js/source/default/server.js`) sends AJAX request to -the Mibew server at regular intervals. Also there is an option to send such -requests immediately. +A part of a client side application (namely `Mibew.Server` object which is +defined in `js/source/default/server.js`) sends AJAX request to the web server +of **Mibew Messenger** at regular intervals. Also there is an option to send +such request immediately. -Encoded package is sent as body of HTTP(S) POST request. The server-side -application invoke all requested functions and generates response package in -JSON format. If the server-side application needs to call something at client -side requests for calls are included in the response package. +Encoded package is sent as the body of HTTP(S) POST request. The **Server** +side application invokes all requested functions and generates the response +package in JSON format. If the **Server** side application needs to call +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 -responsible for the interaction. Actually it's an abstract class, so different -client side application are served by different requests processors: +At the **Server** side `\Mibew\RequestProcessor\ClientSideProcessor` class is +responsible for the interaction. Actually it's an abstract class, so requests +from different client side applications are served by different requests +processors: -* `\Mibew\RequestProcessor\ThreadProcessor` is used to interact with - _chat application_. -* `\Mibew\RequestProcessor\UsersProcessor` is used to interact with - _users application_. +* `\Mibew\RequestProcessor\ThreadProcessor` is used to interact with the + **Chat application**. +* `\Mibew\RequestProcessor\UsersProcessor` is used to interact with the + **Users application**. -## Widget +## The Widget -Widget is a bunch of HTML markup and JavaScript code which is inserted in the -target page. In other words the widget is a chat button. +The **Widget** is a mix of HTML markup and JavaScript code that should be +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 -libraries/frameworks. It's done intentionally to avoid problems with the target -site's libraries. +The code of the **Widget** is written in pure JavaScript without use of any +libraries or frameworks. It is done intentionally to avoid possible problems +with the JavaScript code of the target site. ## Widget — Server interaction -Interaction between server and widget is optional. It's used only when -**Enable "Tracking and inviting"** option is turned on in Mibew settings. +Interaction between the **Server** and the **Widget** is optional. It is used +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 -with cross-domain requests JSONP technique is used. +The **Widget** sends requests to the **Server** at regular intervals. To avoid +problems with cross-domain requests JSONP technique is used. -At the moment there is no way to pass custom data from widget to server. -Nevertheless the server can use powerful RPC-like protocol to do something at -widget side (within target page context). It also allows to load external -JavaScript libraries before a function will be invoked. +At the moment there is no way to pass custom data from the **Widget** to the +**Server**. Nevertheless the **Server** can use powerful RPC-like protocol to +do something at the **Widget** side (within the context of the target web page). +It also makes possible to load external JavaScript libraries before invocation +of a function. diff --git a/src/development/server-side-events.md b/src/development/server-side-events.md index 843691c..cd2a0e2 100644 --- a/src/development/server-side-events.md +++ b/src/development/server-side-events.md @@ -6,17 +6,18 @@ nav_sort: 20 # Server side events -Mibew provides Events subsystem that can be used by plugins. All events logic -encapsulated inside `\Mibew\EventDispatcher\EventDispatcher` class. +**Mibew Messenger** provides Events subsystem that can be used by plugins. All +events logic encapsulated inside `\Mibew\EventDispatcher\EventDispatcher` +class. -There are several common actions that can be done with event dispatcher: +There are several common actions that can be done with the event dispatcher: * attach a listener to an event using `\Mibew\EventDispatcher\EventDispatcher::attachListener()` method. -* detach a listener from the event using +* detach a listener from an event using `\Mibew\EventDispatcher\EventDispatcher::detachListener()` method. -* trigger event using `\Mibew\EventDispatcher\EventDispatcher::triggerEvent()` - method. +* trigger an event using + `\Mibew\EventDispatcher\EventDispatcher::triggerEvent()` method. To get more info about these actions take a look at the source code of `\Mibew\EventDispatcher\EventDispatcher` class. @@ -24,382 +25,392 @@ To get more info about these actions take a look at the source code of ## List of events -* [Ban events](#ban-events) -* [Button events](#button-events) -* [Cron events](#cron-events) -* [Group events](#group-events) -* [Invitation events](#invitation-events) -* [Operator events](#operator-events) -* [Page events](#page-events) -* [Resource events](#resource-events) -* [Routing events](#routing-events) -* [Thread events](#thread-events) -* [Users events](#users-events) -* [Visitor events](#visitor-events) -* [Widget events](#widget-events) +* [Ban events](#ban-events). +* [Button events](#button-events). +* [Cron events](#cron-events). +* [Group events](#group-events). +* [Invitation events](#invitation-events). +* [Operator events](#operator-events). +* [Page events](#page-events). +* [Resource events](#resource-events). +* [Routing events](#routing-events). +* [Thread events](#thread-events). +* [Users events](#users-events). +* [Visitor events](#visitor-events). +* [Widget events](#widget-events). ### Ban events #### Create -The event can be referenced using value of `\Mibew\EventDispatcher\Events::BAN_CREATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::BAN_CREATE` constant. -This event is triggered after a ban has been created. An associative -array with the following items is passed to the event handlers: +This event is triggered after a ban has been created. An associative array with +the following items is passed to event handlers: -* "ban": an instance of `\Mibew\Ban` class. +* 'ban': an instance of `\Mibew\Ban` class, the state of the created ban. #### Update -The event can be referenced using value of `\Mibew\EventDispatcher\Events::BAN_UPDATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::BAN_UPDATE` constant. -This event is triggered after a ban is saved. An associative array with -the following items is passed to the event handlers: +This event is triggered after a ban has been saved. An associative array with +the following items is passed to event handlers: - * "ban": an instance of `\Mibew\Ban`, the state of the ban after the update. - * "original_ban": an instance of `\Mibew\Ban`, the state of the ban before the - update. + * 'ban': an instance of `\Mibew\Ban` class, the state of the ban after update. + * 'original_ban': an instance of `\Mibew\Ban` class, the state of the ban + before update. #### Delete -The event can be referenced using value of `\Mibew\EventDispatcher\Events::BAN_DELETE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::BAN_DELETE` constant. -This event is triggered after a ban has been deleted. An associative -array with the following items is passed to the event handlers: +This event is triggered after a ban has been deleted. An associative array with +the following items is passed to event handlers: -* "id": int, deleted ban ID. +* 'id': integer, ID of the deleted ban. ### Button events #### Generate -The event can be referenced using value of `\Mibew\EventDispatcher\Events::BUTTON_GENERATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::BUTTON_GENERATE` constant. -This event is triggered after a button has been generated. An associative -array with the following items is passed to the event handlers: +This event is triggered after a button has been generated. An associative array +with the following items is passed to event handlers: -* "button": an instance of `\Canteen\HTML5\Fragment` which - represents markup of the button. -* "generator": an instance of `\Mibew\Button\Generator\GeneratorInterface` which - is used for button generation. +* 'button': an instance of `\Canteen\HTML5\Fragment` class, representation of + the markup of the generated button. +* 'generator': an instance of `\Mibew\Button\Generator\GeneratorInterface` + class that was used for button generation. ### Cron events #### Run -The event can be referenced using value of `\Mibew\EventDispatcher\Events::CRON_RUN` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::CRON_RUN` constant. -This event is triggered when cron is run. It provides an ability for plugins to -perform custom maintenance actions. +This event is triggered when system cron tasks are running (more specifically +after the statistics calculation but before the check for updates). It +provides plugins an ability to perform custom maintenance operations. ### Group events #### Create -The event can be referenced using value of `\Mibew\EventDispatcher\Events::GROUP_CREATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::GROUP_CREATE` constant. This event is triggered after a group has been created. An associative array -with the following items is passed to the event handlers: +with the following items is passed to event handlers: -* "group": group's array. +* 'group': array containing all data fields of the created group. See + `create_group()` function in `libs/groups.php` file for more info. #### Update -The event can be referenced using value of `\Mibew\EventDispatcher\Events::GROUP_UPDATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::GROUP_UPDATE` constant. -This event is triggered after a group is saved. An associative array with the -following items is passed to the event handlers: +This event is triggered after a group has been saved. An associative array with +the following items is passed to event handlers: -* "group": array, the state of the group after update. -* "original_group": array, the state of the group before update. +* 'group': array, the state of the group after update. +* 'original_group': array, the state of the group before update. #### Delete -The event can be referenced using value of `\Mibew\EventDispatcher\Events::GROUP_DELETE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::GROUP_DELETE` constant. This event is triggered after a group has been deleted. An associative array -with the following items is passed to the event handlers: +with the following items is passed to event handlers: -* "id": int, deleted group ID. +* 'id': integer, ID of the deleted group. #### Update operators -The event can be referenced using value of `\Mibew\EventDispatcher\Events::GROUP_UPDATE_OPERATORS` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::GROUP_UPDATE_OPERATORS` constant. -This event is triggered after a set of operators related with a group has been -changed. An associative array with the following items is passed to the event +This event is triggered after a set of operators belonging to a group has been +altered. An associative array with the following items is passed to event handlers: -* "group": group's array. -* "original_operators": array, list of operators IDs before the update. -* "operators": array, list of operators IDs after the update. +* 'group': array containing all data fields of the group. +* 'original_operators': array, the list of IDs of operators before update. +* 'operators': array, the list of IDs of operators after update. ### Invitation events #### Create -The event can be referenced using value of `\Mibew\EventDispatcher\Events::INVITATION_CREATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::INVITATION_CREATE` constant. This event is triggered after an invitation has been created. An associative -array with the following items is passed to the event handlers: +array with the following items is passed to event handlers: -* "invitation": an instance of `\Mibew\Thread` class. +* 'invitation': an instance of `\Mibew\Thread` class, the state of the thread + related to the invitation. #### Accept -The event can be referenced using value of `\Mibew\EventDispatcher\Events::INVITATION_ACCEPT` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::INVITATION_ACCEPT` constant. This event is triggered after an invitation has been accepted by a visitor. An -associative array with the following items is passed to the event handlers: +associative array with the following items is passed to event handlers: -* "invitation": an instance of `\Mibew\Thread` class. +* 'invitation': an instance of `\Mibew\Thread` class, the state of the thread + related to the invitation. #### Reject -The event can be referenced using value of `\Mibew\EventDispatcher\Events::INVITATION_REJECT` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::INVITATION_REJECT` constant. This event is triggered after an invitation has been rejected by a visitor. An -associative array with the following items is passed to the event handlers: +associative array with the following items is passed to event handlers: -* "invitation": an instance of `\Mibew\Thread` class. +* 'invitation': an instance of `\Mibew\Thread` class, the state of the thread + related to the invitation. #### Ignore -The event can be referenced using value of `\Mibew\EventDispatcher\Events::INVITATION_IGNORE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::INVITATION_IGNORE` constant. This event is triggered after an invitation has been ignored by a visitor and -automatically closed by the system. An associative array with the following -items is passed to the event handlers: +was automatically closed by the system. An associative array with the following +items is passed to event handlers: -* "invitation": an instance of `\Mibew\Thread` class. +* 'invitation': an instance of `\Mibew\Thread` class, the state of the thread + related to the invitation. ### Operator events #### Authenticate -The event can be referenced using value of `\Mibew\EventDispatcher\Events::OPERATOR_AUTHENTICATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::OPERATOR_AUTHENTICATE` constant. -This event is triggered if an operator cannot be authenticated by the system. It -provides an ability for plugins to implement custom authentication logic. An -associative array with the following items is passed to the event handlers: +This event is triggered if an operator cannot be authenticated by the system +(i.e. the operator is not logged in yet). It provides plugins an ability to +implement custom authentication logic. An associative array with the following +items is passed to event handlers: -* "operator": array, if a plugin has extracted operator from the request - it should set operator's data to this field. -* "request": `\Symfony\Component\HttpFoundation\Request`, +* 'operator': array, if a plugin has extracted operator from the incoming + request, it should populate the array with the operator's data. See + `update_operator()` function in `libs/operator.php` file for more info. +* 'request': an instance of `\Symfony\Component\HttpFoundation\Request` class, incoming request. Can be used by a plugin to extract an operator. #### Log in -The event can be referenced using value of `\Mibew\EventDispatcher\Events::OPERATOR_LOGIN` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::OPERATOR_LOGIN` constant. -This event is triggered after an operator logged in using system login form. An -associative array with the following items is passed to the event handlers: +This event is triggered after an operator has been logged in using the +standard login form. An associative array with the following items is passed +to event handlers: -* "operator": array of the logged in operator info; -* "remember": boolean, indicates if system should remember operator. +* 'operator': array containing all data fields of the operator. +* 'remember': boolean, indicates whether the system should "remember" the + operator. #### Log out -The event can be referenced using value of `\Mibew\EventDispatcher\Events::OPERATOR_LOGOUT` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::OPERATOR_LOGOUT` constant. -This event is triggered after an operator is logged out. +This event is triggered after an operator has been logged out. #### Create -The event can be referenced using value of `\Mibew\EventDispatcher\Events::OPERATOR_CREATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::OPERATOR_CREATE` constant. -This event is triggered after an operator has been created. An associative array -with the following items is passed to the event handlers: +This event is triggered after an operator has been created. An associative +array with the following items is passed to event handlers: -* "operator": operator's array. +* 'operator': array containing all data fields of the operator. #### Update -The event can be referenced using value of `\Mibew\EventDispatcher\Events::OPERATOR_UPDATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::OPERATOR_UPDATE` constant. -This event is triggered after an operator is saved. An associative array with -the following items is passed to the event handlers: +This event is triggered after an operator has been saved. An associative array +with the following items is passed to event handlers: -* "operator": array, the state of the operator after update. -* "original_operator": array, the state of the operator before update. +* 'operator': array, the state of the operator after update. +* 'original_operator': array, the state of the operator before update. #### Delete -The event can be referenced using value of `\Mibew\EventDispatcher\Events::OPERATOR_DELETE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::OPERATOR_DELETE` constant. -This event is triggered after an operator has been deleted. An associative array -with the following items is passed to the event handlers: +This event is triggered after an operator has been deleted. An associative +array with the following items is passed to event handlers: -* "id": int, deleted operator ID. +* 'id': integer, ID of the deleted operator. ### Page events #### Add CSS -The event can be referenced using value of `\Mibew\EventDispatcher\Events::PAGE_ADD_CSS` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::PAGE_ADD_CSS` constant. -This event is triggered before CSS assets are attached to a page. It provides an -ability for plugins to add custom CSS files (or inline styles) to a page. An -associative array with the following items is passed to the event handlers: +This event is triggered before CSS assets are attached to a page of the +administrative interface of **Mibew Messenger**. It provides plugins an +ability to connect pages to custom CSS files or add inline styles to pages. +An associative array with the following items is passed to event handlers: -* "request": `\Symfony\Component\HttpFoundation\Request`, a request instance. +* 'request': an instance of `\Symfony\Component\HttpFound-ation\Request` class. CSS files will be attached to the requested page. -* "css": array of assets. Each asset can be either a string with relative URL of - a CSS file or an array with "content", "type" and "weight" items. See - `\Mibew\Asset\AssetManagerInterface::getCssAssets()` for details of their - meaning. Modify this array to add or remove additional CSS files. +* 'css': array of assets. Each asset can be either a string with the relative + URL of a CSS file or an array with 'content', 'type' and 'weight' items. See + `\Mibew\Asset\AssetManagerInterface::getCssAssets()` for more info. One + should modify this array to add (or remove) extra CSS files. #### Add JavaScript -The event can be referenced using value of `\Mibew\EventDispatcher\Events::PAGE_ADD_JS` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::PAGE_ADD_JS` constant. -This event is triggered before JavaScript assets are attached to a page. It -provides an ability for plugins to add custom JavaScript files (or inline -scripts) to a page. An associative array with the following items is passed to -the event handlers: +This event is triggered before JavaScript assets are attached to a page of the +administrative interface of **Mibew Messenger**. It provides plugins an ability +to connect pages to custom JavaScript files or add inline scripts to pages. +An associative array with the following items is passed to event handlers: -* "request": `\Symfony\Component\HttpFoundation\Request`, a - request instance. JavaScript files will be attached to the requested - page. -* "js": array of assets. Each asset can be either a string with relative URL of - a JavaScript file or an array with "content", "type" and "weight" items. See - `\Mibew\Asset\AssetManagerInterface::getJsAssets()` for details of their - meaning. Modify this array to add or remove additional JavaScript files. +* 'request': an instance of `\Symfony\Component\HttpFoundation\Request` class. + JavaScript files will be attached to the requested page. +* 'js': array of assets. Each asset can be either a string with the relative + URL of a JavaScript file or an array with 'content', 'type' and 'weight' + items. See `\Mibew\Asset\AssetManagerInterface::getJsAssets()` for more info. + One should modify this array to add (or remove) extra JavaScript files. #### JavaScipt plugin options -The event can be referenced using value of `\Mibew\EventDispatcher\Events::PAGE_ADD_JS_PLUGIN_OPTIONS` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::PAGE_ADD_JS_PLUGIN_OPTIONS` constant. This event is triggered before options of JavaScript plugins are attached to a -page. It provides an ability for plugins to pass some data to the client side. -An associative array with the following items is passed to the event handlers: +page. It provides plugins an ability to pass some data to the client side. +An associative array with the following items is passed to event handlers: -* "request": `\Symfony\Component\HttpFoundation\Request`, a request instance. - Plugins will work at the requested page. -* "plugins": associative array, whose keys are plugins names and values are - plugins options. Modify this array to add or change plugins options. +* 'request': an instance of `\Symfony\Component\HttpFoundation\Request` class. + Options will be attached to the requested page. +* 'plugins': associative array, whose keys are names of plugins and values are + their options. One should modify this array to add (or alter) plugins + options. ### Resource events #### Access denied -The event can be referenced using value of `\Mibew\EventDispatcher\Events::RESOURCE_ACCESS_DENIED` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::RESOURCE_ACCESS_DENIED` constant. -This event is triggered if the access for resource is denied. An -associative array with the following items is passed to the event -handlers: +This event is triggered if the access to a resource is denied. An associative +array with the following items is passed to event handlers: -* "request": `\Symfony\Component\HttpFoundation\Request`, incoming request - object. -* "response": `\Symfony\Component\HttpFoundation\Response`, if a plugin wants to - send a custom response to the client it should attach a response object to - this field. +* 'request': an instance of `\Symfony\Component\HttpFoundation\Request` class, + incoming request object. +* 'response': an instance of `\Symfony\Component\HttpFoundation\Response` + class, if a plugin wants to send a custom response to a client it should + attach a response object to this field. #### Not found -The event can be referenced using value of `\Mibew\EventDispatcher\Events::RESOURCE_NOT_FOUND` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::RESOURCE_NOT_FOUND` constant. This event is triggered if a resource is not found. An associative array with -the following items is passed to the event handlers: +the following items is passed to event handlers: -* "request": `\Symfony\Component\HttpFoundation\Request`, incoming request - object. -* "response": `\Symfony\Component\HttpFoundation\Response`, if a plugin - wants to send a custom response to the client it should attach a response - object to this field. +* 'request': an instance of `\Symfony\Component\HttpFoundation\Request` class, + incoming request object. +* 'response': an instance of `\Symfony\Component\HttpFoundation\Response` + class, if a plugin wants to send a custom response to a client it should + attach a response object to this field. ### Routing events #### Alter -The event can be referenced using value of `\Mibew\EventDispatcher\Events::ROUTES_ALTER` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::ROUTES_ALTER` constant. -This event is triggered after all routes are loaded. It provides an ability for -plugins to alter routes collection before it will be used. An associative array -with the following items is passed to the event handlers: +This event is triggered after all routes has been loaded. It provides plugins +an ability to alter the routes collection before it will be used. An +associative array with the following items is passed to event handlers: -* "routes" an instance of `\Symfony\Component\Routing\RouteCollection` class. +* 'routes': an instance of `\Symfony\Component\Routing\RouteCollection` class. ### Thread events #### Function call -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_FUNCTION_CALL` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_FUNCTION_CALL` constant. -This event is triggered when an API a function is called at client side in the -"_chat_" application, but the system is not aware of this function. +This event is triggered if an API function is called at the client side in +the **Chat application**, but the system is not aware of this function. -Plugins can implement custom API functions by attaching handlers to the event. -If a plugin wants to return some results, it should use "results" element of the -event arguments array (see below). +Plugins can implement custom API functions by attaching handlers to this event. +If a plugin should return some results, it should use 'results' element of +the event arguments array (see below). -An associative array with the following items is passed to the event handlers: +An associative array with the following items is passed to event handlers: -* "request_processor": an instance of `\Mibew\RequestProcessor\ThreadProcessor` - which processes the current call. -* "function": string, name of the function that was called. -* "arguments": associative array of arguments that was passed to the function. -* "results": array, list of function results. +* 'request_processor': an instance of `\Mibew\RequestProcessor\ThreadProcessor` + class that handles the current call. +* 'function': string, name of the function that was called. +* 'arguments': associative array of arguments passed to the function. +* 'results': array, the list of results of the function call. Here is an example of the event handler: ```php public function callHandler(&$function) { - // Check that the function we want to implement is called. - if ($function['function'] == 'microtime') { + // Ensure that the function we want to implement was called. + if ($function['function'] === 'microtime') { // Check some function's arguments. $as_float = empty($function['arguments']['as_float']) ? false @@ -413,168 +424,182 @@ public function callHandler(&$function) #### Create -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_CREATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_CREATE` constant. This event is triggered after a thread has been created. An associative array -with the following items is passed to the event handlers: +with the following items is passed to event handlers: -* "thread": an instance of `\Mibew\Thread`. +* 'thread': an instance of `\Mibew\Thread` class, the state of the created + thread. #### Update -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_UPDATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_UPDATE` constant. -This event is triggered after a thread is saved. An associative array with the -following items is passed to the event handlers: +This event is triggered after a thread has been saved. An associative array +with the following items is passed to event handlers: -* "thread": an instance of `\Mibew\Thread`, state of the thread after the +* 'thread': an instance of `\Mibew\Thread` class, the state of the thread after update. -* "original_thread": an instance of `\Mibew\Thread`, state of the thread before - the update. +* 'original_thread': an instance of `\Mibew\Thread` class, the state of the + thread before update. #### Delete -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_DELETE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_DELETE` constant. This event is triggered after a thread has been deleted. An associative array -with the following items is passed to the event handlers: +with the following items is passed to event handlers: -* "id": int, deleted thread ID. +* 'id': integer, ID of the deleted thread. #### Close -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_CLOSE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_CLOSE` constant. This event is triggered after a thread has been closed. An associative array -with the following items is passed to the event handlers: +with the following items is passed to event handlers: -* "thread": an instance of `\Mibew\Thread`. +* 'thread': an instance of `\Mibew\Thread` class, the state of the closed + thread. #### Post message -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_POST_MESSAGE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_POST_MESSAGE` constant. -This event is triggered before a message has been posted to thread. It provides -an ability for plugins to alter message, its kind or options. An associative -array with the following items is passed to the event handlers: +This event is triggered before a message has been posted to a thread. It +provides plugins an ability to alter the message itself and/or its kind or +options. An associative array with the following items is passed to event +handlers: -* "thread": an instance of `\Mibew\Thread`. -* "message_kind": int, message kind. -* "message_body": string, message body. -* "message_options": associative array, list of options passed to - `\Mibew\Thread::postMessage()` method as the third argument. +* 'thread': an instance of `\Mibew\Thread` class, the state of the thread. +* 'message_kind': integer, a kind of the message. See `KIND_*` constants in + `\Mibew\Thread` for more info. +* 'message_body': string, a body of the message. +* 'message_options': associative array, the list of options passed to + `\Mibew\Thread::postMessage()` method as a third argument. #### Alter messages -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_GET_MESSAGES_ALTER` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_GET_MESSAGES_ALTER` constant. -This event is triggered after messages related with a thread are loaded. It -provides an ability for plugins to alter messages set. An associative array with -the following items is passed to the event handlers: +This event is triggered after messages related to a thread has been loaded. It +provides plugins an ability to alter messages. An associative array with the +following items is passed to event handlers: -* "thread": an instance of `\Mibew\Thread`. -* "messages": array, list of messages. Each message is an associative array. See - `\Mibew\Thread::getMessages()` return value for details of its structure. +* 'thread': an instance of `\Mibew\Thread` class, the state of the thread. +* 'messages': array, the list of messages. Each message is an associative + array. See the return value of `\Mibew\Thread::getMessages()` method for more + info. -#### User is ready (since 2.1.0) +#### User is ready (since Mibew Messenger 2.1.0) -The event can be referenced using value of `\Mibew\EventDispatcher\Events::THREAD_USER_IS_READY` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::THREAD_USER_IS_READY` constant. -This event is triggered after the thread is created, the user passed pre-chat -survey and all system messages are sent to him. This event is not triggered if -there are no online operators and the chat cannot be started. An associative -array with the following items is passed to the event handlers: +This event is triggered after the thread has been created, the user +has successfully passed pre-chat survey and all system messages has been sent +to him. This event is not triggered if there are no operators online and +therefore the chat cannot be started. An associative array with the following +items is passed to event handlers: -* "thread": an instance of `\Mibew\Thread`. +* 'thread': an instance of `\Mibew\Thread` class, the state of the thread. ### Users events #### Alter threads -The event can be referenced using value of `\Mibew\EventDispatcher\Events::USERS_UPDATE_THREADS_ALTER` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::USERS_UPDATE_THREADS_ALTER` constant. -This event is triggered before the threads list is sent to the "users" client -side application. It provide an ability to alter the list. A plugin can attach -some fields to each thread or completeley replace the whole list. An associative -array with the following items is passed to the event handlers: +This event is triggered before the list of threads is sent to the +**Users application** on the client side. It provides plugins an ability to +alter the list. A plugin can attach some custom fields to each thread or even +completely replace the whole list. An associative array with the following +items is passed to event handlers: -* "threads": array of threads data arrays. +* 'threads': array of threads, each item is the data related to a single + thread. See `\Mibew\RequestProcessor\UsersProcessor\apiUpdateThreads()` + method for more info. -#### Load visitors +#### Load visitors -The event can be referenced using value of `\Mibew\EventDispatcher\Events::USERS_UPDATE_VISITORS_LOAD` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::USERS_UPDATE_VISITORS_LOAD` constant. -This event is triggered before the list of on site visitors is loaded for -sending to the "users" client side application. It provide an ability for -plugins to load, sort and limit visitors list. An associative array with the -following items is passed to the event handlers: +This event is triggered before the list of active site visitors is loaded to be +sent to the **Users application** on the client side. It provides plugins an +ability to load, sort and/or trim the visitors list. An associative array with +the following items is passed to event handlers: -* "visitors": array of visitors data arrays. Each visitor array must contain at - least the following keys: "id", "userName", "userAgent", "userIp", "remote", - "firstTime", "lastTime", "invitations", "chats", "invitationInfo". If there - are no visitors an empty array should be used. +* 'visitors': array of visitors, each item is the data related to a single + visitor. Each visitor array must contain at least following keys: + 'id', 'userName', 'userAgent', 'userIp', 'remote', 'firstTime', 'lastTime', + 'invitations', 'chats', 'invitationInfo'. If there are no active visitors, + an empty array should be used. -If the "visitors" item was not set by a plugin the default system loader -will be used. +If a plugin will not set the 'visitors' item, the default system loader will +be used. #### Alter visitors -The event can be referenced using value of `\Mibew\EventDispatcher\Events::USERS_UPDATE_VISITORS_ALTER` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::USERS_UPDATE_VISITORS_ALTER` constant. -This event is triggered before the on site visitors list is sent to the -"_users_" client application. It provide an ability to alter the list. A plugin -can attach some fields to each visitor or completeley replace the whole list. An -associative array with the following items is passed to the event handlers: +This event is triggered before the list of active site visitors list is sent to +the **Users application** on the client side. It provides plugins an ability to +alter the list. A plugin can attach some custom fields to each visitor or even +completely replace the whole list. An associative array with the following +items is passed to event handlers: -* "visitors": array of visitors data arrays. +* 'visitors': array of visitors, each item is the data related to a single + visitor. See '[Load visitors](#load-visitors-event)' event and + `\Mibew\RequestProcessor\UsersProcessor\apiUpdateVisitors()` method + for more info. #### Function call -The event can be referenced using value of `\Mibew\EventDispatcher\Events::USERS_FUNCTION_CALL` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::USERS_FUNCTION_CALL` constant. -This event is triggered when an API a function is called at client side in the -"_users_" application, but the system is not aware of this function. +This event is triggered if an API function is called at the client side in +the **Users application**, but the system is not aware of this function. -Plugins can implement custom API functions by attaching handlers to the event. -If a plugin wants to return some results, it should use "results" element of the -event arguments array (see below). +Plugins can implement custom API functions by attaching handlers to this event. +If a plugin should return some results, it should use 'results' element of +the event arguments array (see below). -An associative array with the following items is passed to the event handlers: +An associative array with the following items is passed to event handlers: -* "request_processor": an instance of `\Mibew\RequestProcessor\UsersProcessor` - which processes the current call. -* "function": string, name of the function that was called. -* "arguments": associative array of arguments that was passed to the function. -* "results": array, list of function results. +* 'request_processor': an instance of `\Mibew\RequestProcessor\UsersProcessor` + class that handles the current call. +* 'function': string, name of the function that was called. +* 'arguments': associative array of arguments passed to the function. +* 'results': array, the list of results of the function call. Here is an example of the event handler: ```php public function callHandler(&$function) { - // Check that the function we want to implement is called. - if ($function['function'] == 'microtime') { + // Ensure that the function we want to implement is called. + if ($function['function'] === 'microtime') { // Check some function's arguments. $as_float = empty($function['arguments']['as_float']) ? false @@ -588,88 +613,96 @@ public function callHandler(&$function) ### Visitor events -#### Create +#### Create -The event can be referenced using value of `\Mibew\EventDispatcher\Events::VISITOR_CREATE` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::VISITOR_CREATE` constant. -This event is triggered when a visitor is tracked by the widget for the first -time. An associative array with the following items is passed to the event -handlers: +This event is triggered when a visitor has been tracked by the **Widget** for +the first time. An associative array with the following items is passed to +event handlers: -* "visitor": array, list of visitor's info. See returned value of - `track_get_visitor_by_id()` function for details of its structure. +* 'visitor': array populated with the data of a visitor. See returned value of + `track_get_visitor_by_id()` function from `libs/track.php` for more info. #### Track -The event can be referenced using value of `\Mibew\EventDispatcher\Events::VISITOR_TRACK` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::VISITOR_TRACK` constant. -This event is triggered every time a visitor is tracked by the widget. An -associative array with the following items is passed to the event handlers: +This event is triggered every time a visitor has been tracked by the +**Widget**. An associative array with the following items is passed to event +handlers: -* "visitor": array, list of visitor's info. See returned value of - `track_get_visitor_by_id()` function for details of its structure. +* 'visitor': array populated with the data of a visitor. See returned value of + `track_get_visitor_by_id()` function from `libs/track.php` for more info. +Note that when a visitor will be tracked by the **Widget** for the first time, +initially the '[Create](#visitor-create-event)' event will be triggered, and +the 'Track' event will be triggered only afterwards. #### Delete old -The event can be referenced using value of `\Mibew\EventDispatcher\Events::VISITOR_DELETE_OLD` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::VISITOR_DELETE_OLD` constant. -This event is triggered after old visitors are deleted. An associative array -with the following items is passed to the event handlers: +This event is triggered after old visitors have been deleted. An associative +array with the following items is passed to event handlers: -* "visitors": array, list of removed visitors' IDs. +* 'visitors': array, the list of IDs of removed visitors. ### Widget events #### Alter response -The event can be referenced using value of `\Mibew\EventDispatcher\Events::WIDGET_RESPONSE_ALTER` -constant. +The event can be referenced using the value of +`\Mibew\EventDispatcher\Events::WIDGET_RESPONSE_ALTER` constant. -This event is triggered every time the widget data is ready to be sent. An -associative array with the following items is passed to the event listeners: +This event is triggered every time the **Widget** data is ready to be sent. An +associative array with the following items is passed to event listeners: -* "visitor": array, visitor's info. -* "request": an instance of `\Symfony\Component\HttpFoundation\Request` which - represents incoming request. -* "response": array, set of data that will be sent to the widget. See - description of its stucture and use case below. -* "route_url_generator": an instance of `\Mibew\Routing\Generator\SecureUrlGeneratorInterface`. -* "asset_url_generator": an instance of `\Mibew\Asset\Generator\UrlGeneratorInterface`. +* 'visitor': array populated with the data of a visitor. See returned value of + `track_get_visitor_by_id()` function from `libs/track.php` for more info. +* 'request' an instance of `\Symfony\Component\HttpFoundation\Request` class, + incoming request object. +* 'response': array, a set of data that will be sent to the **Widget**. See + description of its stucture and an example use case below. +* 'route_url_generator': an instance of + `\Mibew\Routing\Generator\SecureUrlGeneratorInterface` class. +* 'asset_url_generator': an instance of + `\Mibew\Asset\Generator\UrlGeneratorInterface` class. -This event can be used to do something at page the visitor is currenlty browsing. +This event can be used to perform something at the page the visitor is +currenlty browsing. -For example we can call a function every time the widget get the response from -the server. Here is the event listener code from a plugin: +For example we can call a function every time the **Widget** gets a response +from the **Server**. Here is the event listener code from a plugin: ```php public function callHandler(&$args) { - // This is just a shortcut for URL generator. + // This is just a shortcut for the URL generator. $g = $args['asset_url_generator']; - // The external libraries can be loaded before the function will be - // called. There can be as many libraries as needed (even none). - // The keys of the "load" array are libraries IDs and values are + // External libraries could be loaded before the function will be + // called. There could be as many libraries as needed (even none). + // Keys of the 'load' array are IDs of the libraries and values are // their URLs. $args['response']['load']['the_lib'] = 'http://example.com/lib.js'; $args['response']['load']['the_func'] = $g->generate($this->getFilesPath() . '/func.js'); - // The "handlers" array contains a list of functions that should be + // The 'handlers' array contains a list of functions that should be // called. $args['response']['handlers'][] = 'usefulFunc'; - // The "dependencies" array lists all libraries a function depend on. - // In this example "usefulFunc" depends on libraries with "the_lib" - // and "the_func" IDs. + // The 'dependencies' array contains a list of all libraries a function depends on. + // In this example 'usefulFunc' depends on libraries with IDs equal to 'the_lib' + // and 'the_func'. $args['response']['dependencies']['usefulFunc'] = array('the_lib', 'the_func'); - // Some extra data can be passed to the function. + // Some extra data could be passed to the function too. $args['response']['data']['usefulFunc'] = array('time' => microtime(true)); } ``` @@ -678,8 +711,8 @@ Here is the JavaScript part of the example: ```javascript (function(Mibew) { - // Notice the full function name. All callable functions must be - // defined as properties of Mibew.APIFunctions object. + // Pay attention to the full function name. All callable functions must be + // defined as a properties of Mibew.APIFunctions object. Mibew.APIFunctions.usefulFunc = function(data) { // Do some job here. console.dir(data.usefulFunc); diff --git a/src/index.md b/src/index.md index 16c1c58..6ed47ec 100644 --- a/src/index.md +++ b/src/index.md @@ -2,12 +2,13 @@ title: Documentation --- -# Mibew documentation +# Mibew Messenger documentation -Mibew Messenger is an open-source live support application written in PHP and -MySQL. It enables one-on-one chat assistance in real-time directly from your -website. +**Mibew Messenger** is an open-source live support application written in PHP +and MySQL. It enables one-on-one chat assistance in real-time directly from +your web site. -Mibew documentation is now available for the community. If you want to improve -the documentation fork its [repository](https://github.com/mibew/docs.mibew.org) -and create an issue (or even a pull request) there. +**Mibew Messenger** documentation is now available for the community. If you +want to improve the documentation, feel free to fork its +[repository](https://github.com/mibew/docs.mibew.org) and create an issue (or +even a pull request) there. diff --git a/src/installation-and-update.md b/src/installation-and-update.md index da5e2f3..516ba86 100644 --- a/src/installation-and-update.md +++ b/src/installation-and-update.md @@ -9,113 +9,133 @@ nav_sort: 0 ## Requirements * Apache web server 1.3.34 or above with the ability to use local .htaccess - files (mod_rewrite module is optional, but recommended) - * MySQL database 5.0 or above - * PHP 5.4 or above with PDO, pdo_mysql and gd extensions + files (mod_rewrite module is optional, but highly recommended). + * MySQL database 5.0 or above. + * PHP 5.4 or above with PDO, pdo_mysql and gd extensions. ## 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 -This version should be used in the most cases. The installation package is just -a `.zip` (`.tar.gz`) archive with all Mibew's files. It contains all third-party -dependencies. The current stable version is available at SourceForge -[here](http://sourceforge.net/projects/mibew/). +This version should be used in most cases. The installation package is just +a `.zip` archive (`.tar.gz` archive is also available) with all files of +**Mibew Messenger**. It contains all third party dependencies too. The link to +the current stable version is available at the +[dedicated page](https://mibew.org/download) on the official site of the +project. ### Building from sources 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 -(patched) version of the Core. +may be interested in the latest development version of **Mibew Messenger**, or +in using custom (patched) version of the **Core**. -The following instructions are addressed to users who have basic knowledge about -[node.js](http://nodejs.org/), [npm](https://www.npmjs.org/), [Gulp](http://gulpjs.com/) -and [Composer](https://getcomposer.org/). +The following instructions are addressed to users who have basic knowledge +about [node.js](http://nodejs.org/), [npm](https://www.npmjs.org/), +[Gulp](http://gulpjs.com/), and [Composer](https://getcomposer.org/). -There are several actions one should do before use the latest version of Mibew -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. -2. Make sure [PHP](http://php.net/) is installed and can be used in CLI mode. +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/). 3. Install [Gulp](http://gulpjs.com/). 5. Navigate to `src/` directory of the local copy of the repository. 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 -available in `src/release` directory. +Finally, `.tar.gz` and `.zip` archives of the ready-to-use development version +of **Mibew Messenger** will be available in `src/release` directory. ## Installation -When the archive with Mibew is downloaded the installation process can be -started. Here are the instructions: +When the archive with **Mibew Messenger** is downloaded the installation +process can be started. Here are the instructions: -1. Create folder with name 'mibew' in the root of your website. -2. Upload all the files contained in installation archive (retaining the directory - structure) into created folder. - Be sure to chmod the mibew folder to `0755`. -3. On unix/linux platforms change the owner of `/mibew/files/avatar` and - `/mibew/cache` folders to the user, under which the web server is running - (for instance, www). The owner should have all rights on the folders - `/mibew/files/avatar` and `/mibew/cache` - (`chmod 0700 /mibew/files/avatar && chmod 0700 /mibew/cache`). -4. Add a MySQL database with the name `mibew` -5. Copy `/mibew/configs/default_config.yml` to `/mibew/configs/config.yml` -6. Edit `/mibew/configs/config.yml` to the information needed to connect to the - database +1. Create the directory with name 'mibew' in the document root of your + website. +2. Upload all files from the installation archive (retaining the directory + structure) into the created directory. + Make sure that both you and your web server can access the contents of the + directory. On \*nix platform you may have to manually set the permissions + bitmask to `0755` (`chmod 0755 mibew`). +3. In case of \*nix platform change the owner of `mibew/files/avatar` and + `mibew/cache` directories to the user of the web server (depending on + system the name of the user could vary, for example it can be `www` or + `www-data`). + The owner should have all rights on the directories `mibew/files/avatar` + 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:///mibew/install` and - perform step-by-step installation. -8. Remove `/mibew/install.php` file from your server -9. Logon as - user: admin - password: + perform step-by-step installation via the web interface. +8. Delete the `mibew/install.php` file. +9. Login as + user: `admin` + password: `` 10. Configure periodically running tasks by setting up an automated - process to visit the page `http:///cron?cron_key=` + process to access the web page + `http:///cron?cron_key=` 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 -Mibew starting from 2.0.0-beta.1 version can be updated to later versions using -built-in update tool. +Starting from the 2.0.0-beta.1 version **Mibew Messenger** can be updated to +later versions using built-in update tool. -Notice that there are neither migration tools nor updtate guides from 1.6.x -versions. +Please note that the update tool doesn't fully automate the whole update +process, but only the database migrations. -1. Backup your `mibew/configs/config.yml` -2. Backup your `mibew/files/avatar` folder. +Also please note that there are neither migration tools nor update guides for +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 - to to so. -3. Disable all plugins -4. Delete all items in mibew folder on the server. -5. Upload all files contained in the downloaded archive (retaining the - directory structure) into mibew folder. -6. On unix/linux platforms change the owner of `/mibew/files/avatar` and - `/mibew/cache` folders to the user, under which the web server is running - (for instance, www). The owner should have all rights on the folders - `/mibew/files/avatar` and `/mibew/cache` - (`chmod 0700 /mibew/files/avatar && chmod 0700 /mibew/cache`). -7. Restore all settings in `mibew/configs/config.yml` -8. Restore contents of `mibew/files/avatar` folder. -9. Visit `http:///mibew/update/` and follow the instructions - to update the database tables (if needed). -10. Remove `mibew/install.php` file from your server. + to do so. +3. Disable all plugins. +4. Delete all items in `mibew` directory on the server. +5. Upload all files from the installation archive (retaining the directory + structure) into `mibew` directory. +6. In case of \*nix platform change the owner of `mibew/files/avatar` and + `mibew/cache` directories to the user of the web server (depending on system + the name of the user could vary, for example it can be `www` or `www-data`). + The owner should have all rights on the directories `mibew/files/avatar` and + `mibew/cache` + (`chmod 0700 mibew/files/avatar && chmod 0700 mibew/cache`). +7. Restore all **Mibew Messenger** settings in `mibew/configs/config.yml`. +8. Restore contents of `mibew/files/avatar` directory. +9. Using your web browser Visit `http:///mibew/update/` and follow + the instructions to update the database tables (if needed). +10. Delete the `mibew/install.php` file. 11. Enable disabled plugins. -## Start work +## Get started Congratulations! You finished the installation/update process. Now you should -perform several steps to start work: -1. Get button code at `http:///mibew/operator/button-code`. -2. Add HTML code of the button setup to the target's site markup. -3. Wait for your visitors on "Pending users" - (`http:///mibew/operator/users`) page. +take several steps to get started: +1. Configure and generate the button code at + `http:///mibew/operator/button-code`. +2. Add HTML code of the button to a target's site markup. +3. Wait for visitors on 'Pending users' page in the administrative interface + of your **Mibew Messenger** (i.e. `http:///mibew/operator/users`). diff --git a/src/plugins.md b/src/plugins.md index 3b8d061..06969ff 100644 --- a/src/plugins.md +++ b/src/plugins.md @@ -6,7 +6,13 @@ nav_sort: 10 # Plugins overview -Mibew can be easily extended via plugins. A plugin is a bunch of features that -could be used without core patching. +**Mibew Messenger** can be extended via plugins. A plugin is a bunch of +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. diff --git a/src/plugins/installation.md b/src/plugins/installation.md index 0e14232..7e9cc46 100644 --- a/src/plugins/installation.md +++ b/src/plugins/installation.md @@ -7,53 +7,61 @@ nav_sort: 0 # Plugin installation 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 -with a plugin before install it. +the same and listed below. Also it's recommended to check the README file +shipped with a plugin before installation. ## The process ### Get the plugin -First of all you need to download the plugin sources. In the most cases plugin's -author provides prepared `.zip` or `.tar.gz` archive with the plugin sources. +First of all you need to download the plugin. In most cases plugin's author +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 -When you've got the plugin's archive you should extract files from it and upload -them to the Mibew's server. The files of the plugin should be in -`/plugins//Mibew/Plugin//` directory. +When you've got the plugin's archive you should extract files from it and +upload them to the **Mibew Messenger**'s web server. The files of the plugin +should be placed in +`/plugins//Mibew/Plugin//` +directory. -For example, the main file of "**FooCorp:Connector**" plugin should have -`/plugins/FooCorp/Mibew/Plugin/Connector/Plugin.php` path. +For example the full name of the main file of "**FooCorp:Connector**" plugin +should be +`/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 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. -All configuration value are set in `configs/config.yml` file. If you are not -familiar with YAML syntax take a look at https://en.wikipedia.org/wiki/YAML or -any other description that can be find on the Internet. +All configuration values for plugins are set in the basic configuration file +of **Mibew Messenger**, i.e. in `configs/config.yml`. If you are not familiar +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 -fully qualified plugins' names and the values are plugins' options. If there is -no configurable plugins installed the `plugins` array is looks like: +Plugins' configurations are stored in the `plugins` associative array, whose +keys are fully qualified plugins' names and the values are plugins' options. +If there are no configurable plugins installed, the `plugins` array should +looks like: ```yaml plugins: [] ``` -Lets assume you are trying to install "**FooCorp:Connector**" plugin that requires -`timeout` and `reconnects` options. The `plugins` array from `configs/config.yml` -file becomes: +Let's assume, you are trying to install "**FooCorp:Connector**" plugin that +requires `timeout` and `reconnects` options. In that case the `plugins` array +in `configs/config.yml` file should looks like: ```yaml plugins: @@ -62,19 +70,19 @@ plugins: reconnects: 3 ``` -Also there are special configuration option `weight` that can be applied to -any plugin and controls order in which plugins are loaded. A plugin with lower -weight will be loaded and executed earlier than the one with higher weight. This -option can be omitted and equals to `0` by default. +Also there is a special service configuration option `weight` that can be +applied to any plugin and controls the order in which plugins are loaded. +The lower the weight, the earlier a plugin is loaded. This option can be +omitted and equals to `0` by default. ### Install the plugin -After the plugin's files are in place and the plugin is configured it should be -installed using Mibew web interface. To do so you should navigate to -`/operator/plugin` page and click on "_enable_" link in plugin's -row. +After the plugin's files are in place and the plugin is properly configured it +should be installed using the administrative interface of **Mibew Messenger**. +To do so you should navigate to `/operator/plugin` page and +click on '_enable_' link in the plugin's row. -If the plugin was installed and enabled correctly the value in "_state_" column -will be changed to "_working_". If it does not check apache's error log for -details about the problem. +If the plugin was installed and enabled successfully the value in '_state_' +column will change to '_working_'. If it did not, one should check the error +log of the web server for details of the problem. diff --git a/src/plugins/update.md b/src/plugins/update.md index 89e0ad0..dc669de 100644 --- a/src/plugins/update.md +++ b/src/plugins/update.md @@ -7,42 +7,39 @@ nav_sort: 10 # Plugin update 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 -with a plugin before update it. +same and listed below. Also it's recommended to check the README file shipped +with a plugin before update. ## The process ### Get the plugin -First of all you need to download new version of plugin's sources. In the most -cases plugin's author provides prepared `.zip` or `.tar.gz` archive with the -plugin sources. +First of all you need to download the plugin. In most cases plugin's author +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. ### Update sources -When you've got the plugin's archive you should extract files from it and -replace old plugin's files with new ones. +When you've got the archive with an actual version of a plugin you should +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 -`/plugins/FooCorp/Mibew/Plugin/Connector/` directory. - -**Warning**: Letters case in the path is important! - -It's highly recommended to backup files before replace them. +It is highly recommended to backup old files before replacement. ### Update database -After plugin's files are updated the database should be updated too. To do so -navigate to `/operator/plugin` page and click on "_update_" link -in plugin's row. +After update of the plugin's files, the database should be updated too. To do +so you should navigate to `/operator/plugin` page and click on +'_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 -changed to "_working_". If it does not check apache's error log for details -about the problem. +If the plugin was updated successfully the value in '_state_' column will +change to '_working_'. If it did not, one should check the error log of the +web server for details of the problem. diff --git a/templates/default.handlebars b/templates/default.handlebars index d1756c7..9bf1336 100644 --- a/templates/default.handlebars +++ b/templates/default.handlebars @@ -9,7 +9,7 @@ - {{title}} — Mibew docs + {{title}} — Mibew Messenger docs @@ -33,7 +33,7 @@