Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Calendar Component Proposal

Proposed Component Name Zend_Calendar
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Calendar
Proposers Thomas Weidner
Revision 0.9 - 21 September 2006: Extension for Zend_Date. (wiki revision: 9)

Table of Contents

1. Overview

Zend_Calendar is an extension class for Zend_Date.
It handles calendar formats different from gregorian calendar.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Simple API
  • Same handling as Zend_Date to increase useability
  • Locale aware
  • Conversion between different Calendar Formats

4. Dependencies on Other Framework Components

5. Theory of Operation

Zend_Calendar will extend Zend_Date to work also with other calendar formats than the gregorian ones.
It will have an adaptor interface to convert between the different formats.

6. Milestones / Tasks

  • [IN PROGRESS] Acceptance of Proposal
  • Code Basic Class with Adaptor Interface
  • Code Arabic Adaptor
  • Write unit tests
  • Write Docu
  • Code Chinese Adaptor
  • Code Hebrew Adaptor
  • Code Indian Adaptor
  • Code Julian Adaptor
  • Code Persian Adaptor
  • Code Bahai Adaptor
  • Code French Adaptor

7. Class Index

  • Zend_Calendar
  • Zend_Calendar_Exception
  • Zend_Calendar_Arabic
  • Zend_Calendar_Chinese
  • Zend_Calendar_Hebrew
  • Zend_Calendar_Julian
  • Zend_Calendar_xxxxx (other calendar formats as written in milestones)

8. Use Cases

Define a arabic date, convert to gregorian

Work with Calendars

Work with Calendars

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Dec 27, 2006

    <p>Public domain JavaScript converters for numerous calendars:
    <a class="external-link" href="http://www.fourmilab.ch/documents/calendar/">http://www.fourmilab.ch/documents/calendar/</a></p>

    1. Dec 28, 2006

      <p>There are numerous online pages out there which do the same...<br />
      The question is: Is this a reason for us not to support other calendar formats with the benefit of Zend_Date ???</p>

      <p>Zend_Calendar could for example also be used for monthly calendar page creation with an iterator interface implemented.</p>

      <p>And also to mention... there are people out there in the WWW which disable javascript because of security reasons...</p>

      1. Aug 10, 2007

        <p>And you forgot the main reason: To make a easy way of different calendars on ZF. Who cares about JS converters?! I'm doing my application using ZF and I simply don't want to depend of any other solution.</p>

  2. Jan 18, 2008

    <p>There are two type of Calendars in Muslim countries:</p>
    <ul class="alternate">
    <li>Arabic Calendar (a.k.a, Islamic Calendar)</li>
    <li>Iranian Calendar (a.k.a., Persian Calendar or Jalali Calendar).</li>
    </ul>

    <p>In Iran, we use Iranian Calendar which is completely different from<br />
    Arabic calendar.</p>

    <p>For example, Jan 1 2008 equals to:</p>

    <ul class="alternate">
    <li>Iranian/Persian Calendar: Month=Dey, Day=11, Year = 1386</li>
    <li>Arabic Calendar: Month=Dhu al-Hijjah, Day=21, Year = 1428</li>
    </ul>

    <p>Now two requests:<br />
    Please add "class Zend_Calendar_Iranian {} ".<br />
    Please and correct the current Use Cases (1385 Dey 05 is an Iranian Date, not Arabic.)</p>

    <p>@see: <a class="external-link" href="http://en.wikipedia.org/wiki/Islamic_calendar">http://en.wikipedia.org/wiki/Islamic_calendar</a><br />
    @see: <a class="external-link" href="http://en.wikipedia.org/wiki/Iranian_calendar">http://en.wikipedia.org/wiki/Iranian_calendar</a></p>

    1. Jan 19, 2008

      <p>This are only example-calendars...</p>

      <p>In fact we will support</p>
      <ul>
      <li>Buddhist Calendar</li>
      <li>Chinese Calendar</li>
      <li>Coptic Calendar</li>
      <li>Ethiopic Calendar</li>
      <li>Gregorian Calendar</li>
      <li>Hebrew Calendar</li>
      <li>Islamic Calendar</li>
      <li>Islamic Civil Calendar</li>
      <li>Japanese Calendar</li>
      <li>Persian Calendar</li>
      </ul>

      <p>These are the calendar formats where we have support informations from unicode.<br />
      But as I have had no time to finish this proposal it will still take some time to be implemented.<br />
      Other things like Zend_File_Upload and improvements to Zend_Translate have more priority than this proposal. But it will not be forgotten... development will just take more time.</p>

  3. Feb 22, 2008

    <p>will this be part of the Zend_Calendar features.<br />
    "Give me date of last Sunday of year 2008" or" What's the date of second Monday for Jan 2007"</p>

    <p>is there a proposal for repeat events<br />
    What about weekly and daily views</p>

    1. Feb 23, 2008

      <p>There is actually no way to recognise "give me date of last Sunday of year 2008" or a silimar string in any known language.</p>

      <p>But you can do this already with the standard Zend_Date API in an equivalent way by simple date calculation.</p>

      <p>Related to your second and third comment:<br />
      This proposal shall make it possible to use different calendar formats than gregorian with Zend_Date. So you can use an islamic date for example.<br />
      It is not intended to create a calendar view. Here you would need a view-helper for example.<br />
      And it is not intended to be used as event handler.</p>

      <p>If you see benefit for a feature you can add a comment showing how the api could look like and what the benefit and usecase would be. I am open to all ideas when they fit.</p>

      1. Feb 27, 2008

        <p>oh i wasn't asking for a natural language interpreter, just that if i want to know whats the date of last sunday of the month jan 2008, will it be able to give me a date</p>

        <p>I'm interested in a proposal that i can use to generate full calendar. it doesn't have to generate the views, but give me something that i can use to generate the views. for eg, If i want to show week 3 to 6 in a calendar view, This proposal should give me the date and day of week 3 to 6. If i ask it show me 3 months from Febuary to march for year 2008, it should give me the date and dates for that. or give me dates for next 7 days starting Feb 26 2008.</p>

        <p>I guess I'm interested in an events calendar, not just a calendar converter to different localizations.</p>

        <p>if you plan to move this into the event type calendar, then i can give you lot of usecases and apis examples.</p>

        1. Feb 27, 2008

          <p>You should take a look at the API of Zend_Date... several things you mentioned here are already possible with just a few single lines.</p>

          <p>For example to get 3 montags from feb 2008 as mentioned with a calendarlike output you can do:</p>
          <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
          $from = new Zend_Date("February 2008", "en");
          $to = $from->addMonths(3);
          for (; $date->addDay(1); $date->isEarlier($to)) {
          print $date->getIso();
          print $date->toString(Zend_Date::WEEKDAY);
          }
          ]]></ac:plain-text-body></ac:macro>

          <p>Anyhow... this will not be a event calendar proposal... a event calendar has to handle dates, events, create views, act on user input and so on...</p>

          <p>This proposal is an extension of Zend_Date for all people which are not using gregorian calendars. Nothing more, nothing less <ac:emoticon ac:name="wink" /></p>

          1. Feb 27, 2008

            <p>mistyped... $date should of course be $from... <ac:emoticon ac:name="smile" /></p>

      2. Feb 27, 2008

        <p>How about we design this this so someone else can extend this and make it into an events calendar. that would be great.</p>

        1. Feb 27, 2008

          <p>All what is needed is already here...<br />
          Why should I create the half of something which itself if useless when so someone else can do the second half to have a working complete component ?</p>

          <p>I have really enough to do in my sparetime with existing proposals and feature enhancements. And as all contributors I am only working on things which make sense for ourself. Actually I have no use for a event component. This may change in future but not in short term. Anyone is free to create such a component for himself.</p>

          <p>But I doesn't see any pro for creating a component which needs 3 lines instead of using existing things only to save 2 lines. There is really enough other work to do...</p>

          <p>My 2 cents...</p>

          1. Feb 28, 2008

            <p>what are you going on about<br />
            I never said make one useless half and have someone else do the other half.</p>

            <p>I'm asking the design to me EXTENSIBLE. it doesn't mean you have to do a half baked job. or it has to be incomplete in any way. You can make a complete calendar (with whatever you want) but it would be designed so later on someone else can come along and extend it like Zend_calendar_Event. Design the api by keeping future improvements in mind. How is that bad is beyond me.</p>

            <p>you mentioned a very important point, about doing "what makes sense to you". So its essentially your project. I didn't know that. thanks for clarifying.</p>

            1. Feb 28, 2008

              <p>Every contributor does what makes sense to him... otherwise he would not have created a proposal.</p>

              <p>I would never create a Service proposal because I have no use of services. And if someone is in need of a event component he is free to create a proposal and add this component to ZF.</p>

              <p>Myself is not in need of such a event component... so why should I spend my sparetime for creating something which I do not see benefit for me ?<br />
              And no, ZF is not my project... you may have mentioned that it is open source and several 100s of developers are working on it. <ac:emoticon ac:name="wink" /> <br />
              Just look at the names beside the proposals.</p>

    2. Feb 23, 2008

      <p>What I forgot to mention:<br />
      This proposal is not dead. I had just other priorities like the new Zend_File_Transfer class and several other improvements and until now there were not many people wanting this integrated. So it has just low priority on my work-list. <ac:emoticon ac:name="smile" /></p>

      1. Aug 11, 2008

        <p>We hope that isn't dead <ac:emoticon ac:name="laugh" />, I really like to see this library on next 2.0 release or maybe in a mini-release <ac:emoticon ac:name="wink" />.</p>

        1. Aug 11, 2008

          <p>Wether dead nor forgotten.</p>

          <p>But there is much other work beside like the file transfer component.<br />
          It's always a matter of priority... the comunity decided for the other component <ac:emoticon ac:name="wink" /></p>

  4. Aug 18, 2008

    <p>When I read of Zend_Calendar I thought of a component capable of handling calendars, something that given some options can generate a calendar (in terms of a table with the calendar of the specified month and year).</p>

    <p>If Zend_Calendar is a mere extension of Zend_Date for handling calendars that differs from the gregorian one, why don't just enhance Zend_Date to handle different calendars instead of creating confusion with this namespace?</p>

    <p>Think of a programmer who wants to implement a calendar in his application, don't you think he will try to use the Zend_Calendar namespaces' classes to make a calendar? A Zend_Calendar that handle different calendars - in terms of calendar types - will likely confuse him.</p>

    <p>I hope I explained my point. </p>

  5. Sep 26, 2008

    <p>Hi, Thomas!</p>

    <p>In my point of view, we have two kinds of calendar.<br />
    One calendar is an object that handles events.<br />
    Of course, this calendar should be aware of locale and should have adapters to convert calendars to the right locale.<br />
    The other calendar, is the calendar related to dates.<br />
    If you want to just extend functionality from Zend_Date, you should keep it locally and create the adapters as Zend_Date_Adapter_Interface to have the conversions of the date specifically and not of the events calendar, that is a set of years, months, days, hours, minutes and seconds. Or simply creating it as Zend_Date_Calendar instead of Zend_Calendar.<br />
    Another thing is instead of having methods called toGregorian(), toIslamic(), etc, it should implement a factory method and the calendar to be converted to should be passed as parameter, like:</p>

    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    $date = '...';
    $calendar = new Zend_Date_Calendar(Zend_Date_Adapter::ARABIC, '1385 Dey 05');
    $calendar->toCalendar('islamic', $date);
    ]]></ac:plain-text-body></ac:macro>

    <p>In the Zend_Calendar, we could use all the features of the Zend_Date, but with other perspective, and also use the Zend_Date adapters to have the correct view for the calendar also. In the Zend_Calendar, I also think it would be nice to be possible to set working days, working hours, first day in the calendar, adding holidays, events, shifts and display the calendar according to all this settings.</p>

    <p>The Zend_Calendar interface should look like this:</p>

    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    interface Zend_Calendar_Interface
    {
    /**

    • Sets the first weekday of the week
      *
    • @param integer|string $weekday
      */
      public function setFirstWeekday($weekday);

    /**

    • Sets the working hours of the day
      *
    • @param string|integer $start The starting working hour
    • @param string|integer $end The ending working hour
      */
      public function setWorkingHours($start, $end);

    /**

    • Sets the working days of the week
      *
    • @param string|integer $firstDay
    • @param string|integer $lastDay
      */
      public function setWorkingDays($firstDay, $lastDay);

    /**

    • Sets the holidays present on this calendar instance
      *
    • @param array $holidays
      */
      public function setHolidays(array $holidays);

    /**

    • Sets the events present on this calendar instance
      *
    • @param array $events
      */
      public function setEvents(array $events);

    /**

    • Adds a holiday present to this calendar instance
      *
    • @param string|integer $holiday Accepts the string date or
    • the timestamp of the holiday
      */
      public function addHoliday($holiday);

    /**

    • Adds an event to this calendar instance
      *
    • @param string|integer $holiday Accepts the string date or
    • the timestamp of the event
      */
      public function addEvent($event);

    /**

    • Returns the preset first weekday of the week
      *
    • @return string
      */
      public function getFirstWeekday();

    /**

    • Returns the calendar header
      *
    • @return array
      */
      public function getHeader();

    /**

    • Gets the working hours of the day
      *
    • @return array
      */
      public function getWorkingHours();

    /**

    • Gets the working days of the week
      *
    • @return array
      */
      public function getWorkingDays();

    /**

    • Returns the holidays in the calendar
      *
    • @return array
      */
      public function getHolidays();

    /**

    • Gets a daily calendar
      *
    • @return array
      */
      public function getDay();

    /**

    • Gets a weekly calendar
      *
    • @return Zend_Calendar_Week
      */
      public function getWeek();

    /**

    • Gets a monthly calendar
      *
    • @return Zend_Calendar_Month
      */
      public function getMonth();

    /**

    • Gets a yearly calendar
      *
    • @return Zend_Calendar_Year
      */
      public function getYear();
      }
      ]]></ac:plain-text-body></ac:macro>

    <p>These set of classes below would be supposed to handle with events:<br />
    Zend_Calendar -> it wouldn't extend Zend_Date<br />
    Zend_Calendar_Year // year object is a set of months<br />
    Zend_Calendar_Month // month object is a set of weeks<br />
    Zend_Calendar_Week // week object is a set of days<br />
    Zend_Calendar_Day // day object is a set of events that will occur at a specifically time in that day<br />
    Zend_Calendar_Event<br />
    Zend_Calendar_Exception<br />
    Zend_Calendar_Adapter // In the case of this calendar, the adapter will work as view translators, translating the calendar objects to its properly locale<br />
    Zend_Calendar_Interface<br />
    Zend_Calendar_Adapter_Arabic<br />
    Zend_Calendar_Adapter_Buddhist<br />
    Zend_Calendar_Adapter_Chinese<br />
    Zend_Calendar_Adapter_Coptic<br />
    Zend_Calendar_Adapter_Ethiopic<br />
    Zend_Calendar_Adapter_Gregorian<br />
    Zend_Calendar_Adapter_Hebrew<br />
    Zend_Calendar_Adapter_Islamic<br />
    Zend_Calendar_Adapter_IslamicCivil<br />
    Zend_Calendar_Adapter_Japanese<br />
    Zend_Calendar_Adapter_Persian<br />
    Zend_Calendar_Adapter_Interface<br />
    Zend_Calendar_Adapter_Exception</p>

    <p>That's my opinion!</p>

    <p>Regards,</p>

    <p>–<br />
    Ramses Paiva<br />
    Software Consultant<br />
    SourceBits Technologies<br />
    www.sourcebits.com</p>

  6. Sep 26, 2008

    <p>Better idea:</p>

    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    class Zend_Calendar_Year extends Zend_Date_Calendar
    {}

    class Zend_Calendar_Month extends Zend_Date_Calendar
    {}

    class Zend_Calendar_Week extends Zend_Date_Calendar
    {}

    class Zend_Calendar_Day extends Zend_Date_Calendar
    {}
    ]]></ac:plain-text-body></ac:macro>

    <p>And the components would be only:<br />
    Zend_Calendar -> it wouldn't extend Zend_Date<br />
    Zend_Calendar_Year // year object is a set of months<br />
    Zend_Calendar_Month // month object is a set of weeks<br />
    Zend_Calendar_Week // week object is a set of days<br />
    Zend_Calendar_Day // day object is a set of events that will occur at a specifically time in that day<br />
    Zend_Calendar_Event<br />
    Zend_Calendar_Exception<br />
    Zend_Calendar_Interface</p>

    <p>And the adapters would have a different approach:<br />
    Zend_Calendar_Adapter -> instead of conversion of dates, it could be used as a database connection to retrieve events (and holidays, once the holidays is a specialization of events)<br />
    Zend_Calendar_Adapter_Interface<br />
    Zend_Calendar_Adapter_Exception<br />
    Zend_Calendar_Adapter_DbTable</p>

    <p>Regards,</p>

    <p>-<br />
    Ramses Paiva<br />
    Software Consultant<br />
    SourceBits Technologies<br />
    www.sourcebits.com</p>

  7. Oct 28, 2008

    <p>This proposal requires some refactoring and Thomas currently does not have the time to do it. This will be archived for resurrection later.</p>