Yii2 pjax tutorial

Pjax is a jQuery plugin that allows quick website navigation by combining ajax and pushState. It works by sending a special request to the server every time a link is clicked or a form is submitted. The server sends back the content that needs to be updated, pjax replaces old content with new content and pushes the new URL to browser history, without the need to update the whole page.

Yii2 framework has a Pjax widget that helps you pjaxify your website in just one easy step.

1. Add one line in the beginning of your view.

<?php
use yii\widgets\Pjax;
?>

2. Add two lines around the content that needs partial updating.

<?php Pjax::begin(); ?>
Content that needs to be updated
<?php Pjax::end(); ?>

You can further configure the widget. Choose which links and which forms will be hadled by Pjax; whether the new URL should be pushed to browser history, replaced or left as is; the timeout after which the page will be reloaded in case there’s no response; Pjax can also scroll the page for you.

Yii2 pjax examples

Refresh

Let’s look at the simplest example first. We have some data on our page that we want to refresh by clicking a link. For simplicity’s sake we’ll use the current server time as our dynamic data.

<?php Pjax::begin(); ?>
<?= Html::a("Refresh", ['site/index'], ['class' => 'btn btn-lg btn-primary']) ?>
<h1>Current time: <?= $time ?></h1>
<?php Pjax::end(); ?>

Our action only provides the $time to the view and renders the view.

public function actionIndex()
{
    return $this->render('index', ['time' => date('H:i:s')]);
}

That’s it. Whenever the widget will detect a pjax request it will serve the required part of the content instead of the whole page.

Don’t forget to add use yii\widgets\Pjax; in your view.

Auto refresh

While we’re on topic of refreshing lets take our previous code and make it refresh the content automatically after a number of seconds. To achieve this we’ll add a couple of lines of JavaScript to our view.

<?php
$script = <<< JS
$(document).ready(function() {
    setInterval(function(){ $("#refreshButton").click(); }, 3000);
});
JS;
$this->registerJs($script);
?>

Navigation

In this example we will have several links pointing to different controller actions that will return different results. Our view will look almost the same as in the previous examples, except now it will have two links/buttons.

<?php Pjax::begin(); ?>
<?= Html::a("Show Time", ['site/time'], ['class' => 'btn btn-lg btn-primary']) ?>
<?= Html::a("Show Date", ['site/date'], ['class' => 'btn btn-lg btn-success']) ?>
<h1>It's: <?= $response ?></h1>
<?php Pjax::end(); ?>

Here are the two actions that will render the different views. It’s as simple as that.

public function actionTime()
{
    return $this->render('time-date', ['response' => date('H:i:s')]);
}
public function actionDate()
{
    return $this->render('time-date', ['response' => date('Y-M-d')]);
}

Conclusion

The Pjax widget is great for some use cases. If something goes wrong or the request will take too much time it can reload the page completely. You can still open links in new tabs or windows. It’s a great replacement for CHtml::ajaxLink from Yii 1.x. Search engines don’t have to render JavaScript to crawl websites that utilize pjax. You can customize it further using JavaScript.

It’s not very efficient because it has to send the required data alongside with HTML code. Depending on your needs, you can make a more efficient web application using a JavaScript MVC framework(e.g. AngularJS), jQuery or even plain JavaScript. All you have to do is separate the views from the data, then, with the help of Ajax, deliver the views as HTML and the data as JSON.