updated documentation #335 #297

README.md

@@ -1,12 +1,14 @@
 # Yii2-user [![Build Status](https://img.shields.io/travis/dektrium/yii2-user/master.svg?style=flat-square)](https://travis-ci.org/dektrium/yii2-user) [![Packagist Version](https://img.shields.io/packagist/v/dektrium/yii2-user.svg?style=flat-square)](https://packagist.org/packages/dektrium/yii2-user) [![Total Downloads](https://img.shields.io/packagist/dt/dektrium/yii2-user.svg?style=flat-square)](https://packagist.org/packages/dektrium/yii2-user) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
 
-Most of web applications provide a way for users to register, log in or reset their forgotten passwords. Rather than
-re-implementing this on each application, you can use Yii2-user which is a flexible user management module for Yii2 that
-handles common tasks such as registration, authentication and password retrieval. Current version includes following features:
+Most of web applications provide a way for users to register, log in or reset
+their forgotten passwords. Rather than re-implementing this on each application,
+you can use Yii2-user which is a flexible user management module for Yii2 that
+handles common tasks such as registration, authentication and password retrieval.
+The latest version includes following features:
 
 * Registration with an optional confirmation per mail
 * Registration via social networks
-* Password retrieval
+* Password recovery
 * Account and profile management
 * Console commands
 * User management interface
@@ -22,10 +24,7 @@ handles common tasks such as registration, authentication and password retrieval
 Anyone and everyone is welcome to contribute. Please take a moment to
 review the [guidelines for contributing](CONTRIBUTING.md).
 
-* [Bug reports](CONTRIBUTING.md#bugs)
-* [Feature requests](CONTRIBUTING.md#features)
-* [Pull requests](CONTRIBUTING.md#pull-requests)
-
 ## License
 
-Yii2-user is released under the MIT License. See the bundled [LICENSE.md](LICENSE.md) for details.
+Yii2-user is released under the MIT License. See the bundled [LICENSE.md](LICENSE.md)
+for details.

UPGRADE.md

@@ -1,16 +1,25 @@
 Upgrading instructions for Yii2-user
 ====================================
 
-The following upgrading instructions are cumulative. That is, if you want to upgrade from version A to version C and
-there is version B between A and C, you need to following the instructions for both A and B.
+The following upgrading instructions are cumulative. That is, if you want to
+upgrade from version A to version C and there is version B between A and C, you
+need to following the instructions for both A and B.
+
+Upgrade from Yii2-user 0.9.* to Yii2-user 0.9.4
+
+- New authentication via social networks has been introduced. You should update
+your `authClientCollection` component as described in [guide](docs/social-auth.md).
+
+- Admin views have been remade. If you override admin view files, you should
+update them accordingly to the made changes.
 
 Upgrade from Yii2-user 0.8.*
 ----------------------------
 
 - **APPLY NEW MIGRATIONS!**
 
-- `webUserClass` module option has been removed. If you use your own user component class you should set in `user`
-application component configuration:
+- `webUserClass` module option has been removed. If you use your own user 
+component class you should set in `user` application component configuration:
 
 ```php
 'components' => [
@@ -20,8 +29,8 @@ application component configuration:
 ],
 ```
 
-- ModelManager component has been removed. If you override models, now you should set them via `modelMap` module's
-property.
+- ModelManager component has been removed. If you override models, now you
+should set them via `modelMap` module's property.
 
 **Before:**
 
@@ -55,8 +64,8 @@ property.
 ],
 ```
 
-- Mailer component has been changed. Now it should be configured via `mailer` module property. You can read more about
-mailer configuration [here](docs/mailer.md).
+- Mailer component has been changed. Now it should be configured via `mailer`
+module property. You can read more about mailer configuration [here](docs/mailer.md).
 
 **Before:**
 
@@ -86,4 +95,5 @@ mailer configuration [here](docs/mailer.md).
 ],
 ```
 
-- Urls `user/settings/email` and `user/settings/password` have been merged into a new one `user/settings/account`.
+- Urls `user/settings/email` and `user/settings/password` have been merged into
+a new one `user/settings/account`.

docs/README.md

@@ -10,6 +10,7 @@ Yii2-user documentation is licensed under the [CC BY 4.0](http://creativecommons
 - [Configuration](configuration.md)
 - [List of available actions](available-actions.md)
 - [Troubleshooting](troubleshooting.md)
+- [Usage with Yii2 advanced template](usage-with-advanced-template.md)
 
 ## Overriding
 
@@ -25,6 +26,7 @@ Yii2-user documentation is licensed under the [CC BY 4.0](http://creativecommons
 
 ## RBAC
 
+- [Powerful RBAC with Yii2-rbac](yii2-rbac.md)
 - [Simpler RBAC with access control filter](custom-access-control.md)
 
 ## Guides

docs/adding-captcha.md

@@ -1,5 +1,4 @@
-How to add captcha to form
-==========================
+# How to add captcha to form
 
 Adding captcha to forms is pretty easy and can be done in three steps:
 
@@ -10,9 +9,7 @@ Adding captcha to forms is pretty easy and can be done in three steps:
 In this guide I would like to show you how to add captcha field in the registration form but you can add captcha
 to any form following this steps.
 
-1. Adding field and validation rules to model
----------------------------------------------
-
+## 1. Adding field and validation rules to model
 
 First of all you need to override Registration form as described in special guide. After this done you have to add
 public property named **captcha** and validation rules.
@@ -44,8 +41,7 @@ public property named **captcha** and validation rules.
 
 ```
 
-2. Adding widget to the view
-----------------------------
+## 2. Adding widget to the view
 
 Before doing this step you have to configure view application component as described in guide. After this done you have
 to create new file named `register.php` in `@app/views/user/registration`. Now you have to add widget to registration
@@ -102,8 +98,7 @@ form, just copy and paste following code into newly created view file.
 ```
 
 
-3. Adding action to the controller
-----------------------------------
+## 3. Adding action to the controller
 
 In order to make captcha work you have to add captcha action to `app\controllers\SiteController` Maybe it is already
 added because standard Yii2 application template adds it automatically.

docs/available-actions.md

@@ -1,21 +1,31 @@
-List of available actions
-=========================
+# List of available actions
 
 Yii2-user includes a lot of actions, which you can access by creating URLs for them. Here is the table of available
 actions which contains route and short description of each action. You can create URLs for them using special Yii
 helper `\yii\helpers\Url::to()`.
 
-|Route                          |Description                                                            |
-|-------------------------------|-----------------------------------------------------------------------|
-|**/user/registration/register**| Displays registration form                                            |
-|**/user/registration/resend**  | Displays resend form                                                  |
-|**/user/registration/confirm** | Confirms a user (requires *id* and *token* query params)              |
-|**/user/security/login**       | Displays login form                                                   |
-|**/user/security/logout**      | Logs the user out (available only via POST method)                    |
-|**/user/recovery/request**     | Displays recovery request form                                        |
-|**/user/recovery/reset**       | Displays password reset form (requires *id* and *token* query params) |
-|**/user/settings/profile**     | Displays profile settings form                                        |
-|**/user/settings/account**     | Displays account settings form (email, username, password)            |
-|**/user/settings/networks**    | Displays social network accounts settings page                        |
-|**/user/profile/show**         | Displays user's profile (requires *id* query param)                   |
-|**/user/admin/index**          | Displays user management interface                                    |
+- **/user/registration/register** Displays registration form
+- **/user/registration/resend**   Displays resend form
+- **/user/registration/confirm**  Confirms a user (requires *id* and *token* query params)
+- **/user/security/login**        Displays login form
+- **/user/security/logout**       Logs the user out (available only via POST method)
+- **/user/recovery/request**      Displays recovery request form
+- **/user/recovery/reset**        Displays password reset form (requires *id* and *token* query params)
+- **/user/settings/profile**      Displays profile settings form
+- **/user/settings/account**      Displays account settings form (email, username, password)
+- **/user/settings/networks**     Displays social network accounts settings page
+- **/user/profile/show**          Displays user's profile (requires *id* query param)
+- **/user/admin/index**           Displays user management interface
+
+## Example of menu
+
+You can add links to registration, login and logout as follows:
+
+```php
+Yii::$app->user->isGuest ?
+    ['label' => 'Sign in', 'url' => ['/user/security/login']] :
+    ['label' => 'Sign out (' . Yii::$app->user->identity->username . ')',
+        'url' => ['/user/security/logout'],
+        'linkOptions' => ['data-method' => 'post']],
+['label' => 'Register', 'url' => ['/user/registration/register'], 'visible' => Yii::$app->user->isGuest]
+```

docs/getting-started.md

@@ -4,6 +4,8 @@ Yii2-user is designed to work out of the box. It means that installation require
 minimal steps. Only one configuration step should be taken and you are ready to
 have user management on your Yii2 website.
 
+> If you're using Yii2 advanced template, you should read [this article](usage-with-advanced-template.md) firstly.
+
 ### 1. Download
 
 Yii2-user can be installed using composer. Run following command to download and
@@ -37,6 +39,11 @@ and run the following command:
 $ php yii migrate/up --migrationPath=@vendor/dektrium/yii2-user/migrations
 ```
 
+## Where do I go now?
+
+You have Yii2-user installed. Not you can check out the [list of articles](README.md)
+for more information.
+
 ## Troubleshooting
 
 If you're having troubles with Yii2-user, make sure to check out the 

docs/mailer.md

@@ -1,5 +1,4 @@
-Mailer
-======
+# Mailer
 
 Yii2-user includes special component named Mailer, which is used to send emails in four different instances:
 
@@ -8,8 +7,7 @@ Yii2-user includes special component named Mailer, which is used to send emails
 - Email change confirmation message
 - Recovery message
 
-Configuration
--------------
+## Configuration
 
 Mailer can be configured as followed:
 

docs/overriding-controllers.md

@@ -1,11 +1,9 @@
-Overriding controllers
-======================
+# Overriding controllers
 
 The default Yii2-user controllers provide a lot of functionality that is sufficient for general use cases. But sometimes
 you may need to extend that functionality and add some logic that suits your needs.
 
-Step 1: Create new controller
------------------------------
+## Step 1: Create new controller
 
 First of all you should create new controller under your own namespace (it is recommended to use `app\controllers\user`)
 and extend it from the controller you want to override.
@@ -27,8 +25,7 @@ class AdminController extends BaseAdminController
 }
 ```
 
-Step 2: Add your controller to controller map
----------------------------------------------
+## Step 2: Add your controller to controller map
 
 To let Yii2-user know about your controller, you should add it to the module's controller map, as follows:
 

docs/overriding-models.md

@@ -1,5 +1,4 @@
-Overriding models
-=================
+# Overriding models
 
 When you are creating application with Yii2-user you can find that you need to override models or forms. This guide
 describes how you can override any model used by Yii2-user. Moreover you can attach any behavior or event handler to any
@@ -34,8 +33,7 @@ In order to make Yii2-user use your class you need to configure module as follow
 ...
 ```
 
-Attaching behaviors and event handlers
---------------------------------------
+## Attaching behaviors and event handlers
 
 Yii2-user allows you to attach behavior or event handler to any model. To do this you can set model map like so:
 

docs/overriding-views.md

@@ -1,5 +1,4 @@
-Overriding views
-================
+# Overriding views
 
 When you start using Yii2-user you will probably find that you need to override the default views provided by the module.
 Although view names are not configurable, Yii2 provides a way to override views using themes. To get started you should
@@ -22,8 +21,7 @@ configure your view application component as follows:
 In the above `pathMap` means that every view in @dektrium/user/views will be first searched under `@app/views/user` and
 if a view exists in the theme directory it will be used instead of the original view.
 
-Example
--------
+## Example
 
 An example of overriding the registration page view is demonstrated below. First make sure you have configured view
 application component.

docs/social-auth.md

@@ -1,12 +1,10 @@
-Authentication via social networks
-==================================
+# Authentication via social networks
 
 Yii2-user provides user registration and login using social sites credentials. It
 also allows to connect multiple social networks to user account and use them to
 log in.
 
-Getting started
----------------
+## Getting started
 
 To get started you should configure `authClientCollection` application component:
 
@@ -26,8 +24,7 @@ To get started you should configure `authClientCollection` application component
 ...
 ```
 
-Available clients
------------------
+## Available clients
 
 Here is the list of clients supported by the module:
 
@@ -118,8 +115,7 @@ Here is the list of clients supported by the module:
 ],
 ```
 
-Configuration example
----------------------
+## Configuration example
 
 The following config allows to log in using 3 networks (Twitter, Facebook and Google):