Overview / Introduction --------------------------------------------- The calendar class is written for any module that has items that correspond to a particular date. The class provides several features which are outlined below and explained in details later in this document. CURRENT FEATURES: I. Pop-Up Javascript Calendar Uses js_insert to add a calendar icon that brings up a popup window to choose a date from a graphical calendar. After choosing the date the month, day, and year fields will be auto-filled in the corresponding form fields. II. Mini Javascript Calendar Shows a calendar in which all the days are javascript hyperlinks. This is good for filling in forms that requires a month, day, and year. Unlike the 'pop-up' calendar this is designed to place a calendar within the the page itself. III. Expanded Month (EVENTS) Shows a complete month view with hyperlinked event titles within the days. IV. Mini Month (EVENTS) Unlike the expanded month view the days are calapsed and the days of the month that have an event are hyperlinked. Pop-Up Javascript Calendar --------------------------------------------- Purpose: The pop-up calendar is used when a form requires users to select a month, day, and year. A small calendar icon will be provided and when the user clicks on the icon a popup window will appear showing the current month with the options to change the month and year. Every day is a hyperlink that when clicked will autofill in the month, day, and year fields use the date selected. Setup: 1) Include the WizardBag class: require_once(PHPWS_SOURCE_DIR . "core/WizardBag.php"); 2) Add js_insert line(s) for each date field: $content = PHPWS_WizardBag::js_insert("mini_cal", NULL, NULL, FALSE, array("month"=>"month_field_name", "day"=>"day_field_name", "year"=>"year_field_name")); The "month_field_name", "day_field_name", and "year_field_name" should be replaced by the corresponding month,day, and year form field names. Note: The popup calendar by default uses your theme colors. You can disable theme colors to reduce memory use by changing 'USE_THEME_COLORS' to FALSE in the file js/mini_cal/settings.php. Mini Javascript Calendar --------------------------------------------- Purpose: The mini javascript calendar provides the same functionality as the popup javascript calendar except instead of popping up the calendar in a new window the calendar is embedded within the page itself. Each day is a hyperlink and there is the options to change the month and year shown. Each day is associated with a javascript function that the module developer will need to provide (such as in a template) when a user click on a date. Setup: 1) Include calendar class require_once(PHPWS_SOURCE_DIR . "core/Calendar.php"); 2) Create instance of calendar $cal = new PHPWS_Cal(); 3) Specify the javascript function to call when a user clicks on a date. $cal->jsOnClickFunc('yourFunction'); 4) Indicate the link to get back to the page where the calendar is display. $cal->setLinkBack("./index.php?module=yourmodule&op=yourops"); If you do not set the link back then the options to select a new month or year will not work properly. 5) Put in the template where the calendar will be display the javascript function that will be called when a user clicks on a date. The function must accept three parameters the month, day, and year in that order. All three are integer values. For February 13, 2004: yourFunction(2,13,2004); 6) Lastly, to get the calendar call the function getMiniMonthView(). $tags["MONTH_VIEW"] = $my_cal->getMiniMonthView(); Full Month Event Calendar --------------------------------------------- Purpose: Shows a full month view with each day expanded showing any events that occur during the day as bulleted items. The user can click the items and to a specific page that you control by the opcodes, same is true for clicking on days with no events. This view is ideal for scheduling events since the user can click on events to edit them or click blank days to go to a form to create a new event. Special Notes: -- The current month and year the user is viewing is associated with the request variable 'ts', which contains a unix time stamp. -- The opcode 'fullMonthCal' is set anytime the user interacts with the calendar. This useful to put in your module's action functions to listen for calendar events. Setup: 1) Include the calendar class. require_once(PHPWS_SOURCE_DIR."core/Calendar.php"); 3) Create a calendar object. You should make this a class variable to retain month and year selected. $this->cal = PHPWS_Cal("module_name", $this); Module name should be replaced with the module that is displaying the calendar. The calendar needs to have a reference to the displaying object in order to call the function discussed in step four, so passing in $this gives the calendar a reference to the current object. 3) Create a function in the class that is displaying the calendar that is called 'cal_getFullMonthActiveDays'. The function takes two parameters which are the month and year. The function should return an EventArray (see the bottom of this documents for a description of an EventArray) that contains all the events that current during the given month and year for your module. function cal_getFullMonthActiveDays($month, $year) { } 4) Specify the link back to display the calendar. Don't worry about the ts the calendar will add that automatically. $cal->setLinkBack("./index.php?module=your_mod&op=op_values"); 5) Lastly, call getExpandedMonthView to get the calendar. $tags["MONTH_VIEW"] = $cal->getExpandedMonthView(); Other useful functions: a) Specify opcode(s) for days with no events. Call the function setBlankOp() with the op to use for days that are empty (i.e. no events). The purpose is so you can link to a form to add an event. If it is left blank then clicking an email block will take you back to the month view $cal->setBlankOp("op=op_values"); You can use to the ts request variable to determine what day the user click on. b) Specify opcode(s) for clicking on events $cal->setItemOp("op=op_values"); This is mainly used for editing items so that you can use your module's same editing opcode. You can use to the ts request variable to determine what day the user click on. Mini Month Event Calendar --------------------------------------------- The mini-month event calendar is similar to the full month calendar but the days are not expanded to show the labels of the events. Instead, if an event occurs on a day then the day will appear has a hyperlink. Special Notes: -- The month and year the user is viewing is stored as a unix timestamp called 'tsSmall' in the request array. -- The opcode 'miniMonthCal' is set anytime the user interacts with the calendar. This useful to put in your module's action functions to listen for calendar events. -- If it is possible for your module to have multiple events on the same day then when a day has multiple event the opcode 'multi_id' will be used. Each id will be seperated by a colon so your module will need to look for the 'multi_id' op and if found can use the php explode function to extract out the ids. Example: The day the user clicked on has three events with ids three, four, and five. Creates: &multi_id=3::4::five& If idPrefixes are being used then each id will be prefixed. Setup): 1) Include the calendar class. require_once(PHPWS_SOURCE_DIR."core/Calendar.php"); 3) Create a calendar object. You should make this a class variable to retain month and year selected. $this->cal = PHPWS_Cal("module_name", $this); Module name should be replaced with the module that is displaying the calendar. The calendar needs to have a reference to the displaying object in order to call the function discussed in step four, so passing in $this gives the calendar a reference to the current object. 3) Create a function in the class that is displaying the calendar that is called 'cal_getActiveDays'. The function takes two parameters which are the month and year. The function should return an EventArray (see the bottom of this documents for a description of an EventArray) that contains all the events that current during the given month and year for your module. function cal_getActiveDays($month, $year) { } 4) Specify the link back to display the calendar. Don't worry about the tsSmall the calendar will add that automatically. $cal->setLinkBack("./index.php?module=your_mod&op=op_values"); 5) Lastly, call getMiniMonthView to get the calendar. $tags["MONTH_VIEW"] = $cal->getMiniMonthView(); Other useful functions: a) Specify opcode(s) for clicking on days with events $cal->setItemOp("op=op_values"); This is mainly used for editing items so that you can use your module's same editing opcode. You can use to the tsSmall request variable to determine what day the user click on. Appendix: --------------------------------------------- EventArray Format: $data[0]['id'] - The id of element in your module. $data[0]['start'] - Timestamp of when the item should begin The actual time is not considered, only the month day, and year. $data[0]['end'] - Timestamp of when item should end $data[0]['label'] - Label is the title that will appear in the month view $data[0]['idPrefix'] - IdPrefix is what will be a prefixed to the id Ex. If $data['idPrefix'] = 'single' $data['id'] = 4 Then it would be "single_id=4" The next event in the array will start at $data[1]. Notes: Start/End Dates Having the start and end time makes it easy to add events that span multiple day, months, or years. If your event is only for a single day then simply make the start and end date the same. idPrefix: The purpose of the idPrefix is if you want to display different kinds of items on the calendar and your code needs to make a distintion. You do NOT have to specify an idPrefix. Templates: By default the calendar uses templates found in /templates/calendar but you can specify your own templates by calling: $calObj->setTemplateDir(PHPWS_SOURCE_DIR."mod/yourmodule/templates/file.tpl"); There should be a month.tpl and smallmonth.tpl file. The month.tpl is only used for the full month event calendar all other calendars use the smallmonth.tpl. Mini-View Month If you would like to have the name of the current month you can uncomment out the {DATE} template variable in smallmonth.tpl. There is also the option to make the month a hyperlink which you can set by calling: $calObj->setFullMonthLink("./index.php?module=yourmod"); This is useful to have the month name link to a full month calendar. Accessor Methods Full Month Event Calendar $calObj->getFullMonthYear(); $calObj->getFullMonthMOnth(); Mini Month Event Calendar $calObj->getMiniViewMonth();