Timeline widget renders a Javascript Simile Timeline, version 2.3.1. The Event data for the timeline are provided by a Yii DataProvider (any object implementing yii\data\DataProviderInterface).
A demonstration of Timeline widget is here.
A little more about the Simile Timeline plus some demo's can be found here: http://www.simile-widgets.org/timeline/. Caution: the information is very sketchy, and often contradictory or plainly wrong. Simile Timeline's code is more than twelve years old and seems to be abandoned for a long time. It isn't even completed: lots and lots of more or less documented features simply are unimplemented. Nevertheless, the Simile Timeline is a great concept and the core code appears to be running quite well. Timeline widget only uses the well proven parts of Simile Timeline and doesn't touch the many loose ends.
The preferred way to install Timeline is through Composer. Either add the following to the require section of your composer.json
file:
"sjaakp/yii2-timeline": "*"
Or run:
composer require sjaakp/yii2-timeline "*"
You can manually install Timeline by downloading the source in ZIP-format.
The code to use Timeline in a View is something like this:
... other View code ...
<?php
// define Timeline
$t = Timeline::begin([
'dataProvider' => $provider,
'attributes' => [
'start' => 'startDate',
... more attributes ...
]
... more Timeline options ...
]);
// define main Band
$t->band([
'width' => '60%',
'intervalUnit' => Timeline::MONTH,
'intervalPixels' => 100
// layout not set, use default
]);
// define secundary Band
$t->band([
'width' => '40%',
'intervalUnit' => Timeline::YEAR,
'intervalPixels' => 120,
'layout' => 'overview'
]);
// complete definition
Timeline::end();
?>
... more View code ...
The method band()
is chainable, so this can also be written like:
<?php
Timeline::begin([
'dataProvider' => $provider,
'attributes' => [
'start' => 'startDate',
... more attributes ...
]
... more Timeline options ...
])->band([
'width' => '60%',
'intervalUnit' => Timeline::MONTH,
'intervalPixels' => 100
])->band([
'width' => '40%',
'intervalUnit' => Timeline::YEAR,
'intervalPixels' => 120,
'layout' => 'overview'
])->end();
?>
Timeline has the following options:
integer
height in pixelsstring
valid CSS height (f.i. in ems)false
height is not set; caution: the height MUST be set by some other means (CSS), otherwise Timeline will not appear.Timeline consists of one or more Bands. They each display the Events in a different time resolution.
A Band is defined by the Timeline method band()
.
public function band( $options, $zones = null )
$options
is an array with the following keys:
Timeline::MILLISECOND
Timeline::SECOND
Timeline::MINUTE
Timeline::HOUR
Timeline::DAY
Timeline::WEEK
Timeline::MONTH
Timeline::YEAR
Timeline::DECADE
Timeline::CENTURY
Timeline::MILLENNIUM
Optionally, each Timeline Band can have one or more Zones, parts where the horizontal resolution differs from the rest of the Band.
$zones
is null
, or an array with the following keys:
Timeline displays Events: Models or ActiveRecords characterized by a moment in time.
The Timeline::attributes property holds the translation from Model attribute names to Timeline attribute names.
A few attributes are essential for Timeline. The Timeline names are:
Events come in two types:
These are the basic Events, having just one point in time. Timeline displays them as little pin icons. Only the above attributes are required.
These have a certain duration. Timeline displays them as a piece of blue 'tape'. Apart from the above, also required is:
Duration Events also have some optional attributes, making the Event Imprecise:
The imprecise part of a Duration Event is displayed as faded blue tape.
Some of the other Event attributes are:
For the daring, there are even more Event attributes.
Timeline understands a lot of date formats (in the options and in the Event data). Every date can be provided in one of the following formats:
string
, recognized by Javascript Date, that is in RFC2822 or ISO-8601 format; among them MySQL date
and datetime
fieldsDateTime
objectarray
, recognized by Javascript Date: [ year, month, day?, hour?, minute?, second?, millisecond? ]
. Notice: month is zero-based, so January == 0, May == 4integer
: Unix time stamp (seconds since the Unix Epoch, 1-1-1970, return value of PHP time()
)
Comments