View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{composition-setup}{composition-setup}]]></ac:plain-text-body></ac:macro>
<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Calendar
{zone-data}

{zone-data:proposer-list}
[Kyle Spraggs|mailto:theman@spiffyjr.me]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
1.0 - 26 February 2010: Initial Draft.
1.1 - 11 March 2010: Initial Ready for Review proposal.
1.2 - 24 March 2010: Reworked proposal for new rewrite of Zend_Calendar
{zone-data}

{zone-data:overview}
Zend_Calendar is a calendar component that can generate a calendar from a renderer (such as Zend View). Zend_Calendar includes the ability to add events from different sources and ships with source handlers for Arrays, Zend_Db_Table, and Doctrine Collections.
{zone-data}

{zone-data:references}
* [github Repository|http://github.com/SpiffyJr/SZend]
* [Spiffy Calendar (early mockup)|http://www.spiffyjr.me/sc-docs/]
{zone-data}

{zone-data:requirements}
* This component *will* include adapters for various event sources.
* This component *will* include support for events from arrays.
* This component *will* include support for events from Zend_Db_Table.
* This component *will* include support for events from Doctrine Collections.
* This component *may* include support for events from iCal format.
* This component *will* include support for multi-day events.
* This component *will not* include support for recurring events.
* This component *will* include adapters for rendering.
* This component *will* include support for rendering using Zend_View.
* This component *will* support caching of the Zend_Date object.
* This component *will* support merging of multiple Zend_Calendar objects.
{zone-data}

{zone-data:dependencies}
* Zend_Date
* Zend_Exception
* Zend_Locale
* Zend_View
{zone-data}

{zone-data:operation}
The component is used to render a calendar and includes the ability to add events from various sources.
{zone-data}

{zone-data:milestones}
* Milestone 1: \[DONE\] Initial Class Design
* Milestone 2: \[DONE\] Create working prototype.
* Milestone 3: Submitted to Ready for Review.
* Milestone 4: Create initial documentation.
* Milestone 5: Create unit tests.
* Milestone 6: (...)
{zone-data}

{zone-data:class-list}
* Zend_Calendar
* Zend_Calendar_Day
* Zend_Calendar_Event
* Zend_Calendar_Event_Abstract
* Zend_Calendar_Event_Array
* Zend_Calendar_Event_DoctrineCollection
* Zend_Calendar_Event_Interface
* Zend_Calendar_Event_ZendDbTable
* Zend_Calendar_Render
* Zend_Calendar_Render_Abstract
* Zend_Calendar_Render_Interface
* Zend_Calendar_Render_ZendView
{zone-data}

{zone-data:use-cases}
{deck:id=Use Cases}
{card:label=Simple Calendar}
Generating a calendar using the default ZendView renderer
{code}
$calendar = new Zend_Calendar()
echo $calendar;
{code}
{card}

{card:label=Events from an array}
This example adds two events using an array to the calendar. Event #1 is added to the calendar using a day of 1 with the current month and year. Event #2 is added using the default day of 5 with the current month and year. Event #3 is added to the current day, month, and year. The event array source always uses the 'eventDate' parameter to determine the date, then the default date and finally the current date.
{code}
$calendar = new Zend_Calendar()
$calendar->createEvent(
'array',
array(
array(
'title' => 'Event #1',
'eventDate' => array('day' => 1))
array('title' => 'Event #2')
),
array(
'day' => 5
));
$calendar->createEvent('array', array(array('title' =>; 'Event #3')));
{code}
{card}

{card:label=Events from Zend_Db_Table}
{code}
$calendar = new Zend_Calendar();
$calendar->setTable(new My_DbTable_Event());

// New event using Zend_Db_Table
$events = new Zend_Calendar_Event_Source_Table();

// Only shows ids greater than 10
$events->select()->where('id >= ?', 10);

// Set a default date in case the table doesn't have one
$events->setDate(array('day' => 10));

// Set the dateField and dateFormat of the date field from the database.
$events->setParams(
array('dateField' => 'date', 'dateFormat' => 'YYYY-MM-DD'));

// Create the event
$calendar->createEvent($events);
echo $calendar;
{code}
{card}
{deck}
{zone-data}

{zone-data:skeletons}
{deck:id=Class Skeletons}
{card:label=Zend_Calendar}
{code}
class Zend_Calendar
{
const SUNDAY = 0;
const MONDAY = 1;
const TUESDAY = 2;
const WEDNESDAY = 3;
const THURSDAY = 4;
const FRIDAY = 5;
const SATURDAY = 6;

/**
* @var int Starting day of the week.
*/
protected $_startOfWeek = self::SUNDAY;

/**
* @var Zend_Date
*/
protected $_date = null;

/**
* @var array Cached list of day names from localization list.
*/
protected $_dayNames = array();

/**
* @var array Cached list of day names from localization list.
*/
protected $_monthNames = array();

/**
* @var array Cached list of days.
*/
protected $_days = array();

/**
* @var array Cached list of weeks.
*/
protected $_weeks = array();

/**
* Calendar constructor.
* Available options:
* * day - day to set the calendar to.
* * month - month to set the calendar to.
* * year - year to set the calendar to.
* * cache - instance of Zend_Cache.
* @param array params
*/
public function __construct(array $options = array())
{}

/**
* Serialize as string
*
* Proxies to {@link render()}.
*
* @return string
*/
public function __toString()
{}

/**
* Method provided for children class initialization.
*/
public function init()
{}

/**
* Gets all days for the calendar.
*/
public function getDays()
{}

/**
* Gets (or sets if doesn't exist) a day for the calendar. Each day
* can contain an unlimited number of events. Days are not created
* until needed for efficiency.
*
* @param array|Zend_Calendar_Day Parameters to specify the day.
*/
public function day($param)
{}

/**
* Retrieve formatted date from calendar's Zend_Date object.
*
* @return mixed
*/
public function get($format)
{}

/**
* Create an event for the calendar using the specified event type.
*
* @param string|Zend_Calendar_Event_Source_* Stringed name of event source or event source object.
* @param variable data
* @param array params
* @return Zend_Calendar
*/
public function addEvent($source, $data = null, array $params = array())
{}

/**
* Render block
*
* @return string
*/
public function render($options = array(), $adapterName = Zend_Calendar_Render::DEFAULT_ADAPTER)
{}

/**
* Retrieve the calendar's Zend_Date object.
*/
public function getDate()
{}

/**
* Sets the calendars date using Zend_Date.
*
* @param mixed an array containing the date or an instance of Zend_Date.
* @return self
*/
public function setDate($date = null)
{}

/**
* End of week based on the start of week.
* @return int end of week.
*/
public function getEndOfWeek()
{}

/**
* Gets a list of years from the current year plus and minus the limit.
* This is useful for generating year selectors for the calendar view.
*
* @param int upper and lower year limit
* @param string format to return year in (default Zend_Date::YEAR)
*/
public function getYearList($limit = 5, $format = Zend_Date::YEAR)
{}

/**
* Populates calendar's day names from translation list and caches them.
*
* @param array format of the day names.
* @return array Day names of calendar.
*/
public function getDayNames(array $format = array())
{}
/**
* Populates calendar's month names from translation list and caches them.
*
* @param array format of the month names.
* @return array Month names of calendar.
*/
public function getMonthNames(array $format = array())
{}

public function getStartOfWeek()
{}

public function setStartOfWeek($start)
{}

public function weeks()
{}

/**
* Parse events and add them to the correct day.
*
* @param array Array of Zend_Calendar_Event(s).
*/
protected function _parseEvents(array $events = array())
{}

/**
* Populates calendar weeks and caches.
*/
protected function _populateWeeks()
{}
}
{code}
{card}

{card:label=Zend_Calendar_Day}
{code}
class Zend_Calendar_Day extends Zend_Date
{
/**
* @var array list of events for this day.
*/
protected $_events = array();

/**
* @return array Array of Zend_Calendar_Event_Source_* for day.
*/
public function events()
{
return $this->_events;
}

/**
* Adds an event to day.
* @param Zend_Calendar_Event
*/
public function addEvent(Zend_Calendar_Event $event)
{}

/**
* Returns true if day is the current day.
* @return boolean
*/
public function isToday()
{}
}
{code}
{card}

{card:label=Zend_Calendar_Event}
{code}
class Zend_Calendar_Event
{
protected $_data;
protected $_day = null;
protected $_month = null;
protected $_year = null;
protected $_params;

public function __construct($data = array(), $params = array(), $date = array())
{}

public function __get($name)
{}

public function getData($name = null)
{}

public function setData(array $data)
{}

public function getDay()
{}

public function setDay($day)
{}

public function getMonth()
{}

public function setMonth($month)
{}

public function getYear()
{}

public function setYear($year)
{}

public function getDate()
{}

public function setDate($date)
{}

public function setParam($name, $value)
{}

public function setParams(array $params)
{}

public function getParam($name)
{}

public function getParams()
{}
}
{code}
{card}

{card:label=Zend_Calendar_Exception}
{code}
class Zend_Calendar_Exception extends Zend_Exception
{}
{code}
{card}

{card:label=Zend_Calendar_Render}
{code}
final class Zend_Calendar_Render
{
const DEFAULT_ADAPTER = 'ZendView';

public static function factory(Zend_Calendar $calendar, array $options = array(),
$adapterName = self::DEFAULT_ADAPTER)
{}
}
{code}
{card}

{card:label=Zend_Calendar_Event_Source_Abstract}
{code}
abstract class Zend_Calendar_Event_Source_Abstract
{
/**
* @var array Array of events for source.
*/
protected $_events = array();

/**
* @var array Data for populating the events using source.
*/
protected $_data = array();

/**
* @var array Params for defining individual properties of each source.
*/
protected $_params = array();

/**
* @var int Default day for events in source.
*/
protected $_day;

/**
* @var int Default month for events in source.
*/
protected $_month;

/**
* @var int Default year for events in source.
*/
protected $_year;

/**
* Class constructor.
*
* @param array Data for source.
* @param array Optional parameters for source.
*/
public function __construct(array $data = array(), array $params = array())
{}

/**
* Used by children classes to initialize source.
*/
public function init()
{}

/**
* @return array Source data.
*/
public function getData()
{}

/**
* @param array Source data.
*/
public function setData($data)
{}

/**
* @return int Default day.
*/
public function getDay()
{}

/**
* @param int Default day.
*/
public function setDay($day)
{}

/**
* @return int Default month.
*/
public function getMonth()
{}

/**
* @param int Default month.
*/
public function setMonth($month)
{}

/**
* @return int Default year.
*/
public function getYear()
{}

/**
* @param int Default year.
*/
public function setYear($year)
{}

/**
* Set the default parameters from array.
*
* @param array Date array.
*/
public function setDate(array $date = array())
{}

/**
* Returns parameter for event source.
*
* @param string Parameter name.
* @return Parameter for given name or null if parameter doesn't exist.
*/
public function getParam($name)
{}

/**
* Returns all parameters for event source.
*
* @return array Event parameters.
*/
public function getParams()
{}

/**
* @param array Event parameters.
*/
public function setParams(array $params = array())
{}

/**
* Populates events using source, data, and parameters
* and returns them.
*
* @return array Array of Zend_Calendar_Event_Source_*.
*/
public function getEvents()
{}
}
{code}
{card}

{card:label=Zend_Calendar_Event_Source_Array}
{code}
class Zend_Calendar_Event_Source_Array extends Zend_Calendar_Event_Source_Abstract implements
Zend_Calendar_Event_Source_Interface
{
public function populateEvents()
{}
}
{code}
{card}

{card:label=Zend_Calendar_Event_Source_Doctrine}
{code}
class Zend_Calendar_Event_Source_Doctrine extends Zend_Calendar_Event_Source_Abstract implements
Zend_Calendar_Event_Source_Interface
{
/**
* @var array Results from Doctrine_Query or Doctrine_Table.
*/
protected $_results;

/**
* @var string Name of field containing the date the event is to take place.
*/
protected $_dateField = 'date';

/**
* @var string Format of the _dateField.
*/
protected $_dateFormat = Zend_Date::ISO_8601;

public function populateEvents()
{}

/**
* Initialize Doctrine source.
*/
public function init()
{}
}
{code}
{card}

{card:label=Zend_Calendar_Event_Source_Interface}
{code}
interface Zend_Calendar_Event_Source_Interface
{
/**
* Populates the events.
*/
public function populateEvents();
}
{code}
{card}

{card:label=Zend_Calendar_Event_Source_Table}
{code}
class Zend_Calendar_Event_Source_Table extends Zend_Calendar_Event_Source_Abstract implements
Zend_Calendar_Event_Source_Interface
{
protected $_select = null;

public function populateEvents()
{}

public function setTable($table)
{}

public function getTable()
{}

public function getSelect()
{}

public function setSelect($select = null)
{}
}
{code}
{card}

{card:label=Zend_Calendar_Event_Exception}
{code}
class Zend_Calendar_Event_Exception extends Zend_Exception
{}
{code}
{card}

{card:label=Zend_Calendar_Render_Abstract}
{code}
class Zend_Calendar_Render_Abstract
{
protected $_calendar = null;

public function __construct(Zend_Calendar $calendar, $options = array())
{
$this->setCalendar($calendar);
$this->init($options);
}

public function init()
{}

public function setCalendar(Zend_Calendar $calendar)
{
$this->_calendar = $calendar;
return $this;
}

public function getCalendar()
{
return $this->_calendar;
}
}
{code}
{card}

{card:label=Zend_Calendar_Render_Interface}
{code}
interface Zend_Calendar_Render_Interface
{
public function render();
}
{code}
{card}

{card:label=Zend_Calendar_Render_ZendView}
{code}
class Zend_Calendar_Render_ZendView extends Zend_Calendar_Render_Abstract implements
Zend_Calendar_Render_Interface
{
protected $_template = null;
protected $_scriptPath = null;

public function init(array $options = array())
{
if (isset($options['viewScript'])) {
$this->setTemplate($options['viewScript']);
} else {
$this->setTemplate('calendar.phtml');
}

if (isset($options['scriptPath'])) {
$this->setScriptPath($options['scriptPath']);
} else {
$this->setScriptPath(APPLICATION_PATH . '/views/layouts/');
}
}

public function setScriptPath($scriptPath)
{
$this->_scriptPath = $scriptPath;
return $this;
}

public function setTemplate($templateName)
{
$this->template = $templateName;
return $this;
}

public function getScriptPath()
{
return $this->_scriptPath;
}

public function getTemplate()
{
return $this->template;
}

public function render()
{
if (!$templateName = $this->getTemplate()) {
return '';
}

$viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
$view = clone $viewRenderer->view;
$view->clearVars();
$view->calendar = $this->getCalendar();
$view->baseUrl = Zend_Controller_Front::getInstance()->getRequest()->getBaseUrl();
$view->addScriptPath($this->getScriptPath());

return $view->render($templateName);
}
}
{code}
{card}
{deck}
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>