Pjax.php 5.68 KB
Newer Older
Qiang Xue committed
1 2 3 4 5 6 7 8 9 10 11
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\widgets;

use Yii;
use yii\base\Widget;
12
use yii\helpers\Html;
Qiang Xue committed
13
use yii\helpers\Json;
14
use yii\web\Response;
Qiang Xue committed
15 16

/**
17 18
 * Pjax is a widget integrating the [pjax](https://github.com/defunkt/jquery-pjax) jQuery plugin.
 *
Qiang Xue committed
19 20 21 22 23
 * Pjax only deals with the content enclosed between its [[begin()]] and [[end()]] calls, called the *body content* of the widget.
 * By default, any link click or form submission (for those forms with `data-pjax` attribute) within the body content
 * will trigger an AJAX request. In responding to the AJAX request, Pjax will send the updated body content (based
 * on the AJAX request) to the client which will replace the old content with the new one. The browser's URL will then
 * be updated using pushState. The whole process requires no reloading of the layout or resources (js, css).
24
 *
Qiang Xue committed
25 26 27 28 29
 * You may configure [[linkSelector]] to specify which links should trigger pjax, and configure [[formSelector]]
 * to specify which form submission may trigger pjax.
 *
 * The following example shows how to use Pjax with the [[\yii\gridview\GridView]] widget so that the grid pagination,
 * sorting and filtering can be done via pjax:
30 31 32 33 34 35 36 37 38
 *
 * ```php
 * use yii\widgets\Pjax;
 *
 * Pjax::begin();
 * echo GridView::widget([...]);
 * Pjax::end();
 * ```
 *
Qiang Xue committed
39 40 41 42 43
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class Pjax extends Widget
{
44 45 46 47 48 49 50
	/**
	 * @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.
51
	 * Note that if the response to the pjax request is a full page, a normal request will be sent again.
52 53
	 */
	public $linkSelector;
54 55 56 57 58 59
	/**
	 * @var string the jQuery selector of the forms whose submissions should trigger pjax requests.
	 * If not set, all forms with `data-pjax` attribute within the enclosed content of Pjax will trigger pjax requests.
	 * Note that if the response to the pjax request is a full page, a normal request will be sent again.
	 */
	public $formSelector;
60 61 62 63 64 65 66 67
	/**
	 * @var boolean whether to enable push state.
	 */
	public $enablePushState = true;
	/**
	 * @var boolean whether to enable replace state.
	 */
	public $enableReplaceState = false;
68
	/**
Qiang Xue committed
69 70 71
	 * @var integer pjax timeout setting (in milliseconds). This timeout is used when making AJAX requests.
	 * Use a bigger number if your server is slow. If the server does not respond within the timeout,
	 * a full page load will be triggered.
72 73
	 */
	public $timeout = 1000;
Qiang Xue committed
74 75 76 77 78
	/**
	 * @var boolean|integer how to scroll the page when pjax response is received. If false, no page scroll will be made.
	 * Use a number if you want to scroll to a particular place.
	 */
	public $scrollTo = false;
79 80 81 82 83
	/**
	 * @var array additional options to be passed to the pjax JS plugin. Please refer to
	 * [pjax project page](https://github.com/defunkt/jquery-pjax) for available options.
	 */
	public $clientOptions;
Qiang Xue committed
84

85 86 87
	/**
	 * @inheritdoc
	 */
Qiang Xue committed
88 89
	public function init()
	{
90 91 92 93 94
		if (!isset($this->options['id'])) {
			$this->options['id'] = $this->getId();
		}

		if ($this->requiresPjax()) {
95 96
			ob_start();
			ob_implicit_flush(false);
97 98 99 100 101
			$view = $this->getView();
			$view->clear();
			$view->beginPage();
			$view->head();
			$view->beginBody();
102 103 104
			if ($view->title !== null) {
				echo Html::tag('title', Html::encode($view->title));
			}
105 106
		}
		echo Html::beginTag('div', $this->options);
Qiang Xue committed
107 108
	}

109 110 111
	/**
	 * @inheritdoc
	 */
Qiang Xue committed
112 113
	public function run()
	{
114
		echo Html::endTag('div');
115 116 117 118

		if (!$this->requiresPjax()) {
			$this->registerClientScript();
			return;
119 120
		}

121 122
		$view = $this->getView();
		$view->endBody();
Qiang Xue committed
123 124 125 126 127 128

		// Do not re-send css files as it may override the css files that were loaded after them.
		// This is a temporary fix for https://github.com/yiisoft/yii2/issues/2310
		// It should be removed once pjax supports loading only missing css files
		$view->cssFiles = null;

129 130
		$view->endPage(true);

Qiang Xue committed
131 132
		$content = ob_get_clean();

133 134 135 136 137 138 139 140
		// 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();
141

142 143 144 145
		// re-enable output buffer to capture content after this widget
		for (; $level > 0; --$level) {
			ob_start();
			ob_implicit_flush(false);
Qiang Xue committed
146 147 148
		}
	}

149 150 151 152 153 154 155 156 157
	/**
	 * @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();
	}

Qiang Xue committed
158 159 160 161 162
	/**
	 * Registers the needed JavaScript.
	 */
	public function registerClientScript()
	{
163
		$id = $this->options['id'];
164 165 166
		$this->clientOptions['push'] = $this->enablePushState;
		$this->clientOptions['replace'] = $this->enableReplaceState;
		$this->clientOptions['timeout'] = $this->timeout;
Qiang Xue committed
167
		$this->clientOptions['scrollTo'] = $this->scrollTo;
168
		$options = Json::encode($this->clientOptions);
169
		$linkSelector = Json::encode($this->linkSelector !== null ? $this->linkSelector : '#' . $id . ' a');
170
		$formSelector = Json::encode($this->formSelector !== null ? $this->formSelector : '#' . $id . ' form[data-pjax]');
Qiang Xue committed
171 172
		$view = $this->getView();
		PjaxAsset::register($view);
173
		$js = "jQuery(document).pjax($linkSelector, \"#$id\", $options);";
Qiang Xue committed
174
		$js .= "\njQuery(document).on('submit', $formSelector, function (event) {jQuery.pjax.submit(event, '#$id', $options);});";
Qiang Xue committed
175 176 177
		$view->registerJs($js);
	}
}