cvs: peardoc /en/package/datetime/calendar faq.xml intro-overview-methods.xml intro-overview.xml intro-purpose.xml

From: Date: Sat, 22 Nov 2003 19:46:16 +0000
Subject: cvs: peardoc /en/package/datetime/calendar faq.xml intro-overview-methods.xml intro-overview.xml intro-purpose.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-1968@lists.php.net to get a copy of this message
quipo Sat Nov 22 14:46:16 2003 EDT Modified files: /peardoc/en/package/datetime/calendar faq.xml intro-overview-methods.xml intro-overview.xml intro-purpose.xml Log: some fixes

Index: peardoc/en/package/datetime/calendar/faq.xml diff -u peardoc/en/package/datetime/calendar/faq.xml:1.1 peardoc/en/package/datetime/calendar/faq.xml:1.2 --- peardoc/en/package/datetime/calendar/faq.xml:1.1 Sat Nov 22 09:12:03 2003 +++ peardoc/en/package/datetime/calendar/faq.xml Sat Nov 22 14:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0"?> -<!-- $Id: faq.xml,v 1.1 2003/11/22 14:12:03 quipo Exp $ --> +<!-- $Id: faq.xml,v 1.2 2003/11/22 19:46:16 quipo Exp $ --> <refentry id="package.datetime.calendar.faq"> <refnamediv> <refname>FAQ</refname> @@ -12,10 +12,14 @@ <para> What if you want WML, SOAP, PDF, GIF, command line, etc. etc.? PEAR::Calendar can be used to generate any output format you like (see the examples for SOAP and WML). Tying it to a particular output content type will limit it's use (a problem that every public domain PHP Calendar library I've looked at suffers from). A PEAR::HTML_Calendar is likely to be developed using PEAR::Calendar. </para> + </refsect1> + <refsect1> <title>There's too many objects, classes and files. It's bloated!</title> <para> Running the examples on Sourceforge's servers (which are always overloaded), example 3.php renders in under 0.1 seconds (usually half that). The code is highly optimized and every "trick in the book" has been applied to make sure PHP only parses / executes the subset of logic you need for your specific problem. If in doubt, use <classname>Cache_Lite</classname> to cache the output HTML. </para> + </refsect1> + <refsect1> <title>You use Unix timestamps to calculate the Calendar, which limits the range of years it can generate. Can this be changed?</title> <para> All calculations are handled by a class implementing the Calendar_Engine interface. The default implemention is based on PHP's <function>date()</function> and <function>mktime()</function> functions (so Unix timestamps are required for that engine). A second engine exists which uses PEAR::Date. It's slower but overcomes the limit on the range of Unixstamps. To switch between engines use the constant <constant>CALENDAR_ENGINE</constant> e.g. @@ -30,6 +34,8 @@ </programlisting> Note that the PEAR::Date engine is based on PEAR Date version 1.3 (version 1.3.1beta is missing a required file and will not work). </para> + </refsect1> + <refsect1> <title>This examples use the English language for days and months. Can this be changed?</title> <para> PEAR::Calendar only uses base 10 numbers for calculations - the names of months and days of the week and generated as the calendar is being rendered (by you). You should only need to change PHP's locale with <function>setlocale()</function> and use the <function>strftime()</function> function e.g.; @@ -44,6 +50,8 @@ </programlisting> Note that <classname>Calendar_Decorator_Textual</classname> provides help in generating month and day of week names in a manner which is independent of the Calendar Engine you are using and can be modified with <function>setlocale()</function>. </para> + </refsect1> + <refsect1> <title>What are EmptyDays?</title> <para> PEAR::Calendar makes it easy to render calendars in tabular format (like humans are used to) such as; @@ -78,11 +86,13 @@ } ]]> </programlisting> - An empty day can still return values, the date it represents being from the previous or next month in the calendar. You may get empty days for <classname>Calendar_Month_Weekdays</classname> and <classname>Calendar_Week</classname>. Using <classname>Calendar_Week</classname>, you will only build 7 days (use <classname>Calendar_Month_Weeks</classname> to build <classname>Calendar_Week</classname> objects), so the <methodname>isFirst()</methodname> and <methodname>isLast()</methodname> methods are not applicable. + An empty day can still return values, the date it represents being from the previous or next month in the calendar. You may get empty days for <classname>Calendar_Month_Weekdays</classname> and <classname>Calendar_Week</classname>. Using <classname>Calendar_Week</classname>, you will only build 7 days (use <classname>Calendar_Month_Weeks</classname> to build <classname>Calendar_Week</classname> objects), so the <function>isFirst()</function> and <function>isLast()</function> methods are not applicable. </para> + </refsect1> + <refsect1> <title>How do I select some dates?</title> <para> - All calendar objects (except <classname>Calendar_Second</classname>, which has no "children") have the method <methodname>build()</methodname> to build the "children" of that object. For example <classname>Calendar_Year</classname>::<methodname>build()</methodname> builds <classname>Calendar_Month</classname> objects while <classname>Calendar_Hour</classname>::<methodname>build()</methodname> builds <classname>Calendar_Minute</classname> objects. You have the option of passing this method an indexed array of Calendar objects which will be used to "select" the matching built children. For example; + All calendar objects (except <classname>Calendar_Second</classname>, which has no "children") have the method <function>build()</function> to build the "children" of that object. For example <classname>Calendar_Year</classname>::<function>build()</function> builds <classname>Calendar_Month</classname> objects while <classname>Calendar_Hour</classname>::<function>build()</function> builds <classname>Calendar_Minute</classname> objects. You have the option of passing this method an indexed array of Calendar objects which will be used to "select" the matching built children. For example; <programlisting role="php"> <![CDATA[ $Month = & new Calendar_Month(2003, 10); // Oct 2003 @@ -101,15 +111,17 @@ } ]]> </programlisting> - <emphasis>Note:</emphasis> date objects you pass to a <methodname>build()</methodname> method replace the corresponding built date objects, allowing you to do things like attach your own subclass of <classname>Calendar_Decorator</classname> to them, then access the decorating functionality inside the loop which renders the calendar. You might display the contents from an "events database table" using this approach. + <emphasis>Note:</emphasis> date objects you pass to a <function>build()</function> method replace the corresponding built date objects, allowing you to do things like attach your own subclass of <classname>Calendar_Decorator</classname> to them, then access the decorating functionality inside the loop which renders the calendar. You might display the contents from an "events database table" using this approach. </para> + </refsect1> + <refsect1> <title>Why do I have to call build() explicitly. Why can't children be built automatically?</title> <para> - First and foremost, for performance. Building the children has a performance cost and you won't always need to have the children, so it should be called explicitly, otherwise you might have $Year->build(), expecting to get just months but behind the scenes, months built days, which built hours, which build minutes etc. Also calling <methodname>build()</methodname> yourself give you a chance to "select" some of the children. + First and foremost, for performance. Building the children has a performance cost and you won't always need to have the children, so it should be called explicitly, otherwise you might have $Year->build(), expecting to get just months but behind the scenes, months built days, which built hours, which build minutes etc. Also calling <function>build()</function> yourself give you a chance to "select" some of the children. </para> <title>How do I validate a date?</title> <para> - Validity is determined by the Caalendar_Engine being used as well as the time the date object you're working with represents (e.g. $Month = &amp; new Month(2003, 2, 29); is invalid, because Feb 2003 was not a leap year). For quick validation, you can call the method <methodname>isValid()</methodname> on any date object, which will return FALSE if there's a problem. For more information of more detailed validation, you can call the method <methodname>getValidator()</methodname> on any date object, which returns an instance of the class <classname>Calendar_Validator</classname>. For example; + Validity is determined by the Caalendar_Engine being used as well as the time the date object you're working with represents (e.g. $Month = &amp; new Month(2003, 2, 29); is invalid, because Feb 2003 was not a leap year). For quick validation, you can call the method <function>isValid()</function> on any date object, which will return FALSE if there's a problem. For more information of more detailed validation, you can call the method <function>getValidator()</function> on any date object, which returns an instance of the class <classname>Calendar_Validator</classname>. For example; <programlisting role="php"> <![CDATA[ $Month = & new Month(2003, 2, 29); // 29th Feb 2003 (?!?) @@ -121,15 +133,17 @@ } ]]> </programlisting> - You can also begin validation by calling <methodname>getValidator()</methodname> then either <methodname>isValidYear()</methodname>, <methodname>isValidMonth()</methodname>, <methodname>isValidDay()</methodname>, <methodname>isValidHour()</methodname>, <methodname>isValidMinute()</methodname> and <methodname>isValidSecond()</methodname> (or just <methodname>isValid()</methodname> which calls all of the isValidxxx methods). + You can also begin validation by calling <function>getValidator()</function> then either <function>isValidYear()</function>, <function>isValidMonth()</function>, <function>isValidDay()</function>, <function>isValidHour()</function>, <function>isValidMinute()</function> and <function>isValidSecond()</function> (or just <function>isValid()</function> which calls all of the isValidxxx methods). </para> + </refsect1> + <refsect1> <title>Can I adjust invalid dates?</title> <para> - If you're allowing end users to navigate your calendar via the URL, were they to modify the URL to something like calendar.php?year=2003&amp;month=13, instead of throwing a validation error at them, you could call the <classname>Calendar</classname>::<methodname>adjust()</methodname> method on the calendar object you create with that URL. You should then end up with January 2004 (in this example). This behaviour is possible thanks to <function>mktime()</function> for the Unix Timestamp engine, while being built into the PEAR Date engine for you. + If you're allowing end users to navigate your calendar via the URL, were they to modify the URL to something like calendar.php?year=2003&amp;month=13, instead of throwing a validation error at them, you could call the <classname>Calendar</classname>::<function>adjust()</function> method on the calendar object you create with that URL. You should then end up with January 2004 (in this example). This behaviour is possible thanks to <function>mktime()</function> for the Unix Timestamp engine, while being built into the PEAR Date engine for you. </para> <title>After calling build(), I just want to get a single child date object with looping through the lot. How?</title> <para> - The method <methodname>fetchAll()</methodname> can be called on any date object to get an indexed array of all the children which have been built, allowing you to reference them directly. Be careful with the first index of this array - in some cases it will be [1] not [0], depending on the type of date object built. For example; + The method <function>fetchAll()</function> can be called on any date object to get an indexed array of all the children which have been built, allowing you to reference them directly. Be careful with the first index of this array - in some cases it will be [1] not [0], depending on the type of date object built. For example; <programlisting role="php"> <![CDATA[ $Month = & new Calendar_Month(2003, 10); @@ -148,8 +162,10 @@ The following classes are always built to have the first index as 1: <classname>Calendar_Month</classname>, <classname>Calendar_Month_Weekdays</classname>, <classname>Calendar_Month_Weeks</classname>, <classname>Calendar_Week</classname> and <classname>Calendar_Day</classname> The following classes are always built to have the first index as 0: <classname>Calendar_Hour</classname>, <classname>Calendar_Minute</classname> and <classname>Calendar_Second</classname> - Note also the method <methodname>size()</methodname> can be called on any date object, after <methodname>build()</methodname> has been called, to get the number of children. + Note also the method <function>size()</function> can be called on any date object, after <function>build()</function> has been called, to get the number of children. </para> + </refsect1> + <refsect1> <title>What does a week actually represent in PEAR::Calendar?</title> <para> Weeks are "pseudo" dates. They're useful for formatting the user interface for end users. Weeks are instantiated with a year, a month and a day of the month. You can then have the week tell you its timestamp (which will be the same as the timestamp for the first day in the week), its numeric position within the <emphasis>tabular</emphasis> month (see Empty Days above), its numeric position within the year (this is an ISO-8601 week number of year, weeks starting on Monday) or an array containing the numeric year, month and the first day of the week (as a number within the month). For example; @@ -171,10 +187,14 @@ ]]> </programlisting> </para> + </refsect1> + <refsect1> <title>How do I get a Calendar_Year to build Calendar_Month_Weekdays or Calendar_Month_Weeks, instead of the default Calendar_Month objects?</title> <para> When working with a <classname>Calendar_Year</classname>, the constants <constant>CALENDAR_MONTH_STATE</constant> controls what type of month object is built. You can define <constant>CALENDAR_MONTH_STATE</constant> to <constant>CALENDAR_USE_MONTH_WEEKDAYS</constant> or <constant>CALENDAR_USE_MONTH_WEEKS</constant> for the Calendar_Month_Weekdays and <classname>Calendar_Month_Week</classname> classes, respectively. </para> + </refsect1> + <refsect1> <title>You use Monday as the start of the week. Can I change that?</title> <para> Yes. For the classes which are concerned with the notion of a "week", you can can pass a value which defines the first day of the week. For the default timestamp based Calendar engine, this is a number from 0 to 6, 0 being Sunday through to 6 being Saturday. Index: peardoc/en/package/datetime/calendar/intro-overview-methods.xml diff -u peardoc/en/package/datetime/calendar/intro-overview-methods.xml:1.1 peardoc/en/package/datetime/calendar/intro-overview-methods.xml:1.2 --- peardoc/en/package/datetime/calendar/intro-overview-methods.xml:1.1 Sat Nov 22 09:12:03 2003 +++ peardoc/en/package/datetime/calendar/intro-overview-methods.xml Sat Nov 22 14:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0"?> -<!-- $Id: intro-overview-methods.xml,v 1.1 2003/11/22 14:12:03 quipo Exp $ --> +<!-- $Id: intro-overview-methods.xml,v 1.2 2003/11/22 19:46:16 quipo Exp $ --> <refentry id="package.datetime.calendar.intro-overview-methods"> <refnamediv> <refname>Method Overview</refname> @@ -31,8 +31,9 @@ </programlisting> Note that the tabular classes, <classname>Calendar_Month_Weekdays</classname> and <classname>Calendar_Month_Weeks</classname> both take an optional third argument (integer) which specifies the first day of the week and adjust tabular display (normally it defaults to Monday (1) - pass the integer value 0 to switch to Sunday as the first day, for example). <classname>Calendar_Week</classname> accepts the first day argument as the fourth to it's constructor. </para> - - <subtitle>Location Methods</subtitle> + </refsect1> + <refsect1> + <title>Location Methods</title> <para> All date and tabular date classes share the methods defined in the abstract base class <classname>Calendar</classname>. Among these are methods for an object of any of these classes to identify itself (what's it's date is) and the previous and next dates. For example; <programlisting role="php"> @@ -49,7 +50,7 @@ echo $Day->nextMonth(); // Displays 11 ]]> </programlisting> - Notice that from the <varname>$Day</varname> I can find out not just about the day itself but also the month (or year/hour/minute/second). Notice also how <methodname>prevDay()</methodname> returned 30, taking care of working out that the previous day is in September for you. There are <methodname>this***()</methodname>, <methodname>prev***()</methodname> and <methodname>next***()</methodname> methods for years, months, days, hours, minutes and seconds. + Notice that from the <varname>$Day</varname> I can find out not just about the day itself but also the month (or year/hour/minute/second). Notice also how <function>prevDay()</function> returned 30, taking care of working out that the previous day is in September for you. There are <function>this***()</function>, <function>prev***()</function> and <function>next***()</function> methods for years, months, days, hours, minutes and seconds. </para> <para> Calling any of these methods and passing the value TRUE will result in a timestamp being returned (the type of timestamp depends on the Calendar Engine you are using - see the FAQ), for example; @@ -66,25 +67,30 @@ echo $Second->thisSecond(TRUE); // Displays 1067081564 ]]> </programlisting> - Notice how the timestamp return increases, depending on the method that was called to obtain it. The first, obtained from <methodname>thisYear(TRUE)</methodname> is a timestamp for the beginning of the year 2003 (1st January 2003 in fact) while the third from <methodname>thisDay(TRUE)</methodname> is a timestamp for 25th October 2003. + Notice how the timestamp return increases, depending on the method that was called to obtain it. The first, obtained from <function>thisYear(TRUE)</function> is a timestamp for the beginning of the year 2003 (1st January 2003 in fact) while the third from <function>thisDay(TRUE)</function> is a timestamp for 25th October 2003. </para> <para> <warning> - The <methodname>prev***()</methodname> and <methodname>next***()</methodname> methods return values calculated relative to the <emphasis>current</emphasis> Calendar object you are working with. In the above example, if you wanted the day <emphasis>and</emphasis> month of the next day (which should be 2nd October 2003), calling <methodname>nextDay()</methodname> then <methodname>nextMonth()</methodname> would give you the 2nd of <emphasis>November</emphasis> not October. Instead you should call <methodname>nextDay()</methodname> passing it the argument TRUE, to get back a timestamp from which the next day can be obtained. Be aware of the <classname>Calendar_Decorator_Uri</classname> which is designed to help build URLs for next / prev links. + <simpara> + The <function>prev***()</function> and <function>next***()</function> methods return values calculated relative to the <emphasis>current</emphasis> Calendar object you are working with. In the above example, if you wanted the day <emphasis>and</emphasis> month of the next day (which should be 2nd October 2003), calling <function>nextDay()</function> then <function>nextMonth()</function> would give you the 2nd of <emphasis>November</emphasis> not October. + Instead you should call <function>nextDay()</function> passing it the argument TRUE, to get back a timestamp from which the next day can be obtained. Be aware of the <classname>Calendar_Decorator_Uri</classname> which is designed to help build URLs for next / prev links. + </simpara> </warning> </para> <para> - There are also the methods <methodname>thisWeek()</methodname>, <methodname>prevWeek()</methodname> and <methodname>nextWeek()</methodname> which only become available if you're using an instance of <classname>Calendar_Week</classname>. The returned value format can be chosen among 'timestamp', 'n_in_month', 'n_in_year' or 'array'. Be careful - if you select 'n_in_month', it will return NULL if it reaches the beginning or end of a month. + There are also the methods <function>thisWeek()</function>, <function>prevWeek()</function> and <function>nextWeek()</function> which only become available if you're using an instance of <classname>Calendar_Week</classname>. The returned value format can be chosen among 'timestamp', 'n_in_month', 'n_in_year' or 'array'. Be careful - if you select 'n_in_month', it will return NULL if it reaches the beginning or end of a month. </para> <para> - Finally all Calendar objects provide the methods <methodname>getTimeStamp()</methodname> and <methodname>setTimeStamp()</methodname>. The former returns a timestamp in the format used by the calendar engine you are working with (i.e. Unix Timestamp if it's the default UnixTs engine or of format YYYY-MM-DD HH:MM:SS). The later excepts a timestamp which is used to replace the values the Calendar object was constructed with. + Finally all Calendar objects provide the methods <function>getTimeStamp()</function> and <function>setTimeStamp()</function>. The former returns a timestamp in the format used by the calendar engine you are working with (i.e. Unix Timestamp if it's the default UnixTs engine or of format YYYY-MM-DD HH:MM:SS). The later excepts a timestamp which is used to replace the values the Calendar object was constructed with. </para> - <subtitle>Building and Fetching</subtitle> + </refsect1> + <refsect1> + <title>Building and Fetching</title> <para> - Every date and tabular date class has a <methodname>build()</methodname> method which is used to generate the children of that date object. For example <classname>Calendar_Month</classname> builds <classname>Calendar_Day</classname> objects, the days being <emphasis>"children"</emphasis> of the month. + Every date and tabular date class has a <function>build()</function> method which is used to generate the children of that date object. For example <classname>Calendar_Month</classname> builds <classname>Calendar_Day</classname> objects, the days being <emphasis>"children"</emphasis> of the month. </para> <para> - Once <methodname>build()</methodname> is called, the children can be fetched from the date object using the simple <methodname>fetch()</methodname> iterator, for example; + Once <function>build()</function> is called, the children can be fetched from the date object using the simple <function>fetch()</function> iterator, for example; <programlisting role="php"> <![CDATA[ $Month = new Calendar_Month(2003, 10); @@ -100,15 +106,17 @@ echo $i; // Displays 31 (31 days in October) ]]> </programlisting> - The <methodname>fetch()</methodname> method returns one child at a time, in ascending date order, and returns FALSE when there are no more children. It also automatically resets the internal collection of children, meaning you can loop over them as many times as you like. + The <function>fetch()</function> method returns one child at a time, in ascending date order, and returns FALSE when there are no more children. It also automatically resets the internal collection of children, meaning you can loop over them as many times as you like. </para> <para> - If you don't like the iterator, and wish to use your own, you can simply extract the children with the <methodname>fetchAll()</methodname> method (returns an indexed array of child date objects) and check the number you got back with <methodname>size()</methodname>. Be careful the index of the array you get back from <methodname>fetchAll()</methodname>. For <classname>Calendar_Year</classname>, <classname>Calendar_Month</classname>, <classname>Calendar_Month_Weekdays</classname>, <classname>Calendar_Month_Weeks</classname> and <classname>Calendar_Week</classname>, the first index of the array is 1 while for <classname>Calendar_Day</classname>, <classname>Calendar_Hour</classname>, <classname>Calendar_Minute</classname> and <classname>Calendar_Second</classname> the index begins with 0. Why? Consider 2003-1-1 00:00:00 ... + If you don't like the iterator, and wish to use your own, you can simply extract the children with the <function>fetchAll()</function> method (returns an indexed array of child date objects) and check the number you got back with <function>size()</function>. Be careful the index of the array you get back from <function>fetchAll()</function>. For <classname>Calendar_Year</classname>, <classname>Calendar_Month</classname>, <classname>Calendar_Month_Weekdays</classname>, <classname>Calendar_Month_Weeks</classname> and <classname>Calendar_Week</classname>, the first index of the array is 1 while for <classname>Calendar_Day</classname>, <classname>Calendar_Hour</classname>, <classname>Calendar_Minute</classname> and <classname>Calendar_Second</classname> the index begins with 0. Why? Consider 2003-1-1 00:00:00 ... </para> <para>Note: Calendar_Second::build() doesn't do anything - it has no children.</para> - <subtitle>Selecting Children</subtitle> + </refsect1> + <refsect1> + <title>Selecting Children</title> <para> - To help with rendering the calendar, the <methodname>build()</methodname> methods accept an index array of date objects which is compares with the children it is building. If it finds that an object that was passed to it matches a child, it set's the childs state to selected, meaning the <methodname>isSelected()</methodname> method (available on any date or tabular date objects) returns TRUE. For example; + To help with rendering the calendar, the <function>build()</function> methods accept an index array of date objects which is compares with the children it is building. If it finds that an object that was passed to it matches a child, it set's the childs state to selected, meaning the <function>isSelected()</function> method (available on any date or tabular date objects) returns TRUE. For example; <programlisting role="php"> <![CDATA[ $Month = new Calendar_Month(2003, 10); @@ -129,21 +137,23 @@ In the above example, only 15th October 2003 and 23rd October 2003 are displayed. </para> <para> - The objects you pass to <methodname>build()</methodname> which match children that are being built <emphasis>replace</emphasis> the child (i.e. if there was a match, you get your object back). This allows you to "inject" your own objects into the loop, best accomplished by extending <classname>Calendar_Decorator</classname>. + The objects you pass to <function>build()</function> which match children that are being built <emphasis>replace</emphasis> the child (i.e. if there was a match, you get your object back). This allows you to "inject" your own objects into the loop, best accomplished by extending <classname>Calendar_Decorator</classname>. </para> <para> - Note: the <classname>Calendar_Year</classname>::<methodname>build()</methodname> method takes a second argument to specify the first day of the week (see above discussion on Constructors). + Note: the <classname>Calendar_Year</classname>::<function>build()</function> method takes a second argument to specify the first day of the week (see above discussion on Constructors). </para> <subtitle>Tabular Days</subtitle> <para> - The <classname>Calendar_Day</classname> class has three unique methods, which don't appear elsewhere, and are used purely for building tabular calendars. The <methodname>isEmpty()</methodname> is used to determine whether the day is an empty day or not (see FAQ for explaination of empty days). The methods <methodname>isFirst()</methodname> and <methodname>isLast()</methodname> are used to mark the beginning and and of a week. + The <classname>Calendar_Day</classname> class has three unique methods, which don't appear elsewhere, and are used purely for building tabular calendars. The <function>isEmpty()</function> is used to determine whether the day is an empty day or not (see FAQ for explaination of empty days). The methods <function>isFirst()</function> and <function>isLast()</function> are used to mark the beginning and and of a week. </para> <para> - Whether you need to use these methods depends on which class was used to build the day objects. If the day was built with <classname>Calendar_Month_Weekdays</classname>, all three of these methods are applicable (you may have empty days and <classname>Calendar_Month_Weekdays</classname> builts a complete month but delimits the beginning and end of each week so you can find it with <methodname>isFirst()</methodname> and <methodname>isLast()</methodname>). If the day was built with <classname>Calendar_Week</classname>, only the <methodname>isEmpty()</methodname> method is applicable (the first or last week in a month may contain empty days). For day objects built in any other manner, <methodname>isEmpty()</methodname>, <methodname>isFirst()</methodname> and <methodname>isLast()</methodname> are meaningless. + Whether you need to use these methods depends on which class was used to build the day objects. If the day was built with <classname>Calendar_Month_Weekdays</classname>, all three of these methods are applicable (you may have empty days and <classname>Calendar_Month_Weekdays</classname> builts a complete month but delimits the beginning and end of each week so you can find it with <function>isFirst()</function> and <function>isLast()</function>). If the day was built with <classname>Calendar_Week</classname>, only the <function>isEmpty()</function> method is applicable (the first or last week in a month may contain empty days). For day objects built in any other manner, <function>isEmpty()</function>, <function>isFirst()</function> and <function>isLast()</function> are meaningless. </para> - <subtitle>Validation</subtitle> + </refsect1> + <refsect1> + <title>Validation</title> <para> - All date objects and tabular objects (except weeks) are capable of validating themselves. By default they accept whatever arguments they are given on construction but you can validate the date with the <methodname>isValid()</methodname> method, for example; + All date objects and tabular objects (except weeks) are capable of validating themselves. By default they accept whatever arguments they are given on construction but you can validate the date with the <function>isValid()</function> method, for example; <programlisting role="php"> <![CDATA[ $Day = new Calendar_Day(2003, 10, 32); @@ -153,7 +163,7 @@ } ]]> </programlisting> - For more fine grained validation, you can first call the <methodname>getValidator()</methodname> method, to return an instance of <classname>Calendar_Validator</classname> then list the validation errors; + For more fine grained validation, you can first call the <function>getValidator()</function> method, to return an instance of <classname>Calendar_Validator</classname> then list the validation errors; <programlisting role="php"> <![CDATA[ $Day = new Calendar_Day(2003, 10, 32); @@ -180,7 +190,7 @@ ]]> </programlisting> </para> - <para>Note that rather than validating dates, you may prefer to automatically adjust them with the <methodname>adjust()</methodname> method, for example; + <para>Note that rather than validating dates, you may prefer to automatically adjust them with the <function>adjust()</function> method, for example; <programlisting role="php"> <![CDATA[ $Day = new Calendar_Day(2003, 10, 32); Index: peardoc/en/package/datetime/calendar/intro-overview.xml diff -u peardoc/en/package/datetime/calendar/intro-overview.xml:1.1 peardoc/en/package/datetime/calendar/intro-overview.xml:1.2 --- peardoc/en/package/datetime/calendar/intro-overview.xml:1.1 Sat Nov 22 09:12:03 2003 +++ peardoc/en/package/datetime/calendar/intro-overview.xml Sat Nov 22 14:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0"?> -<!-- $Id: intro-overview.xml,v 1.1 2003/11/22 14:12:03 quipo Exp $ --> +<!-- $Id: intro-overview.xml,v 1.2 2003/11/22 19:46:16 quipo Exp $ --> <refentry id="package.datetime.calendar.intro-overview"> <refnamediv> <refname>Package Overview</refname> @@ -10,8 +10,12 @@ <refsect1> <title>Package Overview</title> <para> - When working with PEAR::Calendar, there are a total of 12 (public) classes available for you to use, depending on the particular problem you are trying to solve. They break down like; - <subtitle>Date Classes</subtitle> + When working with PEAR::Calendar, there are a total of 12 (public) classes available for you to use, depending on the particular problem you are trying to solve. + They can be grouped in date classes, tabular date classes, validation classes and decorators. + </para> + </refsect1> + <refsect1> + <title>Date Classes</title> <para>Providing representations of all basic human date units. All are subclasses of <classname>Calendar</classname> so provide the methods defined there.</para> <para> <itemizedlist> @@ -47,12 +51,14 @@ </listitem> </itemizedlist> </para> - <subtitle>Tabular Date Classes</subtitle> + </refsect1> + <refsect1 id="package.datetime.calendar.intro-overview.tabular"> + <title>Tabular Date Classes</title> <para>Designed for building calendars in tabular format. All are subclasses of <classname>Calendar</classname> so provide the methods defined there.</para> <para> <itemizedlist> <listitem> - <para><classname>Calendar_Month_Weekdays</classname> - builds <classname>Calendar_Day</classname> objects setting the <methodname>isFirst()</methodname>, <methodname>isLast()</methodname> and <methodname>isEmpty()</methodname> states, to display a month in tabular form. + <para><classname>Calendar_Month_Weekdays</classname> - builds <classname>Calendar_Day</classname> objects setting the <function>isFirst()</function>, <function>isLast()</function> and <function>isEmpty()</function> states, to display a month in tabular form. </para> <para>Include with <programlisting role="php"><![CDATA[ require_once 'Calendar/Month/Weekdays.php'; ]]></programlisting>.</para> </listitem> @@ -62,32 +68,36 @@ <para>Include with <programlisting role="php"><![CDATA[ require_once 'Calendar/Month/Weeks.php'; ]]></programlisting>.</para> </listitem> <listitem> - <para><classname>Calendar_Week</classname> - builds <classname>Calendar_Day</classname> objects, setting the <methodname>isEmpty()</methodname> state if necessary and representing a tabular week in a month (i.e. you get 7 days from it). + <para><classname>Calendar_Week</classname> - builds <classname>Calendar_Day</classname> objects, setting the <function>isEmpty()</function> state if necessary and representing a tabular week in a month (i.e. you get 7 days from it). </para> <para>Include with <programlisting role="php"><![CDATA[ require_once 'Calendar/Week.php'; ]]></programlisting>.</para> </listitem> <listitem> - <para><classname>Calendar_Week</classname> - builds <classname>Calendar_Day</classname> objects, setting the <methodname>isEmpty()</methodname> state if necessary and representing a tabular week in a month (i.e. you get 7 days from it). + <para><classname>Calendar_Week</classname> - builds <classname>Calendar_Day</classname> objects, setting the <function>isEmpty()</function> state if necessary and representing a tabular week in a month (i.e. you get 7 days from it). </para> <para>Include with <programlisting role="php"><![CDATA[ require_once 'Calendar/Week.php'; ]]></programlisting>.</para> </listitem> </itemizedlist> </para> - <subtitle>Validation Classes</subtitle> - <para>Used to validate dates. <classname>Calendar</classname> provides the methods <methodname>isValid()</methodname> to perform a simple check on any date and <methodname>getValidator()</methodname> to return an instance of <classname>Calendar_Validator</classname> for fine grained validation.</para> + </refsect1> + <refsect1 id="package.datetime.calendar.intro-overview.validation"> + <title>Validation Classes</title> + <para>Used to validate dates. <classname>Calendar</classname> provides the methods <function>isValid()</function> to perform a simple check on any date and <function>getValidator()</function> to return an instance of <classname>Calendar_Validator</classname> for fine grained validation.</para> <para> <itemizedlist> <listitem> - <para><classname>Calendar_Validator</classname> - is not instantiated by your code directly (you need need specifically include / create it) but instead returned from the <classname>Calendar</classname>::<methodname>getValidator()</methodname> method you can call on any subclass of <classname>Calendar</classname>. It is used to provide fine grained validation of a date to find out exactly what's wrong with it (for simple validation just call <methodname>isValid()</methodname> on any Date object or Tabular Date object, to know if it was created with valid values. + <para><classname>Calendar_Validator</classname> - is not instantiated by your code directly (you need need specifically include / create it) but instead returned from the <classname>Calendar</classname>::<function>getValidator()</function> method you can call on any subclass of <classname>Calendar</classname>. It is used to provide fine grained validation of a date to find out exactly what's wrong with it (for simple validation just call <function>isValid()</function> on any Date object or Tabular Date object, to know if it was created with valid values. </para> </listitem> <listitem> - <para><classname>Calendar_Validation_Error</classname> - represents a validation error, providing methods to determine what went wrong. Available methods are <methodname>getUnit()</methodname> (e.g. returns Year or Month), <methodname>getValue()</methodname> (the value it failed with), <methodname>getMessage()</methodname> (the validation error message) and <methodname>toString()</methodname> which returns a combination of all the three preceding methods. The default validation error messages are in English but stored in the constants <constant>CALENDAR_VALUE_TOOSMALL</constant> and <constant>CALENDAR_VALUE_TOOLARGE</constant> which you can redefine in your code. + <para><classname>Calendar_Validation_Error</classname> - represents a validation error, providing methods to determine what went wrong. Available methods are <function>getUnit()</function> (e.g. returns Year or Month), <function>getValue()</function> (the value it failed with), <function>getMessage()</function> (the validation error message) and <function>toString()</function> which returns a combination of all the three preceding methods. The default validation error messages are in English but stored in the constants <constant>CALENDAR_VALUE_TOOSMALL</constant> and <constant>CALENDAR_VALUE_TOOLARGE</constant> which you can redefine in your code. </para> </listitem> </itemizedlist> </para> - <subtitle>Decorators</subtitle> + </refsect1> + <refsect1 id="package.datetime.calendar.intro-overview.decorators"> + <title>Decorators</title> <para>Provide a mechanism to add functionality to the main calendar objects (the subclasses of <classname>Calendar</classname>) without needing to directly extend them (and risk overwriting fields accidentally). When you create a decorator, you pass it's constructor an instance of an existing calendar object. You can then make calls to the decorator in exactly the same way as you make calls to the original calendar object. This allows you to "overwrite" calendar methods, add new methods or even apply multiple decorators to the same calendar object. Decorators a typically either "injected" (via selection or the <classname>Calendar_Decorator_Wrapper</classname> decorator) into the loop where the calendar is rendered and / or to alter the output content (e.g. convert a numeric month into a textual month: 1 => January).</para> <para> PEAR::Calendar provides some decorator implementations for you, to help with common tasks. These are not designed to suit everyone and hence are provided as optional code for you to use as needed (avoiding the performance cost associated with parsing code you're not using). @@ -109,13 +119,13 @@ // Some method I've added function getDaysToChristmas() { - $today = parent::thisDay(TRUE); - $Christmas = new Calendar_Day(date('Y'),12,25); + $today = parent::thisDay(true); + $Christmas = new Calendar_Day(date('Y'), 12, 25); $xmasday = $Christmas->thisDay(TRUE); $diff = $xmasday - $today; - if ( $diff < 0 ) { - $NextChristmas = new Calendar_Day($Christmas->nextYear(),12,25); - $nextxmasday = $NextChristmas->thisDay(TRUE); + if ($diff < 0) { + $NextChristmas = new Calendar_Day($Christmas->nextYear(), 12, 25); + $nextxmasday = $NextChristmas->thisDay(true); $diff = $today - $nextxmasday; } return ($diff / 86400); @@ -136,13 +146,12 @@ <para>Include with <programlisting role="php"><![CDATA[ require_once 'Calendar/Decorator/Textual.php'; ]]></programlisting>.</para> </listitem> <listitem> - <para><classname>Calendar_Decorator_Wrapper</classname> - is intended to help you add decorators to the children of the calendar object you are working with. It will wrap the children in the decorator you specify at the point <methodname>fetch()</methodname> or <methodname>fetchAll()</methodname> is called, after a build <methodname>build()</methodname> call. + <para><classname>Calendar_Decorator_Wrapper</classname> - is intended to help you add decorators to the children of the calendar object you are working with. It will wrap the children in the decorator you specify at the point <function>fetch()</function> or <function>fetchAll()</function> is called, after a build <function>build()</function> call. </para> <para>Include with <programlisting role="php"><![CDATA[ require_once 'Calendar/Decorator/Wrapper.php'; ]]></programlisting>.</para> </listitem> </itemizedlist> </para> - </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Index: peardoc/en/package/datetime/calendar/intro-purpose.xml diff -u peardoc/en/package/datetime/calendar/intro-purpose.xml:1.1 peardoc/en/package/datetime/calendar/intro-purpose.xml:1.2 --- peardoc/en/package/datetime/calendar/intro-purpose.xml:1.1 Sat Nov 22 09:12:03 2003 +++ peardoc/en/package/datetime/calendar/intro-purpose.xml Sat Nov 22 14:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" ?> -<!-- $Id: intro-purpose.xml,v 1.1 2003/11/22 14:12:03 quipo Exp $ --> +<!-- $Id: intro-purpose.xml,v 1.2 2003/11/22 19:46:16 quipo Exp $ --> <refentry id="package.datetime.calendar.intro-purpose"> <refnamediv> <refname>Introduction</refname> @@ -9,11 +9,13 @@ </refnamediv> <refsect1> <title>Introduction</title> + <para> <warning> - <para> + <simpara> Some classes in PEAR::Calendar require PEAR::Date be installed. The PEAR::Date 1.3.1beta is missing a file and will not work. Make sure you have PEAR::Date 1.3 (stable) installed. - </para> + </simpara> </warning> + </para> <para> PEAR::Calendar is an package for generating Calendars as data structures. It does not render content or rely on any underlying data store, allowing it to be applied to many problem domains. At the same time it provides an easy to use API that makes rendering, for example, an HTML calendar very easy, while making it possible to "connect" the calendar with your data store. </para>
« previous php.pear.doc (#1968) next »