Fixes #706: Added `yii\widgets\Pjax` and enhanced `GridView` to work with `Pjax`…

framework/CHANGELOG.md

@@ -110,6 +110,7 @@ Yii Framework 2 Change Log
 - Enh: Added `beforeRun()` and `afterRun()` to `yii\base\Action` (qiangxue)
 - Enh: Added support for using timeZone with `yii\base\Formatter` (dizews)
 - Enh: Added `yii\web\View::POS_LOAD` (qiangxue)
+- Enh: Added `yii\web\Response::clearOutputBuffers()` (qiangxue)
 - Chg #1519: `yii\web\User::loginRequired()` now returns the `Response` object instead of exiting the application (qiangxue)
 - Chg #1586: `QueryBuilder::buildLikeCondition()` will now escape special characters and use percentage characters by default (qiangxue)
 - Chg #1610: `Html::activeCheckboxList()` and `Html::activeRadioList()` will submit an empty string if no checkbox/radio is selected (qiangxue)
@@ -147,6 +148,7 @@ Yii Framework 2 Change Log
 - Chg: Removed implementation of `Arrayable` from `yii\Object` (qiangxue)
 - Chg: Renamed `ActiveRecordInterface::createActiveRelation()` to `createRelation()` (qiangxue)
 - New #66: [Auth client library](https://github.com/yiisoft/yii2-authclient) OpenId, OAuth1, OAuth2 clients (klimov-paul)
+- New #706: Added `yii\widgets\Pjax` and enhanced `GridView` to work with `Pjax` to support AJAX-update (qiangxue)
 - New #1393: [Codeception testing framework integration](https://github.com/yiisoft/yii2-codeception) (Ragazzo)
 - New #1438: [MongoDB integration](https://github.com/yiisoft/yii2-mongodb) ActiveRecord and Query (klimov-paul)
 - New #1956: Implemented test fixture framework (qiangxue)

framework/base/Response.php

@@ -27,4 +27,17 @@ class Response extends Component
 	public function send()
 	{
 	}
+
+	/**
+	 * Removes all existing output buffers.
+	 */
+	public function clearOutputBuffers()
+	{
+		// the following manual level counting is to deal with zlib.output_compression set to On
+		for ($level = ob_get_level(); $level > 0; --$level) {
+			if (!@ob_end_clean()) {
+				ob_clean();
+			}
+		}
+	}
 }

framework/widgets/Pjax.php

@@ -9,46 +9,136 @@ namespace yii\widgets;
 
 use Yii;
 use yii\base\Widget;
+use yii\helpers\Html;
 use yii\helpers\Json;
+use yii\web\Response;
 
 /**
+ * Pjax is a widget integrating the [pjax](https://github.com/defunkt/jquery-pjax) jQuery plugin.
+ *
+ * Pjax captures the link clicks in the content enclosed between its [[begin()]] and [[end()]] calls,
+ * turns them into AJAX requests, and replaces the enclosed content with the corresponding AJAX response.
+ *
+ * The following example makes the [[yii\gridview\GridView]] widget support updating via AJAX:
+ *
+ * ```php
+ * use yii\widgets\Pjax;
+ *
+ * Pjax::begin();
+ * echo GridView::widget([...]);
+ * Pjax::end();
+ * ```
+ *
+ * Clicking the sorting and pagination links in the grid will trigger AJAX-based updating of the grid content.
+ * Moreover, if the grid view has turned on filtering, the filtering will also be performed via AJAX.
+ *
+ * By default, Pjax enables [[enablePushState|push state]], which means the browser's current URL will
+ * be updated when an AJAX request is made by Pjax.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */
 class Pjax extends Widget
 {
-	public $links = 'a';
+	/**
+	 * @var array the HTML attributes for the widget container tag.
+	 */
+	public $options = [];
+	/**
+	 * @var string the jQuery selector of the links that should trigger pjax requests.
+	 * If not set, all links within the enclosed content of Pjax will trigger pjax requests.
+	 * Note that the pjax response to a link is a full page, a normal request will be sent again.
+	 */
+	public $linkSelector;
+	/**
+	 * @var boolean whether to enable push state.
+	 */
+	public $enablePushState = true;
+	/**
+	 * @var boolean whether to enable replace state.
+	 */
+	public $enableReplaceState = false;
 
+	/**
+	 * @inheritdoc
+	 */
 	public function init()
 	{
+		if (!isset($this->options['id'])) {
+			$this->options['id'] = $this->getId();
+		}
+
 		ob_start();
 		ob_implicit_flush(false);
-		echo '<div id="' . $this->getId() . '">';
+
+		if ($this->requiresPjax()) {
+			$view = $this->getView();
+			$view->clear();
+			$view->beginPage();
+			$view->head();
+			$view->beginBody();
+		}
+		echo Html::beginTag('div', $this->options);
 	}
 
+	/**
+	 * @inheritdoc
+	 */
 	public function run()
 	{
-		echo '</div>';
+		echo Html::endTag('div');
+		if ($requiresPjax = $this->requiresPjax()) {
+			$view = $this->getView();
+			$view->endBody();
+			$view->endPage(true);
+		}
+
 		$content = ob_get_clean();
 
-		$headers = Yii::$app->getRequest()->getHeaders();
-		if ($headers->get('X-Pjax') && ($selector = $headers->get('X-PJax-Container')) === '#' . $this->getId()) {
-			// todo: send the response and terminate the application
+		if ($requiresPjax) {
+			// only need the content enclosed within this widget
+			$response = Yii::$app->getResponse();
+			$level = ob_get_level();
+			$response->clearOutputBuffers();
+			$response->setStatusCode(200);
+			$response->format = Response::FORMAT_HTML;
+			$response->content = $content;
+			$response->send();
+
+			// re-enable output buffer to capture content after this widget
+			for (; $level > 0; --$level) {
+				ob_start();
+				ob_implicit_flush(false);
+			}
 		} else {
 			$this->registerClientScript();
-			return $content;
+			echo $content;
 		}
 	}
 
 	/**
+	 * @return boolean whether the current request requires pjax response from this widget
+	 */
+	protected function requiresPjax()
+	{
+		$headers = Yii::$app->getRequest()->getHeaders();
+		return $headers->get('X-Pjax') && ($selector = $headers->get('X-Pjax-Container')) === '#' . $this->getId();
+	}
+
+	/**
 	 * Registers the needed JavaScript.
 	 */
 	public function registerClientScript()
 	{
+		$id = $this->options['id'];
+		$options = Json::encode([
+			'push' => $this->enablePushState,
+			'replace' => $this->enableReplaceState,
+		]);
+		$linkSelector = Json::encode($this->linkSelector !== null ? $this->linkSelector : '#' . $id . ' a');
 		$view = $this->getView();
 		PjaxAsset::register($view);
-		$js = 'jQuery(document).pjax("' . Json::encode($this->links) . '", "#' . $this->getId() . '");';
+		$js = "jQuery(document).pjax($linkSelector, \"#$id\", $options);";
 		$view->registerJs($js);
 	}
 }