Documentation
Yii2-swiper
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 theActiveRecord
attribute that defines the ordering. - If
[ '<attributeName>' => function($model) ]
: Function returning value of attribute.
- If
$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. Ifnull
(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. Ifnull
(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 ...