From 48aa1957dedc9a03ece268cd98322c67e1a108f6 Mon Sep 17 00:00:00 2001
From: Sohel Ahmed Mesaniya <sam.wankaner@gmail.com>
Date: Sat, 20 Oct 2018 02:33:02 +0530
Subject: [PATCH] Widget docs enhancement (#16801) [skip ci]

---
 docs/guide/structure-widgets.md | 39 +++++++++++++++++++++++----------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/docs/guide/structure-widgets.md b/docs/guide/structure-widgets.md
index 39427471f1..d4324d8661 100644
--- a/docs/guide/structure-widgets.md
+++ b/docs/guide/structure-widgets.md
@@ -86,6 +86,10 @@ details.
 
 ## Creating Widgets <span id="creating-widgets"></span>
 
+Widget can be created in either of two different ways depending on the requirement.
+
+### 1: Utilizing `widget()` method
+
 To create a widget, extend from [[yii\base\Widget]] and override the [[yii\base\Widget::init()]] and/or
 [[yii\base\Widget::run()]] methods. Usually, the `init()` method should contain the code that initializes the widget
 properties, while the `run()` method should contain the code that generates the rendering result of the widget.
@@ -128,6 +132,21 @@ use app\components\HelloWidget;
 <?= HelloWidget::widget(['message' => 'Good morning']) ?>
 ```
 
+
+Sometimes, a widget may need to render a big chunk of content. While you can embed the content within the `run()`
+method, a better approach is to put it in a [view](structure-views.md) and call [[yii\base\Widget::render()]] to
+render it. For example,
+
+```php
+public function run()
+{
+    return $this->render('hello');
+}
+```
+
+### 2: Utilizing `begin()` and `end()` methods
+
+This is similar to above one with minor difference.
 Below is a variant of `HelloWidget` which takes the content enclosed within the `begin()` and `end()` calls,
 HTML-encodes it and then displays it.
 
@@ -168,22 +187,17 @@ use app\components\HelloWidget;
 ?>
 <?php HelloWidget::begin(); ?>
 
-    content that may contain <tag>'s
+    sample content that may contain one or more <strong>HTML</strong> <pre>tags</pre>
+
+    If this content grows too big, use sub views
+
+    For e.g.
+
+    <?php echo $this->render('viewfile'); // Note: here render() method is of class \yii\base\View as this part of code is within view file and not in Widget class file ?>
 
 <?php HelloWidget::end(); ?>
 ```
 
-Sometimes, a widget may need to render a big chunk of content. While you can embed the content within the `run()`
-method, a better approach is to put it in a [view](structure-views.md) and call [[yii\base\Widget::render()]] to
-render it. For example,
-
-```php
-public function run()
-{
-    return $this->render('hello');
-}
-```
-
 By default, views for a widget should be stored in files in the `WidgetPath/views` directory, where `WidgetPath`
 stands for the directory containing the widget class file. Therefore, the above example will render the view file
 `@app/components/views/hello.php`, assuming the widget class is located under `@app/components`. You may override
@@ -205,3 +219,4 @@ which can be utilized to solve the problem.
 When a widget contains view code only, it is very similar to a [view](structure-views.md). In fact, in this case,
 their only difference is that a widget is a redistributable class, while a view is just a plain PHP script
 that you would prefer to keep within your application.
+