Yii2 Dateline ¶

1. Installation
2. Using Dateline
3. Bands
4. Events
5. Dates

Widget for date-related data in Yii 2.0 PHP Framework. ¶

Dateline widget renders my JavaScript Dateline. The event data for the dateline are provided by a Yii DataProvider (any object implementing yii\data\DataProviderInterface).

A demonstration of Dateline widget is here.

See it in action at Moordatlas.nl (Dutch). At Weltliteratur is a nice example of the underlying JavaScript widget.

Installation ¶

Install Dateline with Composer. Either add the following to the require section of your composer.json file:

"sjaakp/yii2-dateline": "*"

Or run:

composer require sjaakp/yii2-dateline "*"

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

Using Dateline ¶

Yii2-dateline implements a widget of the class Dateline. It gets its data from an ActiveDataProvider, ArrayDataProvider, or other class derived from BaseDataProvider Using it is not unlike using a GridView. For instance, in the Controller you might have something like:

<?php
// ...
public function actionFoo()	{
	$dataProvider = new ActiveDataProvider([
		'query' => InterestingEvent::find(),
	    'pagination' => false
	]);
	
	return $this->render('foo', [
		'dataProvider' => $dataProvider
	]);
}
// ...
?>

An example of rendering a Dateline in the View is:

use sjaakp\dateline\Dateline;

/* ... */

<?php $dl = Dateline::begin([
    'dataProvider' => $dataProvider,
    'attributes' => [
        'id' => 'id',
        'start' => 'date1',
        'text' => 'name'
    ],
    'options' => [
		/* ... */
    ]
]);

$dl->band([
    'size' => '75%',
    'scale' => Dateline::WEEK,
    'interval'=> 90,
])
  ->band([
    'size' => '25%',
    'layout' => 'overview',
    'scale' => Dateline::YEAR,
    'interval'=> 80
]);

Dateline::end();
?>

options ¶

Dateline has the following options:

• dataProvider: the DataProvider for Dateline. Must be set.
• attributes: used to 'translate' the model attributes to Dateline attributes. It is an array with key => value pairs of:
  • {dateline attribute name} => {model attribute name}.
  • {dateline attribute name} => function($model) returning {model attribute value}.
• options: array of options for the underlying Dateline jQuery widget. More information here.
• htmlOptions (optional): array of HTML options for the Dateline container. Use this if you want to explicitly set the ID.

Bands ¶

Dateline consists of one or more Bands. They each display the Events in a different time resolution.

A Band is defined by the Dateline method band().

public function band( $options )

options ¶

$options is an array with the following keys:

• size: the part of Dateline occupied by this band, as a percentage or another CSS3 dimension,
• layout: the only sensible value is 'overview'; all other values (including none) default to 'normal', which is the layout of the main band
• scale: the time unit that divides the horizontal scale of the Band. The value should be one of the following unit constants (yes, Dateline has an astonishing range!):
  • Dateline::MILLISECOND
  • Dateline::SECOND
  • Dateline::MINUTE
  • Dateline::HOUR
  • Dateline::DAY
  • Dateline::WEEK
  • Dateline::MONTH
  • Dateline::YEAR
  • Dateline::DECADE
  • Dateline::CENTURY
  • Dateline::MILLENNIUM
• interval: the width of one division on the horizontal scale in pixels
• multiple (optional): modifies the horizontal scale division to multiples of the unit

Events ¶

Note that we're not talking about PHP or JavaScript events here!

Dateline displays Events. These are Models or ActiveRecords characterized by a moment in time.

The Dateline::attributes property holds the translation from Model attributes to Dateline attributes.

A few attributes are essential for Dateline. The Dateline names are:

• start: the point in time where the Event is situated
• text: the text (or HTML) displayed on the main Dateline

Events come in two types:

Instant Events ¶

These are the basic Events, having just one point in time. Dateline displays them as dot icons. Only the above attributes are required.

Duration Events ¶

These have a certain duration. Dateline displays them as a piece of 'tape'. Apart from the above, also required is:

• stop: the point in time where, well, the Event ends.

Duration Events also have some optional attributes, making the Event imprecise:

• post_start: optional. Indicates a degree of uncertainty in start.

• pre_stop: optional. Indicates a degree of uncertainty in stop.

The imprecise part of a Duration Event is displayed as faded tape.

Optional Event attribute ¶

• class: sets the HTML class(es) of the event in normal layout. Can be used to iconize or colorize an event. For more information, see https://github.com/sjaakp/dateline#iconizing-events

Dates ¶

Dateline 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:

• a string, recognized by JavaScript Date, that is in RFC2822 or ISO-8601 format; among them MySQL date and datetime fields
• an integer: Unix time stamp (seconds since the Unix Epoch, 1-1-1970, return value of PHP time())