7. Special Event

Special event is similar to special day, except you could have more information associated with an event. There are 2 types of event item supported by NlsCalendar when creating special event:

  • URL, specifies url and attributes in this event. Date with special event will be rendered as hyperlink. You can specify URL to open the detail of the event.
  • Custom Event, can be any custom information. Calendar doesn't display custom event automatically since it is user defined custom object. You can use calendar's onChange event to get the selected event and display it.

Special event in calendar is diplayed with special style. The style is configured in stylesheet.

Same as defining special day, there are 2 ways to define special event in the calendar:

  1. Manually sets special event in NlsCalendar's dtEvents property.
  2. Programmatically overrides the getEvents() function.
1. Manually Set the Special Event

Simply add date with format yyyy-mm-dd (for ex. 2007-10-15) into dtEvents list to set special event on the date.


              
          //creates the calendar.
          <script>
            function EventItem(type, desc, start, end, url) {
              this.type=type;
              this.desc=desc;
              this.start=start;
              this.end=end;
              this.url=url;
            };

            function _onDateChange() {
              var s="<table cellspacing='1' cellpadding='3'>";
              s+="<tr style='background-color:#000000;color:#ffffff'><td>Type</td><td>Description</td><td>Start</td><td>End</td><td>Detail</td></tr>";
              var ev=this.getSelEvent();
              if(ev) {
                for(var i=0;i<ev.length;i++) {
                  s+="<tr><td style='border-bottom:#999999 1px dotted'>"+ev[i].type+"</td>";
                  s+="<td style='border-bottom:#999999 1px dotted'>"+ev[i].desc+"</td>";
                  s+="<td style='border-bottom:#999999 1px dotted'>"+ev[i].start+"</td>";
                  s+="<td style='border-bottom:#999999 1px dotted'>"+ev[i].end+"</td>";
                  s+="<td style='border-bottom:#999999 1px dotted'><a href='"+ev[i].url+"'>detail</a></td></tr>";
                }
              }
              s+="</table>";
              document.getElementById("eventViewer").innerHTML=s;
            }


            var cal=new AOCalendar("cal1");
            cal.opt.themeDir="../themes/default/";
            cal.opt.mode=1; 
            cal.opt.showAdjcDates=true;
            cal.opt.dtFormat="$dm/$dd/$YY";
            cal.dtEvents={
            "XXXX-XX-01":new AOCalendar.CEvent(null, null, [new EventItem("Appointment","Regular monthly meeting", " ", " ", "http://www.addobject.com")]),
            "XXXX-XX-14":new AOCalendar.CEvent("http://www.addobject.com", "target='_blank'", null),
            "2007-03-20":new AOCalendar.CEvent(null, null, [new EventItem("Appointment","Meeting with customer, XXL Inc.", "03/20/2007 09:00", "03/20/2007 10:00", "http://www.addobject.com"),
                                                     new EventItem("Appointment","Project discussion with team.", "03/20/2007 13:00", "03/20/2007 15:00", "http://www.addobject.com")
                         ]),
            "2007-04-25":new AOCalendar.CEvent(null, null, [new EventItem("Appointment","Meeting with customer, ZXC Inc.", "04/25/2007 10:00", "04/25/2007 12:00", "http://www.addobject.com")]),
            "2007-05-12":new AOCalendar.CEvent(null, null, [new EventItem("Task","Develop Custom Module.", "05/12/2007 08:00", "05/12/2007 17:00", "http://www.addobject.com")]),
            "2007-06-06":new AOCalendar.CEvent(null, null, [new EventItem("Task","Unit Testing.", "06/06/2007 08:00", "06/06/2007 17:00", "http://www.addobject.com")]),
            "2007-07-21":new AOCalendar.CEvent(null, null, [new EventItem("Notes","John probably arrive today afternoon.", " ", " ", "http://www.addobject.com")]),
            "XXXX-08-16":new AOCalendar.CEvent(null, null, [new EventItem("Anniversary","Rio birthday.", " ", " ", "http://www.addobject.com")])
            };

            cal.onChange=_onDateChange;
            cal.render();

          </script>  
        

As shown in example above, special events are defined in dtEvents associated array. The array has the following format:

        
        {
          "date string" : [Event object],
          "date string" : [Event object],
          "date string" : [Event object]
        }      
      

Each entry is key:value pair (key and value separated by semicolon(:), and each entry is separated by comma(,). The value is AOCalendar.CEvent object. The event object has 3 parameters to create url event or custom event as described earlier in this section.

  • url, specify url of the event. If this paremeter is not null, the date in the calendar will be rendered as link.
  • attr, attribute of the link specified in first paramenter for example "target='_blank' title='Open event detail'".
  • data, array of event detail. Event detail can be any types including custom object.

Below is example to create the event object:

      
        //create an URL type of event. This will rendered as url in the calendar.
        new AOCalendar.CEvent("http://server.com/showdetail.php", " target='_blank' ", null);
        
        //create custom event.
        new AOCalendar.CEvent(null, null, [new myCustomEvent("Dinner with Gary"), 
                                           new myCustomEvent("Andy birthday")]
        );
      

Note that custom event is not displayed in calendar automatically. It is only placeholder for your custom data, it can be any types or objects. To display the event, you will need to retrieve the event and display it as shown in the example code. The example use calendar's onChange event to retrieve the event and display it in the page.

Same as special day, special event is also accessible using JavaScript:

        
        //set event to Dec 25, 2007
        cal.dtEvents["2007-12-25"]=new AOCalendar.CEvent(null, null, ["Christmas Day"]);
      

To remove special event from calendar, you can remove the entry from the list or set the value to false.

        
        //remove event from calendar
        cal.dtEvents["2007-12-25"]=false;
        
        //or delete the entry from the array
        delete dtEvents["2007-12-25"];
      

Also note in the example, you can use wildcard on year, month or date. For example to set every August 01st with special event, you can use "XXXX-08-01". Wildcard character is "X".



2.Programmatically Set Special Event.

Programmatically set special event allows you greater control in calculating dates you'd like special event attached to. It allows you to apply more complex logic for example set period of dates, weekend day with special event, first/last day of month etc.

To programmatically set special event, simply creates a handler function and assign it to NlsCalendar.getEvents() function. Below is an example to set every July 01st to July 03rd with special event.


        //creates the calendar.
        <script>        
          
          function customSpecialEvent(d) {
            var dt=AOCalendar.parseDate(d, "$YY-$dm-$dd");
            
            var cMonth=dt.getMonth();
            var cDate=dt.getDate();
            if(cMonth==6 && cDate>=1 && cDate<=3 ) { //0=January.
              return new AOCalendar(null, null, ["Company annual outing"];
            }

            return false;
          }
          
          
          var cal2=new AOCalendar("cal2");
          cal2.opt.themeDir="../themes/default/";
          cal2.getEvents=customSpecialEvent;
          cal2.render();
        </script>         
      

The getEvents() function is evaluated each time the calendar renders/refreshes. When the function is invoked, a date with format yyyy-mm-dd (for ex. 2007-10-25) is passed into the function. You should evaluate the date value and returns AOCalendar.CEvent object. or false.

An important note when using this function is manually specified event (in dtEvents property) will be ignored. However you can simply check whether the date is defined in the property by using AOCalendar.getMatch() function. This way you have more control on which method (manual or programmatic) takes precendence. Here below is the example.


        //creates the calendar.
        <script>
          
          
          function customSpecialEvent(d) {
            var dt=AOCalendar.parseDate(d, "$YY-$dm-$dd");

            var evnt = AOCalendar.getMatch(d, this.dtEvents);
            if(evnt) return evnt;
            
            var cMonth=dt.getMonth();
            var cDate=dt.getDate();
            if(cMonth==6 && cDate>=1 && cDate<=3 ) { //0=January.
              return new AOCalendar(null, null, ["Company annual outing"];
            }

            return false;
          }
          
          
          var cal2=new AOCalendar("cal2");
          cal2.opt.themeDir="../themes/default/";
          cal2.getEvents=customSpecialEvent;
          cal2.render();
        </script>    
      

As shown in the example above, the AOCalendar.getMatch() function requires 2 parameters, the first is the date to check and second is the list of special events which is dtEvents property.