README

Swiper widget for Yii2

This is a widget and associated behavior for ActiveRecords in the Yii 2.0 PHP Framework. It allows the user to jump to neighbouring records by means of clicking, touch swiping, or using the left and right arrow keys.

Bootstrap 4 is recommended in your site.

A demonstration of yii2-swiper is here.

Installation

The preferred way to install yii2-swiper is through Composer. Either add the following to the require section of your composer.json file:

"sjaakp/yii2-swiper": "*"

Or run:

composer require sjaakp/yii2-swiper "*"

You can manually install yii2-swiper by downloading the source in ZIP-format.

Using Yii2-swiper

Yii2-swiper consists of two classes: PrevNextBehavior and Swiper in namespace sjaakp\swiper.

PrevNextBehavior

This is a Behavior for an ActiveRecord. It supplies the owning ActiveRecord with two methods:

getPrev(): Returns an ActiveQuery to the previous record.
getNext(): Returns an ActiveQuery to the next record.

In other words, the owning ActiveRecord now has two virtual properties:

$prev: the previous record, or null if the current record is the first.
$next: the next record, or null if the current record is the last.

PrevNextBehavior has two properties:

$attribute string|array Has to be set.
- If string: Name of the ActiveRecord attribute that defines the ordering.
- If [ '<attributeName>' => function($model) ]: Function returning value of attribute.
$sort SORT_ASC|SORT_DESC Sets whether the order is incrementing or decrementing. Default: SORT_ASC (incrementing).

PrevNextBehavior can be added to an ActiveRecord like so:

<?php
use sjaakp\swiper\PrevNextBehavior;

class Event extends \yii\db\ActiveRecord
{
    // ...    
    public function behaviors()
    {
        return [
            [
                'class' => PrevNextBehavior::class,
                'attribute' => 'date',
            ]
        ];
    }
    // ...
}

Swiper

This is a Widget, rendering buttons to the previous and next page (if available). It also implements the code to handle touch swiping and keyboard input. Its $model property should be set to an instance of an ActiveRecord having PrevNextBehavior.

Swiper's other properties are:

$labelAttribute string Name of the attribute providing the label text for the buttons. Must be set.
$shortLabelAttribute null|string Name of the attribute providing the short label text for the buttons. Optional. The short label appears when the screen width is smaller than the value indicated by $breakpoint. Default: null (no short labels).
$titleAttribute null|string Name of the attribute providing the popup title text for the buttons. Optional. If null (default) the title text will be the same as the label text.
$breakpoint string The Bootstrap 4 breakpoint defining when short labels will appear. Default: 'sm'.
$url string The base URL of the button links. Default: 'view'.
$swipeId null|string The HTML-id of the element sensible to touch swiping. If null (default) it is the <body> element.
$options array HTML options for the surrounding <nav> element.
$registerLinkTags bool Whether to register link tags in the HTML header for previous and next page. Default: false, to avoid conflicts with other widgets.

In a view file, say event\view, Swiper could be employed along these lines:

<?php
    use sjaakp\swiper\Swiper
?>
<h1>...</h1>
...
<?= Swiper::widget([
    'model' => $model,
    'labelAttribute' => 'title',
    // 'url' => 'view',       // default 
    'registerLinkTags' => true
]) ?>
... other view code ...

sjaakp / yii2-swiper

Maintainers

Details