Scal Planner
Scal is designed to be a basic javascript calendar, a date picker. However, if you have a calendar it is only inevitable that someone will want to turn it into a planner. Adding a mini-planner to scal was fairly simple, just add a dictionary to hold all the planner events and then load the relevant events when a particular month is displayed.
In version v0.1, the planner was part of the main scal.js file. For the sake of performance and extensibility, v0.2 separates the planner from the the main scal.js file. The planner is now in its own js: scalplanner.js. In addition to the structural changes, v0.2 planner events are far more robust and flexible than v0.1.
Using scalplanner.js
Calling up the planner under v0.2 is simple. Just include scalplanner.js after scal.js in your html.
<script type="text/javascript" src="/javascripts/prototype.js"> </script>
<script type="text/javascript" src="/javascripts/scal.js"> </script>
<script type="text/javascript" src="/javascripts/scalplanner.js"> </script>When you instantiate an scal instance pass along a planner array with the rest of the options:
var myplanner = [
{ period: 'December 17, 2007', label: ["Mom's Birthday", "Julie's Birthday"], cls: 'celebration'},
{ period: 'November 10, 2007', label: ['renew license','pickup mom'], cls: 'reminders'},
{ period: $A($R(new Date('November 5, 2007'),new Date('November 9, 2007'))), label: ['dragon days'], cls: 'dragons'}
];
var samplecal = new scal('samplecal',updateyear,{titleformat:'mmmm yyyy',closebutton:'X',dayheadlength:2,weekdaystart:0,planner: myplanner});The example above will do the following:
- Add "Mom's Birthday" on 12/17/2007 with a css class of "celebration"
- Add "Julie's Birthday" on 12/17/2007 with a css class of "celebration"
- Add "renew license" on 11/10/2007 with a css class of "reminders"
- Add "pickup mom" on 11/10/2007 with a css class of "reminders"
- Create a range of planner events from 11/5/2007-11/9/2007 with the value of "dragon days" and a css class of "dragons"
For more on event styles, see planner_test.html in the scal distribution. planner_test contains the css styles for 'celebration', 'reminders', and 'dragons'.
A live example of the planner is also available here on the documentation site.
Using the planner without setting initial events
The example above creates an scal instance with a few events. But what if you don't have events to fill in right away?
Simple enough, just pass in an empty array with options.planner, like so:
samplecal = new scal('samplecal',updateyear,{titleformat:'mmmm yyyy',closebutton:'X',dayheadlength:2,weekdaystart:0,planner: []});This will prep the planner to receive new events using setPlannerValue(year,month,day,val,cls).
Planner Methods
setPlannerValue(year,month,day,val,cls)
Description:
Adds an event to the planner with a class of dayboxevent.
iscal is the only included style that has a dayboxevent style
Required Parameters:
year,month,day should be self-explanatory. Val is the text that will appear on said date.
Optional Parameters:
cls is the css class that will be applied to the new planner event (along with the dayboxevent class).
Return Values:
Returns the element that the planner events were added to.
samplecal.setPlannerValue(2007,11,29,"Remove dragons!", 'dragonremove');updateDayValue(week,day,val,cls)
Description:
Changes the value of a particular cell on the calendar grid.
Required Parameters:
week and day map to row and column as opposed to a true javascript Date. Val is the text that will appear on said date.
Optional Parameters:
cls is the css class that will be applied to the new planner event (along with the dayboxevent class).
Return Values:
Returns the element that the planner events were added to.
samplecal.updateDayValue(2,1, "Pepper Fest!", 'pepperfest');getEventElementsByDate(date object)
Description:
Returns an array of all planner event elements for a specified date.
Required Parameters:
Date object of the the specified element to retrieve.
Optional Parameters:
None
Return Values:
An array of planner event elements for the specified date
var evts = samplecal.getElementsByDate(new Date('December 17, 2007'));getEventElementsByWeek(week number)
Description:
Retrieves the planner event elements for the specified week.
Required Parameters:
Number of the week to retrieve planner event elements for.
Optional Parameters:
None
Return Values:
AOA- Array of arrays containing the planner event elements for days of the given week
// will return an array containing the dates from November 5, 2007 to November 9, 2007
samplecal.getDatesByEvent('dragon days');removeEventsByDate(date, index)
Description:
Removes the planner events elements for a specified date.
By defaults, it removes all planner events elements for the specified date.
Required Parameters:
Date object of the the specified planner event elements to remove.
Optional Parameters:
index paramter is the index of the planner event for the date to remove from.
If the index parameter is given, only one planner event element will be removed.
Return Values:
Returns false if a planner date is not set for the given date.
// remove Mom's birthday (sorry Mom)
samplecal.removeEventsByDate(new Date('December 17, 2007'), 0);
// remove all events for December 17, 2007
samplecal.removeEventsByDate(new Date('December 17, 2007'));getCurrentEvents(true)
Description:
Returns an array of objects for each event for the current month.
Required Parameters:
None
Optional Parameters:
When given a parameter of true value, this method will only return the events for the current month. The default behavior is to return all events that are displayed, and not just the current month's events.
Return Values:
Array of planner event objects
Each object in the returned array has the following properties:
- dt - The date of the planner event
- target - The container element of the planner event elements
// get all events for the current view
samplecal.getCurrentEvents();
// get all events for the current month
samplecal.getCurrentEvents(true);getEventsByDate(date)
Description:
Returns an array of all planner events set for the given planner date.
Required Parameters:
Date object of the the specified planner event elements to retrieve.
Optional Parameters:
None
Return Values:
Array of planner event label string that are set for the given planner date.
// will return ["Mom's Birthday", "Julie's Birthday"]
samplecal.getEventsByDate(new Date('December 17, 2007'));getDatesByEvent(planner event)
Description:
Returns an array of dates that the given planner event falls on.
Required Parameters:
The label string of the planner event to retrieve the date objects for.
Optional Parameters:
None
Return Values:
Array of date objects that the give planner events falls on.
// will return an array containing the dates from November 5, 2007 to November 9, 2007
samplecal.getDatesByEvent('dragon days');getSelectedEvents()
Description:
Retrieves the selected planner day event elements for the current calendar.
Parameters:
None
Return Values:
Array of planner event elements for the selected day.
var selectedEvents = samplecal.getSelectedEvents();getTodaysEvents()
Description:
Retrieves the today planner day event elements for the current calendar.
Parameters:
None
Return Values:
Array of planner event elements for today.
var todayEvents = samplecal.getTodaysEvents(); Filed under
See the new forum link above to post questions, comments, and feature requests.
Comments are now closed on all documentation pages. Old comments attached to documentation pages are for reference only. Please use the forums. Thanks!
Problem when calling setPlannerValue
I have added a new function called replacePlanner with the intent of removing all of the current planner and replacing it with a new planner. First I call removeEventsByDate and that works fine. Then I loop through my new planner calling setPlannerValue. Well, when I do that, for some reason inside the setPlannerValue function it has the wrong value of "this". Instead of "this" referring to the calendar object it refers to the document Window instead.
Any reason for this? Any ideas what I might be doing wrong?
Here's my code:
replacePlanner: function(newPlanner){
for (var d in this.planner) {
var dt = new Date( d );
this.removeEventsByDate(dt);
}
for ( var planId in newPlanner ) {
var plan = newPlanner[planId];
var planDate;
if(Object.isString(plan.period)) {
planDate = new Date(plan.period);
}
else {
planDate = plan.period;
}
if ( planDate != null )
this.setPlannerValue( planDate.getFullYear(), planDate.getMonth() + 1, planDate.getDate(), plan.label, plan.cls );
}
fixed in latest release
Thanks, David.
We actually corrected this in the latest patch (uploaded 2 days ago). Check out the post in the bug forums.
great!
I'll download the new code and try it out!
Multiple Events on same day
Currently the planner does not support multiple events on the same day, but with different display classes. I have modified the code to support it, but it is more of a hack that requires you to enter a css class for every label you enter. It does allow you to have multiple events on the same date without requiring them to be in the same label array. This allows for any random ordering of events unlike the present planner. If you're interested in the changes I'll be glad to send them on.
-David