gremo/pjax-bundle

Symfony bundle that provide a lightweight yet powerfull integration with pjax jQuery plugin.

GremoPjaxBundle

, _(*1)

Symfony bundle that provide a lightweight yet powerfull integration with pjax jQuery plugin., _(*2)

New contributors are welcome!, _(*3)

Installation

Add the bundle in your composer.json file:, _(*4)

{
    "require": {
        "gremo/pjax-bundle": "~1.0"
    }
}

Then enable the bundle in the kernel:, _(*5)

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Gremo\PjaxBundle\GremoPjaxBundle(),
        // ...
    );
}

Configuration

Integration is disabled by default, see "Usage" to find out which method you need to enable., _(*6)

Short configuration:, _(*7)

# GremoPjaxBundle Configuration
gremo_pjax:
    annotations:          false # should annotations be enabled?
    controller_injection: false # should controller injection be enabled?

Full configuration and defaults:, _(*8)

# GremoPjaxBundle Configuration
gremo_pjax:
    # Annotations configuration
    annotations:
        enabled: false # should annotations be enabled?
        # Annotation defaults (see "Annotations")
        defaults:
            version: ~
            filter:  true

    # Controller injection configuration
    controller_injection:
        enabled: false # should controller injection be enabled?
        # How controller parameters should be named?
        parameters:
            X-PJAX: _isPjax
            X-PJAX-Container: _pjaxContainer

Usage

This bundle provides two different types of integration: annotations and controller injection., _(*9)

Annotations

This is the most unobtrusive way and it's fully automatic:, _(*10)

• You don't need custom template logic or controller logic
• Response HTML is automatically filtered (if filter option is true) and a <title> tag is injected in the pjax container fragment
• Response time will slightly increase due to the filtering logic, but you still save bandwidth

Note: everything that is not a successfull response or text/html is simply ignored., _(*11)

Available options: - version (string, default null): sets the pjax version (see Layout Reloading) - filter (bool, default true): whatever respose should contain only the pjax container or the full HTML, _(*12)

Note: annotations defined on a controller action inherit from class annotation and replace defaults from configuration., _(*13)

The @Pjax annotation on a controller class defines all action routes as pjax-aware:, _(*14)

<?php

use Gremo\PjaxBundle\Annotation\Pjax;

/**
 * @Pjax(version="1.2")
 */
class DefaultController extends Controller
{
    // ...
}

Instead, on a controller action, the annotation defines the route as pjax-aware:, _(*15)

<?php

use Gremo\PjaxBundle\Annotation\Pjax;

class DefaultController extends Controller
{
    /**
     * @Pjax(filter=false)
     */
    public function indexAction(Request $request)
    {
        // ...
    }
}

Controller injection

This is the most obtrusive way but potentially the most powerful one:, _(*16)

• You need to define the pjax action parameters (names are configurable)
• You need to define a custom template/controller logic for returing the full HTML or just the pjax container
• Extra logic allows to save queries and reduce the response time

<?php

class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction(Request $request, $_isPjax, $_pjaxContainer)
    {
        if ($_isPjax) {
            // Return just the pjax container HTML if pjax is enabled
            // ...
        }

        // Return the full layout
        // ...
    }
}